user-engine/docs/contracts.md

Public Contracts

Headless Service Surface

UserEngineService is the stable in-process API for the current MVP. Future HTTP or RPC adapters should preserve these operation names:

• health, readiness, operability_snapshot, outbox_diagnostics
• me, create_user, set_account_status, link_identity
• resolve_tenant_context, set_tenant_account_status, add_membership, tenant_diagnostics
• register_application, publish_catalog
• set_profile_value, effective_profile, projection
• audit_records, outbox_events

Error Taxonomy

• ValidationError: caller supplied an invalid shape, state transition, or catalog/profile value.
• AuthorizationDenied: the authorization port or tenant boundary denied the operation.
• NotFoundError: a requested user, account, or active attribute is missing.
• ConflictError: uniqueness or ownership would be violated.

Catalog Contract

Catalogs are active by namespace and owning application. Attribute keys must use the namespace prefix. Active namespace ownership cannot move to another application. Catalog updates cannot move versions backwards or downgrade attribute sensitivity.

Projection Contract

Application runtime, agent-context, and claims-enrichment projections require an application_id and are filtered to that application's active catalogs. Sensitive and secret values are redacted outside admin, audit, and self-service projections.

Audit And Event Contract

Every mutating service operation appends an audit record and outbox event with the same correlation id and resolved tenant. Authorization denials are audited without emitting outbox events.

Migration Contract

The isolated store exposes SCHEMA_VERSION = 0001_initial and a migrate hook. Database-backed stores must expose equivalent readiness semantics before they are accepted by platform adapters.