Identity ledger schema design — PointSav Documentation

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. See also the WORM ledger design and machine-based authorization.

[edit]Key Takeaways

Identity resolution is fully deterministic. The primary identifier (identity_id) is a UUIDv5 derived from the user’s primary email address — the same email always produces the same UUID across any node, with no AI or probabilistic matching. This satisfies ADR-07’s requirement that Ring 1 extraction bypass inference.
Identity records follow WORM discipline. Role changes, new endpoints, and other updates are appended as new records; readers fetch the latest record per identity_id. The full append history is preserved as an immutable audit trail of the identity’s progression over time.
A single identity record is the authoritative source for all communication endpoints: email (RFC 5322), phone (E.164), and typed platform handles (Slack, Teams, Signal). Downstream services resolve endpoints from this record — they do not derive or cache their own.
Ambiguous or conflicting identities are surfaced to a human operator rather than silently merged. Deterministic extraction at Ring 1; human resolution for exceptions. No probabilistic model makes silent merges at ingest.

[edit]Core Design Principles

[edit]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.

[edit]2. Append-Only Integrity

The platform uses 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.

[edit]3. Multi-Channel Communication

Identity records serve as a unified source for all communication endpoints, including:

Email: RFC 5322 compliant, case-insensitive addresses.
Phone: E.164 formatted numbers.
Endpoints: Typed handles for Slack, Teams, Signal, and other integrated platforms.

[edit]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:

A unique role_id.
A categorical role_type (Employee, Vendor, Customer, etc.).
effective_at and expires_at temporal markers.
Extensible attributes for department, title, and permissions.

[edit]Entity Resolution Standards

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.
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.

[edit]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 substrate for all downstream automated processing.