Finalize user-engine contracts and operability

docs/contracts.md

@@ -0,0 +1,49 @@
+# 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.