Diff: architecture/identity-ledger-schema-design.es

From a440e91 to a440e91

+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
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 Foundry ecosystem. 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 Foundry ecosystem. 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
Foundry 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.	Foundry 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]]