Identity Layer

The Identity Layer gives ContextOS stable names for two different things:

• business entities the runtime talks about, such as customers, orders, policies, documents, and tools;
• actors that execute work, such as delegated users, agents, gateways, and adapters.

Stable identity is what lets the runtime bind evidence to entities, bind actions to authority, and replay a run without guessing which object or actor a model meant.

Definition

The Identity Layer owns:

The Ontology defines entity types, relationships, constraints, and classification rules. The Identity Layer generates and resolves identifiers for those entities.

Why It Exists

Without a formal identity layer:

• a plan may refer to ord_881 while a tool expects a different upstream ID;
• memory may store human-readable names that collide or leak PII;
• evidence may cite a record without the source-system mapping needed for audit;
• a tool call may blur the delegated user and the agent workload;
• replay may not know which entity version or actor authority was active.

ContextOS separates those concerns so every run can answer who acted, on whose behalf, against which entity, using which authority.

Entity Identity

CEID

A Canonical Entity ID is the default reference token for agent-visible artifacts.

ceid:{entity_type}:{slug}:{suffix}

Examples:

ceid:order:ord-881:6fa2
ceid:customer:cus-77:91bd
ceid:policy:refund-threshold-high:0b7e

CEIDs are not primary keys. They are stable handles that resolve to source-system IDs through a mapping store. Old CEIDs remain resolvable as aliases after renames, merges, and migrations.

SID

A Semantic ID is a model-facing feature identity, usually produced from embeddings or other side information.

sid:{entity_type}:{sid_model_version}:{token_sequence}

SIDs are useful for retrieval, ranking, recommendation, and other ML systems. They are not suitable as audit handles because they may be regenerated when the feature model changes.

Hard Rules

Actor Identity

Every governed run carries both human and machine authority. The implementation lesson is that “agent identity” cannot be a single string. ContextOS treats it as four linked facts:

1. Registry identity — the durable agent subject, such as agent:contextos/support-refund@1.2.0.
2. Workload identity — the runtime or service identity that proves where the agent is executing, usually SPIFFE-style.
3. Delegation chain — the ordered principals the run is acting for: human, service, automation, parent agent, child agent.
4. Run claim — a short-lived signed claim binding subject, chain, scopes, run ID, tenant, model/runtime profile, expiry, and key ID.

The Tool Gateway should never treat the agent as the user. It checks both: the user must have delegated authority, and the agent workload must be allowed to use that authority for the requested capability.

Agent identity subject

ContextOS uses a versioned agent URN for the audit subject:

agent:contextos/{slug}@{semver}

Examples:

agent:contextos/support-refund@1.2.0
agent:contextos/incident-commander@0.9.4
agent:contextos/data-steward@2.0.0

The URN is not the process identity. It names the agent behavior contract: manifest, owner, lifecycle, policy ceiling, tool surface, prompt pack, and runtime profile. The workload identity proves the process. The signed claim binds the process and the behavior contract to one run.

Ownership and lifecycle

Every registered agent should have structured ownership:

{
  "agent_urn": "agent:contextos/support-refund@1.2.0",
  "owner": {
    "owner_id": "team_support_ops",
    "owner_kind": "team",
    "tenant_id": "tenant_acme_prod",
    "created_by": "usr_platform_admin_11",
    "signing_key_id": "kid_ctxos_support_2026_05",
    "lifecycle": "active"
  },
  "identity_scopes": ["tools:read", "tools:write", "a2a:send"]
}

lifecycle is part of authorization, not decoration. A revoked agent cannot receive new run claims, appear in active discovery, or execute A2A work. A deprecated agent may remain replayable but should not be selected for new runs unless policy explicitly allows a migration window.

Principal chain and on-behalf-of

The principal chain records who the run is for and how authority was delegated. It is ordered oldest-first and should be narrowed, not expanded, at each hop.

[
  { "kind": "user", "id": "usr_771", "tenant_id": "tenant_acme_prod" },
  { "kind": "agent", "id": "agent:contextos/support-refund@1.2.0", "tenant_id": "tenant_acme_prod" },
  { "kind": "agent", "id": "agent:contextos/refund-policy-checker@0.4.0", "tenant_id": "tenant_acme_prod" }
]

A child agent does not inherit the parent’s bearer credential. It receives a fresh claim whose principal chain points back to the original human and parent agent, with a smaller scope set and a shorter expiry.

Identity claim

The run claim is the portable proof attached to RunContext, A2A envelopes, Tool Gateway calls, and audit rows.

{
  "version": "ctxid/1",
  "iss": "contextos:identity",
  "sub": "agent:contextos/support-refund@1.2.0",
  "aud": "contextos:runtime",
  "run_id": "run_a1b2c3d4e5f60718",
  "tenant_id": "tenant_acme_prod",
  "principal_chain": [
    { "kind": "user", "id": "usr_771", "tenant_id": "tenant_acme_prod" }
  ],
  "scopes": ["tools:read", "tools:write", "a2a:send"],
  "nbf": "2026-05-17T10:00:00Z",
  "exp": "2026-05-17T10:05:00Z",
  "kid": "kid_ctxos_support_2026_05",
  "claim_hash": "sha256:...",
  "sig": "..."
}

Minimum rules:

• Claims are short-lived and scoped to one run, session, or A2A hop.
• Child claims must be narrower than parent claims and cannot carry agent:spawn/a2a:send unless policy explicitly permits delegation.
• Tool scopes are an intersection of requested scopes, manifest ceiling, delegated-user scopes, adapter permissions, and approval-mode constraints.
• Claim hashes, not raw secrets, are what operators should see in traces and dashboards.

Credential Exchange

For delegated or destructive work, long-lived credentials should not reach the model or the planner. The boundary pattern is:

1. Validate delegated user claims, agent registry lifecycle, signed run claim, workload identity, and tenant scope.
2. Evaluate policy, manifest scope ceiling, tool, and approval-mode constraints.
3. Mint a short-lived execution credential scoped to one action.
4. Invoke the adapter through the Tool Gateway.
5. Persist credential exchange metadata, policy decision ID, identity claim hash, trace ID, and receipt.

sequenceDiagram
  participant User as User
  participant Agent as Agent Runtime
  participant Identity as Identity Layer
  participant Gateway as Tool Gateway
  participant Tool as Tool Adapter
 
  User->>Agent: Request with delegated auth context
  Agent->>Identity: Validate user delegation and agent workload
  Identity-->>Agent: Signed run claim + narrowed scopes
  Agent->>Gateway: ToolCallEnvelope with claims, tenant, trace, CEIDs
  Gateway->>Gateway: AuthN/AuthZ, policy, approval mode, parameter checks
  Gateway->>Tool: Invoke with short-lived execution credential
  Tool-->>Gateway: Result and receipt
  Gateway-->>Agent: ToolResultEnvelope, policy_decision_id, citations

Resolution Model

Entity resolution should preserve both audit readability and system-specific precision.

{
  "ceid": "ceid:order:ord-881:6fa2",
  "entity_type": "order",
  "entity_key": "ent_01JFG2",
  "is_canonical": true,
  "aliases": ["ceid:order:legacy-881:83bb"],
  "source_mappings": [
    {
      "system": "orders_db",
      "source_id": "ord_881",
      "confidence": 1.0
    }
  ],
  "classification": "INTERNAL",
  "ontology_version": "ont.support@1.0.0",
  "ceid_policy_version": "ceid-policy@2.0.0"
}

Tool adapters resolve CEIDs to source IDs at the boundary. Agent prompts, plans, evidence refs, and memory records should keep CEIDs.

Governance Rules

• Do not embed raw PII in CEID slugs unless a policy explicitly allows it.
• Keep source-system mappings access controlled and audited.
• Treat CEID resolution as a governed read when the source mapping is sensitive.
• Preserve aliases rather than rewriting old evidence or memory.
• Version SID generators and tokenizers; never rely on SID stability across versions.
• Record both delegated user and agent workload identity on ToolEnvelope and DecisionRecord.
• For cross-tenant workflows, require explicit tenant scope on every resolution and tool call.
• Treat agent lifecycle as an authorization input; revoked agents fail closed.
• Rotate signing keys under change control and keep previous keys only for historical replay until their deprecation window expires.
• Emit agent_identity_subject, agent_identity_claim_hash, agent_identity_scopes, and principal_chain metadata on every tool, A2A, policy, and decision audit row.

Failure Modes

Operational Metrics

• CEID uniqueness and collision rate.
• CEID resolution success rate and latency.
• Alias coverage for renamed or merged entities.
• Percentage of planner steps and evidence refs using CEIDs instead of raw source IDs.
• Tool calls with both delegated user and agent workload identity present.
• Tool/A2A calls with signed identity claim hash present.
• Claim verification failure rate by reason: expired, bad signature, missing scope, tenant mismatch.
• Revoked-agent execution attempts denied.
• Key rotation age and trusted-previous-key window.
• Credential exchange failure rate by approval mode.
• SID churn and retrieval quality delta by SID version.
• Cross-tenant resolution denial rate.

Example

For a refund request:

{
  "run_context": {
    "tenant_id": "tenant_acme_prod",
    "user": {
      "user_id": "usr_771",
      "delegation": {
        "subject": "u:user:771",
        "scopes": ["orders.read", "payments.refund"]
      }
    },
    "agent": {
      "agent_id": "agt_support",
      "agent_urn": "agent:contextos/support-refund@1.2.0",
      "workload_identity": "spiffe://contextos/agents/support",
      "identity_claim": {
        "sub": "agent:contextos/support-refund@1.2.0",
        "run_id": "run_a1b2c3d4e5f60718",
        "scopes": ["tools:read", "tools:write"],
        "claim_hash": "sha256:..."
      }
    }
  },
  "entities": {
    "order": "ceid:order:ord-881:6fa2",
    "customer": "ceid:customer:cus-77:91bd"
  }
}

The Planner and Critic reason over CEIDs. The Tool Gateway resolves ceid:order:ord-881:6fa2 to the orders system ID only after policy and identity checks pass.

Common Misconceptions

• “CEIDs replace database IDs.” They do not. They give ContextOS a stable audit handle that maps to source IDs.
• “SIDs are better CEIDs.” They are not. SIDs are model features and can change across versions.
• “The agent acts as the user.” The agent acts under delegated user authority with its own workload identity.
• “Identity is only an Intelligence-plane concern.” Entity identity is Intelligence-plane work; execution authority is Trust-plane work.

Related Docs

• Ontology
• Knowledge Graph
• Governance
• Adapter Mesh
• API Contracts