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