# Coding-session contracts

> Verified against code 2026-08-09.

This dependency-free module owns the strict provider-neutral Pydantic envelope shared by Claude
Code, Codex, Cursor, VS Code, matrx-local, and matrx-sandbox. The system contract is
[`common-docs/systems/coding-session-bridge/FEATURE.md`](/Users/armanisadeghi/code/common-docs/systems/coding-session-bridge/FEATURE.md).

- **No host imports.** The module contains types only and remains importable in a standalone
  `matrx-ai` installation.
- **One schema version.** `BridgeRequest.schema_version=1` rejects unknown fields and invalid
  action-specific combinations.
- **Hooks may omit conversation and stable IDs.** The authenticated host mints bindings and derives
  provider-specific fallback identity under lock.
- **Native appends are exact.** Every native entry carries a stable ID and zero-based source
  sequence; the host verifies or computes its canonical SHA-256.
- **Responses are typed.** Counts, projection receipts, checkpoint gaps, capabilities, raw entry
  pages, and Claude hook output share one `BridgeResponse`; native load pages contain exact
  `BridgeEntry` fields and never host-database record internals.
- **Account identity is opaque, display-safe provenance.** `BridgeSourceMetadata` (append_native
  imports) and the optional `BridgeAccountIdentity` object (observe_hook only) carry the same four
  fields: `provider_account_key` (64-hex), `provider_account_key_version` (2 = deterministic
  platform-namespaced SHA-256, identical on every machine; 1 = the retired per-installation HMAC,
  the default when absent), `provider_account_fingerprint` (validated as the key's first 12 hex
  chars), and `provider_account_label` (≤64 chars, a masked email or org-id prefix — never a raw
  email, credential, or token). The host promotes these to the session metadata root and enforces
  version-aware conflicts.

## Change Log

- 2026-08-12 — Added versioned account-key fields, the fingerprint-consistency validator, and the
  observe_hook-only `BridgeAccountIdentity` carrier.
- 2026-08-09 — Added adapter envelope v1 and typed responses/checkpoints/capabilities.
