# Tenancy, Role Mapping, And Context Governance

## Purpose

This document defines how the platform should identify users, determine their scope of access, and control which customer materials can be used during retrieval and generation.

## Identity Model

The platform should identify users through Microsoft identity and enrich that identity through Microsoft Graph.

### Identity Inputs

- Azure AD or Entra user identifier
- primary email address
- group memberships
- department or business unit attributes
- manager and reporting metadata where relevant
- custom application mapping records for tenant and role resolution

## Role Mapping Model

The platform should resolve every user to a context access profile.

### Required Access Profile Fields

- `tenantId`
- `brandId`
- `businessUnitId`
- `roleId`
- `roleType`
- `permittedCapabilities`
- `permittedApprovalActions`
- `permittedArtifactScopes`
- `dataResidencyClass`

### Example Role Types

- `requester`
- `brand-manager`
- `marketing-lead`
- `legal-reviewer`
- `executive-approver`
- `agency-operator`

## Tenant Isolation Rules

Tenant separation should be enforced before retrieval, tool access, and generation.

### Required Isolation Guarantees

- a user can only retrieve customer assets from the mapped tenant and permitted brand scope
- tenant filtering should happen before relevance ranking
- generated artifacts must inherit the originating tenant and session metadata
- audit logs must preserve tenant attribution for every response
- tools must refuse access when tenant resolution is missing or ambiguous

## Context Classes

The platform should treat source material differently depending on its approval status and reuse policy.

### `approved`

Reusable context that can be indexed for future conversations.

Examples:

- approved brand guidelines
- approved messaging pillars
- approved campaign assets
- approved legal language

### `generated`

Draft work created by the system or users during a live task.

Examples:

- first-pass ad copy
- exploratory messaging variants
- design prompt drafts
- briefing notes captured during the session

### `retired`

Content that should no longer be used for future work except for audit or archive purposes.

Examples:

- outdated brand rules
- superseded claims
- expired campaign assets

## Approved Vs Generated Work Handling

Generated work should never become reusable tenant memory automatically.

### Rules

- all new outputs default to `generated`
- generated outputs remain scoped to the active session or task workspace
- promotion from `generated` to `approved` requires an explicit approval event
- approval events should record who approved the artifact and when
- approved artifacts should be re-indexed with their new approval state
- retired artifacts should be removed from active retrieval results

## Provenance Requirements

Every generated output should be traceable to the inputs and rules that influenced it.

### Provenance Metadata

- `tenantId`
- `userId`
- `sessionId`
- `requestId`
- `modelId`
- `toolInvocations`
- `retrievedSourceIds`
- `promptAssetIds`
- `artifactId`
- `approvalState`
- `generatedAt`

### Provenance Uses

- explain why a response was shaped a certain way
- support quality review and compliance review
- prove which customer rules influenced generated work
- distinguish grounded material from speculative suggestions

## Access Control Decision Flow

```mermaid
flowchart TD
    user[AuthenticatedUser] --> identity[MsGraphProfile]
    identity --> mapping[RoleTenantMapping]
    mapping --> accessProfile[AccessProfile]
    accessProfile --> contextFilter[ContextScopeFilter]
    contextFilter --> approved[ApprovedContextSearch]
    contextFilter --> session[SessionGeneratedContext]
    approved --> promptPack[PromptPackage]
    session --> promptPack
    promptPack --> response[ResponseOrDraft]
    response --> approval[ApprovalDecision]
    approval --> approvedLibrary[ApprovedArtifactLibrary]
```

## Role-Aware Retrieval Rules

- `requester`
  - can create and view drafts within assigned scope
  - cannot approve reusable context
- `brand-manager`
  - can retrieve approved assets for the brand
  - can approve selected generated work
- `legal-reviewer`
  - can access compliance-sensitive guidance
  - can block approval when policy is violated
- `agency-operator`
  - can administer prompt assets and retrieval mappings
  - should not cross tenant boundaries without explicit delegated access

## Operational Recommendations

- maintain a tenant registry outside prompt content
- treat role mapping as application authorization data, not prompt data
- perform hard filters in code before sending any context to the model
- store approval events separately from generated artifact content
- make provenance queryable for support and audit workflows