Diff: architecture/identity-ledger-schema-design.es
From 2210706 to 2210706
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| type: topic | type: topic |
| slug: identity-ledger-schema-design | slug: identity-ledger-schema-design |
| short_description: "The Identity Ledger provides a JSONL-based append-only record of canonical person identities using deterministic UUIDv5 derivation from email addresses and WORM discipline. It serves as the unified source for all communication endpoints and temporal role snapshots, enabling deterministic entity resolution without probabilistic inference." | short_description: "The Identity Ledger provides a JSONL-based append-only record of canonical person identities using deterministic UUIDv5 derivation from email addresses and WORM discipline. It serves as the unified source for all communication endpoints and temporal role snapshots, enabling deterministic entity resolution without probabilistic inference." |
| title: "Identity ledger schema design" | title: "Identity ledger schema design" |
| audience: vendor-public | audience: vendor-public |
| bcsc_class: current-fact | bcsc_class: current-fact |
| language: en | language: en |
| paired_with: identity-ledger-schema-design.es.md | paired_with: identity-ledger-schema-design.es.md |
| category: architecture | category: architecture |
| --- | --- |
| The Identity Ledger provides a JSONL-based, append-only record of canonical person identities within the platform. Following the Three-Ring Architecture’s boundary-ingest pattern, `service-people` publishes this schema to enable deterministic identity resolution across all Ring 2 and Ring 3 knowledge-extraction services. | The Identity Ledger provides a JSONL-based, append-only record of canonical person identities within the platform. Following the Three-Ring Architecture’s boundary-ingest pattern, `service-people` publishes this schema to enable deterministic identity resolution across all Ring 2 and Ring 3 knowledge-extraction services. |
| ## Core Design Principles | ## Core Design Principles |
| ### 1. Deterministic Identity via UUIDv5 | ### 1. Deterministic Identity via UUIDv5 |
| The primary identifier (`identity_id`) is derived deterministically from the user’s primary email address using a UUIDv5 namespace. This ensures that the same email always produces the identical UUID across any node without requiring AI or probabilistic matching, satisfying the strict requirements of ADR-07. | The primary identifier (`identity_id`) is derived deterministically from the user’s primary email address using a UUIDv5 namespace. This ensures that the same email always produces the identical UUID across any node without requiring AI or probabilistic matching, satisfying the strict requirements of ADR-07. |
| ### 2. Append-Only Integrity | ### 2. Append-Only Integrity |
| The platform utilizes a WORM (Write-Once-Read-Many) discipline for identity records. To update an identity—such as a role change or a new communication endpoint—a new record is appended to the ledger. Readers always fetch the latest record per `identity_id`, preserving a full, immutable audit trail of the identity’s history. | The platform utilizes a WORM (Write-Once-Read-Many) discipline for identity records. To update an identity—such as a role change or a new communication endpoint—a new record is appended to the ledger. Readers always fetch the latest record per `identity_id`, preserving a full, immutable audit trail of the identity’s history. |
| ### 3. Multi-Channel Communication | ### 3. Multi-Channel Communication |
| Identity records serve as a unified source for all communication endpoints, including: | Identity records serve as a unified source for all communication endpoints, including: |
| * **Email:** RFC 5322 compliant, case-insensitive addresses. | * **Email:** RFC 5322 compliant, case-insensitive addresses. |
| * **Phone:** E.164 formatted numbers. | * **Phone:** E.164 formatted numbers. |
| * **Endpoints:** Typed handles for Slack, Teams, Signal, and other integrated platforms. | * **Endpoints:** Typed handles for Slack, Teams, Signal, and other integrated platforms. |
| ## Temporal Role Snapshots | ## Temporal Role Snapshots |
| Roles are recorded as immutable snapshots within the `roles` array. This allows the system to track an individual's progression (e.g., from contractor to employee) over time. Each role assignment includes: | Roles are recorded as immutable snapshots within the `roles` array. This allows the system to track an individual's progression (e.g., from contractor to employee) over time. Each role assignment includes: |
| * A unique `role_id`. | * A unique `role_id`. |
| * A categorical `role_type` (Employee, Vendor, Customer, etc.). | * A categorical `role_type` (Employee, Vendor, Customer, etc.). |
| * `effective_at` and `expires_at` temporal markers. | * `effective_at` and `expires_at` temporal markers. |
| * Extensible attributes for department, title, and permissions. | * Extensible attributes for department, title, and permissions. |
| ## Entity Resolution Standards | ## Entity Resolution Standards |
| Per ADR-07, identity resolution must be deterministic and bypass AI inference at the Ring 1 layer: | Per ADR-07, identity resolution must be deterministic and bypass AI inference at the Ring 1 layer: |
| * **Regex Extraction:** Email and phone data are extracted via deterministic patterns. | * **Regex Extraction:** Email and phone data are extracted via deterministic patterns. |
| * **Ambiguity Management:** Unknown or conflicting identities are surfaced to a human operator rather than being silently merged by a probabilistic model. | * **Ambiguity Management:** Unknown or conflicting identities are surfaced to a human operator rather than being silently merged by a probabilistic model. |
| * **Normalization:** Emails are lowercased and deduplicated prior to UUID derivation. | * **Normalization:** Emails are lowercased and deduplicated prior to UUID derivation. |
| ## MCP Integration | ## MCP Integration |
| `service-people` exposes identity data through the Model Context Protocol (MCP), providing resources for looking up records by ID or email, and tools for appending new identity claims from Ring 1 inbound services. This architecture ensures that identity remains a stable, verifiable sustrato for all downstream automated processing. | `service-people` exposes identity data through the Model Context Protocol (MCP), providing resources for looking up records by ID or email, and tools for appending new identity claims from Ring 1 inbound services. This architecture ensures that identity remains a stable, verifiable sustrato for all downstream automated processing. |
| ## See also | ## See also |
| - [[machine-based-auth]] | - [[machine-based-auth]] |
| - [[capability-based-security]] | - [[capability-based-security]] |
| - [[worm-ledger-design]] | - [[worm-ledger-design]] |
| - [[cryptographic-ledgers]] | - [[cryptographic-ledgers]] |