npm - @nurix/etna - Versions diffs - 0.18.0 → 0.18.2 - Mend

@nurix/etna 0.18.0 → 0.18.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (118) hide show

package/data/harnesses/code/skills/boundary/references/boundary-taxonomy.md CHANGED Viewed

@@ -1,92 +1,51 @@
 # Application Boundary Taxonomy
-> The shared knowledge root for the `boundary` skill. Every mode —
-> `check`, `generate`, `create`, `init` — reads this file. It is the single
-> source of truth for *what an application boundary is* and *which kinds exist*,
-> so the four modes can never drift from each other. Extend the catalog here and
-> all four modes inherit it at once.
+> The shared knowledge root for the `boundary` skill. Every mode — `check`, `generate`, `create`, `init` — reads this file. It is the single source of truth for _what an application boundary is_ and _which kinds exist_, so the four modes can never drift from each other. Extend the catalog here and all four modes inherit it at once.
 ---
 ## What an application boundary is
-An **application boundary** is a horizontal, cross-cutting contract — an *edge*
-between modules, layers, services, or deploy units — where an implicit agreement
-must hold on both sides, but is enforced in *different places* on each side. The
-defining hazard: change one side and it compiles/lints/tests clean, then fails
-only at runtime — in production, often silently, sometimes with data loss.
-The dangerous boundaries are the **invisible** ones. A team documents "auth" but
-never "the Redux store shape" or "the entity model," because those read as *just
-how the app is built*. This taxonomy names them so they can't hide.
-The recurring failure signature across every category is the same: **two sides
-that are never statically linked** — a reader and a provider, a producer and a
-consumer, a schema and its generated client, a host and a remote, a config and
-its bundler — so a change on one side surfaces only at boot, install, deploy,
-replay, or never-loudly-at-all (a leaked secret, a stale cache, a silent
-cross-tenant read). The universal mitigation: **make the implicit contract
-explicit and CI-checkable**, and treat the identifier (column, key, route, tag,
-topic, token, header, binding) as a versioned API.
+An **application boundary** is a horizontal, cross-cutting contract — an _edge_ between modules, layers, services, or deploy units — where an implicit agreement must hold on both sides, but is enforced in _different places_ on each side. The defining hazard: change one side and it compiles/lints/tests clean, then fails only at runtime — in production, often silently, sometimes with data loss.
+The dangerous boundaries are the **invisible** ones. A team documents "auth" but never "the Redux store shape" or "the entity model," because those read as _just how the app is built_. This taxonomy names them so they can't hide.
+The recurring failure signature across every category is the same: **two sides that are never statically linked** — a reader and a provider, a producer and a consumer, a schema and its generated client, a host and a remote, a config and its bundler — so a change on one side surfaces only at boot, install, deploy, replay, or never-loudly-at-all (a leaked secret, a stale cache, a silent cross-tenant read). The universal mitigation: **make the implicit contract explicit and CI-checkable**, and treat the identifier (column, key, route, tag, topic, token, header, binding) as a versioned API.
 ## The two categories
 | Category | Sourced from | Examples |
-|---|---|---|
+| --- | --- | --- |
 | **technology** | stack detection (`package.json` + lockfile + source) | db-schema, wire-response-envelope, store-shape, edge-binding |
-| **domain** | the product's information architecture (ADRs, doctrine, contracts pkg) — *not* stack detection | the entity model + topology, tenancy |
+| **domain** | the product's information architecture (ADRs, doctrine, contracts pkg) — _not_ stack detection | the entity model + topology, tenancy |
-The **domain** boundaries are stack-independent and the most catastrophic when
-broken; they come from the IA, not from `package.json`. Everything else is
-**technology** — detected from the deps and source.
+The **domain** boundaries are stack-independent and the most catastrophic when broken; they come from the IA, not from `package.json`. Everything else is **technology** — detected from the deps and source.
 ## `point` vs `transcribe` — the doc-mode
-Each boundary type carries a **doc-mode** that decides how its file records the
-shape:
+Each boundary type carries a **doc-mode** that decides how its file records the shape:
-- **`point`** — *self-locating* shapes a reader finds unaided: a DB schema lives
-  in `schema.prisma`; routes in the router file. Record a **pointer
-  (`file:line`) + invariants + safe-change checklist**. Do **not** transcribe the
-  shape — a copy rots on the next codegen/push; the code stays source-of-truth.
-- **`transcribe`** — *synthesized* contracts with no single code home: the
-  composed Redux store tree (spread across slices), the API response envelope (a
-  convention), the IA topology, tenancy. Transcribe these canonically into the
-  boundary file; feature docs own only their slice and link up.
+- **`point`** — _self-locating_ shapes a reader finds unaided: a DB schema lives in `schema.prisma`; routes in the router file. Record a **pointer (`file:line`) + invariants + safe-change checklist**. Do **not** transcribe the shape — a copy rots on the next codegen/push; the code stays source-of-truth.
+- **`transcribe`** — _synthesized_ contracts with no single code home: the composed Redux store tree (spread across slices), the API response envelope (a convention), the IA topology, tenancy. Transcribe these canonically into the boundary file; feature docs own only their slice and link up.
-Docs never outrank code. For `point` boundaries you mirror with `file:line`, you
-do not fork.
+Docs never outrank code. For `point` boundaries you mirror with `file:line`, you do not fork.
 ## Greenfield / pre-code boundaries
-When `generate` runs on a repo whose contract is **decided but has no code yet**
-(greenfield-after-brainstorm: ADRs/domain-model exist, modules aren't scaffolded),
-a `point` boundary has no `file:line` to mirror — but the boundary is real and the
-conventions are decided. Don't skip it and don't fabricate a pointer. Instead:
-- **Record the decided conventions inline** (the invariants + safe-change essentials
-  the ADRs/domain-model settle), the same content a transcribed shape would carry.
-- **Carry a planned pointer** to where the canonical source *will* land —
-  `planned packages/api/src/db/schema.ts` — so the pointer converts to a real
-  `file:line` when the module lands (a `create`/update refreshes it).
-- **Mark it `point*`** in the index (a `transcribe` boundary whose canonical source
-  is likewise pre-code is `transcribe*`) — the `*` reads against an index footnote:
-  *"point-mode boundary whose pointer lands at implementation — converts to (or
-  gains) a `file:line` pointer when the module lands."*
-- The last safe-change checklist item is "replace the planned pointer with the real
-  `file:line` once code lands."
-A safe-change item that hinges on an **unresolved decision** links to its open-question
-or ADR destination rather than asserting a resolution (kb.md: link, don't fabricate).
-The index also carries a **Skipped (premature for a pre-code repo)** block: boundary
-types not yet exhibited, one line each on why (e.g. *"workspace-package-graph —
-packages not scaffolded; add at scaffold time"*). See the index spec below.
+When `generate` runs on a repo whose contract is **decided but has no code yet** (greenfield-after-brainstorm: ADRs/domain-model exist, modules aren't scaffolded), a `point` boundary has no `file:line` to mirror — but the boundary is real and the conventions are decided. Don't skip it and don't fabricate a pointer. Instead:
+- **Record the decided conventions inline** (the invariants + safe-change essentials the ADRs/domain-model settle), the same content a transcribed shape would carry.
+- **Carry a planned pointer** to where the canonical source _will_ land — `planned packages/api/src/db/schema.ts` — so the pointer converts to a real `file:line` when the module lands (a `create`/update refreshes it).
+- **Mark it `point*`** in the index (a `transcribe` boundary whose canonical source is likewise pre-code is `transcribe*`) — the `*` reads against an index footnote: _"point-mode boundary whose pointer lands at implementation — converts to (or gains) a `file:line` pointer when the module lands."_
+- The last safe-change checklist item is "replace the planned pointer with the real `file:line` once code lands."
+A safe-change item that hinges on an **unresolved decision** links to its open-question or ADR destination rather than asserting a resolution (kb.md: link, don't fabricate).
+The index also carries a **Skipped (premature for a pre-code repo)** block: boundary types not yet exhibited, one line each on why (e.g. _"workspace-package-graph — packages not scaffolded; add at scaffold time"_). See the index spec below.
 ## Boundary file anatomy
-Every file the skill writes to `docs/boundaries/` follows this shape — the format
-that `check` and `init` parse:
+Every file the skill writes to `docs/boundaries/` follows this shape — the format that `check` and `init` parse:
 ```markdown
 # <Boundary name>
@@ -96,21 +55,24 @@ that `check` and `init` parse:
 **Bounds.** <the two sides of this contract — two modules, two layers (app↔DB, render↔hydrate, producer↔consumer), or a module↔external-system>
 ## Shape
 <transcribed contract, OR a pointer: `packages/.../schema.ts:NN` with one-line orientation>
 ## Invariants
 <what must hold>
 ## Blast radius
 <what breaks, and where, if violated>
 ## Safe-change checklist
 - [ ] <step>
 - [ ] <step>
 ```
-`docs/boundaries/README.md` is the index. Its table is one row per boundary with a
-**doc-mode column**, so the fold/skip decisions are auditable from the index alone:
+`docs/boundaries/README.md` is the index. Its table is one row per boundary with a **doc-mode column**, so the fold/skip decisions are auditable from the index alone:
 ```markdown
 | Boundary | Type | Severity | Doc-mode | Bounds (summary) |
@@ -118,603 +80,711 @@ that `check` and `init` parse:
 Below the table, three standing blocks:
-- **Active technology packs** — which packs (persistence, wire, auth, async, config,
-  …) the repo exhibits.
-- **Folds applied** — which catalog types collapsed into which file, surfacing the
-  per-entry fold-notes (below) as a ledger: e.g. *"orm-mapping/relations/enums/indexes
-  → db-schema · error-envelope/status-codes → wire-contracts."*
-- **Skipped** — types deliberately omitted, one line each on why (not exhibited, or
-  premature for a pre-code repo: *"workspace-package-graph — packages not scaffolded;
-  add at scaffold time"*).
-If any boundary is pre-code (`point*`/`transcribe*`), add the footnote: *"\* point-mode
-boundary whose pointer lands at implementation — converts to (or gains) a `file:line`
-pointer when the module lands."*
-**Name the bounding code units** (paths /
-package names) in every `Bounds` line — the distinct vertices named across all
-`Bounds` lines are the **module-discovery feed** `harness-manager` reads to
-propose modules, so name them precisely. A `Bounds` line is not restricted to two
-modules: it may name two **layers** within one module (app↔DB, render↔hydrate,
-producer↔consumer) or a module and an **external system** — so a flat /
-single-module repo still has real boundaries to file (as the intro states).
-**The clustering key — a convergence heuristic, not a hard count:** *one boundary
-file per (source-of-truth × doc-mode)*. Types that point at the same
-source-of-truth in the same doc-mode collapse into one file — all persistence
-types reading one relational schema fold into the `db-schema` file; split only
-where the source-of-truth or the doc-mode differs (a `transcribe` shape over the
-same schema, or a different store). Each catalog entry below carries a fold note:
-**Folds into `x`** (this type lands in `x`'s file), **Canonical home** (this type
-*is* the file others fold into), or **Own home** (a standalone source-of-truth ×
-doc-mode). Two `generate` runs converge on the same file set only where this
-fold-map names the home — where it doesn't, the count is a judgment call, not a
-guarantee.
+- **Active technology packs** — which packs (persistence, wire, auth, async, config, …) the repo exhibits.
+- **Folds applied** — which catalog types collapsed into which file, surfacing the per-entry fold-notes (below) as a ledger: e.g. _"orm-mapping/relations/enums/indexes → db-schema · error-envelope/status-codes → wire-contracts."_
+- **Skipped** — types deliberately omitted, one line each on why (not exhibited, or premature for a pre-code repo: _"workspace-package-graph — packages not scaffolded; add at scaffold time"_).
+If any boundary is pre-code (`point*`/`transcribe*`), add the footnote: _"\* point-mode boundary whose pointer lands at implementation — converts to (or gains) a `file:line` pointer when the module lands."_
+**Name the bounding code units** (paths / package names) in every `Bounds` line — the distinct vertices named across all `Bounds` lines are the **module-discovery feed** `harness-manager` reads to propose modules, so name them precisely. A `Bounds` line is not restricted to two modules: it may name two **layers** within one module (app↔DB, render↔hydrate, producer↔consumer) or a module and an **external system** — so a flat / single-module repo still has real boundaries to file (as the intro states).
+**The clustering key — a convergence heuristic, not a hard count:** _one boundary file per (source-of-truth × doc-mode)_. Types that point at the same source-of-truth in the same doc-mode collapse into one file — all persistence types reading one relational schema fold into the `db-schema` file; split only where the source-of-truth or the doc-mode differs (a `transcribe` shape over the same schema, or a different store). Each catalog entry below carries a fold note: **Folds into `x`** (this type lands in `x`'s file), **Canonical home** (this type _is_ the file others fold into), or **Own home** (a standalone source-of-truth × doc-mode). Two `generate` runs converge on the same file set only where this fold-map names the home — where it doesn't, the count is a judgment call, not a guarantee.
 ## Severity is load-bearing
-Severity (`CRITICAL` / `HIGH` / `MED` / `LOW`) sets `check`-mode review depth and
-`init`-mode scan priority. Each entry below carries a default; adjust from the
-concrete repo + project memory. The pattern that holds across all categories:
-**CRITICAL belongs to shared, single-source, persisted, or trust-crossing
-contracts** (the IA model, db-schema, the wire envelope, auth/tenancy, event
-schemas, secrets, federation/remotes) — the ones touched by everything or that
-break *historical/in-flight* state, not just live traffic.
+Severity (`CRITICAL` / `HIGH` / `MED` / `LOW`) sets `check`-mode review depth and `init`-mode scan priority. Each entry below carries a default; adjust from the concrete repo + project memory. The pattern that holds across all categories: **CRITICAL belongs to shared, single-source, persisted, or trust-crossing contracts** (the IA model, db-schema, the wire envelope, auth/tenancy, event schemas, secrets, federation/remotes) — the ones touched by everything or that break _historical/in-flight_ state, not just live traffic.
-The default is the type's **intrinsic** severity: the skill may **down-adjust** a
-single type with a reason logged in `docs/memory/boundary.md`, but there is **no
-relative rank and no up-or-down quota** across the repo's boundary set — three
-genuine CRITICALs in a micro repo is correct signal, not over-inflation to be
-capped.
+The default is the type's **intrinsic** severity: the skill may **down-adjust** a single type with a reason logged in `docs/memory/boundary.md`, but there is **no relative rank and no up-or-down quota** across the repo's boundary set — three genuine CRITICALs in a micro repo is correct signal, not over-inflation to be capped.
 ---
 # The Catalog
-Organized by the seven boundary categories. Each entry: **type-name —
-SEVERITY · doc-mode**, then what it is · where it appears · what breaks · how to
-detect · the safe-change essentials. Only instantiate the types the detected
-stack/IA actually exhibits; `log()` what you skip and why.
+Organized by the seven boundary categories. Each entry: **type-name — SEVERITY · doc-mode**, then what it is · where it appears · what breaks · how to detect · the safe-change essentials. Only instantiate the types the detected stack/IA actually exhibits; `log()` what you skip and why.
 ---
 ## 0 · DOMAIN (stack-independent — sourced from the IA, not `package.json`)
 #### `information-architecture` — CRITICAL · transcribe
-The entity model + topology (e.g. Brief→Plan→Persona→Audience→Match→Campaign→Run; service planes). **Where:** synthesized from ADRs / module pillars / a `@org/contracts` package — never `package.json`. **Breaks:** re-relating or renaming an entity ripples across *every* module, migration, and wire type. **Detect:** `docs/architecture/` (domain-model, ADRs), `docs/modules/*/pillars/`, a contracts package, `schema.ts`/`models.py` entity defs. **Safe-change:** map every consumer before re-relating; coordinate migrations + wire types + selectors in one change. *(Own home — the IA model is its own transcribed source-of-truth; never folds into a technology file.)* *The flagship domain boundary.*
+The entity model + topology (e.g. Brief→Plan→Persona→Audience→Match→Campaign→Run; service planes). **Where:** synthesized from ADRs / module pillars / a `@org/contracts` package — never `package.json`. **Breaks:** re-relating or renaming an entity ripples across _every_ module, migration, and wire type. **Detect:** `docs/architecture/` (domain-model, ADRs), `docs/modules/*/pillars/`, a contracts package, `schema.ts`/`models.py` entity defs. **Safe-change:** map every consumer before re-relating; coordinate migrations + wire types + selectors in one change. _(Own home — the IA model is its own transcribed source-of-truth; never folds into a technology file.)_ _The flagship domain boundary._
 #### `tenancy` — CRITICAL · transcribe
-The invariant that every request carries a non-spoofable tenant identity and all data access is scoped to it across every layer. **Where:** `tenant_id`/`org_id` columns, subdomain/JWT-claim resolution, `SET LOCAL app.current_tenant`, Better Auth organization plugin. **Breaks:** resolving tenant from a request body (vs validated JWT/subdomain/session) → cross-tenant read; under transaction-pooled PgBouncer a non-`SET LOCAL` GUC leaks tenant context across pooled clients. **Detect:** `tenant_id`/`organizationId` columns, `SET LOCAL`/`set_config(...,true)`, tenant middleware, `req.body.tenantId` (red flag). **Safe-change:** resolve tenant only from non-spoofable sources; transaction-scoped GUCs under pooling; never trust a body tenant id; keep RLS as a backstop (see `row-level-security`). *(Own home — the cross-layer tenant-isolation invariant (`transcribe`); the DB-layer enforcement is auth `row-level-security` (with persistence `row-level-multi-tenancy` folded in).)*
+The invariant that every request carries a non-spoofable tenant identity and all data access is scoped to it across every layer. **Where:** `tenant_id`/`org_id` columns, subdomain/JWT-claim resolution, `SET LOCAL app.current_tenant`, Better Auth organization plugin. **Breaks:** resolving tenant from a request body (vs validated JWT/subdomain/session) → cross-tenant read; under transaction-pooled PgBouncer a non-`SET LOCAL` GUC leaks tenant context across pooled clients. **Detect:** `tenant_id`/`organizationId` columns, `SET LOCAL`/`set_config(...,true)`, tenant middleware, `req.body.tenantId` (red flag). **Safe-change:** resolve tenant only from non-spoofable sources; transaction-scoped GUCs under pooling; never trust a body tenant id; keep RLS as a backstop (see `row-level-security`). _(Own home — the cross-layer tenant-isolation invariant (`transcribe`); the DB-layer enforcement is auth `row-level-security` (with persistence `row-level-multi-tenancy` folded in).)_
 ---
 ## 1 · PERSISTENCE & DATA MODEL
 #### `db-schema` — CRITICAL · point
-Tables, columns, names, types, nullability, defaults physically in the relational DB. **Where:** Postgres 17/MySQL/SQLite via Prisma 7 (`schema.prisma`), Drizzle (`schema.ts`), TypeORM, raw DDL. **Breaks:** a renamed/dropped/retyped column breaks every query, ORM model, serializer, report; nullability changes break INSERTs; a narrowed type truncates/rejects existing data. **Detect:** `schema.prisma`, `schema.ts` (`pgTable`/`mysqlTable`), `entities/**` (`@Entity`/`@Column`), `migrations/**`, `CREATE TABLE`, `ALTER TABLE`, `@db.`. **Safe-change:** expand-then-contract (add nullable → backfill → switch reads → drop); never reuse a dropped column name with a new type in a release; update every reader (ORM, raw SQL, BI/ETL, replicas) in lockstep. *(Canonical home for the relational-schema × `point` cluster — `orm-model-mapping`, `foreign-key-and-relations`, `index-and-constraint`, `db-enum`, `db-view-and-stored-procedure` all fold in unless the repo splits one out.)*
+Tables, columns, names, types, nullability, defaults physically in the relational DB. **Where:** Postgres 17/MySQL/SQLite via Prisma 7 (`schema.prisma`), Drizzle (`schema.ts`), TypeORM, raw DDL. **Breaks:** a renamed/dropped/retyped column breaks every query, ORM model, serializer, report; nullability changes break INSERTs; a narrowed type truncates/rejects existing data. **Detect:** `schema.prisma`, `schema.ts` (`pgTable`/`mysqlTable`), `entities/**` (`@Entity`/`@Column`), `migrations/**`, `CREATE TABLE`, `ALTER TABLE`, `@db.`. **Safe-change:** expand-then-contract (add nullable → backfill → switch reads → drop); never reuse a dropped column name with a new type in a release; update every reader (ORM, raw SQL, BI/ETL, replicas) in lockstep. _(Canonical home for the relational-schema × `point` cluster — `orm-model-mapping`, `foreign-key-and-relations`, `index-and-constraint`, `db-enum`, `db-view-and-stored-procedure` all fold in unless the repo splits one out.)_
 #### `orm-model-mapping` — HIGH · point
-The mapping binding app objects/types to tables — the contract that the model still matches the live DB. **Where:** Prisma `model`/`@@map`, Drizzle table objects, TypeORM `@Entity`, SQLAlchemy, Ecto, generated clients. **Breaks:** DB and model drift independently; a wrong-typed column or stale `@@map` fails at runtime, not compile; the generated client lies to TS callers. **Detect:** ORM schema files, generated clients (`.prisma/client`, `drizzle/`), `@map(`, `@relation`, `prisma generate`, `drizzle-kit`. **Safe-change:** regenerate + recompile after every schema change; keep explicit column names in sync; run a drift check (`prisma migrate diff`, `drizzle-kit check`) in CI; treat the generated client as build output. *(Folds into `db-schema` — same relational-schema source-of-truth, same `point` doc-mode.)*
+The mapping binding app objects/types to tables — the contract that the model still matches the live DB. **Where:** Prisma `model`/`@@map`, Drizzle table objects, TypeORM `@Entity`, SQLAlchemy, Ecto, generated clients. **Breaks:** DB and model drift independently; a wrong-typed column or stale `@@map` fails at runtime, not compile; the generated client lies to TS callers. **Detect:** ORM schema files, generated clients (`.prisma/client`, `drizzle/`), `@map(`, `@relation`, `prisma generate`, `drizzle-kit`. **Safe-change:** regenerate + recompile after every schema change; keep explicit column names in sync; run a drift check (`prisma migrate diff`, `drizzle-kit check`) in CI; treat the generated client as build output. _(Folds into `db-schema` — same relational-schema source-of-truth, same `point` doc-mode.)_
 #### `db-migration` — CRITICAL · point
-The ordered, immutable history of DDL/DML transforming one schema version to the next. **Where:** Prisma Migrate, Drizzle Kit, Flyway, Liquibase, Alembic, Knex, Atlas. **Breaks:** editing an applied migration, a non-idempotent step, or a `db push` that bypasses history causes **drift** — the runner's recorded hash no longer matches the live schema and refuses (or applies partially). **Detect:** `prisma/migrations/**`, `drizzle/**`, `migrations/**`, `_prisma_migrations`/`schema_migrations` tables, checksum columns, `migrate deploy`. **Safe-change:** never edit an applied migration — add a new one; never mix `db push` with `migrate dev` on one DB; test forward against a prod-shaped snapshot; verify the from-hash before deploy. *(Own home — the migration history is a distinct source-of-truth from the live schema; do not fold into `db-schema`.)* *(This repo's doctrine: drop-&-push the declared schema locally; never author migration SQL — see project memory.)*
+The ordered, immutable history of DDL/DML transforming one schema version to the next. **Where:** Prisma Migrate, Drizzle Kit, Flyway, Liquibase, Alembic, Knex, Atlas. **Breaks:** editing an applied migration, a non-idempotent step, or a `db push` that bypasses history causes **drift** — the runner's recorded hash no longer matches the live schema and refuses (or applies partially). **Detect:** `prisma/migrations/**`, `drizzle/**`, `migrations/**`, `_prisma_migrations`/`schema_migrations` tables, checksum columns, `migrate deploy`. **Safe-change:** never edit an applied migration — add a new one; never mix `db push` with `migrate dev` on one DB; test forward against a prod-shaped snapshot; verify the from-hash before deploy. _(Own home — the migration history is a distinct source-of-truth from the live schema; do not fold into `db-schema`.)_ _(This repo's doctrine: drop-&-push the declared schema locally; never author migration SQL — see project memory.)_
 #### `foreign-key-and-relations` — HIGH · point
-Referential-integrity edges (FK constraints) + the ORM relations on top. **Where:** `REFERENCES … ON DELETE/UPDATE`, Prisma `@relation`, Drizzle `references()`, TypeORM `@ManyToOne`. **Breaks:** changing a cascade silently changes delete semantics — `ON DELETE CASCADE` wipes child rows; `RESTRICT` blocks assumed deletes; mismatched ORM cardinality returns wrong shapes. **Detect:** `REFERENCES`, `FOREIGN KEY`, `ON DELETE`, `@relation(`, `onDelete:`, `relations(`. **Safe-change:** audit every cascade's blast radius before changing; change DB FK + ORM relation together; clean orphans before adding an FK; index the FK column. *(Folds into `db-schema` — same relational-schema source-of-truth, same `point` doc-mode.)*
+Referential-integrity edges (FK constraints) + the ORM relations on top. **Where:** `REFERENCES … ON DELETE/UPDATE`, Prisma `@relation`, Drizzle `references()`, TypeORM `@ManyToOne`. **Breaks:** changing a cascade silently changes delete semantics — `ON DELETE CASCADE` wipes child rows; `RESTRICT` blocks assumed deletes; mismatched ORM cardinality returns wrong shapes. **Detect:** `REFERENCES`, `FOREIGN KEY`, `ON DELETE`, `@relation(`, `onDelete:`, `relations(`. **Safe-change:** audit every cascade's blast radius before changing; change DB FK + ORM relation together; clean orphans before adding an FK; index the FK column. _(Folds into `db-schema` — same relational-schema source-of-truth, same `point` doc-mode.)_
 #### `index-and-constraint` — HIGH · point
-Unique/check/exclusion/partial/composite indexes the app's correctness and latency depend on. **Where:** Postgres `CREATE UNIQUE INDEX`/`CHECK`/`EXCLUDE`, Prisma `@@unique`/`@@index`, Drizzle `uniqueIndex()`. **Breaks:** code relies on a unique constraint for upsert/idempotency (`ON CONFLICT`) — dropping it lets duplicates in; dropping a hot-query index is a silent latency cliff; composite column-order changes regress range/tenant filters. **Detect:** `CREATE INDEX`, `UNIQUE`, `CHECK (`, `@@unique(`, `ON CONFLICT`, `uniqueIndex(`, `WHERE` (partial). **Safe-change:** `CONCURRENTLY` to avoid locks; grep `ON CONFLICT`/`findUnique` before dropping a unique index; dedupe before adding UNIQUE; preserve leading-column order. *(Folds into `db-schema` — same relational-schema source-of-truth, same `point` doc-mode.)*
+Unique/check/exclusion/partial/composite indexes the app's correctness and latency depend on. **Where:** Postgres `CREATE UNIQUE INDEX`/`CHECK`/`EXCLUDE`, Prisma `@@unique`/`@@index`, Drizzle `uniqueIndex()`. **Breaks:** code relies on a unique constraint for upsert/idempotency (`ON CONFLICT`) — dropping it lets duplicates in; dropping a hot-query index is a silent latency cliff; composite column-order changes regress range/tenant filters. **Detect:** `CREATE INDEX`, `UNIQUE`, `CHECK (`, `@@unique(`, `ON CONFLICT`, `uniqueIndex(`, `WHERE` (partial). **Safe-change:** `CONCURRENTLY` to avoid locks; grep `ON CONFLICT`/`findUnique` before dropping a unique index; dedupe before adding UNIQUE; preserve leading-column order. _(Folds into `db-schema` — same relational-schema source-of-truth, same `point` doc-mode.)_
 #### `db-enum` — MED · point
-A closed value set enforced at DB level, mirrored in code. **Where:** Postgres `CREATE TYPE … AS ENUM`, Prisma `enum`, Drizzle `pgEnum`, MySQL `ENUM`. **Breaks:** Postgres can't remove an enum value and restricts adding inside a txn; app switch/exhaustiveness and the DB set drift — writing an unknown value throws, reading an unhandled one falls through. **Detect:** `CREATE TYPE`, `AS ENUM`, `enum {`, `pgEnum(`, TS unions mirroring DB enums. **Safe-change:** add values, never reorder/remove; add to DB before deploying code that writes it; keep the app union in sync and handle unknowns defensively. *(Folds into `db-schema` — same relational-schema source-of-truth, same `point` doc-mode.)*
+A closed value set enforced at DB level, mirrored in code. **Where:** Postgres `CREATE TYPE … AS ENUM`, Prisma `enum`, Drizzle `pgEnum`, MySQL `ENUM`. **Breaks:** Postgres can't remove an enum value and restricts adding inside a txn; app switch/exhaustiveness and the DB set drift — writing an unknown value throws, reading an unhandled one falls through. **Detect:** `CREATE TYPE`, `AS ENUM`, `enum {`, `pgEnum(`, TS unions mirroring DB enums. **Safe-change:** add values, never reorder/remove; add to DB before deploying code that writes it; keep the app union in sync and handle unknowns defensively. _(Folds into `db-schema` — same relational-schema source-of-truth, same `point` doc-mode.)_
 #### `jsonb-column-shape` — HIGH · transcribe
-The implicit structure of a JSON/JSONB column read/written by key path. **Where:** Postgres `jsonb`, MySQL `JSON`, Prisma `Json`, Drizzle `jsonb()`, validated (or not) by Zod at the edge. **Breaks:** the DB enforces *nothing* inside, so the contract lives entirely in code on both sides; a renamed inner key or nesting change breaks readers with no DDL, no migration, no compile error — and old rows keep the old shape forever. **Detect:** `jsonb`/`Json`, accessors `->`/`->>`/`#>`, `jsonb_path_query`, Zod schemas on JSON columns, GIN indexes. **Safe-change:** version the embedded shape (`_v`) and read all live versions; validate with Zod on write AND read; data-migrate old rows; index only after the shape is stable. *(Own home — same schema source-of-truth as `db-schema` but `transcribe` doc-mode (the shape lives only in code), so it splits into its own file.)*
+The implicit structure of a JSON/JSONB column read/written by key path. **Where:** Postgres `jsonb`, MySQL `JSON`, Prisma `Json`, Drizzle `jsonb()`, validated (or not) by Zod at the edge. **Breaks:** the DB enforces _nothing_ inside, so the contract lives entirely in code on both sides; a renamed inner key or nesting change breaks readers with no DDL, no migration, no compile error — and old rows keep the old shape forever. **Detect:** `jsonb`/`Json`, accessors `->`/`->>`/`#>`, `jsonb_path_query`, Zod schemas on JSON columns, GIN indexes. **Safe-change:** version the embedded shape (`_v`) and read all live versions; validate with Zod on write AND read; data-migrate old rows; index only after the shape is stable. _(Own home — same schema source-of-truth as `db-schema` but `transcribe` doc-mode (the shape lives only in code), so it splits into its own file.)_
 #### `fulltext-search-index` — MED · point
-Lexical search structures + their tokenization/config contract. **Where:** Postgres `tsvector`/`to_tsvector`/GIN, MySQL `FULLTEXT`, Elasticsearch/Meilisearch/Typesense mappings. **Breaks:** index-time config (language/stemming/weights) must match query-time or recall silently degrades; a config or stored-`tsvector` change needs a full reindex; queries against a stale index return wrong results with no error. **Detect:** `tsvector`, `to_tsvector(`, `plainto_tsquery`, `@@`, `setweight`, ES `analyzer`. **Safe-change:** keep index- and query-time config identical; reindex fully after any change; pin the language/dictionary explicitly. *(Own home — the lexical-index config is a distinct source-of-truth from the relational schema; do not fold into `db-schema`.)*
+Lexical search structures + their tokenization/config contract. **Where:** Postgres `tsvector`/`to_tsvector`/GIN, MySQL `FULLTEXT`, Elasticsearch/Meilisearch/Typesense mappings. **Breaks:** index-time config (language/stemming/weights) must match query-time or recall silently degrades; a config or stored-`tsvector` change needs a full reindex; queries against a stale index return wrong results with no error. **Detect:** `tsvector`, `to_tsvector(`, `plainto_tsquery`, `@@`, `setweight`, ES `analyzer`. **Safe-change:** keep index- and query-time config identical; reindex fully after any change; pin the language/dictionary explicitly. _(Own home — the lexical-index config is a distinct source-of-truth from the relational schema; do not fold into `db-schema`.)_
 #### `vector-search-index` — HIGH · point
-Embedding columns + their ANN index, where dimension, metric, and index type are a hard contract. **Where:** pgvector (`vector(N)`, HNSW, IVFFlat), Pinecone, Qdrant, Cloudflare Vectorize. **Breaks:** dimension is fixed per column and must match the embedding model — switching models breaks every insert; the **distance operator must match the index operator class** (`<->` L2 / `<=>` cosine / `<#>` IP) or Postgres silently seq-scans; pgvector caps at 2000 dims. **Detect:** `vector(`, `USING hnsw`/`ivfflat`, `vector_cosine_ops`/`_l2_ops`/`_ip_ops`, `<->`/`<=>`/`<#>`, `CREATE EXTENSION vector`, `embedding` columns. **Safe-change:** re-embed + reindex when changing model/dimension; match query operator to index operator class; store the embedding-model identity as provenance; mind the 2000-dim cap and `m`/`ef_construction`. *(Own home — the embedding/ANN-index contract is a distinct source-of-truth (and its IA/embedding-provenance facet can be CRITICAL); do not fold into `db-schema`.)* *(This repo: install pgvector in db-init so a from-scratch push succeeds — project memory.)*
+Embedding columns + their ANN index, where dimension, metric, and index type are a hard contract. **Where:** pgvector (`vector(N)`, HNSW, IVFFlat), Pinecone, Qdrant, Cloudflare Vectorize. **Breaks:** dimension is fixed per column and must match the embedding model — switching models breaks every insert; the **distance operator must match the index operator class** (`<->` L2 / `<=>` cosine / `<#>` IP) or Postgres silently seq-scans; pgvector caps at 2000 dims. **Detect:** `vector(`, `USING hnsw`/`ivfflat`, `vector_cosine_ops`/`_l2_ops`/`_ip_ops`, `<->`/`<=>`/`<#>`, `CREATE EXTENSION vector`, `embedding` columns. **Safe-change:** re-embed + reindex when changing model/dimension; match query operator to index operator class; store the embedding-model identity as provenance; mind the 2000-dim cap and `m`/`ef_construction`. _(Own home — the embedding/ANN-index contract is a distinct source-of-truth (and its IA/embedding-provenance facet can be CRITICAL); do not fold into `db-schema`.)_ _(This repo: install pgvector in db-init so a from-scratch push succeeds — project memory.)_
 #### `cache-key-schema` — MED · transcribe
-The naming convention, key structure, value serialization, and embedded version of cached entries. **Where:** Redis 7, Memcached, Cloudflare KV, ioredis/node-redis, framework caches. **Breaks:** producer and consumer of a key are often different deploys — if the value serialization changes but the key doesn't, a new reader deserializes an old value and crashes/misreads; key-pattern changes orphan old keys. **Detect:** `redis.set(`/`get(`, `:`-delimited key builders, `cache:` prefixes, `JSON.stringify`/`msgpack` around cache, `EXPIRE`/`SETEX`, `:v{n}` in keys. **Safe-change:** bump a version segment when value shape changes (old keys miss and re-populate); make deserializers version-aware; always set a TTL; namespace hierarchically, invalidate by version bump not `KEYS` wildcards. *(Canonical home for the cache-store × `transcribe` cluster — `cache-ttl-and-consistency` folds in (the freshness facet of the same cache contract).)*
+The naming convention, key structure, value serialization, and embedded version of cached entries. **Where:** Redis 7, Memcached, Cloudflare KV, ioredis/node-redis, framework caches. **Breaks:** producer and consumer of a key are often different deploys — if the value serialization changes but the key doesn't, a new reader deserializes an old value and crashes/misreads; key-pattern changes orphan old keys. **Detect:** `redis.set(`/`get(`, `:`-delimited key builders, `cache:` prefixes, `JSON.stringify`/`msgpack` around cache, `EXPIRE`/`SETEX`, `:v{n}` in keys. **Safe-change:** bump a version segment when value shape changes (old keys miss and re-populate); make deserializers version-aware; always set a TTL; namespace hierarchically, invalidate by version bump not `KEYS` wildcards. _(Canonical home for the cache-store × `transcribe` cluster — `cache-ttl-and-consistency` folds in (the freshness facet of the same cache contract).)_
 #### `cache-ttl-and-consistency` — MED · transcribe
-The expiry/eviction + freshness contract — how stale is acceptable, when entries invalidate. **Where:** Redis TTL/`maxmemory-policy`, HTTP `Cache-Control`/`s-maxage`, Next.js `revalidate`/`tags`, write-through/-behind. **Breaks:** TTL/invalidation live on the writer; readers assume a freshness SLA — lowering TTL spikes DB load (stampede); raising it serves stale data; an eviction-policy change can evict keys assumed durable. **Detect:** `EXPIRE`/`SETEX`/`ttl:`, `maxmemory-policy`, `revalidate:`, `staleWhileRevalidate`, invalidation hooks on writes. **Safe-change:** coordinate TTL with the freshness expectation + origin capacity; add jitter to avoid synchronized expiry; invalidate on every source write; document durable vs evictable keys. *(Folds into `cache-key-schema` — same cache-store source-of-truth, same `transcribe` doc-mode.)*
+The expiry/eviction + freshness contract — how stale is acceptable, when entries invalidate. **Where:** Redis TTL/`maxmemory-policy`, HTTP `Cache-Control`/`s-maxage`, Next.js `revalidate`/`tags`, write-through/-behind. **Breaks:** TTL/invalidation live on the writer; readers assume a freshness SLA — lowering TTL spikes DB load (stampede); raising it serves stale data; an eviction-policy change can evict keys assumed durable. **Detect:** `EXPIRE`/`SETEX`/`ttl:`, `maxmemory-policy`, `revalidate:`, `staleWhileRevalidate`, invalidation hooks on writes. **Safe-change:** coordinate TTL with the freshness expectation + origin capacity; add jitter to avoid synchronized expiry; invalidate on every source write; document durable vs evictable keys. _(Folds into `cache-key-schema` — same cache-store source-of-truth, same `transcribe` doc-mode.)_
 #### `row-level-multi-tenancy` — CRITICAL · transcribe
-Data-isolation enforced at the row level (see domain `tenancy` for the cross-layer invariant; this is its DB-layer enforcement). **Where:** Postgres RLS (`CREATE POLICY`, `FORCE ROW LEVEL SECURITY`, `current_setting('app.tenant_id')`), `tenant_id` columns, schema/DB-per-tenant. **Breaks:** a new table without the tenant column or RLS policy is invisible until tenant A reads tenant B; RLS is silently bypassed by the table owner (without `FORCE`), `BYPASSRLS` roles, superusers, `SECURITY DEFINER` views. **Detect:** `CREATE POLICY`, `ENABLE/FORCE ROW LEVEL SECURITY`, `current_setting('app.`, `BYPASSRLS`, `tenant_id` columns. **Safe-change:** every new tenant-scoped table gets column + policy + `FORCE` in one change; never run app traffic as a `BYPASSRLS`/owner/superuser role; `SET LOCAL` under poolers; tenant_id as leading composite-index column; `security_invoker = true` views. *(Folds into auth `row-level-security` — same RLS-policy source-of-truth, same `transcribe` doc-mode; this is its persistence-layer view. Backstops domain `tenancy`.)*
+Data-isolation enforced at the row level (see domain `tenancy` for the cross-layer invariant; this is its DB-layer enforcement). **Where:** Postgres RLS (`CREATE POLICY`, `FORCE ROW LEVEL SECURITY`, `current_setting('app.tenant_id')`), `tenant_id` columns, schema/DB-per-tenant. **Breaks:** a new table without the tenant column or RLS policy is invisible until tenant A reads tenant B; RLS is silently bypassed by the table owner (without `FORCE`), `BYPASSRLS` roles, superusers, `SECURITY DEFINER` views. **Detect:** `CREATE POLICY`, `ENABLE/FORCE ROW LEVEL SECURITY`, `current_setting('app.`, `BYPASSRLS`, `tenant_id` columns. **Safe-change:** every new tenant-scoped table gets column + policy + `FORCE` in one change; never run app traffic as a `BYPASSRLS`/owner/superuser role; `SET LOCAL` under poolers; tenant_id as leading composite-index column; `security_invoker = true` views. _(Folds into auth `row-level-security` — same RLS-policy source-of-truth, same `transcribe` doc-mode; this is its persistence-layer view. Backstops domain `tenancy`.)_
 #### `soft-delete-convention` — HIGH · transcribe
-"Deleted" rows are flagged, not removed, and every query must respect the flag. **Where:** `deleted_at` columns, Prisma soft-delete extensions, TypeORM `@DeleteDateColumn`, Sequelize `paranoid`, Rails `acts_as_paranoid`. **Breaks:** the "don't show deleted" rule is in app/ORM scope filters, not the DB — a new query/raw SQL/report that forgets it resurrects deleted rows; a UNIQUE constraint collides with a soft-deleted row and blocks legit re-creation. **Detect:** `deleted_at`/`is_deleted`/`archived_at`, `WHERE deleted_at IS NULL`, `paranoid`, global ORM scopes, partial unique indexes. **Safe-change:** enforce the filter centrally (global scope/middleware); make unique constraints partial (`WHERE deleted_at IS NULL`); audit raw SQL/reports; define hard-purge retention. *(Own home — the "respect the flag" rule is a transcribed app/ORM-scope convention, not the relational schema; do not fold into `db-schema`.)*
+"Deleted" rows are flagged, not removed, and every query must respect the flag. **Where:** `deleted_at` columns, Prisma soft-delete extensions, TypeORM `@DeleteDateColumn`, Sequelize `paranoid`, Rails `acts_as_paranoid`. **Breaks:** the "don't show deleted" rule is in app/ORM scope filters, not the DB — a new query/raw SQL/report that forgets it resurrects deleted rows; a UNIQUE constraint collides with a soft-deleted row and blocks legit re-creation. **Detect:** `deleted_at`/`is_deleted`/`archived_at`, `WHERE deleted_at IS NULL`, `paranoid`, global ORM scopes, partial unique indexes. **Safe-change:** enforce the filter centrally (global scope/middleware); make unique constraints partial (`WHERE deleted_at IS NULL`); audit raw SQL/reports; define hard-purge retention. _(Own home — the "respect the flag" rule is a transcribed app/ORM-scope convention, not the relational schema; do not fold into `db-schema`.)_
 #### `audit-and-event-sourcing-tables` — HIGH · point
-Append-only stores of facts/changes — audit logs, event stores, the outbox — where the event schema is a long-lived contract with future readers. **Where:** EventStoreDB, Marten, Axon, Kafka + outbox tables, `audit_log`/`events` tables, bitemporal tables. **Breaks:** events are immutable and replayed — a projector built today must understand events written years ago; changing an event's payload breaks replay/projection rebuilds; you can never migrate past events, only version them. **Detect:** `events`/`event_store`/`outbox`/`audit_log` tables, `event_type`/`aggregate_id`/`sequence`/`version` columns, `append`/`replay`/`project`, upcasters, Debezium. **Safe-change:** version event types + add upcasters; never mutate/delete history; keep projectors tolerant of all versions; test a full replay; audit columns are compliance-frozen (additive only). *(Own home — the append-only event/audit store is a distinct source-of-truth from the live schema; do not fold into `db-schema`. Cross-ref async `event-schema` for the event wire-shape.)*
+Append-only stores of facts/changes — audit logs, event stores, the outbox — where the event schema is a long-lived contract with future readers. **Where:** EventStoreDB, Marten, Axon, Kafka + outbox tables, `audit_log`/`events` tables, bitemporal tables. **Breaks:** events are immutable and replayed — a projector built today must understand events written years ago; changing an event's payload breaks replay/projection rebuilds; you can never migrate past events, only version them. **Detect:** `events`/`event_store`/`outbox`/`audit_log` tables, `event_type`/`aggregate_id`/`sequence`/`version` columns, `append`/`replay`/`project`, upcasters, Debezium. **Safe-change:** version event types + add upcasters; never mutate/delete history; keep projectors tolerant of all versions; test a full replay; audit columns are compliance-frozen (additive only). _(Own home — the append-only event/audit store is a distinct source-of-truth from the live schema; do not fold into `db-schema`. Cross-ref async `event-schema` for the event wire-shape.)_
 #### `read-model-projection-and-materialized-view` — MED · point
-Denormalized derived stores — materialized views, CQRS read models, rollups — contracted between the refresher and the reader. **Where:** Postgres `MATERIALIZED VIEW` (+ `REFRESH … CONCURRENTLY`), CQRS read models, dbt models, D1 derived tables. **Breaks:** two contracts — the source schema it's derived from (a source column change breaks the refresh) and the read-model schema consumers query; `CONCURRENTLY` needs a unique index; stale projections serve wrong data with no error. **Detect:** `CREATE/REFRESH MATERIALIZED VIEW`, projection handlers, `*_summary`/`*_read_model` tables, dbt `models/`, refresh jobs. **Safe-change:** update the view + rebuild when a source column changes; keep a unique index for `CONCURRENTLY`; monitor refresh failures; version read-model schema separately. *(Own home — the derived/read-model store is a distinct source-of-truth from the base schema it projects; do not fold into `db-schema`.)*
+Denormalized derived stores — materialized views, CQRS read models, rollups — contracted between the refresher and the reader. **Where:** Postgres `MATERIALIZED VIEW` (+ `REFRESH … CONCURRENTLY`), CQRS read models, dbt models, D1 derived tables. **Breaks:** two contracts — the source schema it's derived from (a source column change breaks the refresh) and the read-model schema consumers query; `CONCURRENTLY` needs a unique index; stale projections serve wrong data with no error. **Detect:** `CREATE/REFRESH MATERIALIZED VIEW`, projection handlers, `*_summary`/`*_read_model` tables, dbt `models/`, refresh jobs. **Safe-change:** update the view + rebuild when a source column changes; keep a unique index for `CONCURRENTLY`; monitor refresh failures; version read-model schema separately. _(Own home — the derived/read-model store is a distinct source-of-truth from the base schema it projects; do not fold into `db-schema`.)_
 #### `db-view-and-stored-procedure` — HIGH · point
-Server-side DB logic — views, procedures/functions, triggers — that code and other objects depend on as an interface. **Where:** Postgres `CREATE VIEW`/`FUNCTION`/`TRIGGER` (PL/pgSQL), Supabase RPC, `SECURITY DEFINER`. **Breaks:** a proc is an API with a signature; a trigger embeds invisible business logic that fires on INSERT; `SECURITY DEFINER` silently bypasses RLS; changing a signature breaks callers; dropping a selected column breaks the view. **Detect:** `CREATE VIEW`/`OR REPLACE FUNCTION`/`TRIGGER`, `LANGUAGE plpgsql`, `SECURITY DEFINER`, `supabase.rpc(`, `BEFORE/AFTER INSERT`. **Safe-change:** treat proc signatures as public API; recreate dependent views on column change; audit triggers for side effects; set `security_invoker` deliberately so RLS holds. *(Folds into `db-schema` — same relational-DDL source-of-truth, same `point` doc-mode; split out only if procs/triggers carry enough business logic to warrant their own file.)*
+Server-side DB logic — views, procedures/functions, triggers — that code and other objects depend on as an interface. **Where:** Postgres `CREATE VIEW`/`FUNCTION`/`TRIGGER` (PL/pgSQL), Supabase RPC, `SECURITY DEFINER`. **Breaks:** a proc is an API with a signature; a trigger embeds invisible business logic that fires on INSERT; `SECURITY DEFINER` silently bypasses RLS; changing a signature breaks callers; dropping a selected column breaks the view. **Detect:** `CREATE VIEW`/`OR REPLACE FUNCTION`/`TRIGGER`, `LANGUAGE plpgsql`, `SECURITY DEFINER`, `supabase.rpc(`, `BEFORE/AFTER INSERT`. **Safe-change:** treat proc signatures as public API; recreate dependent views on column change; audit triggers for side effects; set `security_invoker` deliberately so RLS holds. _(Folds into `db-schema` — same relational-DDL source-of-truth, same `point` doc-mode; split out only if procs/triggers carry enough business logic to warrant their own file.)_
 #### `blob-object-storage-key-convention` — MED · point
-The path/key scheme + metadata contract for object storage, plus the DB pointers to it. **Where:** S3, GCS, Azure Blob, Cloudflare R2, MinIO; `object_key`/`storage_path` columns; presigned URLs. **Breaks:** the key scheme is a contract among uploader, downloader, lifecycle rules, and DB rows — changing the template orphans existing objects; a prefix change breaks lifecycle/CDN paths; there's no FK between DB and bucket. **Detect:** `s3.putObject`/`getSignedUrl`, `r2.put`, key-template builders, `object_key`/`file_url` columns, `${tenant}/${id}/` patterns, lifecycle config. **Safe-change:** never change the template for existing objects without a copy/re-point migration; store the full key in the DB; coordinate prefix changes with lifecycle + CDN; namespace by tenant. *(Own home — the object-store key scheme is a distinct source-of-truth from the relational schema; do not fold into `db-schema`.)*
+The path/key scheme + metadata contract for object storage, plus the DB pointers to it. **Where:** S3, GCS, Azure Blob, Cloudflare R2, MinIO; `object_key`/`storage_path` columns; presigned URLs. **Breaks:** the key scheme is a contract among uploader, downloader, lifecycle rules, and DB rows — changing the template orphans existing objects; a prefix change breaks lifecycle/CDN paths; there's no FK between DB and bucket. **Detect:** `s3.putObject`/`getSignedUrl`, `r2.put`, key-template builders, `object_key`/`file_url` columns, `${tenant}/${id}/` patterns, lifecycle config. **Safe-change:** never change the template for existing objects without a copy/re-point migration; store the full key in the DB; coordinate prefix changes with lifecycle + CDN; namespace by tenant. _(Own home — the object-store key scheme is a distinct source-of-truth from the relational schema; do not fold into `db-schema`.)_
 #### `connection-pool-and-isolation-level` — HIGH · point
-Assumptions about pooling mode, transaction isolation, statement timeouts, and session-state lifetime. **Where:** PgBouncer/Pgpool (session/transaction/statement pooling), `pg`/Prisma/Drizzle pool config, RDS Proxy, `SET TRANSACTION ISOLATION LEVEL`. **Breaks:** code relying on session state (`SET`, prepared statements, advisory locks, `SET ROLE`, RLS context) breaks under transaction-mode pooling where a "session" is shared across clients; lowering from SERIALIZABLE introduces write-skew/phantoms under concurrency. **Detect:** `pgbouncer`, `pool_mode = transaction`, `?pgbouncer=true`, `SET TRANSACTION ISOLATION`, `SET LOCAL`, `pg_advisory_lock`, `statement_timeout`. **Safe-change:** `SET LOCAL` only + disable server-side prepared statements under transaction pooling; don't lower isolation below the app's invariants (retry on serialization failure); set explicit timeouts; size the pool against `max_connections` + pooler mode. *(Own home — the pooler/driver config is a distinct source-of-truth from the schema; do not fold into `db-schema`.)*
+Assumptions about pooling mode, transaction isolation, statement timeouts, and session-state lifetime. **Where:** PgBouncer/Pgpool (session/transaction/statement pooling), `pg`/Prisma/Drizzle pool config, RDS Proxy, `SET TRANSACTION ISOLATION LEVEL`. **Breaks:** code relying on session state (`SET`, prepared statements, advisory locks, `SET ROLE`, RLS context) breaks under transaction-mode pooling where a "session" is shared across clients; lowering from SERIALIZABLE introduces write-skew/phantoms under concurrency. **Detect:** `pgbouncer`, `pool_mode = transaction`, `?pgbouncer=true`, `SET TRANSACTION ISOLATION`, `SET LOCAL`, `pg_advisory_lock`, `statement_timeout`. **Safe-change:** `SET LOCAL` only + disable server-side prepared statements under transaction pooling; don't lower isolation below the app's invariants (retry on serialization failure); set explicit timeouts; size the pool against `max_connections` + pooler mode. _(Own home — the pooler/driver config is a distinct source-of-truth from the schema; do not fold into `db-schema`.)_
 #### `db-extension-and-collation` — HIGH · point
-DB-level dependencies — installed extensions, server encoding, `LC_COLLATE`/ICU — that objects and sort/compare semantics rely on. **Where:** Postgres `CREATE EXTENSION` (`pgvector`, `pgcrypto`, `uuid-ossp`, `postgis`, `citext`), collations, `COLLATE`, init scripts. **Breaks:** a schema object needs its extension installed first (a from-scratch deploy fails otherwise); a collation-version change (glibc/ICU upgrade) silently changes string sort order, corrupting B-tree index ordering → wrong results / "duplicate" unique-index rows. **Detect:** `CREATE EXTENSION`, `db-init`/`init.sql`, `shared_preload_libraries`, `COLLATE`, `citext`, `pg_trgm`. **Safe-change:** install extensions in DB-init before the migration that uses them; reindex collation-dependent indexes after any ICU/glibc change; pin encoding/collation across primary/replicas/CI. *(Own home — DB-init / cluster-level deps are a distinct source-of-truth from the schema objects that rely on them; do not fold into `db-schema`.)*
+DB-level dependencies — installed extensions, server encoding, `LC_COLLATE`/ICU — that objects and sort/compare semantics rely on. **Where:** Postgres `CREATE EXTENSION` (`pgvector`, `pgcrypto`, `uuid-ossp`, `postgis`, `citext`), collations, `COLLATE`, init scripts. **Breaks:** a schema object needs its extension installed first (a from-scratch deploy fails otherwise); a collation-version change (glibc/ICU upgrade) silently changes string sort order, corrupting B-tree index ordering → wrong results / "duplicate" unique-index rows. **Detect:** `CREATE EXTENSION`, `db-init`/`init.sql`, `shared_preload_libraries`, `COLLATE`, `citext`, `pg_trgm`. **Safe-change:** install extensions in DB-init before the migration that uses them; reindex collation-dependent indexes after any ICU/glibc change; pin encoding/collation across primary/replicas/CI. _(Own home — DB-init / cluster-level deps are a distinct source-of-truth from the schema objects that rely on them; do not fold into `db-schema`.)_
 #### `auth-and-framework-managed-tables` — HIGH · point
-Tables whose schema is owned by a framework/library, not your app migrations — and which your schema tooling can clobber. **Where:** Better Auth tables (`user`, `session`, `account`, `verification`), Auth.js adapter tables, Lucia, Temporal/job-queue tables. **Breaks:** two migration authorities target one DB — `drizzle-kit push`/`prisma migrate` can **drop the Better Auth tables**, breaking login until the library's own migration is re-run; the library reads its tables by exact column names, so an app-side rename breaks auth. **Detect:** `better-auth`, `@better-auth/cli migrate`, `auth.ts`, `user`/`session`/`account` tables, two tools writing one DB. **Safe-change:** after any push/migrate touching the shared DB, re-run `@better-auth/cli migrate`; keep framework tables reconciled with (or out of) your ORM source; never rename framework table/column names; verify login after every auth-table change. *(Own home — the framework library owns this schema authority, a distinct source-of-truth your app migrations must not clobber; do not fold into `db-schema`. Cross-ref auth `auth-contract` for the session-table shape.)* *(This repo's exact failure mode — project memory.)*
+Tables whose schema is owned by a framework/library, not your app migrations — and which your schema tooling can clobber. **Where:** Better Auth tables (`user`, `session`, `account`, `verification`), Auth.js adapter tables, Lucia, Temporal/job-queue tables. **Breaks:** two migration authorities target one DB — `drizzle-kit push`/`prisma migrate` can **drop the Better Auth tables**, breaking login until the library's own migration is re-run; the library reads its tables by exact column names, so an app-side rename breaks auth. **Detect:** `better-auth`, `@better-auth/cli migrate`, `auth.ts`, `user`/`session`/`account` tables, two tools writing one DB. **Safe-change:** after any push/migrate touching the shared DB, re-run `@better-auth/cli migrate`; keep framework tables reconciled with (or out of) your ORM source; never rename framework table/column names; verify login after every auth-table change. _(Own home — the framework library owns this schema authority, a distinct source-of-truth your app migrations must not clobber; do not fold into `db-schema`. Cross-ref auth `auth-contract` for the session-table shape.)_ _(This repo's exact failure mode — project memory.)_
 ---
 ## 2 · API & WIRE / SYNCHRONOUS CONTRACTS
 #### `wire-response-envelope` — CRITICAL · transcribe
-The top-level shape wrapping every response body (e.g. `{status, message, data}`), independent of the per-endpoint payload. **Where:** Express 5 REST (this repo's `{status, message, data}`), Axios interceptors that unwrap `.data.data`. **Breaks:** every client unwraps identically — renaming `data`, flipping `status`'s type (1/0 vs boolean), or moving errors out of the envelope breaks every consumer that destructures it. **Detect:** `res.json({ status`, shared response builders (`sendSuccess`, `apiResponse.js`), client interceptors reading `response.data.data`. **Safe-change:** change the envelope in a versioned namespace, never in place; update the shared builder + client interceptor together; keep `status` semantics stable. *(Canonical home for the REST-wire-convention × `transcribe` cluster — `error-envelope-and-error-codes` and `http-status-code-convention` fold in (the failure-shape and status-mapping facets of the same envelope contract).)* *(This repo's documented envelope — `.claude/rules/general.md`.)*
+The top-level shape wrapping every response body (e.g. `{status, message, data}`), independent of the per-endpoint payload. **Where:** Express 5 REST (this repo's `{status, message, data}`), Axios interceptors that unwrap `.data.data`. **Breaks:** every client unwraps identically — renaming `data`, flipping `status`'s type (1/0 vs boolean), or moving errors out of the envelope breaks every consumer that destructures it. **Detect:** `res.json({ status`, shared response builders (`sendSuccess`, `apiResponse.js`), client interceptors reading `response.data.data`. **Safe-change:** change the envelope in a versioned namespace, never in place; update the shared builder + client interceptor together; keep `status` semantics stable. _(Canonical home for the REST-wire-convention × `transcribe` cluster — `error-envelope-and-error-codes` and `http-status-code-convention` fold in (the failure-shape and status-mapping facets of the same envelope contract).)_ _(This repo's documented envelope — `.claude/rules/general.md`.)_
 #### `error-envelope-and-error-codes` — HIGH · transcribe
-The structured failure shape + stable code taxonomy (`{status:0,…}`, RFC 9457 `problem+json`, `{error:{code}}`). **Where:** Express centralized error handler, gRPC `google.rpc.Status`, GraphQL `extensions.code`, Stripe-style `error.code`. **Breaks:** clients branch on `error.code` — renaming a code, changing its HTTP status, or restructuring `details` breaks retry logic, user messages, and alerts, silently (transport still "succeeds"). **Detect:** the last `app.use((err,req,res,next)` handler, error-code enums, `extensions.code`, `problem+json`. **Safe-change:** treat codes as append-only; keep the status↔code mapping stable; version alongside the success envelope; document every code consumers branch on. *(Folds into `wire-response-envelope` — same REST-wire-convention source-of-truth, same `transcribe` doc-mode; the failure facet of the one envelope contract.)*
+The structured failure shape + stable code taxonomy (`{status:0,…}`, RFC 9457 `problem+json`, `{error:{code}}`). **Where:** Express centralized error handler, gRPC `google.rpc.Status`, GraphQL `extensions.code`, Stripe-style `error.code`. **Breaks:** clients branch on `error.code` — renaming a code, changing its HTTP status, or restructuring `details` breaks retry logic, user messages, and alerts, silently (transport still "succeeds"). **Detect:** the last `app.use((err,req,res,next)` handler, error-code enums, `extensions.code`, `problem+json`. **Safe-change:** treat codes as append-only; keep the status↔code mapping stable; version alongside the success envelope; document every code consumers branch on. _(Folds into `wire-response-envelope` — same REST-wire-convention source-of-truth, same `transcribe` doc-mode; the failure facet of the one envelope contract.)_
 #### `rest-endpoint-shape` — HIGH · point
-Method + path + params + request/response body of one REST endpoint. **Where:** Express 5 routers, Fastify, Next.js route handlers. **Breaks:** renaming a route, changing `:id`→`:userId`, making an optional field required, or removing a response field breaks every caller across the HTTP gap with no compile signal. **Detect:** `**/routes/**`, `**/*.routes.*`, `router.(get|post|…)`, client `axios.get('/...')`/`fetch`. **Safe-change:** add fields, don't rename/remove; deprecate before deletion; keep query params optional; update client call sites + typed SDK together. *(Canonical home for the REST-endpoint × `point` cluster — `request-validation-schema` and `response-dto-shape` fold in (the inbound and outbound shapes of the same endpoint), unless the repo files validation/DTO contracts separately.)*
+Method + path + params + request/response body of one REST endpoint. **Where:** Express 5 routers, Fastify, Next.js route handlers. **Breaks:** renaming a route, changing `:id`→`:userId`, making an optional field required, or removing a response field breaks every caller across the HTTP gap with no compile signal. **Detect:** `**/routes/**`, `**/*.routes.*`, `router.(get|post|…)`, client `axios.get('/...')`/`fetch`. **Safe-change:** add fields, don't rename/remove; deprecate before deletion; keep query params optional; update client call sites + typed SDK together. _(Canonical home for the REST-endpoint × `point` cluster — `request-validation-schema` and `response-dto-shape` fold in (the inbound and outbound shapes of the same endpoint), unless the repo files validation/DTO contracts separately.)_
 #### `http-status-code-convention` — HIGH · transcribe
-The team's outcome→status mapping (`200/201/400/401=unauth/403=forbidden/404/409/422/429/500`). **Where:** Express `res.status(...)`, client interceptors branching on `err.response.status`. **Breaks:** clients route behavior off status (401→refresh+retry, 409→conflict UI, 429→backoff) — switching 400↔422 or confusing 401/403 breaks retry/redirect logic. **Detect:** `res.status(`, interceptors checking `status === 401`, `retryableStatusCodes`. **Safe-change:** keep 401=unauthenticated / 403=unauthorized fixed; don't migrate validation 400↔422 without updating clients; keep 429 paired with retry headers. *(Folds into `wire-response-envelope` — same REST-wire-convention source-of-truth, same `transcribe` doc-mode; the status-mapping facet.)* *(This repo's documented convention — `.claude/rules/general.md`.)*
+The team's outcome→status mapping (`200/201/400/401=unauth/403=forbidden/404/409/422/429/500`). **Where:** Express `res.status(...)`, client interceptors branching on `err.response.status`. **Breaks:** clients route behavior off status (401→refresh+retry, 409→conflict UI, 429→backoff) — switching 400↔422 or confusing 401/403 breaks retry/redirect logic. **Detect:** `res.status(`, interceptors checking `status === 401`, `retryableStatusCodes`. **Safe-change:** keep 401=unauthenticated / 403=unauthorized fixed; don't migrate validation 400↔422 without updating clients; keep 429 paired with retry headers. _(Folds into `wire-response-envelope` — same REST-wire-convention source-of-truth, same `transcribe` doc-mode; the status-mapping facet.)_ _(This repo's documented convention — `.claude/rules/general.md`.)_
 #### `openapi-spec-contract` — HIGH · point
-A machine-readable OpenAPI/Swagger doc as source of truth for generated clients/mocks/tests. **Where:** `openapi.{yaml,json}`, `zod-to-openapi`, `tsoa`, NestJS Swagger, openapi-generator SDKs. **Breaks:** generated SDKs, mocks, and docs derive from the spec — spec↔server drift makes clients send/expect wrong shapes, visible only at runtime. **Detect:** `**/openapi.{yaml,json}`, `openapi: 3.x`, generator config, spec-validation in CI. **Safe-change:** regenerate spec-from-code (or code-from-spec) in one change; run an OpenAPI breaking-change linter (`oasdiff`, Redocly) in CI; bump `info.version`; republish SDKs. *(Own home — where the repo is spec-first, the spec file is the REST source-of-truth and `rest-endpoint-shape` cross-refs it; do not fold the spec into per-endpoint files.)*
+A machine-readable OpenAPI/Swagger doc as source of truth for generated clients/mocks/tests. **Where:** `openapi.{yaml,json}`, `zod-to-openapi`, `tsoa`, NestJS Swagger, openapi-generator SDKs. **Breaks:** generated SDKs, mocks, and docs derive from the spec — spec↔server drift makes clients send/expect wrong shapes, visible only at runtime. **Detect:** `**/openapi.{yaml,json}`, `openapi: 3.x`, generator config, spec-validation in CI. **Safe-change:** regenerate spec-from-code (or code-from-spec) in one change; run an OpenAPI breaking-change linter (`oasdiff`, Redocly) in CI; bump `info.version`; republish SDKs. _(Own home — where the repo is spec-first, the spec file is the REST source-of-truth and `rest-endpoint-shape` cross-refs it; do not fold the spec into per-endpoint files.)_
 #### `request-validation-schema` — HIGH · point
-The runtime schema (Zod/yup/Joi/class-validator) defining a valid inbound request. **Where:** Zod 4 `z.object()` in Express middleware, `safeParse`, tRPC `.input()`, NestJS DTOs. **Breaks:** the schema *is* the request contract — tightening it (new required field, narrowed enum, `.strict()`) silently 400s previously-valid clients; loosening lets malformed data through. **Detect:** `z.object`, `.parse(`/`.safeParse(`, `zodResolver`, `@IsString`, `schemas/`/`validators/`. **Safe-change:** new body fields optional/defaulted; avoid `.strict()` regressions; share the schema with the client so both move together; enums append-only. *(Folds into `rest-endpoint-shape` — same endpoint/handler source-of-truth, same `point` doc-mode; the inbound-shape facet. Cross-ref frontend `form-schema-contract`.)*
+The runtime schema (Zod/yup/Joi/class-validator) defining a valid inbound request. **Where:** Zod 4 `z.object()` in Express middleware, `safeParse`, tRPC `.input()`, NestJS DTOs. **Breaks:** the schema _is_ the request contract — tightening it (new required field, narrowed enum, `.strict()`) silently 400s previously-valid clients; loosening lets malformed data through. **Detect:** `z.object`, `.parse(`/`.safeParse(`, `zodResolver`, `@IsString`, `schemas/`/`validators/`. **Safe-change:** new body fields optional/defaulted; avoid `.strict()` regressions; share the schema with the client so both move together; enums append-only. _(Folds into `rest-endpoint-shape` — same endpoint/handler source-of-truth, same `point` doc-mode; the inbound-shape facet. Cross-ref frontend `form-schema-contract`.)_
 #### `response-dto-shape` — HIGH · point
-The field set, types, and nullability of an endpoint's serialized response (the DTO inside the envelope). **Where:** Express JSON responses, ORM serializers, DTO mappers, GraphQL object types. **Breaks:** removing/renaming a field, changing number↔string, or flipping nullability breaks every reader — including TS clients whose types were derived once and now lie. **Detect:** response serializers, `res.json({...})` literals, `select`/`pick` projections, client `interface *Response`. **Safe-change:** add freely, deprecate before removing; never change a field's JSON type in place; keep date/number serialization stable; sync client types from one source. *(Folds into `rest-endpoint-shape` — same endpoint/handler source-of-truth, same `point` doc-mode; the outbound-shape facet (the DTO inside the envelope).)*
+The field set, types, and nullability of an endpoint's serialized response (the DTO inside the envelope). **Where:** Express JSON responses, ORM serializers, DTO mappers, GraphQL object types. **Breaks:** removing/renaming a field, changing number↔string, or flipping nullability breaks every reader — including TS clients whose types were derived once and now lie. **Detect:** response serializers, `res.json({...})` literals, `select`/`pick` projections, client `interface *Response`. **Safe-change:** add freely, deprecate before removing; never change a field's JSON type in place; keep date/number serialization stable; sync client types from one source. _(Folds into `rest-endpoint-shape` — same endpoint/handler source-of-truth, same `point` doc-mode; the outbound-shape facet (the DTO inside the envelope).)_
 #### `graphql-schema-contract` — CRITICAL · point
-The SDL — types, fields, args, enums, directives — resolvers fulfill and clients query. **Where:** Apollo Server, GraphQL Yoga, `schema.graphql`, code-first (Pothos/Nexus), `@graphql-codegen`. **Breaks:** removing/renaming a field, tightening nullability, removing an enum value, or changing an arg breaks existing client queries at execution; codegen'd types + persisted-query docs go stale. **Detect:** `**/*.graphql`, `typeDefs`, `gql\``, `buildSchema`/`makeExecutableSchema`, `codegen.yml`. **Safe-change:** run a schema-diff check (GraphQL Inspector, `rover graph check`, Hive) in CI; `@deprecated` + usage metrics before removal; don't tighten output nullability or remove in-use enum values; regenerate client types every change. *(Canonical home for the GraphQL-SDL × `point` cluster — `graphql-federation-subgraph-contract` folds in (its directives live in the SDL); `graphql-persisted-query-contract` keeps its own file (a separate registry).)*
+The SDL — types, fields, args, enums, directives — resolvers fulfill and clients query. **Where:** Apollo Server, GraphQL Yoga, `schema.graphql`, code-first (Pothos/Nexus), `@graphql-codegen`. **Breaks:** removing/renaming a field, tightening nullability, removing an enum value, or changing an arg breaks existing client queries at execution; codegen'd types + persisted-query docs go stale. **Detect:** `**/*.graphql`, `typeDefs`, `gql\``, `buildSchema`/`makeExecutableSchema`, `codegen.yml`. **Safe-change:** run a schema-diff check (GraphQL Inspector, `rover graph check`, Hive) in CI; `@deprecated`+ usage metrics before removal; don't tighten output nullability or remove in-use enum values; regenerate client types every change. *(Canonical home for the GraphQL-SDL ×`point`cluster —`graphql-federation-subgraph-contract`folds in (its directives live in the SDL);`graphql-persisted-query-contract` keeps its own file (a separate registry).)\*
 #### `graphql-federation-subgraph-contract` — CRITICAL · point
-The federation entity/key contract — `@key`, `@external`, `@requires`, `@provides`, `@shareable`, `@tag` — between a subgraph and the composed supergraph. **Where:** Apollo Federation v2, WunderGraph Cosmo, GraphQL Hive, `@apollo/subgraph`. **Breaks:** changing an entity `@key`, removing an `@external` field another subgraph `@requires`, or breaking a `@shareable` type fails *supergraph composition* — taking down fields owned by other teams. **Detect:** `@key(`, `@external`, `@requires`, `@provides`, `@shareable`, `extend type`, `@tag`, `supergraph.yaml`. **Safe-change:** `rover subgraph check`/Cosmo/Hive composition checks before publish; coordinate entity-key changes across referencing subgraphs; don't remove depended-on `@external`/`@provides`. *(Folds into `graphql-schema-contract` — the federation directives live in the same SDL source-of-truth, same `point` doc-mode; split out a `supergraph.yaml`-level file only in a dedicated federation gateway.)*
+The federation entity/key contract — `@key`, `@external`, `@requires`, `@provides`, `@shareable`, `@tag` — between a subgraph and the composed supergraph. **Where:** Apollo Federation v2, WunderGraph Cosmo, GraphQL Hive, `@apollo/subgraph`. **Breaks:** changing an entity `@key`, removing an `@external` field another subgraph `@requires`, or breaking a `@shareable` type fails _supergraph composition_ — taking down fields owned by other teams. **Detect:** `@key(`, `@external`, `@requires`, `@provides`, `@shareable`, `extend type`, `@tag`, `supergraph.yaml`. **Safe-change:** `rover subgraph check`/Cosmo/Hive composition checks before publish; coordinate entity-key changes across referencing subgraphs; don't remove depended-on `@external`/`@provides`. _(Folds into `graphql-schema-contract` — the federation directives live in the same SDL source-of-truth, same `point` doc-mode; split out a `supergraph.yaml`-level file only in a dedicated federation gateway.)_
 #### `graphql-persisted-query-contract` — HIGH · point
-The registry of allowlisted/hashed operation documents shared between client build output and the server allowlist. **Where:** Apollo APQ/persisted queries, Hive persisted documents, Relay persisted queries. **Breaks:** the server only executes registered hashes — editing an operation without republishing the allowlist (or changing the hash algorithm) → `PersistedQueryNotFound`, blocking all traffic for that operation. **Detect:** `persistedQueries`, `automaticPersistedQueries`, `sha256Hash`, `extensions.persistedQuery`, the persisted-query manifest. **Safe-change:** republish the manifest whenever a query changes; pin the hashing algorithm across client/server; roll out new manifests before dependent clients; stabilize the schema first. *(Own home — the persisted-query manifest/registry is a distinct source-of-truth from the SDL; do not fold into `graphql-schema-contract`.)*
+The registry of allowlisted/hashed operation documents shared between client build output and the server allowlist. **Where:** Apollo APQ/persisted queries, Hive persisted documents, Relay persisted queries. **Breaks:** the server only executes registered hashes — editing an operation without republishing the allowlist (or changing the hash algorithm) → `PersistedQueryNotFound`, blocking all traffic for that operation. **Detect:** `persistedQueries`, `automaticPersistedQueries`, `sha256Hash`, `extensions.persistedQuery`, the persisted-query manifest. **Safe-change:** republish the manifest whenever a query changes; pin the hashing algorithm across client/server; roll out new manifests before dependent clients; stabilize the schema first. _(Own home — the persisted-query manifest/registry is a distinct source-of-truth from the SDL; do not fold into `graphql-schema-contract`.)_
 #### `grpc-protobuf-wire-contract` — CRITICAL · point
-Protobuf message/service defs whose field numbers + wire types are a binary-compatibility contract. **Where:** gRPC, `.proto` (proto2/3), `buf`, `protoc` stubs, Connect-RPC, gRPC-Web. **Breaks:** field numbers identify fields on the wire and can never be reused — changing a number/type/`repeated`-ness, or reusing a deleted number, silently corrupts data across services on different `.proto` versions, no exception. **Detect:** `**/*.proto`, `= 1;` field numbers, `reserved`, `service { rpc }`, `buf.yaml`. **Safe-change:** never reuse/renumber field numbers (`reserved` removed ones); add fields with new numbers only; `buf breaking` in CI; never change wire type or cardinality in place. *(Canonical home for the `.proto` × `point` cluster — `grpc-service-method-contract` folds in (the service surface lives in the same `.proto`).)*
+Protobuf message/service defs whose field numbers + wire types are a binary-compatibility contract. **Where:** gRPC, `.proto` (proto2/3), `buf`, `protoc` stubs, Connect-RPC, gRPC-Web. **Breaks:** field numbers identify fields on the wire and can never be reused — changing a number/type/`repeated`-ness, or reusing a deleted number, silently corrupts data across services on different `.proto` versions, no exception. **Detect:** `**/*.proto`, `= 1;` field numbers, `reserved`, `service { rpc }`, `buf.yaml`. **Safe-change:** never reuse/renumber field numbers (`reserved` removed ones); add fields with new numbers only; `buf breaking` in CI; never change wire type or cardinality in place. _(Canonical home for the `.proto` × `point` cluster — `grpc-service-method-contract` folds in (the service surface lives in the same `.proto`).)_
 #### `grpc-service-method-contract` — HIGH · point
-The gRPC service surface — RPC names, request/response types, streaming mode. **Where:** gRPC `service` blocks, generated stubs, reflection, Connect/gRPC-Web. **Breaks:** renaming an RPC, changing its messages, or switching streaming mode (unary→stream) breaks generated clients with `UNIMPLEMENTED`/deserialization errors; the method path is a routing contract. **Detect:** `rpc \w+\(`, `stream` in `.proto`, `*ServiceClient`/`*ServiceServer`, `UNIMPLEMENTED`. **Safe-change:** add new RPCs rather than mutate; keep the fully-qualified path stable; don't change streaming mode of an in-use RPC; regenerate + republish stubs. *(Folds into `grpc-protobuf-wire-contract` — same `.proto` source-of-truth, same `point` doc-mode; the service-surface facet.)*
+The gRPC service surface — RPC names, request/response types, streaming mode. **Where:** gRPC `service` blocks, generated stubs, reflection, Connect/gRPC-Web. **Breaks:** renaming an RPC, changing its messages, or switching streaming mode (unary→stream) breaks generated clients with `UNIMPLEMENTED`/deserialization errors; the method path is a routing contract. **Detect:** `rpc \w+\(`, `stream` in `.proto`, `*ServiceClient`/`*ServiceServer`, `UNIMPLEMENTED`. **Safe-change:** add new RPCs rather than mutate; keep the fully-qualified path stable; don't change streaming mode of an in-use RPC; regenerate + republish stubs. _(Folds into `grpc-protobuf-wire-contract` — same `.proto` source-of-truth, same `point` doc-mode; the service-surface facet.)_
 #### `trpc-router-contract` — HIGH · point
-The tRPC router's procedures, `.input()`/`.output()` schemas, and the exported `AppRouter` type flowing end-to-end. **Where:** tRPC v11, `createTRPCClient<AppRouter>`, Next.js + tRPC monorepos. **Breaks:** the contract is the TS type shared by import — caught at compile only if client/server build the same types; deploy-skew (server ahead of client) breaks at runtime, and mismatched package versions throw on connect. **Detect:** `initTRPC`, `router({`, `.input(`, `publicProcedure`, `createTRPCClient<`, `export type AppRouter`. **Safe-change:** deploy server + client from the same `AppRouter` version; keep tRPC package versions identical; version procedures via `v1`/`v2` sub-routers; exported-type changes are semver-major. *(Own home — the exported `AppRouter` type is its own end-to-end source-of-truth, distinct from REST endpoints.)*
+The tRPC router's procedures, `.input()`/`.output()` schemas, and the exported `AppRouter` type flowing end-to-end. **Where:** tRPC v11, `createTRPCClient<AppRouter>`, Next.js + tRPC monorepos. **Breaks:** the contract is the TS type shared by import — caught at compile only if client/server build the same types; deploy-skew (server ahead of client) breaks at runtime, and mismatched package versions throw on connect. **Detect:** `initTRPC`, `router({`, `.input(`, `publicProcedure`, `createTRPCClient<`, `export type AppRouter`. **Safe-change:** deploy server + client from the same `AppRouter` version; keep tRPC package versions identical; version procedures via `v1`/`v2` sub-routers; exported-type changes are semver-major. _(Own home — the exported `AppRouter` type is its own end-to-end source-of-truth, distinct from REST endpoints.)_
 #### `api-versioning-strategy` — HIGH · transcribe
-How the API expresses version — URL path, header, media-type param, query — and what each version freezes. **Where:** Express prefixes (`/v1`), header routing, proto `package myapi.v1`, GraphQL field-level versioning. **Breaks:** clients pin a version — changing the default, dropping a version, or moving version header→URL silently routes clients to incompatible behavior. **Detect:** `/v1`/`/v2` prefixes, `Accept-Version`/`X-API-Version` reads, `package *.v1`, version-routing middleware. **Safe-change:** keep old versions alive until consumers migrate (announce sunset); don't change default/unversioned behavior; keep the selection mechanism stable. *(Own home — the version-selection convention is a distinct cross-cutting `transcribe` contract, not the per-endpoint shape.)*
+How the API expresses version — URL path, header, media-type param, query — and what each version freezes. **Where:** Express prefixes (`/v1`), header routing, proto `package myapi.v1`, GraphQL field-level versioning. **Breaks:** clients pin a version — changing the default, dropping a version, or moving version header→URL silently routes clients to incompatible behavior. **Detect:** `/v1`/`/v2` prefixes, `Accept-Version`/`X-API-Version` reads, `package *.v1`, version-routing middleware. **Safe-change:** keep old versions alive until consumers migrate (announce sunset); don't change default/unversioned behavior; keep the selection mechanism stable. _(Own home — the version-selection convention is a distinct cross-cutting `transcribe` contract, not the per-endpoint shape.)_
 #### `pagination-filtering-sorting-contract` — MED · transcribe
-The paging (offset/cursor/keyset), filter, sort param convention + page-metadata shape (`hasMore`, `nextCursor`, `total`). **Where:** REST list endpoints, GraphQL Relay connections (`edges`/`pageInfo`), `?limit=&offset=`/`?cursor=`. **Breaks:** clients loop on exact param names + metadata fields — switching offset→cursor, renaming `nextCursor`, changing cursor encoding, or altering default page size breaks iteration (drops rows / infinite loops). **Detect:** `limit`/`offset`/`page`/`cursor`/`after`, `pageInfo`/`hasNextPage`/`endCursor`, `sort=`/`filter[`. **Safe-change:** keep param names + default page size stable; treat cursors as opaque; add filter/sort options additively; keep page-metadata field names fixed. *(Own home — the paging/filter/sort convention spans list endpoints as one transcribed contract, not a single endpoint's shape.)*
+The paging (offset/cursor/keyset), filter, sort param convention + page-metadata shape (`hasMore`, `nextCursor`, `total`). **Where:** REST list endpoints, GraphQL Relay connections (`edges`/`pageInfo`), `?limit=&offset=`/`?cursor=`. **Breaks:** clients loop on exact param names + metadata fields — switching offset→cursor, renaming `nextCursor`, changing cursor encoding, or altering default page size breaks iteration (drops rows / infinite loops). **Detect:** `limit`/`offset`/`page`/`cursor`/`after`, `pageInfo`/`hasNextPage`/`endCursor`, `sort=`/`filter[`. **Safe-change:** keep param names + default page size stable; treat cursors as opaque; add filter/sort options additively; keep page-metadata field names fixed. _(Own home — the paging/filter/sort convention spans list endpoints as one transcribed contract, not a single endpoint's shape.)_
 #### `cors-preflight-contract` — HIGH · transcribe
-The CORS contract — allowed origins/methods/headers, credentials flag, and which custom headers trigger preflight. **Where:** Express `cors({ origin: FRONTEND_URL })`, gateway/edge CORS, browser `OPTIONS` preflight. **Breaks:** the browser enforces at request-shape level — adding a custom header (`X-Tenant-Id`) without `Access-Control-Allow-Headers`, tightening `origin`, or enabling credentials without `allow-credentials` silently blocks requests in the browser only (server tests pass). **Detect:** `cors(`, `Access-Control-Allow-`, `allowedHeaders`/`credentials`, `origin:`, custom client headers. **Safe-change:** add new custom headers to `allowedHeaders`; keep `origin` allowlist synced to deployed frontends (every env); match `credentials:true` with a non-wildcard origin; list read headers in `exposedHeaders`. *(Canonical home; runtime `cors-policy` folds in — same CORS contract, infra-layer view.)*
+The CORS contract — allowed origins/methods/headers, credentials flag, and which custom headers trigger preflight. **Where:** Express `cors({ origin: FRONTEND_URL })`, gateway/edge CORS, browser `OPTIONS` preflight. **Breaks:** the browser enforces at request-shape level — adding a custom header (`X-Tenant-Id`) without `Access-Control-Allow-Headers`, tightening `origin`, or enabling credentials without `allow-credentials` silently blocks requests in the browser only (server tests pass). **Detect:** `cors(`, `Access-Control-Allow-`, `allowedHeaders`/`credentials`, `origin:`, custom client headers. **Safe-change:** add new custom headers to `allowedHeaders`; keep `origin` allowlist synced to deployed frontends (every env); match `credentials:true` with a non-wildcard origin; list read headers in `exposedHeaders`. _(Canonical home; runtime `cors-policy` folds in — same CORS contract, infra-layer view.)_
 #### `content-negotiation-media-type` — MED · point
-The `Content-Type`/`Accept` contract — which media types the server produces/consumes and how it parses by type. **Where:** Express `express.json()`/`urlencoded()`, `res.format()`, vendor media types (`application/vnd.app.v2+json`), `problem+json`. **Breaks:** a client sending `application/json` to an endpoint that switched to `multipart/form-data`, or a server dropping a vendor type, breaks parsing — empty bodies or 415s. **Detect:** `Content-Type`/`Accept`, `res.format(`, `express.json`/`urlencoded`/`text`, `+json`/`vnd.`, multer. **Safe-change:** keep accepted/produced types stable per endpoint; don't switch body encoding without client updates; return 406/415 correctly. *(Own home — the media-type parse contract is a distinct request-shape convention; do not fold into `rest-endpoint-shape`.)*
+The `Content-Type`/`Accept` contract — which media types the server produces/consumes and how it parses by type. **Where:** Express `express.json()`/`urlencoded()`, `res.format()`, vendor media types (`application/vnd.app.v2+json`), `problem+json`. **Breaks:** a client sending `application/json` to an endpoint that switched to `multipart/form-data`, or a server dropping a vendor type, breaks parsing — empty bodies or 415s. **Detect:** `Content-Type`/`Accept`, `res.format(`, `express.json`/`urlencoded`/`text`, `+json`/`vnd.`, multer. **Safe-change:** keep accepted/produced types stable per endpoint; don't switch body encoding without client updates; return 406/415 correctly. _(Own home — the media-type parse contract is a distinct request-shape convention; do not fold into `rest-endpoint-shape`.)_
 #### `file-upload-multipart-contract` — MED · point
-The multipart field-name, count, size-limit, MIME contract for uploads (or presigned-URL flows). **Where:** multer (`upload.single('avatar')`), busboy, GraphQL multipart, S3/R2 presigned PUT/POST. **Breaks:** the server keys off exact field names + size/MIME limits — renaming `file`→`upload`, tightening `fileSize`, or changing allowed MIME silently rejects uploads; presigned policy mismatch rejects the PUT. **Detect:** `multer`, `upload.single`/`array`/`fields`, `multipart/form-data`, `fileSize`/`limits`, `createPresignedPost`. **Safe-change:** keep field names stable; don't tighten size/MIME without notifying clients; keep presigned-POST policy aligned with the client form. *(Own home — the multipart field/size/MIME contract is distinct; do not fold into `rest-endpoint-shape`. Cross-ref persistence `blob-object-storage-key-convention` for presigned-URL flows.)*
+The multipart field-name, count, size-limit, MIME contract for uploads (or presigned-URL flows). **Where:** multer (`upload.single('avatar')`), busboy, GraphQL multipart, S3/R2 presigned PUT/POST. **Breaks:** the server keys off exact field names + size/MIME limits — renaming `file`→`upload`, tightening `fileSize`, or changing allowed MIME silently rejects uploads; presigned policy mismatch rejects the PUT. **Detect:** `multer`, `upload.single`/`array`/`fields`, `multipart/form-data`, `fileSize`/`limits`, `createPresignedPost`. **Safe-change:** keep field names stable; don't tighten size/MIME without notifying clients; keep presigned-POST policy aligned with the client form. _(Own home — the multipart field/size/MIME contract is distinct; do not fold into `rest-endpoint-shape`. Cross-ref persistence `blob-object-storage-key-convention` for presigned-URL flows.)_
 #### `inbound-webhook-contract` — HIGH · point
-The contract for webhooks your service *receives* — payload schema, headers, signature scheme, idempotency. **Where:** Stripe (`stripe-signature`), GitHub (`X-Hub-Signature-256`), Shopify HMAC, Express raw-body handlers. **Breaks:** (1) the provider changes payload/version/signing → your verifier rejects/misparses; (2) JSON middleware re-serializes the body → HMAC over parsed body no longer matches the raw-body signature — both fail silently or 400 every delivery. **Detect:** `X-Hub-Signature`, `stripe-signature`, `constructEvent`, `createHmac`, `timingSafeEqual`, `express.raw`, `req.rawBody`. **Safe-change:** verify signatures over the **raw** body before JSON parsing; `timingSafeEqual` not `===`; make handlers idempotent on delivery IDs; track the provider's webhook API version. *(Own home — the inbound contract is owned by the external provider (`point` at their docs); distinct from `outbound-webhook-contract` you emit.)*
+The contract for webhooks your service _receives_ — payload schema, headers, signature scheme, idempotency. **Where:** Stripe (`stripe-signature`), GitHub (`X-Hub-Signature-256`), Shopify HMAC, Express raw-body handlers. **Breaks:** (1) the provider changes payload/version/signing → your verifier rejects/misparses; (2) JSON middleware re-serializes the body → HMAC over parsed body no longer matches the raw-body signature — both fail silently or 400 every delivery. **Detect:** `X-Hub-Signature`, `stripe-signature`, `constructEvent`, `createHmac`, `timingSafeEqual`, `express.raw`, `req.rawBody`. **Safe-change:** verify signatures over the **raw** body before JSON parsing; `timingSafeEqual` not `===`; make handlers idempotent on delivery IDs; track the provider's webhook API version. _(Own home — the inbound contract is owned by the external provider (`point` at their docs); distinct from `outbound-webhook-contract` you emit.)_
 #### `outbound-webhook-contract` — HIGH · transcribe
-The payload schema, event-type taxonomy, signature, and retry semantics your service *emits* to subscribers. **Where:** webhook dispatchers, Svix, `POST` to subscriber URLs with `X-Signature`. **Breaks:** subscribers parse your payload + verify your signature — renaming an event type, changing the payload, rotating the secret without notice, or altering the signature header silently breaks every (external, uncontrolled) subscriber. **Detect:** webhook-send code, event-type enums, signature construction, retry/backoff config. **Safe-change:** version the event payload (`api_version`); event-type names append-only; rotate secrets with overlap windows + notice; keep signature header + algorithm stable. *(Own home — the payload you emit is a transcribed contract you own, distinct from the inbound provider contract.)*
+The payload schema, event-type taxonomy, signature, and retry semantics your service _emits_ to subscribers. **Where:** webhook dispatchers, Svix, `POST` to subscriber URLs with `X-Signature`. **Breaks:** subscribers parse your payload + verify your signature — renaming an event type, changing the payload, rotating the secret without notice, or altering the signature header silently breaks every (external, uncontrolled) subscriber. **Detect:** webhook-send code, event-type enums, signature construction, retry/backoff config. **Safe-change:** version the event payload (`api_version`); event-type names append-only; rotate secrets with overlap windows + notice; keep signature header + algorithm stable. _(Own home — the payload you emit is a transcribed contract you own, distinct from the inbound provider contract.)_
 #### `auth-token-wire-contract` — CRITICAL · transcribe
-How credentials travel per request and what the server expects — `Authorization: Bearer` vs cookie session, claim shape, header name, 401-challenge format. **Where:** Express auth middleware, `jose` verification, Better Auth cookie/session, `WWW-Authenticate`, `X-API-Key`. **Breaks:** the request-shape edge between client and auth — moving header→cookie, renaming the header, changing required claims, or altering the 401 challenge silently 401s every authenticated request; interacts with CORS credentials. **Detect:** `Authorization`, `Bearer`, `req.headers.authorization`, `jose`/`jwtVerify`, `X-API-Key`, cookie-session reads, `WWW-Authenticate`. **Safe-change:** keep transport (header vs cookie) + header name stable; required claims additive; coordinate issuance + verification together; align with CORS `credentials`/`allowedHeaders`. *(Folds into auth `auth-contract` — same credential source-of-truth, same `transcribe` doc-mode; this is its wire/transport view. Cross-ref auth `jwt-claims-contract` for the claim set.)*
+How credentials travel per request and what the server expects — `Authorization: Bearer` vs cookie session, claim shape, header name, 401-challenge format. **Where:** Express auth middleware, `jose` verification, Better Auth cookie/session, `WWW-Authenticate`, `X-API-Key`. **Breaks:** the request-shape edge between client and auth — moving header→cookie, renaming the header, changing required claims, or altering the 401 challenge silently 401s every authenticated request; interacts with CORS credentials. **Detect:** `Authorization`, `Bearer`, `req.headers.authorization`, `jose`/`jwtVerify`, `X-API-Key`, cookie-session reads, `WWW-Authenticate`. **Safe-change:** keep transport (header vs cookie) + header name stable; required claims additive; coordinate issuance + verification together; align with CORS `credentials`/`allowedHeaders`. _(Folds into auth `auth-contract` — same credential source-of-truth, same `transcribe` doc-mode; this is its wire/transport view. Cross-ref auth `jwt-claims-contract` for the claim set.)_
 #### `conditional-request-caching-contract` — MED · point
-The HTTP caching/concurrency contract — `ETag`/`If-None-Match`, `Last-Modified`/`If-Modified-Since`, `If-Match` for optimistic concurrency. **Where:** Express `etag`, CDN/proxy caches, `304`/`412 Precondition Failed` on `PUT`/`PATCH`. **Breaks:** clients/proxies cache on `ETag` and gate writes on `If-Match` — changing the ETag algorithm (weak↔strong), dropping it, or altering `If-Match` enforcement → stale reads or lost-update writes returning unexpected `412`. **Detect:** `ETag`/`etag`, `If-None-Match`/`If-Match`, `Last-Modified`, `304`/`412` handling. **Safe-change:** keep ETag generation deterministic/stable; preserve `If-Match` enforcement on writes; keep `304`/`412` semantics consistent. *(Own home — the ETag/`If-Match` concurrency contract (`point`) is distinct from the `Cache-Control` TTL/CDN facet; cross-ref runtime `cache-header-contract`.)*
+The HTTP caching/concurrency contract — `ETag`/`If-None-Match`, `Last-Modified`/`If-Modified-Since`, `If-Match` for optimistic concurrency. **Where:** Express `etag`, CDN/proxy caches, `304`/`412 Precondition Failed` on `PUT`/`PATCH`. **Breaks:** clients/proxies cache on `ETag` and gate writes on `If-Match` — changing the ETag algorithm (weak↔strong), dropping it, or altering `If-Match` enforcement → stale reads or lost-update writes returning unexpected `412`. **Detect:** `ETag`/`etag`, `If-None-Match`/`If-Match`, `Last-Modified`, `304`/`412` handling. **Safe-change:** keep ETag generation deterministic/stable; preserve `If-Match` enforcement on writes; keep `304`/`412` semantics consistent. _(Own home — the ETag/`If-Match` concurrency contract (`point`) is distinct from the `Cache-Control` TTL/CDN facet; cross-ref runtime `cache-header-contract`.)_
 #### `idempotency-key-contract` — HIGH · transcribe
-The dedup contract for safe retries of non-idempotent operations — an `Idempotency-Key` header (HTTP) or a dedup id (messaging) → cached/deduped result. **Where:** Stripe-style `Idempotency-Key`, payment/order APIs; and (messaging) SQS FIFO `MessageDeduplicationId`, Kafka `enable.idempotence`, BullMQ `jobId`. **Breaks:** client + server must agree on the key recipe + dedup window — changing how the key is derived makes previously-deduped ops look distinct → duplicate side effects (double charge/email); shortening the TTL re-executes late retries. **Detect:** `Idempotency-Key`/`idempotency_key`, dedup-store lookups, `MessageDeduplicationId`, `jobId:`, Powertools `@idempotent`. **Safe-change:** document exactly which fields compose the key; never change the recipe without a migration; keep the dedup window ≥ max retry horizon; persist the key with the result; co-version on both sides. *(Canonical home for both the HTTP-header and message-dedup facets.)*
+The dedup contract for safe retries of non-idempotent operations — an `Idempotency-Key` header (HTTP) or a dedup id (messaging) → cached/deduped result. **Where:** Stripe-style `Idempotency-Key`, payment/order APIs; and (messaging) SQS FIFO `MessageDeduplicationId`, Kafka `enable.idempotence`, BullMQ `jobId`. **Breaks:** client + server must agree on the key recipe + dedup window — changing how the key is derived makes previously-deduped ops look distinct → duplicate side effects (double charge/email); shortening the TTL re-executes late retries. **Detect:** `Idempotency-Key`/`idempotency_key`, dedup-store lookups, `MessageDeduplicationId`, `jobId:`, Powertools `@idempotent`. **Safe-change:** document exactly which fields compose the key; never change the recipe without a migration; keep the dedup window ≥ max retry horizon; persist the key with the result; co-version on both sides. _(Canonical home for both the HTTP-header and message-dedup facets.)_
 ---
 ## 3 · FRONTEND, CLIENT-STATE & UI
-> Recurring failure mode in this category: **untyped string identifiers** — slice
-> paths, cache tags, route paths, param keys, i18n/flag/event/storage/query keys
-> — where producer and consumer drift with *no compile error*, surfacing only as
-> silent runtime degradation. Universal fix: centralize each identifier set in one
-> typed module and CI-gate drift.
+> Recurring failure mode in this category: **untyped string identifiers** — slice paths, cache tags, route paths, param keys, i18n/flag/event/storage/query keys — where producer and consumer drift with _no compile error_, surfacing only as silent runtime degradation. Universal fix: centralize each identifier set in one typed module and CI-gate drift.
 #### `store-shape` — HIGH · transcribe
-The serializable shape of the global client state tree (slice names, nesting, key paths) every reader/writer agrees on. **Where:** Redux Toolkit 2 `configureStore`+`createSlice`, Zustand, Jotai, Pinia. **Breaks:** renaming a slice or moving a key returns `undefined` to every consuming selector with no compile error if selectors use string paths; persisted state rehydrates into the wrong shape. **Detect:** `configureStore({ reducer: {…} })` (the reducer map *is* the top-level shape), `createSlice`, `**/store.*`, `**/slices/**`. **Safe-change:** grep all `state.<slice>`/`useSelector` before renaming; bump `redux-persist` version + migration if persisted; slice names additive; co-locate selectors with the slice. *(Canonical home for the client-store tree (`transcribe`) — `selector-contract` keeps its own file (`point` read-API over the same store, different doc-mode); persisted-store rehydration cross-refs `client-storage-schema`.)*
+The serializable shape of the global client state tree (slice names, nesting, key paths) every reader/writer agrees on. **Where:** Redux Toolkit 2 `configureStore`+`createSlice`, Zustand, Jotai, Pinia. **Breaks:** renaming a slice or moving a key returns `undefined` to every consuming selector with no compile error if selectors use string paths; persisted state rehydrates into the wrong shape. **Detect:** `configureStore({ reducer: {…} })` (the reducer map _is_ the top-level shape), `createSlice`, `**/store.*`, `**/slices/**`. **Safe-change:** grep all `state.<slice>`/`useSelector` before renaming; bump `redux-persist` version + migration if persisted; slice names additive; co-locate selectors with the slice. _(Canonical home for the client-store tree (`transcribe`) — `selector-contract` keeps its own file (`point` read-API over the same store, different doc-mode); persisted-store rehydration cross-refs `client-storage-schema`.)_
 #### `selector-contract` — MED · point
-Memoized selectors whose input deps + output shape are an implicit API between store and components. **Where:** Reselect/RTK `createSelector`, `entityAdapter.getSelectors`, `useSelector`. **Breaks:** changing output shape (array→keyed object, +/- fields) breaks every reader; changing memo inputs causes stale results or re-render storms; an unstable return triggers infinite re-renders. **Detect:** `createSelector(`, `getSelectors(`, `**/selectors.*`, `select*` exports. **Safe-change:** treat exported selectors' return type as public; verify memo inputs cover added fields; never return a fresh reference unmemoized. *(Own home — the selector read-API is `point` over the same store as `store-shape` but a different doc-mode, so it files separately.)*
+Memoized selectors whose input deps + output shape are an implicit API between store and components. **Where:** Reselect/RTK `createSelector`, `entityAdapter.getSelectors`, `useSelector`. **Breaks:** changing output shape (array→keyed object, +/- fields) breaks every reader; changing memo inputs causes stale results or re-render storms; an unstable return triggers infinite re-renders. **Detect:** `createSelector(`, `getSelectors(`, `**/selectors.*`, `select*` exports. **Safe-change:** treat exported selectors' return type as public; verify memo inputs cover added fields; never return a fresh reference unmemoized. _(Own home — the selector read-API is `point` over the same store as `store-shape` but a different doc-mode, so it files separately.)_
 #### `rtk-query-cache-tags` — HIGH · point
-The tag taxonomy (`providesTags`/`invalidatesTags`) wiring queries to mutation invalidation. **Where:** RTK Query `createApi`, `tagTypes`, `injectEndpoints`. **Breaks:** a tag typo or a mutation that forgets to invalidate → stale UI with no error; renaming a tag in one endpoint but not another breaks consistency; over-broad tags cause refetch storms. **Detect:** `createApi(`, `tagTypes:`, `providesTags:`, `invalidatesTags:`, `**/*Api.*`. **Safe-change:** define `tagTypes` as one const enum referenced everywhere (no inline literals); audit which queries provide an affected tag when adding a mutation; use `{type,id}` granularity. *(Own home — the RTK Query tag taxonomy is its own source-of-truth; the non-RTK equivalent is `query-cache-key-contract`.)*
+The tag taxonomy (`providesTags`/`invalidatesTags`) wiring queries to mutation invalidation. **Where:** RTK Query `createApi`, `tagTypes`, `injectEndpoints`. **Breaks:** a tag typo or a mutation that forgets to invalidate → stale UI with no error; renaming a tag in one endpoint but not another breaks consistency; over-broad tags cause refetch storms. **Detect:** `createApi(`, `tagTypes:`, `providesTags:`, `invalidatesTags:`, `**/*Api.*`. **Safe-change:** define `tagTypes` as one const enum referenced everywhere (no inline literals); audit which queries provide an affected tag when adding a mutation; use `{type,id}` granularity. _(Own home — the RTK Query tag taxonomy is its own source-of-truth; the non-RTK equivalent is `query-cache-key-contract`.)_
 #### `route-table` — HIGH · point
-The route definition tree mapping URL patterns to components/loaders — the contract between the address bar and the app. **Where:** react-router 7 (`createBrowserRouter`, `routes.ts`, `<Route>`), TanStack Router, Next.js App Router. **Breaks:** renaming/restructuring a path breaks bookmarks, deep links, redirects, sitemaps, inbound `<Link>`/`navigate()`; framework-mode typegen + loader wiring break. **Detect:** `createBrowserRouter(`, `routes.{ts,tsx}`, `<Route path=`, `app/**/page.*`, `.react-router/types`. **Safe-change:** add a redirect from old→new on a public URL change; grep `<Link to=`/`navigate(`/`href=`; regenerate route types; keep route IDs stable if loaders reference them. *(Canonical home for the route tree (`point`) — `url-param-contract` folds in (the params the route table defines), unless the repo files param contracts separately.)*
+The route definition tree mapping URL patterns to components/loaders — the contract between the address bar and the app. **Where:** react-router 7 (`createBrowserRouter`, `routes.ts`, `<Route>`), TanStack Router, Next.js App Router. **Breaks:** renaming/restructuring a path breaks bookmarks, deep links, redirects, sitemaps, inbound `<Link>`/`navigate()`; framework-mode typegen + loader wiring break. **Detect:** `createBrowserRouter(`, `routes.{ts,tsx}`, `<Route path=`, `app/**/page.*`, `.react-router/types`. **Safe-change:** add a redirect from old→new on a public URL change; grep `<Link to=`/`navigate(`/`href=`; regenerate route types; keep route IDs stable if loaders reference them. _(Canonical home for the route tree (`point`) — `url-param-contract` folds in (the params the route table defines), unless the repo files param contracts separately.)_
 #### `url-param-contract` — HIGH · point
-The path/query/search-param names + types components read from the URL. **Where:** react-router `useParams`/`useSearchParams`, loader `params`, Next.js `searchParams`, nuqs. **Breaks:** renaming `:userId`→`:id` or `?tab=`→`?view=` yields `undefined` in reads while old links carry the old key; string-vs-number parsing diverges. **Detect:** `useParams(`, `useSearchParams(`, `params.<name>`, `searchParams.get(`, `:` segments, `useQueryState`. **Safe-change:** match the param name in route def + every read; validate with Zod at the boundary; support old + new keys during a deprecation window. *(Folds into `route-table` — the params are defined by the same router source-of-truth, same `point` doc-mode.)*
+The path/query/search-param names + types components read from the URL. **Where:** react-router `useParams`/`useSearchParams`, loader `params`, Next.js `searchParams`, nuqs. **Breaks:** renaming `:userId`→`:id` or `?tab=`→`?view=` yields `undefined` in reads while old links carry the old key; string-vs-number parsing diverges. **Detect:** `useParams(`, `useSearchParams(`, `params.<name>`, `searchParams.get(`, `:` segments, `useQueryState`. **Safe-change:** match the param name in route def + every read; validate with Zod at the boundary; support old + new keys during a deprecation window. _(Folds into `route-table` — the params are defined by the same router source-of-truth, same `point` doc-mode.)_
 #### `component-prop-contract` — HIGH · point
-The public props interface (+ defaults) of a reusable/published component. **Where:** React 19 `interface Props`, design-system / `@nurix/components` exports, headless-UI render props. **Breaks:** renaming/removing a prop, tightening a type, changing a default, or flipping controlled↔uncontrolled breaks every consumer; for a published package the blast radius is every importing app (semver). **Detect:** `interface *Props`, `React.FC<`, `**/components/**`, barrel `index.ts`, package `exports`. **Safe-change:** treat exported props as semver-governed; add props optional with safe defaults; deprecate don't delete; grep all `<ComponentName` usages before changing required props. *(Own home — a component's props interface is its own source-of-truth; for a published component cross-ref config `package-public-api` (the install-boundary view).)*
+The public props interface (+ defaults) of a reusable/published component. **Where:** React 19 `interface Props`, design-system / `@nurix/components` exports, headless-UI render props. **Breaks:** renaming/removing a prop, tightening a type, changing a default, or flipping controlled↔uncontrolled breaks every consumer; for a published package the blast radius is every importing app (semver). **Detect:** `interface *Props`, `React.FC<`, `**/components/**`, barrel `index.ts`, package `exports`. **Safe-change:** treat exported props as semver-governed; add props optional with safe defaults; deprecate don't delete; grep all `<ComponentName` usages before changing required props. _(Own home — a component's props interface is its own source-of-truth; for a published component cross-ref config `package-public-api` (the install-boundary view).)_
 #### `react-context-contract` — MED · point
-The value shape a Provider supplies + the expectation a matching Provider wraps every consumer. **Where:** React 19 `createContext`/`use`/`useContext`, theme/auth/router providers, Redux/RTK/i18next providers. **Breaks:** changing the value shape breaks all `useContext` readers; a consumer outside its provider gets the default (often `undefined` → crash) with no compile error; duplicate providers diverge silently. **Detect:** `createContext(`, `useContext(`, `*Provider`, `*Context`, `**/providers/**`. **Safe-change:** keep the value type stable (add, don't repurpose); throw a clear error in the hook if context is `undefined`; verify provider placement when moving routes/layouts. *(Own home — each Provider's value shape is its own source-of-truth.)*
+The value shape a Provider supplies + the expectation a matching Provider wraps every consumer. **Where:** React 19 `createContext`/`use`/`useContext`, theme/auth/router providers, Redux/RTK/i18next providers. **Breaks:** changing the value shape breaks all `useContext` readers; a consumer outside its provider gets the default (often `undefined` → crash) with no compile error; duplicate providers diverge silently. **Detect:** `createContext(`, `useContext(`, `*Provider`, `*Context`, `**/providers/**`. **Safe-change:** keep the value type stable (add, don't repurpose); throw a clear error in the hook if context is `undefined`; verify provider placement when moving routes/layouts. _(Own home — each Provider's value shape is its own source-of-truth.)_
 #### `design-token-contract` — MED · transcribe
-Named design tokens (colors/spacing/radii/type) exposed as utility classes + CSS custom properties, plus the theme-mode selector and required style imports. **Where:** Tailwind 4 `@theme` (CSS-first), `--color-*` custom properties, `dark:` variant / `data-theme`, `@nurix/components` styles import, Style Dictionary. **Breaks:** in Tailwind 4 every `@theme` token *is* a CSS var + generates a utility — renaming a token removes the utility (`bg-brand` stops applying) and breaks `var(--color-brand)`; a mis-namespaced var is silently dropped; changing the mode selector (`.dark`→`[data-theme]`) disables every `dark:` style; forgetting the styles import renders components unstyled. **Detect:** `@theme {`, `--color-`/`--spacing-`, `var(--`, `tailwind.config.*`, `@apply`, `dark:`, `import '@nurix/components/styles'`. **Safe-change:** grep utility usages AND `var(--token)` before renaming; keep namespaces valid; provide alias tokens during a rename; keep one token source; verify rendered UI. *(Canonical home; cross-ref config `css-design-token-contract` for the build/import facet.)*
+Named design tokens (colors/spacing/radii/type) exposed as utility classes + CSS custom properties, plus the theme-mode selector and required style imports. **Where:** Tailwind 4 `@theme` (CSS-first), `--color-*` custom properties, `dark:` variant / `data-theme`, `@nurix/components` styles import, Style Dictionary. **Breaks:** in Tailwind 4 every `@theme` token _is_ a CSS var + generates a utility — renaming a token removes the utility (`bg-brand` stops applying) and breaks `var(--color-brand)`; a mis-namespaced var is silently dropped; changing the mode selector (`.dark`→`[data-theme]`) disables every `dark:` style; forgetting the styles import renders components unstyled. **Detect:** `@theme {`, `--color-`/`--spacing-`, `var(--`, `tailwind.config.*`, `@apply`, `dark:`, `import '@nurix/components/styles'`. **Safe-change:** grep utility usages AND `var(--token)` before renaming; keep namespaces valid; provide alias tokens during a rename; keep one token source; verify rendered UI. _(Canonical home; cross-ref config `css-design-token-contract` for the build/import facet.)_
 #### `i18n-message-keys` — MED · point
-Translation keys (+ namespaces + interpolation placeholders) shared between code lookups and locale catalogs. **Where:** i18next/react-i18next `t('key')`, `Trans`, FormatJS `defineMessages`, `locales/{lng}/{ns}.json`. **Breaks:** renaming a key in code but not catalogs (or vice versa) shows the raw key/`missingKey`; missing interpolation vars render literal `{{name}}`; namespace load failure drops a screen's text. **Detect:** `t(`, `useTranslation(`, `<Trans`, `i18nKey=`, `**/locales/**`, `i18next-parser` config. **Safe-change:** run `i18next-parser --ci` to fail on code keys missing from catalogs; generate TS key types; keep placeholder names in sync across locales; configure `fallbackLng`. *(Own home — the translation-key set + catalogs are their own source-of-truth.)*
+Translation keys (+ namespaces + interpolation placeholders) shared between code lookups and locale catalogs. **Where:** i18next/react-i18next `t('key')`, `Trans`, FormatJS `defineMessages`, `locales/{lng}/{ns}.json`. **Breaks:** renaming a key in code but not catalogs (or vice versa) shows the raw key/`missingKey`; missing interpolation vars render literal `{{name}}`; namespace load failure drops a screen's text. **Detect:** `t(`, `useTranslation(`, `<Trans`, `i18nKey=`, `**/locales/**`, `i18next-parser` config. **Safe-change:** run `i18next-parser --ci` to fail on code keys missing from catalogs; generate TS key types; keep placeholder names in sync across locales; configure `fallbackLng`. _(Own home — the translation-key set + catalogs are their own source-of-truth.)_
 #### `form-schema-contract` — HIGH · point
-Field names/types/validation shared between a form's fields, its schema, and the submit payload. **Where:** React Hook Form `register`+`zodResolver`, Zod 4, Formik+Yup, TanStack Form, `@nurix/components` form fields. **Breaks:** renaming a field in the schema but not `register('name')` leaves it unvalidated/unsubmitted silently; schema types diverge from the API payload; `defaultValues` keys must match field names or RHF drops them. **Detect:** `useForm(`, `register('`, `Controller name=`, `zodResolver(`, `defaultValues:`, `**/*.schema.ts`. **Safe-change:** derive field names from the Zod schema (`z.infer`) so a rename is a type error; align `defaultValues` keys; verify the submit payload still matches the server. *(Own home — the form-field↔schema↔payload contract is its own source-of-truth; cross-ref API `request-validation-schema` (the server side it must match).)*
+Field names/types/validation shared between a form's fields, its schema, and the submit payload. **Where:** React Hook Form `register`+`zodResolver`, Zod 4, Formik+Yup, TanStack Form, `@nurix/components` form fields. **Breaks:** renaming a field in the schema but not `register('name')` leaves it unvalidated/unsubmitted silently; schema types diverge from the API payload; `defaultValues` keys must match field names or RHF drops them. **Detect:** `useForm(`, `register('`, `Controller name=`, `zodResolver(`, `defaultValues:`, `**/*.schema.ts`. **Safe-change:** derive field names from the Zod schema (`z.infer`) so a rename is a type error; align `defaultValues` keys; verify the submit payload still matches the server. _(Own home — the form-field↔schema↔payload contract is its own source-of-truth; cross-ref API `request-validation-schema` (the server side it must match).)_
 #### `client-storage-schema` — HIGH · transcribe
-The versioned shape of browser-persisted data future code must read back. **Where:** `localStorage`/`sessionStorage`, IndexedDB, localforage, `redux-persist` (`version`+`createMigrate`), Zustand `persist`, TanStack Query persisters. **Breaks:** changing the persisted shape without a migration means returning users rehydrate stale/incompatible data into new code — crashes on first load after deploy; localforage driver/db-name changes orphan data. **Detect:** `localStorage.`/`sessionStorage.`, `localforage.`, `indexedDB.open(`, `persistReducer(`, `createMigrate(`, `version:`, `persist(`, key literals. **Safe-change:** bump persist `version` + add a `createMigrate` migration per shape change; whitelist which slices persist; keep keys/DB names stable; guard rehydration with schema validation, reset on parse failure. *(Own home — the browser-persisted shape is its own versioned source-of-truth; cross-ref frontend `store-shape` when the persisted data is the store.)*
+The versioned shape of browser-persisted data future code must read back. **Where:** `localStorage`/`sessionStorage`, IndexedDB, localforage, `redux-persist` (`version`+`createMigrate`), Zustand `persist`, TanStack Query persisters. **Breaks:** changing the persisted shape without a migration means returning users rehydrate stale/incompatible data into new code — crashes on first load after deploy; localforage driver/db-name changes orphan data. **Detect:** `localStorage.`/`sessionStorage.`, `localforage.`, `indexedDB.open(`, `persistReducer(`, `createMigrate(`, `version:`, `persist(`, key literals. **Safe-change:** bump persist `version` + add a `createMigrate` migration per shape change; whitelist which slices persist; keep keys/DB names stable; guard rehydration with schema validation, reset on parse failure. _(Own home — the browser-persisted shape is its own versioned source-of-truth; cross-ref frontend `store-shape` when the persisted data is the store.)_
 #### `feature-flag-gating` — MED · point
-The flag keys + expected defaults gating client UI/behavior. **Where:** LaunchDarkly `useFlags`/`variation`, OpenFeature, Statsig, GrowthBook, Cloudflare Flagship. **Breaks:** a flag key is permanent — renaming/archiving without removing all code refs returns the default (often `false`), silently hiding a shipped feature; missing defaults cause load flicker; stale flags accumulate as dead branches. **Detect:** `useFlags(`, `variation(`, `getFlag(`, flag-key literals, `**/flags.*`, SDK init. **Safe-change:** centralize keys in one typed module; supply explicit "off"-safe defaults; archive only after grepping the key to zero refs. *(Folds into config `feature-flag-contract` — same flag-key source-of-truth; this is its client-gating facet.)*
+The flag keys + expected defaults gating client UI/behavior. **Where:** LaunchDarkly `useFlags`/`variation`, OpenFeature, Statsig, GrowthBook, Cloudflare Flagship. **Breaks:** a flag key is permanent — renaming/archiving without removing all code refs returns the default (often `false`), silently hiding a shipped feature; missing defaults cause load flicker; stale flags accumulate as dead branches. **Detect:** `useFlags(`, `variation(`, `getFlag(`, flag-key literals, `**/flags.*`, SDK init. **Safe-change:** centralize keys in one typed module; supply explicit "off"-safe defaults; archive only after grepping the key to zero refs. _(Folds into config `feature-flag-contract` — same flag-key source-of-truth; this is its client-gating facet.)_
 #### `asset-public-path-contract` — MED · point
-The base/public path + asset URL resolution mapping imports and `/public` refs to deployed URLs. **Where:** Vite `base` + `import.meta.env.BASE_URL`, `/public`, hashed filenames, CDN origins. **Breaks:** changing `base` (sub-path deploy) breaks hardcoded `/asset` URLs; `import.meta.env.BASE_URL` is statically replaced and must appear verbatim; moving to a CDN breaks relative refs. **Detect:** `base:` in `vite.config`, `import.meta.env.BASE_URL`, `/public/`, hardcoded `/assets/`, `new URL('...', import.meta.url)`. **Safe-change:** use `BASE_URL` verbatim for dynamic URLs; audit hardcoded paths when changing `base`/CDN; let the bundler rewrite imported assets. *(Own home — the public-path/asset-URL resolution is its own contract; cross-ref config `bundler-entry-output-externals` for output naming.)*
+The base/public path + asset URL resolution mapping imports and `/public` refs to deployed URLs. **Where:** Vite `base` + `import.meta.env.BASE_URL`, `/public`, hashed filenames, CDN origins. **Breaks:** changing `base` (sub-path deploy) breaks hardcoded `/asset` URLs; `import.meta.env.BASE_URL` is statically replaced and must appear verbatim; moving to a CDN breaks relative refs. **Detect:** `base:` in `vite.config`, `import.meta.env.BASE_URL`, `/public/`, hardcoded `/assets/`, `new URL('...', import.meta.url)`. **Safe-change:** use `BASE_URL` verbatim for dynamic URLs; audit hardcoded paths when changing `base`/CDN; let the bundler rewrite imported assets. _(Own home — the public-path/asset-URL resolution is its own contract; cross-ref config `bundler-entry-output-externals` for output naming.)_
 #### `ssr-hydration-contract` — HIGH · point
-The requirement that server-rendered markup exactly matches the client's first render, and transferred state is serializable. **Where:** React 19 `hydrateRoot`, Next.js App Router, react-router 7 framework mode, Remix, Astro islands. **Breaks:** any divergence (locale dates, `Date.now()`, `window` access, random IDs, `typeof window` branches) throws a hydration mismatch and discards the server tree; a text mismatch is a hard error in React 19. **Detect:** `hydrateRoot(`, `renderToString`/`renderToPipeableStream`, `useSyncExternalStore`, `typeof window`, `new Date()` in render, `suppressHydrationWarning`. **Safe-change:** move client-only/non-deterministic logic into `useEffect`/`useSyncExternalStore`; render the same first-paint content on both sides; keep date/number formatting locale-stable. *(Own home — the markup-match requirement is distinct from the serializability rule in `state-serialization-contract`.)*
+The requirement that server-rendered markup exactly matches the client's first render, and transferred state is serializable. **Where:** React 19 `hydrateRoot`, Next.js App Router, react-router 7 framework mode, Remix, Astro islands. **Breaks:** any divergence (locale dates, `Date.now()`, `window` access, random IDs, `typeof window` branches) throws a hydration mismatch and discards the server tree; a text mismatch is a hard error in React 19. **Detect:** `hydrateRoot(`, `renderToString`/`renderToPipeableStream`, `useSyncExternalStore`, `typeof window`, `new Date()` in render, `suppressHydrationWarning`. **Safe-change:** move client-only/non-deterministic logic into `useEffect`/`useSyncExternalStore`; render the same first-paint content on both sides; keep date/number formatting locale-stable. _(Own home — the markup-match requirement is distinct from the serializability rule in `state-serialization-contract`.)_
 #### `state-serialization-contract` — HIGH · transcribe
-The rule that data crossing server→client (or worker/postMessage) must be JSON-serializable; structured types are lost. **Where:** Next.js Server→Client props/RSC payload, TanStack Query `dehydrate`, react-router loader data, `postMessage`, `structuredClone`. **Breaks:** `Date`, `Map`, `Set`, `BigInt`, `undefined`, class instances, functions don't survive default serialization — a `Date` arrives as a string and consumers expecting a `Date` prototype diverge/throw; methods are stripped. **Detect:** `dehydrate(`, `HydrationBoundary`, `superjson`/`devalue`, `JSON.stringify`/`parse` across a boundary, Server→Client `props`, `postMessage(`. **Safe-change:** pass only JSON-safe values or use superjson/devalue; serialize `Date`/`Map`/`Set` explicitly + rehydrate; don't pass functions/class instances Server→Client. *(Own home — the server→client serialization rule; cross-ref runtime `worker-thread-boundary` for the structured-clone facet across threads.)*
+The rule that data crossing server→client (or worker/postMessage) must be JSON-serializable; structured types are lost. **Where:** Next.js Server→Client props/RSC payload, TanStack Query `dehydrate`, react-router loader data, `postMessage`, `structuredClone`. **Breaks:** `Date`, `Map`, `Set`, `BigInt`, `undefined`, class instances, functions don't survive default serialization — a `Date` arrives as a string and consumers expecting a `Date` prototype diverge/throw; methods are stripped. **Detect:** `dehydrate(`, `HydrationBoundary`, `superjson`/`devalue`, `JSON.stringify`/`parse` across a boundary, Server→Client `props`, `postMessage(`. **Safe-change:** pass only JSON-safe values or use superjson/devalue; serialize `Date`/`Map`/`Set` explicitly + rehydrate; don't pass functions/class instances Server→Client. _(Own home — the server→client serialization rule; cross-ref runtime `worker-thread-boundary` for the structured-clone facet across threads.)_
 #### `custom-element-contract` — MED · point
-A custom element's public surface — tag name, observed attributes, properties, events, slots, CSS shadow parts. **Where:** Web Components (`customElements.define`, `observedAttributes`), Lit, Stencil; React 19 (now sets custom-element properties), Vue `defineCustomElement`. **Breaks:** renaming a tag breaks all usages + registration (double-register throws); attribute↔property reflection mismatches; renaming a slot leaves projected content unrendered; changing a `part` name breaks external `::part()` styling. **Detect:** `customElements.define(`, `observedAttributes`, `attributeChangedCallback`, `static properties`, `<slot name=`, `::part(`. **Safe-change:** keep tag/observed-attribute/slot/part names stable (public API); maintain attribute↔property symmetry; guard `define` against double-registration; treat emitted CustomEvent names/`detail` as contract. *(Canonical home for the custom-element public surface (`point`) — `dom-event-contract` folds in (the emitted-event facet of the same element).)*
+A custom element's public surface — tag name, observed attributes, properties, events, slots, CSS shadow parts. **Where:** Web Components (`customElements.define`, `observedAttributes`), Lit, Stencil; React 19 (now sets custom-element properties), Vue `defineCustomElement`. **Breaks:** renaming a tag breaks all usages + registration (double-register throws); attribute↔property reflection mismatches; renaming a slot leaves projected content unrendered; changing a `part` name breaks external `::part()` styling. **Detect:** `customElements.define(`, `observedAttributes`, `attributeChangedCallback`, `static properties`, `<slot name=`, `::part(`. **Safe-change:** keep tag/observed-attribute/slot/part names stable (public API); maintain attribute↔property symmetry; guard `define` against double-registration; treat emitted CustomEvent names/`detail` as contract. _(Canonical home for the custom-element public surface (`point`) — `dom-event-contract` folds in (the emitted-event facet of the same element).)_
 #### `dom-event-contract` — LOW · point
-Custom DOM/CustomEvent names + `detail` shapes components dispatch and listeners consume. **Where:** `dispatchEvent(new CustomEvent('name',{detail}))`, web-component events, Vue `emits`, `@dnd-kit` events. **Breaks:** renaming an event or changing `detail` silently breaks listeners (handler never fires / reads `undefined`); `bubbles`/`composed` affect shadow-DOM delivery. **Detect:** `new CustomEvent(`, `dispatchEvent(`, `addEventListener('`, `emit(`/`emits:`. **Safe-change:** treat event names + `detail` shapes as public (version them); keep `bubbles`/`composed` consistent with where listeners attach. *(Folds into `custom-element-contract` — same component DOM-surface source-of-truth, same `point` doc-mode; the emitted-event facet. Stands alone only for framework-agnostic events with no custom element.)*
+Custom DOM/CustomEvent names + `detail` shapes components dispatch and listeners consume. **Where:** `dispatchEvent(new CustomEvent('name',{detail}))`, web-component events, Vue `emits`, `@dnd-kit` events. **Breaks:** renaming an event or changing `detail` silently breaks listeners (handler never fires / reads `undefined`); `bubbles`/`composed` affect shadow-DOM delivery. **Detect:** `new CustomEvent(`, `dispatchEvent(`, `addEventListener('`, `emit(`/`emits:`. **Safe-change:** treat event names + `detail` shapes as public (version them); keep `bubbles`/`composed` consistent with where listeners attach. _(Folds into `custom-element-contract` — same component DOM-surface source-of-truth, same `point` doc-mode; the emitted-event facet. Stands alone only for framework-agnostic events with no custom element.)_
 #### `deep-link-scheme-contract` — HIGH · point
-URL scheme / universal-link / app-link patterns routing external entry points (email, push, OAuth callbacks, mobile) into in-app destinations. **Where:** custom schemes (`myapp://`), iOS Universal Links / Android App Links (`apple-app-site-association`, `assetlinks.json`), OAuth redirect URIs, magic-links, react-router targets. **Breaks:** changing a path/scheme breaks links already sent in emails/push (irrecoverable) and OAuth provider allowlists; a missing AASA/assetlinks falls back to browser; redirect-URI mismatch breaks auth. **Detect:** `://` schemes, `apple-app-site-association`, `.well-known/assetlinks.json`, OAuth `redirectUri`/`callbackURL` (Better Auth `trustedOrigins`), `**/.well-known/**`. **Safe-change:** keep old deep-link/redirect paths alive with redirects; update OAuth allowlists + AASA/assetlinks in lockstep; never repurpose a path's meaning. *(Own home — the deep-link/scheme/AASA config is its own source-of-truth; cross-ref auth `redirect-uri-allowlist` for the OAuth-callback overlap.)*
+URL scheme / universal-link / app-link patterns routing external entry points (email, push, OAuth callbacks, mobile) into in-app destinations. **Where:** custom schemes (`myapp://`), iOS Universal Links / Android App Links (`apple-app-site-association`, `assetlinks.json`), OAuth redirect URIs, magic-links, react-router targets. **Breaks:** changing a path/scheme breaks links already sent in emails/push (irrecoverable) and OAuth provider allowlists; a missing AASA/assetlinks falls back to browser; redirect-URI mismatch breaks auth. **Detect:** `://` schemes, `apple-app-site-association`, `.well-known/assetlinks.json`, OAuth `redirectUri`/`callbackURL` (Better Auth `trustedOrigins`), `**/.well-known/**`. **Safe-change:** keep old deep-link/redirect paths alive with redirects; update OAuth allowlists + AASA/assetlinks in lockstep; never repurpose a path's meaning. _(Own home — the deep-link/scheme/AASA config is its own source-of-truth; cross-ref auth `redirect-uri-allowlist` for the OAuth-callback overlap.)_
 #### `analytics-event-contract` — MED · transcribe
-The event names + property keys + value types (the "tracking plan") shared between client instrumentation and downstream analytics/warehouse. **Where:** Segment `track`, Snowplow self-describing events, GA4 `gtag('event')`, Amplitude/Mixpanel/PostHog `capture`. **Breaks:** a tracking plan is a producer→consumer data contract — renaming an event/property or changing a type silently breaks dashboards/funnels and fragments historical continuity, with no app error. **Detect:** `track(`, `gtag('event'`, `capture(`, `logEvent(`, event-name literals, `**/analytics/**`. **Safe-change:** centralize names/keys in a typed module/schema; version events (add new, deprecate); validate against the tracking-plan schema in CI; property types additive. *(Own home — the analytics tracking plan is its own producer→consumer source-of-truth, distinct from domain `event-schema`.)*
+The event names + property keys + value types (the "tracking plan") shared between client instrumentation and downstream analytics/warehouse. **Where:** Segment `track`, Snowplow self-describing events, GA4 `gtag('event')`, Amplitude/Mixpanel/PostHog `capture`. **Breaks:** a tracking plan is a producer→consumer data contract — renaming an event/property or changing a type silently breaks dashboards/funnels and fragments historical continuity, with no app error. **Detect:** `track(`, `gtag('event'`, `capture(`, `logEvent(`, event-name literals, `**/analytics/**`. **Safe-change:** centralize names/keys in a typed module/schema; version events (add new, deprecate); validate against the tracking-plan schema in CI; property types additive. _(Own home — the analytics tracking plan is its own producer→consumer source-of-truth, distinct from domain `event-schema`.)_
 #### `query-cache-key-contract` — HIGH · point
-Cache-key arrays/structure identifying cached server-state entries + driving invalidation (non-RTK). **Where:** TanStack Query `queryKey`/`invalidateQueries`, SWR keys/`mutate`, Apollo `typePolicies`/`keyFields`/`__typename`. **Breaks:** a query key + its invalidation target must match exactly — a key-shape change in one place but not the invalidator → stale UI or permanent cache miss; Apollo normalization relies on stable `id`/`keyFields`/`__typename`. **Detect:** `queryKey:`, `useQuery(`, `invalidateQueries(`, `useSWR(`, `mutate(`, `typePolicies`, `keyFields`, `**/queries/**`. **Safe-change:** centralize query-key factories (never hand-write at call sites); keep invalidation keys structurally aligned; preserve Apollo `keyFields`/`__typename`. *(Own home — the TanStack/SWR/Apollo cache-key source-of-truth; the RTK equivalent is `rtk-query-cache-tags`.)*
+Cache-key arrays/structure identifying cached server-state entries + driving invalidation (non-RTK). **Where:** TanStack Query `queryKey`/`invalidateQueries`, SWR keys/`mutate`, Apollo `typePolicies`/`keyFields`/`__typename`. **Breaks:** a query key + its invalidation target must match exactly — a key-shape change in one place but not the invalidator → stale UI or permanent cache miss; Apollo normalization relies on stable `id`/`keyFields`/`__typename`. **Detect:** `queryKey:`, `useQuery(`, `invalidateQueries(`, `useSWR(`, `mutate(`, `typePolicies`, `keyFields`, `**/queries/**`. **Safe-change:** centralize query-key factories (never hand-write at call sites); keep invalidation keys structurally aligned; preserve Apollo `keyFields`/`__typename`. _(Own home — the TanStack/SWR/Apollo cache-key source-of-truth; the RTK equivalent is `rtk-query-cache-tags`.)_
 ---
 ## 4 · IDENTITY, AUTH & TENANCY
-> See domain `tenancy` for the cross-layer tenant-isolation invariant. The
-> CRITICAL tier here is anything whose failure is a *silent auth bypass or data
-> disclosure*, not a loud error.
+> See domain `tenancy` for the cross-layer tenant-isolation invariant. The CRITICAL tier here is anything whose failure is a _silent auth bypass or data disclosure_, not a loud error.
 #### `auth-contract` — CRITICAL · transcribe
-The credential a client presents + the server validates — session cookie vs bearer token, and each one's structure. **Where:** Better Auth `session` table (`token`, `userId`, `expiresAt`, `ipAddress`), jose-signed JWTs, Express auth middleware. **Breaks:** flipping stateful-session↔stateless-JWT makes every validator, logout/revocation path, and middleware silently fail or accept stale credentials; Better Auth uses `expiresAt` (not `expires`) and issues a *session token* for email+password — assuming an access/refresh pair breaks consumers. **Detect:** `auth.ts`/`auth.config.*`, `betterAuth({…})`, `jose` (`jwtVerify`/`SignJWT`), `req.cookies`/`Set-Cookie`, session-table schema. **Safe-change:** confirm every validator agrees stateful vs stateless before flipping; keep field/cookie names byte-stable (renames = migrations); verify logout/revocation still invalidates; re-run Better Auth CLI migrate after a schema push. *(Canonical home for the credential contract (`transcribe`) — API `auth-token-wire-contract` folds in (its wire/transport view); `jwt-claims-contract` keeps its own file (the claim set, `point`).)*
+The credential a client presents + the server validates — session cookie vs bearer token, and each one's structure. **Where:** Better Auth `session` table (`token`, `userId`, `expiresAt`, `ipAddress`), jose-signed JWTs, Express auth middleware. **Breaks:** flipping stateful-session↔stateless-JWT makes every validator, logout/revocation path, and middleware silently fail or accept stale credentials; Better Auth uses `expiresAt` (not `expires`) and issues a _session token_ for email+password — assuming an access/refresh pair breaks consumers. **Detect:** `auth.ts`/`auth.config.*`, `betterAuth({…})`, `jose` (`jwtVerify`/`SignJWT`), `req.cookies`/`Set-Cookie`, session-table schema. **Safe-change:** confirm every validator agrees stateful vs stateless before flipping; keep field/cookie names byte-stable (renames = migrations); verify logout/revocation still invalidates; re-run Better Auth CLI migrate after a schema push. _(Canonical home for the credential contract (`transcribe`) — API `auth-token-wire-contract` folds in (its wire/transport view); `jwt-claims-contract` keeps its own file (the claim set, `point`).)_
 #### `jwt-claims-contract` — CRITICAL · point
-The set + meaning of claims (`iss`, `aud`, `sub`, `exp`, `nbf`, `scope`, custom) issuer and verifier must agree on. **Where:** jose/`jsonwebtoken`, RFC 9068 access-token JWTs, Keycloak/Auth0/WorkOS, gateway validators. **Breaks:** a valid token from a trusted issuer is still wrong if `aud` isn't enforced; `sub` is unique only within an `iss`, so keying on `sub` alone collides identities; adding/renaming a custom claim silently drops authz on old-name readers; loosening `iss`/`aud` opens token-substitution. **Detect:** `jwtVerify(token, key, { issuer, audience })`, claim string reads (`payload.role`), JWKS URL config. **Safe-change:** always enforce `iss` AND `aud`; key identity on `(iss, sub)`; treat custom claims as versioned; bounded clock skew (≤60s); claims additive. *(Own home — the claim set is `point` source-of-truth, distinct from the `transcribe` credential contract `auth-contract`; the verifier's key edge is `signing-key-rotation`.)*
+The set + meaning of claims (`iss`, `aud`, `sub`, `exp`, `nbf`, `scope`, custom) issuer and verifier must agree on. **Where:** jose/`jsonwebtoken`, RFC 9068 access-token JWTs, Keycloak/Auth0/WorkOS, gateway validators. **Breaks:** a valid token from a trusted issuer is still wrong if `aud` isn't enforced; `sub` is unique only within an `iss`, so keying on `sub` alone collides identities; adding/renaming a custom claim silently drops authz on old-name readers; loosening `iss`/`aud` opens token-substitution. **Detect:** `jwtVerify(token, key, { issuer, audience })`, claim string reads (`payload.role`), JWKS URL config. **Safe-change:** always enforce `iss` AND `aud`; key identity on `(iss, sub)`; treat custom claims as versioned; bounded clock skew (≤60s); claims additive. _(Own home — the claim set is `point` source-of-truth, distinct from the `transcribe` credential contract `auth-contract`; the verifier's key edge is `signing-key-rotation`.)_
 #### `signing-key-rotation` — CRITICAL · point
-The trust edge where the verifier fetches + caches the issuer's public keys (JWKS). **Where:** `/.well-known/jwks.json`, `kid` header, jose `createRemoteJWKSet`, Keycloak/Auth0, SAML signing certs. **Breaks:** on rotation, verifiers caching stale JWKS reject all fresh tokens — teams then "temporarily" disable validation forever; `alg` confusion (`none`, RS↔HS) is a classic bypass. **Detect:** `createRemoteJWKSet`, `jwks_uri`, `kid`, hardcoded PEMs, `algorithms: [...]`, cache TTL. **Safe-change:** force a JWKS re-fetch on verify-failure-with-cached-key before rejecting; pin an explicit `algorithms` allowlist (never `none`); overlap old+new keys until old tokens expire; match cache TTL to rotation cadence. *(Own home — the JWKS/key-rotation trust edge is a distinct source-of-truth from the claim set.)*
+The trust edge where the verifier fetches + caches the issuer's public keys (JWKS). **Where:** `/.well-known/jwks.json`, `kid` header, jose `createRemoteJWKSet`, Keycloak/Auth0, SAML signing certs. **Breaks:** on rotation, verifiers caching stale JWKS reject all fresh tokens — teams then "temporarily" disable validation forever; `alg` confusion (`none`, RS↔HS) is a classic bypass. **Detect:** `createRemoteJWKSet`, `jwks_uri`, `kid`, hardcoded PEMs, `algorithms: [...]`, cache TTL. **Safe-change:** force a JWKS re-fetch on verify-failure-with-cached-key before rejecting; pin an explicit `algorithms` allowlist (never `none`); overlap old+new keys until old tokens expire; match cache TTL to rotation cadence. _(Own home — the JWKS/key-rotation trust edge is a distinct source-of-truth from the claim set.)_
 #### `refresh-token-rotation` — HIGH · point
-The exchange contract for a refresh token → new access token: single-use rotation, grace windows, replay revocation. **Where:** OAuth2 token endpoint, Better Auth `oauthRefreshToken` table (`token`, `clientId`, `revoked`, `scopes`, `expiresAt`). **Breaks:** if rotation marks old tokens `revoked` and a client races two requests, the second is a replay and the whole family is revoked; changing TTL/grace/single-use semantics silently logs users out or leaves stolen tokens valid. **Detect:** `oauthRefreshToken`/`refresh_tokens` schema, `revoked` columns, `grant_type=refresh_token`, rotation config. **Safe-change:** decide single-use vs grace-window explicitly; scope replay revocation to the family not the user (unless intended); store hashed; test concurrent-refresh races. *(Own home — the refresh-token exchange/rotation table is its own source-of-truth; cross-ref `oauth-oidc-flow` for the grant.)*
+The exchange contract for a refresh token → new access token: single-use rotation, grace windows, replay revocation. **Where:** OAuth2 token endpoint, Better Auth `oauthRefreshToken` table (`token`, `clientId`, `revoked`, `scopes`, `expiresAt`). **Breaks:** if rotation marks old tokens `revoked` and a client races two requests, the second is a replay and the whole family is revoked; changing TTL/grace/single-use semantics silently logs users out or leaves stolen tokens valid. **Detect:** `oauthRefreshToken`/`refresh_tokens` schema, `revoked` columns, `grant_type=refresh_token`, rotation config. **Safe-change:** decide single-use vs grace-window explicitly; scope replay revocation to the family not the user (unless intended); store hashed; test concurrent-refresh races. _(Own home — the refresh-token exchange/rotation table is its own source-of-truth; cross-ref `oauth-oidc-flow` for the grant.)_
 #### `session-cookie-attributes` — HIGH · point
-The flags on the session cookie — `SameSite`, `Secure`, `HttpOnly`, `Domain`, `Path`, `Max-Age`. **Where:** `Set-Cookie`, Better Auth cookie config, Express `res.cookie`/`cookie-session`, proxy cookie rewriting. **Breaks:** `SameSite=Lax→None` disables CSRF defense; dropping `Secure` allows interception; changing `Domain` breaks cross-subdomain auth or over-shares to siblings; `HttpOnly=false` exposes the session to XSS — all silent (the cookie still "works"). **Detect:** `res.cookie(...{sameSite,secure,httpOnly,domain})`, `Set-Cookie`, `cookiePrefix`/`crossSubDomainCookies`, `proxy_cookie_domain`. **Safe-change:** keep `HttpOnly`+`Secure` always; don't widen `Domain` without auditing siblings; pair `SameSite=None` with explicit CSRF; treat cookie name/prefix as cross-service contract. *(Own home — the cookie-flag set is its own source-of-truth; cross-ref `csrf-token-contract` (the `SameSite`/double-submit interaction).)*
+The flags on the session cookie — `SameSite`, `Secure`, `HttpOnly`, `Domain`, `Path`, `Max-Age`. **Where:** `Set-Cookie`, Better Auth cookie config, Express `res.cookie`/`cookie-session`, proxy cookie rewriting. **Breaks:** `SameSite=Lax→None` disables CSRF defense; dropping `Secure` allows interception; changing `Domain` breaks cross-subdomain auth or over-shares to siblings; `HttpOnly=false` exposes the session to XSS — all silent (the cookie still "works"). **Detect:** `res.cookie(...{sameSite,secure,httpOnly,domain})`, `Set-Cookie`, `cookiePrefix`/`crossSubDomainCookies`, `proxy_cookie_domain`. **Safe-change:** keep `HttpOnly`+`Secure` always; don't widen `Domain` without auditing siblings; pair `SameSite=None` with explicit CSRF; treat cookie name/prefix as cross-service contract. _(Own home — the cookie-flag set is its own source-of-truth; cross-ref `csrf-token-contract` (the `SameSite`/double-submit interaction).)_
 #### `csrf-token-contract` — HIGH · point
-The anti-CSRF mechanism (synchronizer token, double-submit cookie, origin check) + where the token is read/validated. **Where:** `csurf`/custom middleware, Better Auth CSRF + trusted-origins, `X-CSRF-Token` header + double-submit cookie. **Breaks:** SameSite alone doesn't cover mutating GETs/sibling-domain vulns — if the frontend stops sending the token, or the cookie becomes `HttpOnly` (breaking double-submit read), state-changing requests fail or lose protection; changing trusted-origins silently blocks/admits callers. **Detect:** `csrf`/`csurf`, `X-CSRF-Token`/`X-XSRF-Token`, `trustedOrigins`/`allowedOrigins`, double-submit cookie not `HttpOnly`. **Safe-change:** keep header + cookie names in lockstep FE/BE; double-submit CSRF cookie must be JS-readable; update `trustedOrigins` on every new frontend origin. *(Own home — the anti-CSRF mechanism is its own source-of-truth; cross-ref `session-cookie-attributes` for the `SameSite` interaction.)*
+The anti-CSRF mechanism (synchronizer token, double-submit cookie, origin check) + where the token is read/validated. **Where:** `csurf`/custom middleware, Better Auth CSRF + trusted-origins, `X-CSRF-Token` header + double-submit cookie. **Breaks:** SameSite alone doesn't cover mutating GETs/sibling-domain vulns — if the frontend stops sending the token, or the cookie becomes `HttpOnly` (breaking double-submit read), state-changing requests fail or lose protection; changing trusted-origins silently blocks/admits callers. **Detect:** `csrf`/`csurf`, `X-CSRF-Token`/`X-XSRF-Token`, `trustedOrigins`/`allowedOrigins`, double-submit cookie not `HttpOnly`. **Safe-change:** keep header + cookie names in lockstep FE/BE; double-submit CSRF cookie must be JS-readable; update `trustedOrigins` on every new frontend origin. _(Own home — the anti-CSRF mechanism is its own source-of-truth; cross-ref `session-cookie-attributes` for the `SameSite` interaction.)_
 #### `row-level-security` — CRITICAL · transcribe
-DB-enforced policies backstopping app-layer tenant/authz logic. **Where:** Postgres `CREATE POLICY`/`ENABLE`/`FORCE ROW LEVEL SECURITY`, GUC `app.current_tenant`, Supabase RLS. **Breaks:** RLS only works as well as the context fed it — a new table without a policy, a `BYPASSRLS` role, a missing `FORCE`, or a forgotten `SET LOCAL` silently returns all rows; a query path using a superuser/owner connection bypasses every policy. **Detect:** `ENABLE/FORCE ROW LEVEL SECURITY`, `CREATE POLICY`, `current_setting('app.current_tenant')`, `BYPASSRLS` grants, migrations lacking policies on new tenant tables. **Safe-change:** add a policy to every new tenant table in the same migration; `FORCE` so owners are constrained too; run app queries under a non-`BYPASSRLS` role; verify the tenant GUC on every connection path. *(Canonical home for the RLS-policy contract (`transcribe`) — persistence `row-level-multi-tenancy` folds in (its persistence-layer view); backstops domain `tenancy` (the cross-layer invariant, its own home).)*
+DB-enforced policies backstopping app-layer tenant/authz logic. **Where:** Postgres `CREATE POLICY`/`ENABLE`/`FORCE ROW LEVEL SECURITY`, GUC `app.current_tenant`, Supabase RLS. **Breaks:** RLS only works as well as the context fed it — a new table without a policy, a `BYPASSRLS` role, a missing `FORCE`, or a forgotten `SET LOCAL` silently returns all rows; a query path using a superuser/owner connection bypasses every policy. **Detect:** `ENABLE/FORCE ROW LEVEL SECURITY`, `CREATE POLICY`, `current_setting('app.current_tenant')`, `BYPASSRLS` grants, migrations lacking policies on new tenant tables. **Safe-change:** add a policy to every new tenant table in the same migration; `FORCE` so owners are constrained too; run app queries under a non-`BYPASSRLS` role; verify the tenant GUC on every connection path. _(Canonical home for the RLS-policy contract (`transcribe`) — persistence `row-level-multi-tenancy` folds in (its persistence-layer view); backstops domain `tenancy` (the cross-layer invariant, its own home).)_
 #### `object-level-authorization` — CRITICAL · point
-Per-object/per-instance permission checks (the IDOR surface), tying a subject to a specific resource via relationships. **Where:** Google Zanzibar model, OpenFGA/SpiceDB/Permify (`object#relation@user`), Oso, app `can(user, action, resource)`. **Breaks:** endpoints that authorize the action but not the specific object id are IDOR-vulnerable; changing a relationship schema silently grants/denies access to existing objects; cache-staleness serves outdated decisions. **Detect:** OpenFGA/SpiceDB schema (`.fga`), `Check`/`ListObjects`, tuple-writes, route handlers looking up `:id` without an ownership check, Oso policies. **Safe-change:** authorize the specific resource id, not just the action/role; treat relationship-schema edits as access-changing migrations; invalidate authz caches on relationship writes; keep tuple-writes transactional with the resource mutation. *(Own home — the relationship/ReBAC authz model is its own source-of-truth, distinct from `rbac-permission-model` and `abac-policy-engine`.)*
+Per-object/per-instance permission checks (the IDOR surface), tying a subject to a specific resource via relationships. **Where:** Google Zanzibar model, OpenFGA/SpiceDB/Permify (`object#relation@user`), Oso, app `can(user, action, resource)`. **Breaks:** endpoints that authorize the action but not the specific object id are IDOR-vulnerable; changing a relationship schema silently grants/denies access to existing objects; cache-staleness serves outdated decisions. **Detect:** OpenFGA/SpiceDB schema (`.fga`), `Check`/`ListObjects`, tuple-writes, route handlers looking up `:id` without an ownership check, Oso policies. **Safe-change:** authorize the specific resource id, not just the action/role; treat relationship-schema edits as access-changing migrations; invalidate authz caches on relationship writes; keep tuple-writes transactional with the resource mutation. _(Own home — the relationship/ReBAC authz model is its own source-of-truth, distinct from `rbac-permission-model` and `abac-policy-engine`.)_
 #### `rbac-permission-model` — HIGH · transcribe
-The role/permission taxonomy — role names, permission strings, role→permission maps — shared between policy and enforcement. **Where:** Better Auth `admin`/`organization` plugins, permission strings (`billing:read`), enum role columns, middleware guards. **Breaks:** renaming a role or permission string (`admin`→`owner`, `post:write`→`posts:create`) breaks every guard checking the old string — silently denying, or granting if a default-allow exists; a new role without seeded permissions is powerless or over-powered. **Detect:** permission-string literals, `hasPermission`/`requireRole`, role enums, `ac.newRole(...)`, seed files. **Safe-change:** centralize permission strings in one module; migrate role assignments on rename; unknown permission = default-deny; grep all enforcement points on any change. *(Own home — the role/permission taxonomy is its own `transcribe` source-of-truth, distinct from the per-object (`object-level-authorization`) and attribute-policy (`abac-policy-engine`) models.)*
+The role/permission taxonomy — role names, permission strings, role→permission maps — shared between policy and enforcement. **Where:** Better Auth `admin`/`organization` plugins, permission strings (`billing:read`), enum role columns, middleware guards. **Breaks:** renaming a role or permission string (`admin`→`owner`, `post:write`→`posts:create`) breaks every guard checking the old string — silently denying, or granting if a default-allow exists; a new role without seeded permissions is powerless or over-powered. **Detect:** permission-string literals, `hasPermission`/`requireRole`, role enums, `ac.newRole(...)`, seed files. **Safe-change:** centralize permission strings in one module; migrate role assignments on rename; unknown permission = default-deny; grep all enforcement points on any change. _(Own home — the role/permission taxonomy is its own `transcribe` source-of-truth, distinct from the per-object (`object-level-authorization`) and attribute-policy (`abac-policy-engine`) models.)_
 #### `abac-policy-engine` — HIGH · point
-Attribute/condition policies evaluated by an external engine against a structured input. **Where:** OPA/Rego, AWS Cedar/Verified Permissions, Oso, Cerbos. **Breaks:** the engine + caller share an *input schema* (the attributes shipped per decision) — if the app stops sending an attribute the policy relies on, it silently denies (or default-allows); Rego/Cedar semantic changes alter outcomes with no app code change. **Detect:** `.rego`/`.cedar`/Cerbos YAML, OPA `data`/`input` calls, `authorize(input)`, default-decision rules. **Safe-change:** version the decision-input schema + validate before sending; explicit `default allow = false`; deploy policy + app in lockstep on input changes; test missing/null attributes. *(Own home — the external policy + decision-input schema is its own source-of-truth, distinct from `rbac-permission-model` and `object-level-authorization`.)*
+Attribute/condition policies evaluated by an external engine against a structured input. **Where:** OPA/Rego, AWS Cedar/Verified Permissions, Oso, Cerbos. **Breaks:** the engine + caller share an _input schema_ (the attributes shipped per decision) — if the app stops sending an attribute the policy relies on, it silently denies (or default-allows); Rego/Cedar semantic changes alter outcomes with no app code change. **Detect:** `.rego`/`.cedar`/Cerbos YAML, OPA `data`/`input` calls, `authorize(input)`, default-decision rules. **Safe-change:** version the decision-input schema + validate before sending; explicit `default allow = false`; deploy policy + app in lockstep on input changes; test missing/null attributes. _(Own home — the external policy + decision-input schema is its own source-of-truth, distinct from `rbac-permission-model` and `object-level-authorization`.)_
 #### `oauth-oidc-flow` — HIGH · point
-The OAuth2/OIDC flow contract — grant type, PKCE, `state`/`nonce`, token endpoint, provider metadata. **Where:** Better Auth social/OIDC providers, OAuth 2.1 plugin, Auth.js, Keycloak/Auth0/Entra, `.well-known/openid-configuration`. **Breaks:** switching grants (implicit→code+PKCE), dropping `state`/`nonce`, or changing scopes breaks the callback and can reopen CSRF/replay; provider metadata changes (endpoints, algs) silently break the flow. **Detect:** `response_type`/`grant_type`, `code_verifier`/`code_challenge`, `state`/`nonce`, provider config, callback handlers. **Safe-change:** use auth-code + PKCE, enforce `state` + (OIDC) `nonce`; keep scopes + callback URL synced to provider registration; validate the ID token on callback; refresh provider metadata. *(Own home — the grant/flow contract; the callback allowlist (`redirect-uri-allowlist`) and consent records (`consent-scope-grant`) keep their own files.)*
+The OAuth2/OIDC flow contract — grant type, PKCE, `state`/`nonce`, token endpoint, provider metadata. **Where:** Better Auth social/OIDC providers, OAuth 2.1 plugin, Auth.js, Keycloak/Auth0/Entra, `.well-known/openid-configuration`. **Breaks:** switching grants (implicit→code+PKCE), dropping `state`/`nonce`, or changing scopes breaks the callback and can reopen CSRF/replay; provider metadata changes (endpoints, algs) silently break the flow. **Detect:** `response_type`/`grant_type`, `code_verifier`/`code_challenge`, `state`/`nonce`, provider config, callback handlers. **Safe-change:** use auth-code + PKCE, enforce `state` + (OIDC) `nonce`; keep scopes + callback URL synced to provider registration; validate the ID token on callback; refresh provider metadata. _(Own home — the grant/flow contract; the callback allowlist (`redirect-uri-allowlist`) and consent records (`consent-scope-grant`) keep their own files.)_
 #### `redirect-uri-allowlist` — CRITICAL · point
-The set of pre-registered, exact-match redirect/callback URIs an auth server will redirect to. **Where:** OAuth/OIDC client registration, Better Auth `redirectURLs`/`trustedOrigins`, Google/Auth0/Entra app config. **Breaks:** loose matching (wildcard/prefix/regex) enables authorization-code exfiltration + open-redirect token theft; adding a frontend origin without registering its callback silently breaks login. **Detect:** `redirect_uri`/`redirectURLs`/`callbackURL`, wildcard/`startsWith` URI matching, provider registration, `trustedOrigins`. **Safe-change:** exact 1:1 string comparison (no wildcards/regex/prefix); require HTTPS absolute URIs; register every new callback before deploying the client; on unmatched URI, error without redirecting. *(Own home — a CRITICAL security surface kept separate from `oauth-oidc-flow`; cross-ref frontend `deep-link-scheme-contract` for the in-app deep-link overlap.)*
+The set of pre-registered, exact-match redirect/callback URIs an auth server will redirect to. **Where:** OAuth/OIDC client registration, Better Auth `redirectURLs`/`trustedOrigins`, Google/Auth0/Entra app config. **Breaks:** loose matching (wildcard/prefix/regex) enables authorization-code exfiltration + open-redirect token theft; adding a frontend origin without registering its callback silently breaks login. **Detect:** `redirect_uri`/`redirectURLs`/`callbackURL`, wildcard/`startsWith` URI matching, provider registration, `trustedOrigins`. **Safe-change:** exact 1:1 string comparison (no wildcards/regex/prefix); require HTTPS absolute URIs; register every new callback before deploying the client; on unmatched URI, error without redirecting. _(Own home — a CRITICAL security surface kept separate from `oauth-oidc-flow`; cross-ref frontend `deep-link-scheme-contract` for the in-app deep-link overlap.)_
 #### `api-key-auth` — HIGH · point
-Format, storage, scoping, validation of API keys / service tokens for machine-to-machine auth. **Where:** Better Auth `apiKey` plugin, `X-API-Key`, mTLS client certs, signed service JWTs, HMAC request signing. **Breaks:** changing the key prefix, hashing scheme, or scope encoding silently invalidates live integrations or accepts forged keys; plaintext-stored keys turn a DB leak into total compromise; rotating a shared key without a dual-validity window breaks every caller at once. **Detect:** `X-API-Key`/`Authorization: ApiKey`, `apiKey` config, key-hashing code, prefix constants, mTLS/cert config, HMAC verification. **Safe-change:** store hashed + constant-time compare; scope keys least-privilege + tie to a principal; rotate with an overlap window; keep prefix/format stable (changes = migration). *(Own home — the M2M API-key format/storage/scoping is its own source-of-truth.)*
+Format, storage, scoping, validation of API keys / service tokens for machine-to-machine auth. **Where:** Better Auth `apiKey` plugin, `X-API-Key`, mTLS client certs, signed service JWTs, HMAC request signing. **Breaks:** changing the key prefix, hashing scheme, or scope encoding silently invalidates live integrations or accepts forged keys; plaintext-stored keys turn a DB leak into total compromise; rotating a shared key without a dual-validity window breaks every caller at once. **Detect:** `X-API-Key`/`Authorization: ApiKey`, `apiKey` config, key-hashing code, prefix constants, mTLS/cert config, HMAC verification. **Safe-change:** store hashed + constant-time compare; scope keys least-privilege + tie to a principal; rotate with an overlap window; keep prefix/format stable (changes = migration). _(Own home — the M2M API-key format/storage/scoping is its own source-of-truth.)_
 #### `sso-saml-assertion` — HIGH · point
-The SAML SP↔IdP trust contract — assertion signing, `NameID` format, attribute mapping, `entityID`, metadata. **Where:** SAML 2.0 IdPs (Entra, Okta, authentik), SP libraries, metadata XML, signing certs. **Breaks:** if the IdP rotates its signing cert without the SP re-importing metadata, all assertions fail signature validation; changing `NameID` format re-keys identity and can duplicate accounts; renaming an IdP attribute drops role/group mapping. **Detect:** IdP metadata XML/URLs, `entityID`/issuer, `NameIDFormat`, attribute mapping, X.509 fingerprints, ACS URL. **Safe-change:** re-import metadata on cert rotation; pin `NameID` format + key on a stable identifier; validate the signature on the right XML element; keep `entityID`/ACS synced; overlap IdP certs during rotation. *(Own home — the SAML SP↔IdP trust contract is its own source-of-truth, distinct from the OIDC flow.)*
+The SAML SP↔IdP trust contract — assertion signing, `NameID` format, attribute mapping, `entityID`, metadata. **Where:** SAML 2.0 IdPs (Entra, Okta, authentik), SP libraries, metadata XML, signing certs. **Breaks:** if the IdP rotates its signing cert without the SP re-importing metadata, all assertions fail signature validation; changing `NameID` format re-keys identity and can duplicate accounts; renaming an IdP attribute drops role/group mapping. **Detect:** IdP metadata XML/URLs, `entityID`/issuer, `NameIDFormat`, attribute mapping, X.509 fingerprints, ACS URL. **Safe-change:** re-import metadata on cert rotation; pin `NameID` format + key on a stable identifier; validate the signature on the right XML element; keep `entityID`/ACS synced; overlap IdP certs during rotation. _(Own home — the SAML SP↔IdP trust contract is its own source-of-truth, distinct from the OIDC flow.)_
 #### `impersonation` — HIGH · transcribe
-The act-as / admin-assume mechanism + its audit/scope guarantees. **Where:** Better Auth admin `impersonateUser`, support "log in as", Entra `user_impersonation` scope, act-as session claims. **Breaks:** an impersonation session not carrying the *real actor* breaks audit attribution; missing read-only constraints/auto-expiry/separate audit turns support tooling into undetectable privilege escalation. **Detect:** `impersonate`/`actAs`/`onBehalfOf`, `impersonatedBy`/`actorId` session fields, admin-plugin config, impersonation audit writes + TTL. **Safe-change:** carry both real-actor + target identity; log every start/stop to an immutable trail; auto-expire (~30 min) + tightly scope; revoke active sessions on suspicious grants. *(Own home — the act-as mechanism + its audit/scope guarantees are their own source-of-truth.)*
+The act-as / admin-assume mechanism + its audit/scope guarantees. **Where:** Better Auth admin `impersonateUser`, support "log in as", Entra `user_impersonation` scope, act-as session claims. **Breaks:** an impersonation session not carrying the _real actor_ breaks audit attribution; missing read-only constraints/auto-expiry/separate audit turns support tooling into undetectable privilege escalation. **Detect:** `impersonate`/`actAs`/`onBehalfOf`, `impersonatedBy`/`actorId` session fields, admin-plugin config, impersonation audit writes + TTL. **Safe-change:** carry both real-actor + target identity; log every start/stop to an immutable trail; auto-expire (~30 min) + tightly scope; revoke active sessions on suspicious grants. _(Own home — the act-as mechanism + its audit/scope guarantees are their own source-of-truth.)_
 #### `consent-scope-grant` — HIGH · transcribe
-The record of which scopes a user consented to for a client + how it's enforced/revoked. **Where:** OAuth consent screens, Better Auth OAuth provider consent + `oauthAccessToken` scopes, Entra consent grants. **Breaks:** adding a scope to a client without re-prompting silently grants access the user never approved (or fails enforcement); illicit consent grants are an attack vector; no revocation leaves a compromised app with standing access. **Detect:** `scopes`/`scope` columns, consent handlers, `prompt=consent`, consent-grant records, revocation endpoints. **Safe-change:** re-prompt consent when adding scopes; enforce the granted scope set on every token (not just issuance); provide + test revocation propagating to live tokens; audit unusual scope/client pairs. *(Own home — the consent-grant record + enforcement is its own source-of-truth; cross-ref `oauth-oidc-flow` for the scope-issuance flow.)*
+The record of which scopes a user consented to for a client + how it's enforced/revoked. **Where:** OAuth consent screens, Better Auth OAuth provider consent + `oauthAccessToken` scopes, Entra consent grants. **Breaks:** adding a scope to a client without re-prompting silently grants access the user never approved (or fails enforcement); illicit consent grants are an attack vector; no revocation leaves a compromised app with standing access. **Detect:** `scopes`/`scope` columns, consent handlers, `prompt=consent`, consent-grant records, revocation endpoints. **Safe-change:** re-prompt consent when adding scopes; enforce the granted scope set on every token (not just issuance); provide + test revocation propagating to live tokens; audit unusual scope/client pairs. _(Own home — the consent-grant record + enforcement is its own source-of-truth; cross-ref `oauth-oidc-flow` for the scope-issuance flow.)_
 #### `per-identity-rate-limit-quota` — MED · transcribe
-Rate limits + usage quotas keyed per identity/tenant/API-key. **Where:** `express-rate-limit`, Better Auth rate-limit, Redis token-bucket, gateway/Cloudflare per-key limits, plan quotas. **Breaks:** changing the limit *key* (IP→user→tenant) lets one tenant exhaust a shared bucket (noisy-neighbor) or throttles a whole tenant for one user; a non-shared counter store breaks limits across instances. **Detect:** `rateLimit({ keyGenerator })`, Redis `INCR`/token-bucket keys, `windowMs`/`max`, quota tables, `429` handling. **Safe-change:** pick the limit key deliberately + document; shared store (Redis) across instances; keep quota config synced to billing plans; run auth before rate-limit keying. *(Own home — the per-identity rate-limit/quota keying is its own source-of-truth.)*
+Rate limits + usage quotas keyed per identity/tenant/API-key. **Where:** `express-rate-limit`, Better Auth rate-limit, Redis token-bucket, gateway/Cloudflare per-key limits, plan quotas. **Breaks:** changing the limit _key_ (IP→user→tenant) lets one tenant exhaust a shared bucket (noisy-neighbor) or throttles a whole tenant for one user; a non-shared counter store breaks limits across instances. **Detect:** `rateLimit({ keyGenerator })`, Redis `INCR`/token-bucket keys, `windowMs`/`max`, quota tables, `429` handling. **Safe-change:** pick the limit key deliberately + document; shared store (Redis) across instances; keep quota config synced to billing plans; run auth before rate-limit keying. _(Own home — the per-identity rate-limit/quota keying is its own source-of-truth.)_
 #### `encryption-at-rest-key-boundary` — CRITICAL · point
-The boundary between encrypted data, its DEKs, and the KEKs/root keys in a KMS. **Where:** AWS/GCP KMS envelope encryption, field/column-level encryption, Confluent CSFLE. **Breaks:** rotating/losing the KEK without re-wrapping DEKs renders data permanently unreadable; widening who can `Decrypt` silently expands PII access; changing the DEK-per-record scheme breaks decryption of historical data. **Detect:** KMS calls (`GenerateDataKey`/`Decrypt`/`Encrypt`), `keyId`/KEK ARNs, envelope-wrap code, encrypted-column markers, KMS key policies. **Safe-change:** rotate KEKs not DEKs; restrict `Decrypt` least-privilege + audit; store `keyId`/version with ciphertext; never drop a KEK while any DEK is wrapped under it. *(Own home — the KEK/DEK/KMS key hierarchy is its own source-of-truth; cross-ref config `secrets-management` for non-data secrets.)*
+The boundary between encrypted data, its DEKs, and the KEKs/root keys in a KMS. **Where:** AWS/GCP KMS envelope encryption, field/column-level encryption, Confluent CSFLE. **Breaks:** rotating/losing the KEK without re-wrapping DEKs renders data permanently unreadable; widening who can `Decrypt` silently expands PII access; changing the DEK-per-record scheme breaks decryption of historical data. **Detect:** KMS calls (`GenerateDataKey`/`Decrypt`/`Encrypt`), `keyId`/KEK ARNs, envelope-wrap code, encrypted-column markers, KMS key policies. **Safe-change:** rotate KEKs not DEKs; restrict `Decrypt` least-privilege + audit; store `keyId`/version with ciphertext; never drop a KEK while any DEK is wrapped under it. _(Own home — the KEK/DEK/KMS key hierarchy is its own source-of-truth; cross-ref config `secrets-management` for non-data secrets.)_
 #### `pii-classification` — HIGH · transcribe
-Labeling of which fields are PII/PHI/financial + the handling rules (encryption, masking, logging, retention) it drives. **Where:** classification tags in schema, masking middleware, `pino` redact paths, DLP rules, retention policies. **Breaks:** adding a PII field without classifying it lets it flow into logs/analytics/unencrypted columns; changing what counts as PII without updating redaction/encryption opens a quiet leak — classification is the input *other* boundaries consume. **Detect:** `pino` `redact`, masking utils, classification tags, encrypted-column lists, DLP/retention config, log statements emitting user fields. **Safe-change:** classify every new personal-data field at schema time; wire classification to redaction + encryption + retention; re-audit redaction on rename/add; one canonical classification source. *(Own home — the PII/PHI classification is the input other boundaries consume (encryption, masking, logging, retention); keep it canonical and singular.)*
+Labeling of which fields are PII/PHI/financial + the handling rules (encryption, masking, logging, retention) it drives. **Where:** classification tags in schema, masking middleware, `pino` redact paths, DLP rules, retention policies. **Breaks:** adding a PII field without classifying it lets it flow into logs/analytics/unencrypted columns; changing what counts as PII without updating redaction/encryption opens a quiet leak — classification is the input _other_ boundaries consume. **Detect:** `pino` `redact`, masking utils, classification tags, encrypted-column lists, DLP/retention config, log statements emitting user fields. **Safe-change:** classify every new personal-data field at schema time; wire classification to redaction + encryption + retention; re-audit redaction on rename/add; one canonical classification source. _(Own home — the PII/PHI classification is the input other boundaries consume (encryption, masking, logging, retention); keep it canonical and singular.)_
 #### `account-linking-identity-resolution` — HIGH · point
-The rule merging multiple credentials (social + password, multiple IdPs) into one user. **Where:** Better Auth `account` table + `accountLinking` config, OAuth `provider`+`providerAccountId`, email-based auto-linking. **Breaks:** auto-linking by *unverified* email enables account takeover; changing the linking key (email vs `(provider, providerAccountId)`) silently merges/splits accounts; toggling auto-link changes who can claim an existing account. **Detect:** `account` schema (`providerId`/`accountId`/`userId`), `accountLinking`/`trustedProviders`, email-match merge logic, find-or-create handlers. **Safe-change:** only auto-link on a *verified* email from trusted providers; key external identities on `(provider, providerAccountId)` not email; require re-auth before merging; audit linking-config changes. *(Own home — the credential-merge/identity-resolution rule is its own source-of-truth.)*
+The rule merging multiple credentials (social + password, multiple IdPs) into one user. **Where:** Better Auth `account` table + `accountLinking` config, OAuth `provider`+`providerAccountId`, email-based auto-linking. **Breaks:** auto-linking by _unverified_ email enables account takeover; changing the linking key (email vs `(provider, providerAccountId)`) silently merges/splits accounts; toggling auto-link changes who can claim an existing account. **Detect:** `account` schema (`providerId`/`accountId`/`userId`), `accountLinking`/`trustedProviders`, email-match merge logic, find-or-create handlers. **Safe-change:** only auto-link on a _verified_ email from trusted providers; key external identities on `(provider, providerAccountId)` not email; require re-auth before merging; audit linking-config changes. _(Own home — the credential-merge/identity-resolution rule is its own source-of-truth.)_
 #### `mfa-step-up-contract` — HIGH · point
-Which actions require MFA, the factor types, and how "verified-recently" is represented. **Where:** Better Auth `twoFactor`/`passkey`, TOTP/WebAuthn, `amr`/`acr` claims, AAL levels, step-up gates. **Breaks:** a sensitive endpoint checking "is authenticated" but not "passed MFA / recently re-verified" silently allows it without step-up; changing the factor, freshness window, or `acr`/`amr` claim names weakens/breaks the gate. **Detect:** `twoFactor`/`webauthn`/`passkey` config, `acr`/`amr`/`aal` reads, step-up/`requireFreshSession` guards, `mfa_verified_at` fields. **Safe-change:** gate sensitive actions on factor level + recency, not just "logged in"; keep `acr`/`amr`/AAL names stable; enforce a freshness window; recovery factors without weakening the primary gate. *(Own home — the MFA/step-up gate + freshness representation is its own source-of-truth.)*
+Which actions require MFA, the factor types, and how "verified-recently" is represented. **Where:** Better Auth `twoFactor`/`passkey`, TOTP/WebAuthn, `amr`/`acr` claims, AAL levels, step-up gates. **Breaks:** a sensitive endpoint checking "is authenticated" but not "passed MFA / recently re-verified" silently allows it without step-up; changing the factor, freshness window, or `acr`/`amr` claim names weakens/breaks the gate. **Detect:** `twoFactor`/`webauthn`/`passkey` config, `acr`/`amr`/`aal` reads, step-up/`requireFreshSession` guards, `mfa_verified_at` fields. **Safe-change:** gate sensitive actions on factor level + recency, not just "logged in"; keep `acr`/`amr`/AAL names stable; enforce a freshness window; recovery factors without weakening the primary gate. _(Own home — the MFA/step-up gate + freshness representation is its own source-of-truth.)_
 #### `service-account-workload-identity` — HIGH · point
-Non-human principal identity — service accounts, workload-identity federation, instance/pod IAM roles — + the trust minting their tokens. **Where:** K8s ServiceAccount/OIDC, GCP workload identity, AWS IRSA/instance profiles, SPIFFE/SPIRE, GitHub Actions OIDC. **Breaks:** changing a workload token's audience/subject, or the trust-policy `sub`/`aud` condition (e.g. GitHub `repo:org/name:ref`), silently breaks federation or — if loosened — lets an untrusted workload assume the role. **Detect:** IAM trust policies with OIDC conditions, `audience`/`sub` conditions, K8s `serviceAccountName`, SPIFFE IDs, workload-identity-pool config. **Safe-change:** scope trust conditions tightly (avoid wildcards); keep token audience synced between issuer + trusting resource; short-TTL tokens; review trust edits as privilege-grant changes. *(Own home — non-human workload identity + its trust-minting is its own source-of-truth, distinct from human-user credential contracts.)*
+Non-human principal identity — service accounts, workload-identity federation, instance/pod IAM roles — + the trust minting their tokens. **Where:** K8s ServiceAccount/OIDC, GCP workload identity, AWS IRSA/instance profiles, SPIFFE/SPIRE, GitHub Actions OIDC. **Breaks:** changing a workload token's audience/subject, or the trust-policy `sub`/`aud` condition (e.g. GitHub `repo:org/name:ref`), silently breaks federation or — if loosened — lets an untrusted workload assume the role. **Detect:** IAM trust policies with OIDC conditions, `audience`/`sub` conditions, K8s `serviceAccountName`, SPIFFE IDs, workload-identity-pool config. **Safe-change:** scope trust conditions tightly (avoid wildcards); keep token audience synced between issuer + trusting resource; short-TTL tokens; review trust edits as privilege-grant changes. _(Own home — non-human workload identity + its trust-minting is its own source-of-truth, distinct from human-user credential contracts.)_
 #### `password-credential-policy` — HIGH · point
-The password hashing scheme + credential-handling rules (algorithm, params, breach checks, reset-token shape). **Where:** Better Auth `emailAndPassword` (scrypt default) / custom `password.hash`, argon2/bcrypt, reset/verification token tables. **Breaks:** changing the hash algorithm/params without a rehash-on-verify path silently locks out every existing user; weakening params lowers crack resistance; reset/verification-token shape + TTL is its own contract. **Detect:** `password.hash`/`verify` config, argon2/bcrypt/scrypt imports, credential columns, reset-token tables + TTL. **Safe-change:** rehash transparently on next login when changing algorithm; params ≥ current OWASP guidance; reset/verification tokens single-use + expiring; never log raw credentials/reset tokens. *(Own home — the password-hashing scheme + credential-handling rules are their own source-of-truth.)*
+The password hashing scheme + credential-handling rules (algorithm, params, breach checks, reset-token shape). **Where:** Better Auth `emailAndPassword` (scrypt default) / custom `password.hash`, argon2/bcrypt, reset/verification token tables. **Breaks:** changing the hash algorithm/params without a rehash-on-verify path silently locks out every existing user; weakening params lowers crack resistance; reset/verification-token shape + TTL is its own contract. **Detect:** `password.hash`/`verify` config, argon2/bcrypt/scrypt imports, credential columns, reset-token tables + TTL. **Safe-change:** rehash transparently on next login when changing algorithm; params ≥ current OWASP guidance; reset/verification tokens single-use + expiring; never log raw credentials/reset tokens. _(Own home — the password-hashing scheme + credential-handling rules are their own source-of-truth.)_
 ---
 ## 5 · ASYNCHRONOUS & MESSAGING
-> The CRITICAL tier here (`event-schema`, `cdc-stream-contract`,
-> `workflow-determinism-contract`, `schema-registry-contract`) shares one trait:
-> failure breaks **persisted / in-flight / replayed** state — silent *and*
-> historical, not just live. The universal defense: producer/consumer version
-> skew survives a rolling deploy only if payloads are additive + versioned and
-> both sides share one validated schema.
+> The CRITICAL tier here (`event-schema`, `cdc-stream-contract`, `workflow-determinism-contract`, `schema-registry-contract`) shares one trait: failure breaks **persisted / in-flight / replayed** state — silent _and_ historical, not just live. The universal defense: producer/consumer version skew survives a rolling deploy only if payloads are additive + versioned and both sides share one validated schema.
 #### `message-queue-payload` — HIGH · transcribe
-The shape of a job/message body enqueued by a producer + deserialized by a worker. **Where:** BullMQ/Bull (`queue.add`→`Worker`), Redis streams, SQS, RabbitMQ, Kafka, Sidekiq/Celery. **Breaks:** producer + consumer deploy/version independently — add/rename/retype a field and **in-flight jobs already on the queue** carry the old shape while the new worker expects the new (or vice versa during rolling deploys); JSON has no queue-layer schema enforcement. **Detect:** `queue.add(`, `new Queue(`/`new Worker(`, `.process(`, `sqs.sendMessage`, `channel.sendToQueue`, a shared DTO imported by both sides (absent = high-risk). **Safe-change:** payload changes additive (optional + default); tag with `schemaVersion` the worker branches on, or drain before a breaking change; share one validated schema validated on enqueue AND dequeue; account for the mixed-version deploy window. *(Canonical home for the job/message-body contract (`transcribe`) — `job-name-contract` keeps its own file (the routing string, `point`).)*
+The shape of a job/message body enqueued by a producer + deserialized by a worker. **Where:** BullMQ/Bull (`queue.add`→`Worker`), Redis streams, SQS, RabbitMQ, Kafka, Sidekiq/Celery. **Breaks:** producer + consumer deploy/version independently — add/rename/retype a field and **in-flight jobs already on the queue** carry the old shape while the new worker expects the new (or vice versa during rolling deploys); JSON has no queue-layer schema enforcement. **Detect:** `queue.add(`, `new Queue(`/`new Worker(`, `.process(`, `sqs.sendMessage`, `channel.sendToQueue`, a shared DTO imported by both sides (absent = high-risk). **Safe-change:** payload changes additive (optional + default); tag with `schemaVersion` the worker branches on, or drain before a breaking change; share one validated schema validated on enqueue AND dequeue; account for the mixed-version deploy window. _(Canonical home for the job/message-body contract (`transcribe`) — `job-name-contract` keeps its own file (the routing string, `point`).)_
 #### `job-name-contract` — MED · point
-The string job/task name routing a queued item to a processor. **Where:** BullMQ named jobs (`job.name`), Celery task names, Sidekiq classes, Temporal Activity Type names. **Breaks:** rename the job string on the producer without the worker and the job lands in the queue but **no processor matches** — it sits unprocessed or hits a default/throw; the compiler sees two unrelated literals. **Detect:** the literal on both sides, `switch (job.name)`, `@Process('name')`. **Safe-change:** centralize names in a shared enum; on rename, handle both old + new until the old queue drains; assert an exhaustive handler (default throws/logs). *(Own home — the job-routing string is `point`, a different doc-mode from the `transcribe` payload `message-queue-payload`, so it files separately.)*
+The string job/task name routing a queued item to a processor. **Where:** BullMQ named jobs (`job.name`), Celery task names, Sidekiq classes, Temporal Activity Type names. **Breaks:** rename the job string on the producer without the worker and the job lands in the queue but **no processor matches** — it sits unprocessed or hits a default/throw; the compiler sees two unrelated literals. **Detect:** the literal on both sides, `switch (job.name)`, `@Process('name')`. **Safe-change:** centralize names in a shared enum; on rename, handle both old + new until the old queue drains; assert an exhaustive handler (default throws/logs). _(Own home — the job-routing string is `point`, a different doc-mode from the `transcribe` payload `message-queue-payload`, so it files separately.)_
 #### `event-schema` — CRITICAL · transcribe
-A domain/integration event's fields/types/semantics shared between one publisher and many subscribers. **Where:** Kafka topics, NATS subjects, EventBridge, Redis pub/sub, event-sourced domain events, the `@nurix/chat` wire envelope. **Breaks:** a breaking field change ripples to every subscriber, each failing at different deploy times; events are often **persisted** (event store/Kafka log) so old-shape events must remain readable forever (replay). **Detect:** `emit(`/`publish(`, topic/subject constants, event-type discriminators (`type`/`eventType`), `*.avsc`/`*.proto`/`events/*.ts`. **Safe-change:** events are append-only — add fields, never remove/retype; new variants get new discriminators; keep old-version deserialization while old events exist; carry an explicit `version`; use a schema registry / shared package with CI compatibility checks. *(Canonical home for the domain/integration event shape (`transcribe`) — `command-event-boundary` folds in (the CQRS command/event split over the same events); `topic-subject-naming` keeps its own file (the rendezvous string, `point`); cross-ref `schema-registry-contract` when a registry enforces it.)*
+A domain/integration event's fields/types/semantics shared between one publisher and many subscribers. **Where:** Kafka topics, NATS subjects, EventBridge, Redis pub/sub, event-sourced domain events, the `@nurix/chat` wire envelope. **Breaks:** a breaking field change ripples to every subscriber, each failing at different deploy times; events are often **persisted** (event store/Kafka log) so old-shape events must remain readable forever (replay). **Detect:** `emit(`/`publish(`, topic/subject constants, event-type discriminators (`type`/`eventType`), `*.avsc`/`*.proto`/`events/*.ts`. **Safe-change:** events are append-only — add fields, never remove/retype; new variants get new discriminators; keep old-version deserialization while old events exist; carry an explicit `version`; use a schema registry / shared package with CI compatibility checks. _(Canonical home for the domain/integration event shape (`transcribe`) — `command-event-boundary` folds in (the CQRS command/event split over the same events); `topic-subject-naming` keeps its own file (the rendezvous string, `point`); cross-ref `schema-registry-contract` when a registry enforces it.)_
 #### `topic-subject-naming` — HIGH · point
-The string identifying a topic/subject/exchange/routing-key/channel producers write to and consumers subscribe to. **Where:** Kafka topics, NATS subjects (wildcards), RabbitMQ exchange + routing keys, MQTT, Debezium CDC topics, SNS ARNs, Redis pub/sub channels. **Breaks:** the string is the rendezvous point — renaming a topic, changing an env prefix, or altering a routing-key wildcard makes producers/consumers silently stop meeting (publish into the void); Debezium derives topic names from table names, so a table rename relocates the stream. **Detect:** topic/subject literals, `subscribe(`, `routingKey`, `bindQueue`, `topic.prefix`, `KAFKA_TOPIC_PREFIX`. **Safe-change:** centralize names + derive env prefixes from one helper; dual-publish to old + new on rename; pin Debezium/CDC topic naming explicitly; verify wildcard patterns after segment changes. *(Own home — the topic/subject rendezvous string is `point`, a different doc-mode from the `transcribe` `event-schema`, so it files separately.)*
+The string identifying a topic/subject/exchange/routing-key/channel producers write to and consumers subscribe to. **Where:** Kafka topics, NATS subjects (wildcards), RabbitMQ exchange + routing keys, MQTT, Debezium CDC topics, SNS ARNs, Redis pub/sub channels. **Breaks:** the string is the rendezvous point — renaming a topic, changing an env prefix, or altering a routing-key wildcard makes producers/consumers silently stop meeting (publish into the void); Debezium derives topic names from table names, so a table rename relocates the stream. **Detect:** topic/subject literals, `subscribe(`, `routingKey`, `bindQueue`, `topic.prefix`, `KAFKA_TOPIC_PREFIX`. **Safe-change:** centralize names + derive env prefixes from one helper; dual-publish to old + new on rename; pin Debezium/CDC topic naming explicitly; verify wildcard patterns after segment changes. _(Own home — the topic/subject rendezvous string is `point`, a different doc-mode from the `transcribe` `event-schema`, so it files separately.)_
 #### `command-event-boundary` — HIGH · transcribe
-The CQRS split: commands (imperative, single handler, may reject) vs events (factual, past-tense, fan-out), and each one's contract. **Where:** CQRS/event-sourced systems, Axon, EventStoreDB, Kafka command/event topics, NestJS CQRS. **Breaks:** mislabeling or reshaping one breaks read-model projections (events) or write-side validation (commands); read models rebuild by replaying events, so an event-contract change corrupts every projection. **Detect:** `commands/`/`events/`, `*Command`/`*Event`, `CommandHandler`/`EventHandler`, `aggregate.apply(`, past-tense vs imperative naming. **Safe-change:** events immutable + additive (version, don't mutate); projections handle old versions (upcasting); don't conflate command + event shapes; test projection rebuild from the full stream. *(Folds into `event-schema` — same event source-of-truth, same `transcribe` doc-mode; the CQRS command/event split facet. Stands alone in a dedicated CQRS module.)*
+The CQRS split: commands (imperative, single handler, may reject) vs events (factual, past-tense, fan-out), and each one's contract. **Where:** CQRS/event-sourced systems, Axon, EventStoreDB, Kafka command/event topics, NestJS CQRS. **Breaks:** mislabeling or reshaping one breaks read-model projections (events) or write-side validation (commands); read models rebuild by replaying events, so an event-contract change corrupts every projection. **Detect:** `commands/`/`events/`, `*Command`/`*Event`, `CommandHandler`/`EventHandler`, `aggregate.apply(`, past-tense vs imperative naming. **Safe-change:** events immutable + additive (version, don't mutate); projections handle old versions (upcasting); don't conflate command + event shapes; test projection rebuild from the full stream. _(Folds into `event-schema` — same event source-of-truth, same `transcribe` doc-mode; the CQRS command/event split facet. Stands alone in a dedicated CQRS module.)_
 #### `cdc-stream-contract` — CRITICAL · point
-A change-data-capture stream's row-shape envelope (before/after/op), topic mapping, and source DB schema downstream consumers depend on. **Where:** Debezium, Kafka Connect, AWS DMS, Postgres logical replication, Snowflake Streams, Materialize. **Breaks:** the stream's shape is **derived from the source DB schema** owned by a different team that may not know consumers exist — a column rename/type change/table rename silently reshapes or relocates the stream; the DB migration looks innocuous on the producing side. **Detect:** `debezium`, connector JSON, `slot.name`, `publication`, `REPLICA IDENTITY`, `transforms` SMT, `before`/`after`/`op` envelope fields, `pgoutput`. **Safe-change:** treat CDC-source columns as a published contract + coordinate migrations with consumers; pin topic routing + `REPLICA IDENTITY`; schema-registry with compatibility enforcement; dual-emit before dropping. *(Own home — the CDC stream envelope is its own source-of-truth (derived from, but distinct from, `db-schema`); cross-ref `schema-registry-contract` when a registry enforces it.)*
+A change-data-capture stream's row-shape envelope (before/after/op), topic mapping, and source DB schema downstream consumers depend on. **Where:** Debezium, Kafka Connect, AWS DMS, Postgres logical replication, Snowflake Streams, Materialize. **Breaks:** the stream's shape is **derived from the source DB schema** owned by a different team that may not know consumers exist — a column rename/type change/table rename silently reshapes or relocates the stream; the DB migration looks innocuous on the producing side. **Detect:** `debezium`, connector JSON, `slot.name`, `publication`, `REPLICA IDENTITY`, `transforms` SMT, `before`/`after`/`op` envelope fields, `pgoutput`. **Safe-change:** treat CDC-source columns as a published contract + coordinate migrations with consumers; pin topic routing + `REPLICA IDENTITY`; schema-registry with compatibility enforcement; dual-emit before dropping. _(Own home — the CDC stream envelope is its own source-of-truth (derived from, but distinct from, `db-schema`); cross-ref `schema-registry-contract` when a registry enforces it.)_
 #### `cron-schedule-contract` — MED · point
-A scheduled job's cron expression/interval, timezone assumption, expected frequency, and the idempotency that frequency implies. **Where:** BullMQ repeatable jobs/`JobScheduler`, node-cron, Temporal Schedules, K8s CronJobs, EventBridge Scheduler, Cloudflare Cron Triggers, GitHub Actions `schedule`, pg_cron. **Breaks:** the schedule string + job logic are an implicit contract — tightening "daily"→"hourly" duplicates side effects; a timezone (UTC vs local) shift changes the run instant; BullMQ repeat-key changes spawn duplicate schedulers; DST silently shifts run times. **Detect:** cron strings, `repeat: { pattern/every }`, `Cron(`, `schedule:`, `kind: CronJob`, `ScheduleExpression`, `tz`/`timezone`, `[triggers] crons`. **Safe-change:** make jobs idempotent so frequency/overlap changes don't double-apply; pin + document timezone (prefer UTC, account for DST); remove the old repeatable job when changing a BullMQ repeat key; add overlap guards. *(Canonical home for the cron contract — runtime `cron-timezone-contract` folds in (the scheduler-TZ/infra facet of the same schedule).)*
+A scheduled job's cron expression/interval, timezone assumption, expected frequency, and the idempotency that frequency implies. **Where:** BullMQ repeatable jobs/`JobScheduler`, node-cron, Temporal Schedules, K8s CronJobs, EventBridge Scheduler, Cloudflare Cron Triggers, GitHub Actions `schedule`, pg_cron. **Breaks:** the schedule string + job logic are an implicit contract — tightening "daily"→"hourly" duplicates side effects; a timezone (UTC vs local) shift changes the run instant; BullMQ repeat-key changes spawn duplicate schedulers; DST silently shifts run times. **Detect:** cron strings, `repeat: { pattern/every }`, `Cron(`, `schedule:`, `kind: CronJob`, `ScheduleExpression`, `tz`/`timezone`, `[triggers] crons`. **Safe-change:** make jobs idempotent so frequency/overlap changes don't double-apply; pin + document timezone (prefer UTC, account for DST); remove the old repeatable job when changing a BullMQ repeat key; add overlap guards. _(Canonical home for the cron contract — runtime `cron-timezone-contract` folds in (the scheduler-TZ/infra facet of the same schedule).)_
 #### `workflow-determinism-contract` — CRITICAL · point
-The requirement that workflow code replays deterministically against persisted event history, making any logic change a versioning event. **Where:** Temporal, Cadence, Step Functions, Azure Durable Functions, Restate, Inngest. **Breaks:** a running workflow's state is reconstructed by **replaying its history** through current code — adding/removing/reordering an `await` on a command-producing API, changing branching, or reordering activities makes replay diverge → non-determinism error on already-running workflows; the change passes new-workflow tests but bricks in-flight executions. **Detect:** `proxyActivities`, `executeActivity`, `workflow.sleep`, `condition(`, `patched(`/`getVersion(`, `defineSignal`/`defineQuery`, Worker Versioning Build IDs, task queue names. **Safe-change:** gate logic changes with `patched()`/`getVersion()` (or Build IDs) so old histories replay on old code; keep I/O/randomness/time in Activities; replay against real production histories in CI; don't remove a patch marker until pre-patch workflows complete. *(Canonical home for the workflow contract (`point`) — `workflow-signal-query-contract` and `workflow-activity-contract` fold in (the signal/query and activity surfaces of the same worker), unless the repo files them separately.)* *(This repo ran Temporal — project memory notes the cf-realtime migration away from it.)*
+The requirement that workflow code replays deterministically against persisted event history, making any logic change a versioning event. **Where:** Temporal, Cadence, Step Functions, Azure Durable Functions, Restate, Inngest. **Breaks:** a running workflow's state is reconstructed by **replaying its history** through current code — adding/removing/reordering an `await` on a command-producing API, changing branching, or reordering activities makes replay diverge → non-determinism error on already-running workflows; the change passes new-workflow tests but bricks in-flight executions. **Detect:** `proxyActivities`, `executeActivity`, `workflow.sleep`, `condition(`, `patched(`/`getVersion(`, `defineSignal`/`defineQuery`, Worker Versioning Build IDs, task queue names. **Safe-change:** gate logic changes with `patched()`/`getVersion()` (or Build IDs) so old histories replay on old code; keep I/O/randomness/time in Activities; replay against real production histories in CI; don't remove a patch marker until pre-patch workflows complete. _(Canonical home for the workflow contract (`point`) — `workflow-signal-query-contract` and `workflow-activity-contract` fold in (the signal/query and activity surfaces of the same worker), unless the repo files them separately.)_ _(This repo ran Temporal — project memory notes the cf-realtime migration away from it.)_
 #### `workflow-signal-query-contract` — HIGH · point
-Names + arg/return shapes of Temporal Signals (async input), Queries (sync read), Updates external callers send into a running workflow. **Where:** Temporal `defineSignal`/`defineQuery`/`defineUpdate`, Cadence signals, Durable Functions external events. **Breaks:** rename a signal or change its args and senders silently send signals **no handler matches** (dropped) or with the wrong shape; workflows already running with the old registration won't see the new name. **Detect:** `defineSignal('name')`, `setHandler(`, `workflow.signal(`, `handle.query(`, name literals on both sides. **Safe-change:** centralize signal/query/update names + arg types in a shared module; add new names alongside old (keep old handlers until pre-change workflows finish); validate arg shapes in the handler; version payloads like event schemas. *(Folds into `workflow-determinism-contract` — same workflow-worker source-of-truth, same `point` doc-mode; the signal/query/update surface.)*
+Names + arg/return shapes of Temporal Signals (async input), Queries (sync read), Updates external callers send into a running workflow. **Where:** Temporal `defineSignal`/`defineQuery`/`defineUpdate`, Cadence signals, Durable Functions external events. **Breaks:** rename a signal or change its args and senders silently send signals **no handler matches** (dropped) or with the wrong shape; workflows already running with the old registration won't see the new name. **Detect:** `defineSignal('name')`, `setHandler(`, `workflow.signal(`, `handle.query(`, name literals on both sides. **Safe-change:** centralize signal/query/update names + arg types in a shared module; add new names alongside old (keep old handlers until pre-change workflows finish); validate arg shapes in the handler; version payloads like event schemas. _(Folds into `workflow-determinism-contract` — same workflow-worker source-of-truth, same `point` doc-mode; the signal/query/update surface.)_
 #### `workflow-activity-contract` — HIGH · point
-The Activity Type name + input/output shapes + timeout/retry policy between a workflow and its activity worker. **Where:** Temporal/Cadence Activities, Step Functions tasks, Durable Functions activities. **Breaks:** activities run on separately-deployed workers polling a task queue — change an activity's shape or rename its type and workflows scheduling the old shape hit workers expecting the new (or "activity not registered"); changing retry/timeout changes failure semantics the workflow assumes. **Detect:** `proxyActivities<…>`, `@activityMethod`, `registerActivities`, `ActivityOptions`, `startToCloseTimeout`, `RetryPolicy`, activity-type + task-queue constants. **Safe-change:** share activity input/output types via one interface module; register new versions before removing old (keep old workers until old workflows drain); treat timeout/retry as part of the contract. *(Folds into `workflow-determinism-contract` — same workflow-worker source-of-truth, same `point` doc-mode; the activity-type surface.)*
+The Activity Type name + input/output shapes + timeout/retry policy between a workflow and its activity worker. **Where:** Temporal/Cadence Activities, Step Functions tasks, Durable Functions activities. **Breaks:** activities run on separately-deployed workers polling a task queue — change an activity's shape or rename its type and workflows scheduling the old shape hit workers expecting the new (or "activity not registered"); changing retry/timeout changes failure semantics the workflow assumes. **Detect:** `proxyActivities<…>`, `@activityMethod`, `registerActivities`, `ActivityOptions`, `startToCloseTimeout`, `RetryPolicy`, activity-type + task-queue constants. **Safe-change:** share activity input/output types via one interface module; register new versions before removing old (keep old workers until old workflows drain); treat timeout/retry as part of the contract. _(Folds into `workflow-determinism-contract` — same workflow-worker source-of-truth, same `point` doc-mode; the activity-type surface.)_
 #### `delivery-semantics-contract` — HIGH · transcribe
-The shared assumption about delivery guarantee — at-most-once / at-least-once / effectively-once — between the messaging layer and the handler. **Where:** SQS standard vs FIFO, Kafka (at-least-once default; EOS with transactions), RabbitMQ acks, NATS JetStream, BullMQ. **Breaks:** a handler assuming exactly-once on an at-least-once queue double-applies side effects; switching a queue type (FIFO→standard, Kafka EOS on/off) silently flips the guarantee under handlers assuming the old; auto-ack vs manual-ack changes whether a crash loses or redelivers. **Detect:** `.fifo` suffix, `ContentBasedDeduplication`, `enable.idempotence`/`isolation.level=read_committed`, `noAck`/`autoAck`, `visibilityTimeout`. **Safe-change:** make handlers idempotent regardless of the claimed guarantee (assume at-least-once); document the guarantee + re-audit on queue-type change; treat manual-ack/visibility-timeout as contract. *(Own home — the delivery-guarantee assumption is its own transcribed contract.)*
+The shared assumption about delivery guarantee — at-most-once / at-least-once / effectively-once — between the messaging layer and the handler. **Where:** SQS standard vs FIFO, Kafka (at-least-once default; EOS with transactions), RabbitMQ acks, NATS JetStream, BullMQ. **Breaks:** a handler assuming exactly-once on an at-least-once queue double-applies side effects; switching a queue type (FIFO→standard, Kafka EOS on/off) silently flips the guarantee under handlers assuming the old; auto-ack vs manual-ack changes whether a crash loses or redelivers. **Detect:** `.fifo` suffix, `ContentBasedDeduplication`, `enable.idempotence`/`isolation.level=read_committed`, `noAck`/`autoAck`, `visibilityTimeout`. **Safe-change:** make handlers idempotent regardless of the claimed guarantee (assume at-least-once); document the guarantee + re-audit on queue-type change; treat manual-ack/visibility-timeout as contract. _(Own home — the delivery-guarantee assumption is its own transcribed contract.)_
 #### `message-ordering-partition-key` — HIGH · point
-The key/strategy determining ordering + which partition/shard/group a message lands in. **Where:** Kafka partition key, SQS FIFO `MessageGroupId`, Kinesis partition key, RabbitMQ consistent-hash, Pub/Sub ordering keys. **Breaks:** ordering is only guaranteed *within* a partition/group — changing the key derivation scatters related messages across partitions, silently losing ordering (events processed out of order corrupt state machines); changing partition *count* also remaps keys. **Detect:** `partitionKey`, `MessageGroupId`, `key:` in `producer.send`, `partitioner`, `num.partitions`, consumers assuming sequential per-entity processing. **Safe-change:** keep the partition/group key stable + document the entity it orders by; avoid changing partition count for keyed topics (plan a re-key migration); verify consumers don't assume cross-partition global ordering. *(Own home — the ordering/partition-key strategy is its own source-of-truth.)*
+The key/strategy determining ordering + which partition/shard/group a message lands in. **Where:** Kafka partition key, SQS FIFO `MessageGroupId`, Kinesis partition key, RabbitMQ consistent-hash, Pub/Sub ordering keys. **Breaks:** ordering is only guaranteed _within_ a partition/group — changing the key derivation scatters related messages across partitions, silently losing ordering (events processed out of order corrupt state machines); changing partition _count_ also remaps keys. **Detect:** `partitionKey`, `MessageGroupId`, `key:` in `producer.send`, `partitioner`, `num.partitions`, consumers assuming sequential per-entity processing. **Safe-change:** keep the partition/group key stable + document the entity it orders by; avoid changing partition count for keyed topics (plan a re-key migration); verify consumers don't assume cross-partition global ordering. _(Own home — the ordering/partition-key strategy is its own source-of-truth.)_
 #### `outbox-pattern-contract` — HIGH · point
-The contract making local DB writes + message publishing atomic via an outbox table a relay publishes. **Where:** transactional outbox with Debezium/polling relays, Kafka Connect outbox SMT, NestJS/Spring outbox libs. **Breaks:** the outbox **table schema** is the contract between the writing transaction + the relay — changing columns (aggregate id/type/payload/sequence) breaks the relay's row→message mapping; events go nowhere; the relay also encodes the event-schema contract (inherits its risks). **Detect:** `outbox`/`event_outbox` tables, outbox SMT config, relay polling (`WHERE published = false`), `aggregateid`/`payload` columns, Debezium event router. **Safe-change:** treat the outbox schema as co-owned by writer + relay; columns additive + keep relay mapping synced; preserve ordering/sequence columns; test committed-write → published-message end-to-end. *(Own home — the outbox-table schema is co-owned by writer + relay, its own source-of-truth; cross-ref `event-schema` (the relay also encodes it).)*
+The contract making local DB writes + message publishing atomic via an outbox table a relay publishes. **Where:** transactional outbox with Debezium/polling relays, Kafka Connect outbox SMT, NestJS/Spring outbox libs. **Breaks:** the outbox **table schema** is the contract between the writing transaction + the relay — changing columns (aggregate id/type/payload/sequence) breaks the relay's row→message mapping; events go nowhere; the relay also encodes the event-schema contract (inherits its risks). **Detect:** `outbox`/`event_outbox` tables, outbox SMT config, relay polling (`WHERE published = false`), `aggregateid`/`payload` columns, Debezium event router. **Safe-change:** treat the outbox schema as co-owned by writer + relay; columns additive + keep relay mapping synced; preserve ordering/sequence columns; test committed-write → published-message end-to-end. _(Own home — the outbox-table schema is co-owned by writer + relay, its own source-of-truth; cross-ref `event-schema` (the relay also encodes it).)_
 #### `saga-step-contract` — HIGH · transcribe
-The ordered sequence of local transactions + their compensating (undo) transactions, plus the events/commands linking each step. **Where:** orchestration sagas (Temporal/orchestrator) + choreography sagas, Axon Saga, MassTransit, Camunda/Zeebe. **Breaks:** each forward step implies a compensation contract — adding/reordering a step without adjusting its compensation leaves a mid-saga failure **partially committed with no rollback** (money reserved never released); the compensation + linking event/command names are an invisible cross-service contract. **Detect:** `compensate`/`Saga`/`@SagaStep`/`compensation`, orchestrator state machines, choreography handlers triggering the next step, Temporal try/catch + rollback activities. **Safe-change:** every new forward step gets its compensating action wired into the failure path; keep compensations idempotent + tolerant of nothing-to-undo; preserve linking event/command names (version them); failure-inject each step. *(Own home — the saga step/compensation sequence is its own source-of-truth.)*
+The ordered sequence of local transactions + their compensating (undo) transactions, plus the events/commands linking each step. **Where:** orchestration sagas (Temporal/orchestrator) + choreography sagas, Axon Saga, MassTransit, Camunda/Zeebe. **Breaks:** each forward step implies a compensation contract — adding/reordering a step without adjusting its compensation leaves a mid-saga failure **partially committed with no rollback** (money reserved never released); the compensation + linking event/command names are an invisible cross-service contract. **Detect:** `compensate`/`Saga`/`@SagaStep`/`compensation`, orchestrator state machines, choreography handlers triggering the next step, Temporal try/catch + rollback activities. **Safe-change:** every new forward step gets its compensating action wired into the failure path; keep compensations idempotent + tolerant of nothing-to-undo; preserve linking event/command names (version them); failure-inject each step. _(Own home — the saga step/compensation sequence is its own source-of-truth.)_
 #### `dead-letter-queue-contract` — MED · point
-Where/when/in-what-shape failed messages route after exhausting retries + who drains/replays them. **Where:** SQS redrive + DLQ, BullMQ failed set, RabbitMQ `x-dead-letter-exchange`, Kafka DLQ topics, Pub/Sub dead-letter topics. **Breaks:** the redrive `maxReceiveCount`, DLQ name, and whether anything monitors/replays it are an implicit contract — changing `maxReceiveCount` or the binding makes poison messages loop forever (no DLQ) or get discarded (DLQ with no consumer); replaying assumes the consumer's payload contract hasn't drifted. **Detect:** `RedrivePolicy`, `maxReceiveCount`, `deadLetterTargetArn`, `x-dead-letter-exchange`, `.dlq` suffix, `getFailed()`, DLQ alarm config. **Safe-change:** pair every queue with a monitored DLQ + alarm/consumer; set `maxReceiveCount` consciously; verify the current consumer accepts replayed (possibly stale) payloads; keep DLQ names stable + namespaced. *(Own home — the redrive/DLQ contract is its own source-of-truth; cross-ref `retry-backoff-contract` (the attempts it exhausts before redrive).)*
+Where/when/in-what-shape failed messages route after exhausting retries + who drains/replays them. **Where:** SQS redrive + DLQ, BullMQ failed set, RabbitMQ `x-dead-letter-exchange`, Kafka DLQ topics, Pub/Sub dead-letter topics. **Breaks:** the redrive `maxReceiveCount`, DLQ name, and whether anything monitors/replays it are an implicit contract — changing `maxReceiveCount` or the binding makes poison messages loop forever (no DLQ) or get discarded (DLQ with no consumer); replaying assumes the consumer's payload contract hasn't drifted. **Detect:** `RedrivePolicy`, `maxReceiveCount`, `deadLetterTargetArn`, `x-dead-letter-exchange`, `.dlq` suffix, `getFailed()`, DLQ alarm config. **Safe-change:** pair every queue with a monitored DLQ + alarm/consumer; set `maxReceiveCount` consciously; verify the current consumer accepts replayed (possibly stale) payloads; keep DLQ names stable + namespaced. _(Own home — the redrive/DLQ contract is its own source-of-truth; cross-ref `retry-backoff-contract` (the attempts it exhausts before redrive).)_
 #### `retry-backoff-contract` — MED · transcribe
-The retry policy — attempts, backoff curve, jitter, what's retryable — between the messaging layer/SDK and the side-effecting handler. **Where:** BullMQ `attempts`/`backoff`, SQS visibility-timeout retries, Temporal `RetryPolicy`, Kafka retry topics, Step Functions retriers. **Breaks:** the handler's side effects must survive the policy — more attempts or shorter backoff multiplies side effects on a non-idempotent handler; a visibility timeout shorter than processing time lets another consumer pick up the same message mid-flight (concurrent duplicate). **Detect:** `attempts:`, `backoff: { type: 'exponential' }`, `RetryPolicy`, `maximumAttempts`, `visibilityTimeout`, `nonRetryableErrorTypes`. **Safe-change:** keep visibility/lock timeout > worst-case processing; classify retryable vs terminal explicitly (don't retry validation failures); re-verify idempotency when attempts/backoff change; jitter to avoid thundering herds. *(Own home — the retry/backoff policy is its own source-of-truth; cross-ref `dead-letter-queue-contract` (the terminal redrive).)*
+The retry policy — attempts, backoff curve, jitter, what's retryable — between the messaging layer/SDK and the side-effecting handler. **Where:** BullMQ `attempts`/`backoff`, SQS visibility-timeout retries, Temporal `RetryPolicy`, Kafka retry topics, Step Functions retriers. **Breaks:** the handler's side effects must survive the policy — more attempts or shorter backoff multiplies side effects on a non-idempotent handler; a visibility timeout shorter than processing time lets another consumer pick up the same message mid-flight (concurrent duplicate). **Detect:** `attempts:`, `backoff: { type: 'exponential' }`, `RetryPolicy`, `maximumAttempts`, `visibilityTimeout`, `nonRetryableErrorTypes`. **Safe-change:** keep visibility/lock timeout > worst-case processing; classify retryable vs terminal explicitly (don't retry validation failures); re-verify idempotency when attempts/backoff change; jitter to avoid thundering herds. _(Own home — the retry/backoff policy is its own source-of-truth; cross-ref `dead-letter-queue-contract` (the terminal redrive).)_
 #### `schema-registry-contract` — CRITICAL · point
-The centrally-registered, versioned serialization schema for a topic's messages + its enforced compatibility mode. **Where:** Confluent Schema Registry, Apicurio, AWS Glue, Karapace, Buf, with Avro/Protobuf/JSON-Schema serdes. **Breaks:** the **compatibility mode** (BACKWARD/FORWARD/FULL/TRANSITIVE) defines which producer/consumer upgrade orders are safe — Protobuf field-number reuse or Avro fields without defaults break silently (reused Protobuf number deserializes garbage, no error); the wrong mode breaks consumers fleet-wide. **Detect:** `*.avsc`/`*.proto`, `buf.yaml`, `schema.registry.url`, `KafkaAvroSerializer`/`KafkaProtobufSerializer`, `compatibility` config, subject-naming strategy, `reserved`, Avro `default`. **Safe-change:** set + CI-enforce a compatibility mode (BACKWARD or FULL_TRANSITIVE); Avro: every new field gets a default; Protobuf: never reuse numbers, `reserved` removed ones, use `optional`; co-version producer + consumer serdes. *(Own home — the registry + its compatibility mode is its own source-of-truth; `event-schema` and `cdc-stream-contract` cross-ref it as the enforcer.)*
+The centrally-registered, versioned serialization schema for a topic's messages + its enforced compatibility mode. **Where:** Confluent Schema Registry, Apicurio, AWS Glue, Karapace, Buf, with Avro/Protobuf/JSON-Schema serdes. **Breaks:** the **compatibility mode** (BACKWARD/FORWARD/FULL/TRANSITIVE) defines which producer/consumer upgrade orders are safe — Protobuf field-number reuse or Avro fields without defaults break silently (reused Protobuf number deserializes garbage, no error); the wrong mode breaks consumers fleet-wide. **Detect:** `*.avsc`/`*.proto`, `buf.yaml`, `schema.registry.url`, `KafkaAvroSerializer`/`KafkaProtobufSerializer`, `compatibility` config, subject-naming strategy, `reserved`, Avro `default`. **Safe-change:** set + CI-enforce a compatibility mode (BACKWARD or FULL_TRANSITIVE); Avro: every new field gets a default; Protobuf: never reuse numbers, `reserved` removed ones, use `optional`; co-version producer + consumer serdes. _(Own home — the registry + its compatibility mode is its own source-of-truth; `event-schema` and `cdc-stream-contract` cross-ref it as the enforcer.)_
 #### `realtime-channel-naming` — HIGH · transcribe
-The convention for naming/subscribing to real-time channels/rooms, including auth scoping. **Where:** Cloudflare Realtime / Durable Object rooms (this repo's `cf-realtime` L1), Pusher (`private-`/`presence-` prefixes), Ably, socket.io rooms/namespaces, Supabase Realtime, Phoenix Channels. **Breaks:** the channel name is the meeting point between client subscribe + server publish, and prefixes encode **authorization** (Pusher `private-`/`presence-` require auth) — rename a channel or change its templating (`chat:{tenantId}:{sessionId}`) and clients subscribe to a channel the server never publishes to (no messages, no error); drop an auth prefix and a private channel becomes public. **Detect:** channel-name templates, `subscribe('private-...')`, `presence-`, socket.io `.to(room)`/namespace, DO `idFromName`, presence/auth callbacks, `@nurix/chat` channel config. **Safe-change:** centralize channel-name templating shared client + server; preserve auth-prefix conventions; keep tenant/session scoping consistent across publish + subscribe; dual-publish on rename. *(Canonical home for the realtime channel-naming + auth-scoping rendezvous (`transcribe`) — `presence-state-contract` folds in (member-state within the same channels); the per-message envelope is `websocket-wire-envelope`.)*
+The convention for naming/subscribing to real-time channels/rooms, including auth scoping. **Where:** Cloudflare Realtime / Durable Object rooms (this repo's `cf-realtime` L1), Pusher (`private-`/`presence-` prefixes), Ably, socket.io rooms/namespaces, Supabase Realtime, Phoenix Channels. **Breaks:** the channel name is the meeting point between client subscribe + server publish, and prefixes encode **authorization** (Pusher `private-`/`presence-` require auth) — rename a channel or change its templating (`chat:{tenantId}:{sessionId}`) and clients subscribe to a channel the server never publishes to (no messages, no error); drop an auth prefix and a private channel becomes public. **Detect:** channel-name templates, `subscribe('private-...')`, `presence-`, socket.io `.to(room)`/namespace, DO `idFromName`, presence/auth callbacks, `@nurix/chat` channel config. **Safe-change:** centralize channel-name templating shared client + server; preserve auth-prefix conventions; keep tenant/session scoping consistent across publish + subscribe; dual-publish on rename. _(Canonical home for the realtime channel-naming + auth-scoping rendezvous (`transcribe`) — `presence-state-contract` folds in (member-state within the same channels); the per-message envelope is `websocket-wire-envelope`.)_
 #### `presence-state-contract` — MED · transcribe
-The shape + semantics of presence/member-state payloads synced across clients in a channel. **Where:** Pusher presence channels, Ably presence, socket.io presence, Phoenix Presence, Supabase Realtime presence, Liveblocks, Yjs awareness. **Breaks:** presence member-info is a payload contract among all connected clients, which are **mixed versions in the wild** (old app versions linger far longer than backend deploys) — change member-info fields and old clients render `undefined`; change the user-id key and dedup/avatar logic breaks. **Detect:** `presence-` channels, `members.each`, `member.info`, `presence.enter(`, `Presence.list`, `awareness.setLocalState`. **Safe-change:** add presence fields additively + keep old ones; keep the identity key stable; make client rendering tolerant of missing fields; version on a breaking change. *(Folds into `realtime-channel-naming` — same realtime-channel source-of-truth, same `transcribe` doc-mode; the member-state facet. Cross-ref `websocket-wire-envelope` for the message envelope.)*
+The shape + semantics of presence/member-state payloads synced across clients in a channel. **Where:** Pusher presence channels, Ably presence, socket.io presence, Phoenix Presence, Supabase Realtime presence, Liveblocks, Yjs awareness. **Breaks:** presence member-info is a payload contract among all connected clients, which are **mixed versions in the wild** (old app versions linger far longer than backend deploys) — change member-info fields and old clients render `undefined`; change the user-id key and dedup/avatar logic breaks. **Detect:** `presence-` channels, `members.each`, `member.info`, `presence.enter(`, `Presence.list`, `awareness.setLocalState`. **Safe-change:** add presence fields additively + keep old ones; keep the identity key stable; make client rendering tolerant of missing fields; version on a breaking change. _(Folds into `realtime-channel-naming` — same realtime-channel source-of-truth, same `transcribe` doc-mode; the member-state facet. Cross-ref `websocket-wire-envelope` for the message envelope.)_
 #### `websocket-wire-envelope` — HIGH · transcribe
-The message envelope/framing on a long-lived socket — the `type`/`event` discriminator + payload — multiplexing many message kinds over one connection. **Where:** socket.io events, raw WebSocket JSON frames, this repo's `@nurix/chat` wire envelope over cf-realtime, `graphql-ws`, STOMP, Phoenix Channels. **Breaks:** one socket carries many message types keyed by a discriminator — add/rename a `type` or change a payload and the **mixed-version client population** can't parse it (old clients ignore new types / crash on changed payloads); unlike request/response there's no per-call negotiation, the envelope is global to the connection; a socket.io major-version bump is a protocol mismatch (HTTP 400 on connect). **Detect:** `socket.emit(`/`socket.on(`, `JSON.parse(event.data)`+`switch (msg.type)`, discriminated-union message types, `graphql-ws`, `@nurix/chat` inbound/outbound handling, `EIO=`/protocol version. **Safe-change:** discriminated `type` field, add types additively; clients ignore unknown types gracefully; share the envelope type def client + server; negotiate a protocol/envelope version at handshake for breaking changes; keep socket.io client/server majors compatible. *(Canonical home; cross-ref frontend/API `websocket-message-protocol`.)*
+The message envelope/framing on a long-lived socket — the `type`/`event` discriminator + payload — multiplexing many message kinds over one connection. **Where:** socket.io events, raw WebSocket JSON frames, this repo's `@nurix/chat` wire envelope over cf-realtime, `graphql-ws`, STOMP, Phoenix Channels. **Breaks:** one socket carries many message types keyed by a discriminator — add/rename a `type` or change a payload and the **mixed-version client population** can't parse it (old clients ignore new types / crash on changed payloads); unlike request/response there's no per-call negotiation, the envelope is global to the connection; a socket.io major-version bump is a protocol mismatch (HTTP 400 on connect). **Detect:** `socket.emit(`/`socket.on(`, `JSON.parse(event.data)`+`switch (msg.type)`, discriminated-union message types, `graphql-ws`, `@nurix/chat` inbound/outbound handling, `EIO=`/protocol version. **Safe-change:** discriminated `type` field, add types additively; clients ignore unknown types gracefully; share the envelope type def client + server; negotiate a protocol/envelope version at handshake for breaking changes; keep socket.io client/server majors compatible. _(Canonical home; cross-ref frontend/API `websocket-message-protocol`.)_
 #### `pubsub-channel-contract` — MED · point
-Channel name + payload contract for fire-and-forget pub/sub with no persistence or schema enforcement. **Where:** Redis `PUBLISH`/`SUBSCRIBE`/`PSUBSCRIBE`, Postgres `LISTEN`/`NOTIFY`, in-process EventEmitter, `BroadcastChannel`, MQTT. **Breaks:** no broker schema/persistence/registration — publisher + subscriber agree only by convention on the channel string + JSON shape; mismatch = silent drop (Redis pub/sub doesn't buffer for absent subscribers); Postgres `NOTIFY` payloads are 8000-byte-capped (growing one silently truncates/fails). **Detect:** `redis.publish(`, `subscribe(`/`psubscribe(`, `LISTEN`/`NOTIFY`, `emitter.emit(`, `new BroadcastChannel(`. **Safe-change:** centralize channel names + validate payload on both ends; keep `NOTIFY` payloads small (pass an id, re-fetch); don't rely on pub/sub for delivery guarantees. *(Own home — broker-less fire-and-forget pub/sub (`point`) is distinct from the persisted-stream `event-schema` and the socket `websocket-wire-envelope`.)*
+Channel name + payload contract for fire-and-forget pub/sub with no persistence or schema enforcement. **Where:** Redis `PUBLISH`/`SUBSCRIBE`/`PSUBSCRIBE`, Postgres `LISTEN`/`NOTIFY`, in-process EventEmitter, `BroadcastChannel`, MQTT. **Breaks:** no broker schema/persistence/registration — publisher + subscriber agree only by convention on the channel string + JSON shape; mismatch = silent drop (Redis pub/sub doesn't buffer for absent subscribers); Postgres `NOTIFY` payloads are 8000-byte-capped (growing one silently truncates/fails). **Detect:** `redis.publish(`, `subscribe(`/`psubscribe(`, `LISTEN`/`NOTIFY`, `emitter.emit(`, `new BroadcastChannel(`. **Safe-change:** centralize channel names + validate payload on both ends; keep `NOTIFY` payloads small (pass an id, re-fetch); don't rely on pub/sub for delivery guarantees. _(Own home — broker-less fire-and-forget pub/sub (`point`) is distinct from the persisted-stream `event-schema` and the socket `websocket-wire-envelope`.)_
 #### `stream-consumer-offset-contract` — HIGH · point
-Consumer groups, offset/cursor management, and consumer-group naming for replayable log streams. **Where:** Kafka consumer groups + offsets, Kinesis shard iterators, Redis Streams consumer groups (`XREADGROUP`/`XACK`), Pulsar subscriptions, NATS JetStream durables. **Breaks:** the consumer-group/subscription **name** owns the offset — rename it and it starts from `auto.offset.reset` (earliest = reprocess everything; latest = skip the backlog), both silently catastrophic; changing commit timing changes whether a crash reprocesses or loses messages; a renamed Redis Streams group strands un-acked PEL messages. **Detect:** `group.id`/`groupId:`, `auto.offset.reset`, `enable.auto.commit`, `XGROUP CREATE`/`XACK`, durable subscription names. **Safe-change:** treat group/subscription names as stable identifiers; set `auto.offset.reset` deliberately + know the fresh-group consequence; match commit timing to handler idempotency; rewind via explicit offset reset, not a group rename. *(Own home — the consumer-group/offset contract is its own source-of-truth.)*
+Consumer groups, offset/cursor management, and consumer-group naming for replayable log streams. **Where:** Kafka consumer groups + offsets, Kinesis shard iterators, Redis Streams consumer groups (`XREADGROUP`/`XACK`), Pulsar subscriptions, NATS JetStream durables. **Breaks:** the consumer-group/subscription **name** owns the offset — rename it and it starts from `auto.offset.reset` (earliest = reprocess everything; latest = skip the backlog), both silently catastrophic; changing commit timing changes whether a crash reprocesses or loses messages; a renamed Redis Streams group strands un-acked PEL messages. **Detect:** `group.id`/`groupId:`, `auto.offset.reset`, `enable.auto.commit`, `XGROUP CREATE`/`XACK`, durable subscription names. **Safe-change:** treat group/subscription names as stable identifiers; set `auto.offset.reset` deliberately + know the fresh-group consequence; match commit timing to handler idempotency; rewind via explicit offset reset, not a group rename. _(Own home — the consumer-group/offset contract is its own source-of-truth.)_
 #### `batch-window-contract` — MED · point
-Batch size, max wait/window, and partial-failure semantics between a stream/queue and a batch handler. **Where:** Lambda event-source mapping (`BatchSize`, `MaximumBatchingWindow`, `ReportBatchItemFailures`), Kafka `max.poll.records`, SQS batch-of-10. **Breaks:** increasing `BatchSize` makes a handler that throws on one bad record fail the **whole batch** (and reprocess all of it); toggling partial-batch-failure reporting flips redrive behavior — without it, one poison message blocks the whole batch. **Detect:** `BatchSize`, `MaximumBatchingWindow`, `ReportBatchItemFailures`/`functionResponseType`, `max.poll.records`, `partialBatchResponse`. **Safe-change:** enable partial-batch-failure reporting; make per-record processing idempotent (whole batch may redeliver); re-test poison-message handling when batch size/window changes. *(Own home — the batch-size/window/partial-failure contract is its own source-of-truth.)*
+Batch size, max wait/window, and partial-failure semantics between a stream/queue and a batch handler. **Where:** Lambda event-source mapping (`BatchSize`, `MaximumBatchingWindow`, `ReportBatchItemFailures`), Kafka `max.poll.records`, SQS batch-of-10. **Breaks:** increasing `BatchSize` makes a handler that throws on one bad record fail the **whole batch** (and reprocess all of it); toggling partial-batch-failure reporting flips redrive behavior — without it, one poison message blocks the whole batch. **Detect:** `BatchSize`, `MaximumBatchingWindow`, `ReportBatchItemFailures`/`functionResponseType`, `max.poll.records`, `partialBatchResponse`. **Safe-change:** enable partial-batch-failure reporting; make per-record processing idempotent (whole batch may redeliver); re-test poison-message handling when batch size/window changes. _(Own home — the batch-size/window/partial-failure contract is its own source-of-truth.)_
 ---
 ## 6 · CONFIG, ENV & BUILD
-> Recurring signature: two sides never statically linked (reader/provider,
-> schema/generated, host/remote, tsconfig/bundler, package.json/lockfile) — a
-> change on one passes compilation and surfaces only at boot/install/deploy, or
-> never-loudly (leaked secret, stale cache, wrong DI scope). The highest-severity
-> ones cross a **trust or deploy boundary**.
+> Recurring signature: two sides never statically linked (reader/provider, schema/generated, host/remote, tsconfig/bundler, package.json/lockfile) — a change on one passes compilation and surfaces only at boot/install/deploy, or never-loudly (leaked secret, stale cache, wrong DI scope). The highest-severity ones cross a **trust or deploy boundary**.
 #### `env-var-contract` — HIGH · transcribe
-The agreement that named env vars (expected names/types/required-ness) are present at runtime for code that reads them. **Where:** `process.env.X`, `import.meta.env`, `os.environ`; `.env*`, dotenv; deploy manifests (Helm, ECS, Vercel, `wrangler.toml [vars]`). **Breaks:** reader (code) + provider (deploy env) never reference each other statically — rename `DATABASE_URL`, drop a var, or change `"true"`→`1` and the consumer fails as `undefined` coercions / silent `NaN` / a default-port fallback. **Detect:** `process.env.`/`import.meta.env.`, `.env*`, `.env.example`, a Zod/envalid/`@t3-oss/env` schema (`env.ts`), `wrangler.toml`, compose `environment:`. **Safe-change:** update `.env.example` + the validation schema in the same commit; rename in *all* environments (CI secrets, prod dashboard, IaC); fail-fast at boot over silent defaults; document type coercion (env values are strings). *(Canonical home for the env-var key set (`transcribe`) — `env-parity` folds in (the same key set across environments).)*
+The agreement that named env vars (expected names/types/required-ness) are present at runtime for code that reads them. **Where:** `process.env.X`, `import.meta.env`, `os.environ`; `.env*`, dotenv; deploy manifests (Helm, ECS, Vercel, `wrangler.toml [vars]`). **Breaks:** reader (code) + provider (deploy env) never reference each other statically — rename `DATABASE_URL`, drop a var, or change `"true"`→`1` and the consumer fails as `undefined` coercions / silent `NaN` / a default-port fallback. **Detect:** `process.env.`/`import.meta.env.`, `.env*`, `.env.example`, a Zod/envalid/`@t3-oss/env` schema (`env.ts`), `wrangler.toml`, compose `environment:`. **Safe-change:** update `.env.example` + the validation schema in the same commit; rename in _all_ environments (CI secrets, prod dashboard, IaC); fail-fast at boot over silent defaults; document type coercion (env values are strings). _(Canonical home for the env-var key set (`transcribe`) — `env-parity` folds in (the same key set across environments).)_
 #### `env-parity` — HIGH · transcribe
-The contract that dev/CI/staging/prod expose the *same* config keys (differing only in values). **Where:** `.env.{development,production}`, Vite modes, `NODE_ENV`, CI secret stores, Vercel/Netlify per-env vars, K8s ConfigMaps/Secrets per namespace, Twelve-Factor. **Breaks:** a var present in dev but absent in prod (or vice versa) is a "works on my machine" gap that surfaces only post-deploy; drift in *which keys exist* silently changes code paths. **Detect:** diff key-sets across `.env.*` + `.env.example`, CI `env:`/`secrets:` vs the schema, `--mode`/`NODE_ENV` branches. **Safe-change:** keep one canonical key list + assert every env satisfies it in CI; when adding a var set it in *every* env before merge; avoid `NODE_ENV`-conditional reads of partially-set vars; treat `.env.example` as a tracked contract. *(Folds into `env-var-contract` — same env-var key-set source-of-truth, same `transcribe` doc-mode; the cross-environment-parity facet.)*
+The contract that dev/CI/staging/prod expose the _same_ config keys (differing only in values). **Where:** `.env.{development,production}`, Vite modes, `NODE_ENV`, CI secret stores, Vercel/Netlify per-env vars, K8s ConfigMaps/Secrets per namespace, Twelve-Factor. **Breaks:** a var present in dev but absent in prod (or vice versa) is a "works on my machine" gap that surfaces only post-deploy; drift in _which keys exist_ silently changes code paths. **Detect:** diff key-sets across `.env.*` + `.env.example`, CI `env:`/`secrets:` vs the schema, `--mode`/`NODE_ENV` branches. **Safe-change:** keep one canonical key list + assert every env satisfies it in CI; when adding a var set it in _every_ env before merge; avoid `NODE_ENV`-conditional reads of partially-set vars; treat `.env.example` as a tracked contract. _(Folds into `env-var-contract` — same env-var key-set source-of-truth, same `transcribe` doc-mode; the cross-environment-parity facet.)_
 #### `build-time-vs-runtime-config` — HIGH · point
-The line between config baked into the bundle at build (immutable per artifact) vs read at runtime (changeable per deploy). **Where:** Vite `import.meta.env`/`define`, Next.js `NEXT_PUBLIC_*` vs server env, Webpack `DefinePlugin`, esbuild `--define`, promoted Docker images, SSG. **Breaks:** build-time config is frozen into the artifact — promoting the same image to prod won't pick up new values, and an env-specific value gets hard-coded for all; code expecting a runtime var finds a stale build-time literal; both look identical in source (`process.env.X`). **Detect:** `define`/`DefinePlugin`/`--define`, `NEXT_PUBLIC_`/`VITE_` reads, CI building with env-specific vars, one image tag deployed to multiple envs. **Safe-change:** per-var, decide build-time vs runtime; never bake env-specific values into promoted images; document which prefix inlines at build; for SSG, rebuild per env or fetch config client-side. *(Own home — the build-vs-runtime line is `point` at the bundler config, a different doc-mode/concern from the `transcribe` env-var key set.)*
+The line between config baked into the bundle at build (immutable per artifact) vs read at runtime (changeable per deploy). **Where:** Vite `import.meta.env`/`define`, Next.js `NEXT_PUBLIC_*` vs server env, Webpack `DefinePlugin`, esbuild `--define`, promoted Docker images, SSG. **Breaks:** build-time config is frozen into the artifact — promoting the same image to prod won't pick up new values, and an env-specific value gets hard-coded for all; code expecting a runtime var finds a stale build-time literal; both look identical in source (`process.env.X`). **Detect:** `define`/`DefinePlugin`/`--define`, `NEXT_PUBLIC_`/`VITE_` reads, CI building with env-specific vars, one image tag deployed to multiple envs. **Safe-change:** per-var, decide build-time vs runtime; never bake env-specific values into promoted images; document which prefix inlines at build; for SSG, rebuild per env or fetch config client-side. _(Own home — the build-vs-runtime line is `point` at the bundler config, a different doc-mode/concern from the `transcribe` env-var key set.)_
 #### `client-exposed-env` — CRITICAL · point
-The contract that only vars under a designated public prefix ship to the browser, and nothing secret is ever placed under it. **Where:** Vite `VITE_*`, Next.js `NEXT_PUBLIC_*`, Expo `EXPO_PUBLIC_*`, Gatsby `GATSBY_*`. **Breaks:** the prefix is the *only* gate between server secret + public bundle — misnaming `VITE_STRIPE_SECRET` leaks a key into shipped JS; in some Vite versions referencing a missing var dumps the *entire* env into the bundle; the leak is silent (the app works, the secret is public). **Detect:** secret-shaped names under public prefixes (`VITE_.*(SECRET|KEY|TOKEN|PASSWORD)`), bundle-output audit, `.env` secrets next to prefixed vars. **Safe-change:** never put secrets under a client prefix; audit the built bundle (grep output) in CI; always reference defined vars; treat the public prefix as a forever-public surface. *(Own home — the public-prefix leak gate is a distinct CRITICAL surface, kept separate from `env-var-contract`; cross-ref frontend `client-env-var-contract` (its consuming-side view).)*
+The contract that only vars under a designated public prefix ship to the browser, and nothing secret is ever placed under it. **Where:** Vite `VITE_*`, Next.js `NEXT_PUBLIC_*`, Expo `EXPO_PUBLIC_*`, Gatsby `GATSBY_*`. **Breaks:** the prefix is the _only_ gate between server secret + public bundle — misnaming `VITE_STRIPE_SECRET` leaks a key into shipped JS; in some Vite versions referencing a missing var dumps the _entire_ env into the bundle; the leak is silent (the app works, the secret is public). **Detect:** secret-shaped names under public prefixes (`VITE_.*(SECRET|KEY|TOKEN|PASSWORD)`), bundle-output audit, `.env` secrets next to prefixed vars. **Safe-change:** never put secrets under a client prefix; audit the built bundle (grep output) in CI; always reference defined vars; treat the public prefix as a forever-public surface. _(Own home — the public-prefix leak gate is a distinct CRITICAL surface, kept separate from `env-var-contract`; cross-ref frontend `client-env-var-contract` (its consuming-side view).)_
 #### `secrets-management` — CRITICAL · point
-The contract between where secrets are stored (vault/SSM/manager) + how code retrieves them (paths, IAM scope, mounts). **Where:** Vault, AWS Secrets Manager/SSM, GCP Secret Manager, Azure Key Vault, Doppler, K8s Secrets/External Secrets, Docker `secrets:`, BuildKit `--mount=type=secret`. **Breaks:** the secret path + the IAM permission to read it are a contract code can't validate at build — rename a path, rotate without dual-writing, or tighten IAM and the app fails to boot or uses a stale cached value; rotation breaks long-lived connections holding old credentials. **Detect:** SDK calls (`SecretsManagerClient`, `vault read`), `external-secrets` CRDs, `secrets:` in compose, IAM `secretsmanager:GetSecretValue`, init-container secret fetches. **Safe-change:** treat secret paths as versioned (dual-write old+new during rename/rotation); co-change the IAM granting read; re-fetch on auth failure not cache-forever; never bake secrets into images (use mounts); scan history. *(Own home — the secret-store path + IAM-read contract is its own source-of-truth; cross-ref auth `encryption-at-rest-key-boundary` for data-encryption keys.)*
+The contract between where secrets are stored (vault/SSM/manager) + how code retrieves them (paths, IAM scope, mounts). **Where:** Vault, AWS Secrets Manager/SSM, GCP Secret Manager, Azure Key Vault, Doppler, K8s Secrets/External Secrets, Docker `secrets:`, BuildKit `--mount=type=secret`. **Breaks:** the secret path + the IAM permission to read it are a contract code can't validate at build — rename a path, rotate without dual-writing, or tighten IAM and the app fails to boot or uses a stale cached value; rotation breaks long-lived connections holding old credentials. **Detect:** SDK calls (`SecretsManagerClient`, `vault read`), `external-secrets` CRDs, `secrets:` in compose, IAM `secretsmanager:GetSecretValue`, init-container secret fetches. **Safe-change:** treat secret paths as versioned (dual-write old+new during rename/rotation); co-change the IAM granting read; re-fetch on auth failure not cache-forever; never bake secrets into images (use mounts); scan history. _(Own home — the secret-store path + IAM-read contract is its own source-of-truth; cross-ref auth `encryption-at-rest-key-boundary` for data-encryption keys.)_
 #### `feature-flag-contract` — HIGH · transcribe
-The agreement on a flag's key, default value, and the off=legacy/on=new convention. **Where:** LaunchDarkly, Flagsmith, Unleash, ConfigCat, GrowthBook, PostHog, Statsig; in-house `flags.ts`; `process.env.FEATURE_X`. **Breaks:** SDK config (defaults, targeting) + the gated branch are two sides — changing a default, deleting a still-referenced flag, or inverting off/on semantics flips behavior silently; in distributed systems removing a flag one service still reads creates partial-rollout failure. **Detect:** flag init + `getFlag`/`variation`/`isEnabled('key')`, flag-key constants, stale dead branches, SDK fallback defaults. **Safe-change:** preserve off=previous-safe-behavior so disabling is rollback; two-step removal in distributed systems (make safe unconditionally → deploy everywhere → delete); remove dead branches + SDK defaults + targeting together; sane SDK fallbacks. *(Canonical home for the flag-key contract (`transcribe`) — frontend `feature-flag-gating` folds in (its client-UI-gating facet).)*
+The agreement on a flag's key, default value, and the off=legacy/on=new convention. **Where:** LaunchDarkly, Flagsmith, Unleash, ConfigCat, GrowthBook, PostHog, Statsig; in-house `flags.ts`; `process.env.FEATURE_X`. **Breaks:** SDK config (defaults, targeting) + the gated branch are two sides — changing a default, deleting a still-referenced flag, or inverting off/on semantics flips behavior silently; in distributed systems removing a flag one service still reads creates partial-rollout failure. **Detect:** flag init + `getFlag`/`variation`/`isEnabled('key')`, flag-key constants, stale dead branches, SDK fallback defaults. **Safe-change:** preserve off=previous-safe-behavior so disabling is rollback; two-step removal in distributed systems (make safe unconditionally → deploy everywhere → delete); remove dead branches + SDK defaults + targeting together; sane SDK fallbacks. _(Canonical home for the flag-key contract (`transcribe`) — frontend `feature-flag-gating` folds in (its client-UI-gating facet).)_
 #### `workspace-package-graph` — HIGH · point
-The contract that a monorepo package may only import siblings it explicitly declares as workspace deps — no phantom/hoisted imports. **Where:** pnpm workspaces (`pnpm-workspace.yaml`, `workspace:*`, strict `node_modules`), npm/yarn/Bun workspaces, Nx, Turborepo. **Breaks:** under hoisting a package can import an undeclared dep hoisted to root (works locally, breaks on publish or layout change); pnpm's strict layout forbids it; removing/renaming a workspace package breaks every undeclared importer silently. **Detect:** `pnpm-workspace.yaml`/root `workspaces`, `workspace:*` deps, imports of package names not in that package's `dependencies`, `nx graph`/`turbo` graph. **Safe-change:** declare every cross-package import as a `workspace:` dep; on rename/remove update all dependents + lockfile; pin internal deps `workspace:*`; CI dependency-graph check for undeclared imports. *(Own home — the workspace dependency graph is its own source-of-truth.)* *(A workspace is NOT a module — see how `harness-manager` reads boundary `Bounds` vertices.)*
+The contract that a monorepo package may only import siblings it explicitly declares as workspace deps — no phantom/hoisted imports. **Where:** pnpm workspaces (`pnpm-workspace.yaml`, `workspace:*`, strict `node_modules`), npm/yarn/Bun workspaces, Nx, Turborepo. **Breaks:** under hoisting a package can import an undeclared dep hoisted to root (works locally, breaks on publish or layout change); pnpm's strict layout forbids it; removing/renaming a workspace package breaks every undeclared importer silently. **Detect:** `pnpm-workspace.yaml`/root `workspaces`, `workspace:*` deps, imports of package names not in that package's `dependencies`, `nx graph`/`turbo` graph. **Safe-change:** declare every cross-package import as a `workspace:` dep; on rename/remove update all dependents + lockfile; pin internal deps `workspace:*`; CI dependency-graph check for undeclared imports. _(Own home — the workspace dependency graph is its own source-of-truth.)_ _(A workspace is NOT a module — see how `harness-manager` reads boundary `Bounds` vertices.)_
 #### `import-layering-rule` — MED · point
-Architectural rules constraining which layers/modules may import which (domain ⊥ UI; feature A ⊥ feature B internals). **Where:** ESLint `no-restricted-imports`/`no-restricted-paths`, `eslint-plugin-boundaries`, Nx `enforce-module-boundaries` (tags), `dependency-cruiser`, Sheriff. **Breaks:** the rule lives in lint config not the type system — a violating import compiles + runs fine but erodes architecture (circular deps, leaked internals); refactoring a path silently makes blocked imports allowed (or vice versa). **Detect:** `.eslintrc*`/`eslint.config.*` restricted-import blocks, `.dependency-cruiser.js`, Nx `tags`+`depConstraints`, `eslint-plugin-boundaries` `elements`. **Safe-change:** verify moved files still match the layer globs; keep lint rules synced to the conceptual architecture; run boundary lint in CI; prefer barrel/public-entry imports. *(Own home — the layer/import-restriction rule (lint config) is its own source-of-truth.)* *(CRITICAL if the rule guards a security/tenancy boundary.)*
+Architectural rules constraining which layers/modules may import which (domain ⊥ UI; feature A ⊥ feature B internals). **Where:** ESLint `no-restricted-imports`/`no-restricted-paths`, `eslint-plugin-boundaries`, Nx `enforce-module-boundaries` (tags), `dependency-cruiser`, Sheriff. **Breaks:** the rule lives in lint config not the type system — a violating import compiles + runs fine but erodes architecture (circular deps, leaked internals); refactoring a path silently makes blocked imports allowed (or vice versa). **Detect:** `.eslintrc*`/`eslint.config.*` restricted-import blocks, `.dependency-cruiser.js`, Nx `tags`+`depConstraints`, `eslint-plugin-boundaries` `elements`. **Safe-change:** verify moved files still match the layer globs; keep lint rules synced to the conceptual architecture; run boundary lint in CI; prefer barrel/public-entry imports. _(Own home — the layer/import-restriction rule (lint config) is its own source-of-truth.)_ _(CRITICAL if the rule guards a security/tenancy boundary.)_
 #### `tsconfig-paths` — MED · point
-Import-alias mapping (`@app/*`) declared in `tsconfig.json` `paths`+`baseUrl`. **Where:** TS `paths`; mirrored in Vite (`resolve.alias`/`vite-tsconfig-paths`), Jest (`moduleNameMapper`), Webpack, Node (`tsconfig-paths`), Vitest. **Breaks:** `paths` only affects *type-check* resolution — the bundler/runtime needs the same aliases separately; if they drift, type-check passes but build/tests fail to resolve (or resolve to the wrong file) silently. **Detect:** `tsconfig*.json` `paths`/`baseUrl`, vs `vite.config`/`webpack` `alias`, `jest` `moduleNameMapper`; `vite-tsconfig-paths` plugin. **Safe-change:** change an alias in all resolvers at once or use a plugin deriving them from tsconfig; prefer one source of truth; verify build + tests, not just `tsc`. *(Canonical home for the tsconfig × `point` cluster — `tsconfig-project-references` folds in (the build-graph facet of the same tsconfig), unless the monorepo files the references graph separately.)*
+Import-alias mapping (`@app/*`) declared in `tsconfig.json` `paths`+`baseUrl`. **Where:** TS `paths`; mirrored in Vite (`resolve.alias`/`vite-tsconfig-paths`), Jest (`moduleNameMapper`), Webpack, Node (`tsconfig-paths`), Vitest. **Breaks:** `paths` only affects _type-check_ resolution — the bundler/runtime needs the same aliases separately; if they drift, type-check passes but build/tests fail to resolve (or resolve to the wrong file) silently. **Detect:** `tsconfig*.json` `paths`/`baseUrl`, vs `vite.config`/`webpack` `alias`, `jest` `moduleNameMapper`; `vite-tsconfig-paths` plugin. **Safe-change:** change an alias in all resolvers at once or use a plugin deriving them from tsconfig; prefer one source of truth; verify build + tests, not just `tsc`. _(Canonical home for the tsconfig × `point` cluster — `tsconfig-project-references` folds in (the build-graph facet of the same tsconfig), unless the monorepo files the references graph separately.)_
 #### `tsconfig-project-references` — MED · point
-The build-graph contract between composite TS projects — `references` wiring, `composite: true`, emitted `.d.ts`/`.tsbuildinfo`. **Where:** TS project references (`tsc --build`), monorepo tsconfig graphs, `declarationMap`. **Breaks:** a referenced project must emit declarations the referencing one reads; `composite` changes `rootDir` defaults — break the graph, forget `composite`, or change a referenced output layout and downstream builds use stale `.d.ts`, skip rebuilds, or fail to find outputs (incremental builds make staleness silent). **Detect:** `references` arrays, `composite`/`declaration`/`tsBuildInfoFile`, `tsc -b`, `.tsbuildinfo`, per-project `outDir`/`rootDir`. **Safe-change:** keep `composite`+`declaration` on every referenced project; update the `references` graph on dep changes (`tsc -b`); don't change a referenced `outDir`/`rootDir` without updating consumers; clear `.tsbuildinfo` to debug staleness. *(Folds into `tsconfig-paths` — same tsconfig source-of-truth, same `point` doc-mode; the build-graph facet. Stands alone in a large composite-project monorepo.)*
+The build-graph contract between composite TS projects — `references` wiring, `composite: true`, emitted `.d.ts`/`.tsbuildinfo`. **Where:** TS project references (`tsc --build`), monorepo tsconfig graphs, `declarationMap`. **Breaks:** a referenced project must emit declarations the referencing one reads; `composite` changes `rootDir` defaults — break the graph, forget `composite`, or change a referenced output layout and downstream builds use stale `.d.ts`, skip rebuilds, or fail to find outputs (incremental builds make staleness silent). **Detect:** `references` arrays, `composite`/`declaration`/`tsBuildInfoFile`, `tsc -b`, `.tsbuildinfo`, per-project `outDir`/`rootDir`. **Safe-change:** keep `composite`+`declaration` on every referenced project; update the `references` graph on dep changes (`tsc -b`); don't change a referenced `outDir`/`rootDir` without updating consumers; clear `.tsbuildinfo` to debug staleness. _(Folds into `tsconfig-paths` — same tsconfig source-of-truth, same `point` doc-mode; the build-graph facet. Stands alone in a large composite-project monorepo.)_
 #### `package-public-api` — CRITICAL · point
-A package's published entry points (what consumers may import) + the semver promise that breaking them bumps major. **Where:** `package.json` `exports`/`main`/`module`/`types`/`typesVersions`, subpath + conditional exports, `files`, API Extractor, `@nurix/*` scopes; barrel `index.ts`. **Breaks:** `exports` *encapsulates* the package — anything mapped is public API (changing it is breaking), anything unmapped throws `ERR_PACKAGE_PATH_NOT_EXPORTED` for deep imports consumers rely on; adding `exports`, removing a subpath, reordering conditions, or changing `types` silently breaks imports/type resolution across the install boundary. **Detect:** `package.json` `exports`/`main`/`types`/`files`, conditional-export maps, deep-import patterns in consumers, `publishConfig`, barrel exports. **Safe-change:** every mapped subpath is public (removal = major bump); don't expose internals you'll want to change; keep `types`/`typesVersions` aligned with runtime `exports` (dual ESM/CJS); verify consumers can import after publish. *(Canonical home; cross-ref frontend `barrel-export-contract`.)*
+A package's published entry points (what consumers may import) + the semver promise that breaking them bumps major. **Where:** `package.json` `exports`/`main`/`module`/`types`/`typesVersions`, subpath + conditional exports, `files`, API Extractor, `@nurix/*` scopes; barrel `index.ts`. **Breaks:** `exports` _encapsulates_ the package — anything mapped is public API (changing it is breaking), anything unmapped throws `ERR_PACKAGE_PATH_NOT_EXPORTED` for deep imports consumers rely on; adding `exports`, removing a subpath, reordering conditions, or changing `types` silently breaks imports/type resolution across the install boundary. **Detect:** `package.json` `exports`/`main`/`types`/`files`, conditional-export maps, deep-import patterns in consumers, `publishConfig`, barrel exports. **Safe-change:** every mapped subpath is public (removal = major bump); don't expose internals you'll want to change; keep `types`/`typesVersions` aligned with runtime `exports` (dual ESM/CJS); verify consumers can import after publish. _(Canonical home; cross-ref frontend `barrel-export-contract`.)_
 #### `peer-dependency-contract` — HIGH · point
-The agreement that a package's host supplies a compatible version of a shared dep (React, a plugin's framework) rather than bundling its own. **Where:** `peerDependencies`+`peerDependenciesMeta`, plugin ecosystems (React, ESLint, Vite/Webpack plugins, `@nurix/components`), pnpm strict peers. **Breaks:** package + host independently declare versions that must overlap — a widened/narrowed range or a host upgrading past it produces duplicate-instance bugs (two React copies → broken hooks/context), `ERR_PEER_DEP_*`, or crashes; pnpm enforces strictly, npm/yarn historically ignore silently. **Detect:** `peerDependencies`/`peerDependenciesMeta`, pnpm peer warnings, duplicate singleton copies in the lockfile, `dedupe`/`overrides`/`resolutions` hacks. **Safe-change:** keep peer ranges as wide as compatible (major bump to narrow); for singletons ensure exactly one copy (`dedupe`/`resolutions`/federation `singleton`); test lowest + highest supported; don't move a peer into `dependencies`. *(Own home — the peer-dependency overlap contract is its own source-of-truth; cross-ref `lockfile-resolution-contract` (the resolved tree).)*
+The agreement that a package's host supplies a compatible version of a shared dep (React, a plugin's framework) rather than bundling its own. **Where:** `peerDependencies`+`peerDependenciesMeta`, plugin ecosystems (React, ESLint, Vite/Webpack plugins, `@nurix/components`), pnpm strict peers. **Breaks:** package + host independently declare versions that must overlap — a widened/narrowed range or a host upgrading past it produces duplicate-instance bugs (two React copies → broken hooks/context), `ERR_PEER_DEP_*`, or crashes; pnpm enforces strictly, npm/yarn historically ignore silently. **Detect:** `peerDependencies`/`peerDependenciesMeta`, pnpm peer warnings, duplicate singleton copies in the lockfile, `dedupe`/`overrides`/`resolutions` hacks. **Safe-change:** keep peer ranges as wide as compatible (major bump to narrow); for singletons ensure exactly one copy (`dedupe`/`resolutions`/federation `singleton`); test lowest + highest supported; don't move a peer into `dependencies`. _(Own home — the peer-dependency overlap contract is its own source-of-truth; cross-ref `lockfile-resolution-contract` (the resolved tree).)_
 #### `module-federation-remotes` — CRITICAL · point
-The runtime contract between a host + remotely-loaded micro-frontends — remote URLs/entry names, exposed-module map, `shared` versions/singletons. **Where:** Webpack/Rspack Module Federation, `@module-federation/enhanced`, Native Federation, Vite `@originjs/vite-plugin-federation`. **Breaks:** host + remote build/deploy independently yet must agree at runtime on exposed-module names + shared-lib versions — rename an exposed path, change a remote URL, or let a shared singleton drift and the host fails to load the remote / loads duplicate React breaking `useState`/`useContext` silently; version postfixes (`-rc.1`) can break singleton sharing. **Detect:** `ModuleFederationPlugin` (`remotes`/`exposes`/`shared`/`singleton`/`requiredVersion`/`strictVersion`), `remoteEntry.js` URLs, `import('remote/Module')`. **Safe-change:** treat exposed names + URLs as a versioned runtime API; mark framework libs `singleton: true`+`requiredVersion`+`strictVersion`; avoid prerelease singletons; coordinate host+remote deploys + add a runtime version/health check. *(Own home — the host↔remote federation contract is its own runtime source-of-truth.)*
+The runtime contract between a host + remotely-loaded micro-frontends — remote URLs/entry names, exposed-module map, `shared` versions/singletons. **Where:** Webpack/Rspack Module Federation, `@module-federation/enhanced`, Native Federation, Vite `@originjs/vite-plugin-federation`. **Breaks:** host + remote build/deploy independently yet must agree at runtime on exposed-module names + shared-lib versions — rename an exposed path, change a remote URL, or let a shared singleton drift and the host fails to load the remote / loads duplicate React breaking `useState`/`useContext` silently; version postfixes (`-rc.1`) can break singleton sharing. **Detect:** `ModuleFederationPlugin` (`remotes`/`exposes`/`shared`/`singleton`/`requiredVersion`/`strictVersion`), `remoteEntry.js` URLs, `import('remote/Module')`. **Safe-change:** treat exposed names + URLs as a versioned runtime API; mark framework libs `singleton: true`+`requiredVersion`+`strictVersion`; avoid prerelease singletons; coordinate host+remote deploys + add a runtime version/health check. _(Own home — the host↔remote federation contract is its own runtime source-of-truth.)_
 #### `di-container-registration` — HIGH · point
-The contract between DI tokens/keys + their registered providers consumers resolve at runtime. **Where:** NestJS providers + `@Inject(TOKEN)`, InversifyJS bindings, tsyringe, Angular DI/`InjectionToken`, typedi, Awilix. **Breaks:** tokens + registrations match at runtime not via the type system (string/symbol tokens especially) — rename a token, forget to register a provider, or change its scope (singleton↔request) and resolution throws at boot or injects the wrong instance silently (a shared singleton where per-request was assumed leaks state across tenants). **Detect:** `@Inject(`/`@injectable`/`container.register`/`bind(...).to(...)`/`InjectionToken`/`provide:`, token constants, module `providers`/`exports`, `forwardRef`. **Safe-change:** use typed/`InjectionToken` tokens over strings; register every injected token + import the providing module where resolved; preserve scope semantics (state-sharing); update registration + injection sites together on rename. *(Own home — the DI token↔provider registration is its own source-of-truth.)*
+The contract between DI tokens/keys + their registered providers consumers resolve at runtime. **Where:** NestJS providers + `@Inject(TOKEN)`, InversifyJS bindings, tsyringe, Angular DI/`InjectionToken`, typedi, Awilix. **Breaks:** tokens + registrations match at runtime not via the type system (string/symbol tokens especially) — rename a token, forget to register a provider, or change its scope (singleton↔request) and resolution throws at boot or injects the wrong instance silently (a shared singleton where per-request was assumed leaks state across tenants). **Detect:** `@Inject(`/`@injectable`/`container.register`/`bind(...).to(...)`/`InjectionToken`/`provide:`, token constants, module `providers`/`exports`, `forwardRef`. **Safe-change:** use typed/`InjectionToken` tokens over strings; register every injected token + import the providing module where resolved; preserve scope semantics (state-sharing); update registration + injection sites together on rename. _(Own home — the DI token↔provider registration is its own source-of-truth.)_
 #### `code-generation-io` — HIGH · point
-The contract that generated code stays in sync with its source-of-truth schema (and consumers import the generated output, not edit it). **Where:** Prisma (`prisma generate`→`@prisma/client`), GraphQL Code Generator, Protobuf/gRPC (`buf`), OpenAPI generators, tRPC inference, Drizzle, `wrangler types`. **Breaks:** schema + generated artifact must regenerate together — forget to generate and types drift while the DB/API changed (code compiles against stale types, mismatches at runtime); hand-editing generated files is clobbered next run; cross-project, frontend types lag a backend schema change with no compile error until regen. **Detect:** `schema.prisma`, `codegen.{yml,ts}`, `*.proto`, `buf.gen.yaml`, `openapi.{yaml,json}`, generated dirs (`@prisma/client`, `__generated__/`, `*.gen.ts`), `generate`/`postinstall` scripts. **Safe-change:** regenerate in the same commit + CI `git diff --exit-code`; never hand-edit generated files; wire generate into `postinstall`/build; version + coordinate consumer regen for cross-service schemas. *(Own home — the schema↔generated-artifact sync is its own cross-cutting contract; the schema-specific types (`orm-model-mapping`, `openapi-spec-contract`, `graphql-schema-contract`, `grpc-protobuf-wire-contract`) cross-ref it.)*
+The contract that generated code stays in sync with its source-of-truth schema (and consumers import the generated output, not edit it). **Where:** Prisma (`prisma generate`→`@prisma/client`), GraphQL Code Generator, Protobuf/gRPC (`buf`), OpenAPI generators, tRPC inference, Drizzle, `wrangler types`. **Breaks:** schema + generated artifact must regenerate together — forget to generate and types drift while the DB/API changed (code compiles against stale types, mismatches at runtime); hand-editing generated files is clobbered next run; cross-project, frontend types lag a backend schema change with no compile error until regen. **Detect:** `schema.prisma`, `codegen.{yml,ts}`, `*.proto`, `buf.gen.yaml`, `openapi.{yaml,json}`, generated dirs (`@prisma/client`, `__generated__/`, `*.gen.ts`), `generate`/`postinstall` scripts. **Safe-change:** regenerate in the same commit + CI `git diff --exit-code`; never hand-edit generated files; wire generate into `postinstall`/build; version + coordinate consumer regen for cross-service schemas. _(Own home — the schema↔generated-artifact sync is its own cross-cutting contract; the schema-specific types (`orm-model-mapping`, `openapi-spec-contract`, `graphql-schema-contract`, `grpc-protobuf-wire-contract`) cross-ref it.)_
 #### `bundler-entry-output-externals` — MED · point
-A bundle's entry points, output filenames/format, and which deps are externalized (expected at runtime). **Where:** Vite `build.rollupOptions`/`build.lib`, Rollup, esbuild, Webpack `entry`/`output`/`externals`, tsup. **Breaks:** output filenames/formats + externals are an implicit contract with whatever loads the bundle — change an entry name/hashing/format and the HTML/loader references a missing file; mark a dep external that isn't provided → `Cannot find module`; stop externalizing a peer → it's duplicated. **Detect:** `vite.config`/`rollup.config`/`webpack` `entry`/`input`/`output`/`external`/`build.lib`, `format`, manifest plugins, HTML/CDN refs to output names. **Safe-change:** keep externals consistent with what the runtime provides; coordinate filename/format changes with consumers; externalize peer deps in library builds; verify the consumer loads the artifact. *(Own home — the bundle entry/output/externals contract is its own source-of-truth; cross-ref frontend `asset-public-path-contract` for output URLs.)*
+A bundle's entry points, output filenames/format, and which deps are externalized (expected at runtime). **Where:** Vite `build.rollupOptions`/`build.lib`, Rollup, esbuild, Webpack `entry`/`output`/`externals`, tsup. **Breaks:** output filenames/formats + externals are an implicit contract with whatever loads the bundle — change an entry name/hashing/format and the HTML/loader references a missing file; mark a dep external that isn't provided → `Cannot find module`; stop externalizing a peer → it's duplicated. **Detect:** `vite.config`/`rollup.config`/`webpack` `entry`/`input`/`output`/`external`/`build.lib`, `format`, manifest plugins, HTML/CDN refs to output names. **Safe-change:** keep externals consistent with what the runtime provides; coordinate filename/format changes with consumers; externalize peer deps in library builds; verify the consumer loads the artifact. _(Own home — the bundle entry/output/externals contract is its own source-of-truth; cross-ref frontend `asset-public-path-contract` for output URLs.)_
 #### `docker-build-arg-env` — HIGH · point
-The distinction between Dockerfile `ARG` (build-time only, gone from the container but in image history) + `ENV` (baked into image + container). **Where:** Dockerfile `ARG`/`ENV`, `--build-arg`, compose `build.args` vs `environment`, BuildKit `--mount=type=secret`. **Breaks:** `ARG` + `ENV` look interchangeable but differ on whether the value survives into the container + leaks into history — a secret via `--build-arg` is baked into image history (extractable); relying on an `ARG` at runtime finds it undefined; promoting an image with `ENV` baked in carries that value everywhere. **Detect:** `ARG`/`ENV` lines, `--build-arg` in CI, compose `build.args`/`environment`, `--mount=type=secret`, `docker history`. **Safe-change:** never pass secrets via `--build-arg`/`ENV` (use secret mounts); `ARG` only for build-time choices, `ENV` only for every-promotion-target runtime values; scan image history; rotate any secret ever passed as a build-arg. *(Own home — the Dockerfile `ARG`/`ENV` distinction is its own source-of-truth; cross-ref runtime `container-image-contract` (the baked image interface) and `secrets-management`.)*
+The distinction between Dockerfile `ARG` (build-time only, gone from the container but in image history) + `ENV` (baked into image + container). **Where:** Dockerfile `ARG`/`ENV`, `--build-arg`, compose `build.args` vs `environment`, BuildKit `--mount=type=secret`. **Breaks:** `ARG` + `ENV` look interchangeable but differ on whether the value survives into the container + leaks into history — a secret via `--build-arg` is baked into image history (extractable); relying on an `ARG` at runtime finds it undefined; promoting an image with `ENV` baked in carries that value everywhere. **Detect:** `ARG`/`ENV` lines, `--build-arg` in CI, compose `build.args`/`environment`, `--mount=type=secret`, `docker history`. **Safe-change:** never pass secrets via `--build-arg`/`ENV` (use secret mounts); `ARG` only for build-time choices, `ENV` only for every-promotion-target runtime values; scan image history; rotate any secret ever passed as a build-arg. _(Own home — the Dockerfile `ARG`/`ENV` distinction is its own source-of-truth; cross-ref runtime `container-image-contract` (the baked image interface) and `secrets-management`.)_
 #### `config-schema-defaults` — MED · point
-The contract a validated config schema carries — required vs optional keys, types, and *default values* filling absent keys. **Where:** Zod/`@t3-oss/env`/envalid/convict schemas, `node-config` JSON hierarchies, framework config (`next.config`), `cosmiconfig` `.*rc`. **Breaks:** defaults are the silent fallback between operator-set + code-assumed — change a default (timeout, page size) and behavior shifts everywhere the key was unset (no error); make an optional key required and existing deploys fail at boot. **Detect:** `z.object({…}).default(...)`, envalid/convict `default`, `.optional()`/`.required()`, `cosmiconfig`/`*.config.*`, the config-loading module. **Safe-change:** treat defaults as observable behavior (changelog a change); a new required key without a default breaks deploys (provide a default or migrate first); keep schema types aligned with consumers; validate + fail-fast at boot. *(Own home — the validated config schema + its defaults are `point` source-of-truth; cross-ref `env-var-contract` (the env keys it validates).)*
+The contract a validated config schema carries — required vs optional keys, types, and _default values_ filling absent keys. **Where:** Zod/`@t3-oss/env`/envalid/convict schemas, `node-config` JSON hierarchies, framework config (`next.config`), `cosmiconfig` `.*rc`. **Breaks:** defaults are the silent fallback between operator-set + code-assumed — change a default (timeout, page size) and behavior shifts everywhere the key was unset (no error); make an optional key required and existing deploys fail at boot. **Detect:** `z.object({…}).default(...)`, envalid/convict `default`, `.optional()`/`.required()`, `cosmiconfig`/`*.config.*`, the config-loading module. **Safe-change:** treat defaults as observable behavior (changelog a change); a new required key without a default breaks deploys (provide a default or migrate first); keep schema types aligned with consumers; validate + fail-fast at boot. _(Own home — the validated config schema + its defaults are `point` source-of-truth; cross-ref `env-var-contract` (the env keys it validates).)_
 #### `ci-pipeline-config-contract` — MED · point
-The contract between CI workflows + the repo — required secrets/vars, expected scripts, runner/Node versions, cache keys, matrix. **Where:** GitHub Actions (`.github/workflows/*.yml`), GitLab CI, CircleCI, Turborepo/Nx remote cache, `engines`. **Breaks:** the workflow references repo scripts (`pnpm build`), secrets, + tool versions independently — rename a script, drop a secret, or bump the runner's Node and pipelines fail or (with caching) produce stale artifacts; cache-key drift silently serves wrong outputs. **Detect:** `.github/workflows/`, `.gitlab-ci.yml`, `secrets.`/`vars.`, `setup-node` `node-version`, `engines`/scripts referenced in CI, cache `key:`. **Safe-change:** grep workflows when renaming `package.json` scripts; add required secrets/vars before the workflow merges; keep CI Node/tool versions aligned with `engines`+lockfile; invalidate cache keys when inputs change. *(Own home — the CI-workflow↔repo contract is its own source-of-truth; cross-ref `node-engines-runtime-contract` and `lockfile-resolution-contract`.)*
+The contract between CI workflows + the repo — required secrets/vars, expected scripts, runner/Node versions, cache keys, matrix. **Where:** GitHub Actions (`.github/workflows/*.yml`), GitLab CI, CircleCI, Turborepo/Nx remote cache, `engines`. **Breaks:** the workflow references repo scripts (`pnpm build`), secrets, + tool versions independently — rename a script, drop a secret, or bump the runner's Node and pipelines fail or (with caching) produce stale artifacts; cache-key drift silently serves wrong outputs. **Detect:** `.github/workflows/`, `.gitlab-ci.yml`, `secrets.`/`vars.`, `setup-node` `node-version`, `engines`/scripts referenced in CI, cache `key:`. **Safe-change:** grep workflows when renaming `package.json` scripts; add required secrets/vars before the workflow merges; keep CI Node/tool versions aligned with `engines`+lockfile; invalidate cache keys when inputs change. _(Own home — the CI-workflow↔repo contract is its own source-of-truth; cross-ref `node-engines-runtime-contract` and `lockfile-resolution-contract`.)_
 #### `node-engines-runtime-contract` — MED · point
-The contract that the runtime/package-manager present matches what the code + lockfile were built against. **Where:** `package.json` `engines`+`packageManager` (Corepack), `.nvmrc`/`.node-version`, volta, `.tool-versions`, Docker base tags, CI `setup-node`. **Breaks:** declared engine + installed runtime are separate — a mismatched Node major breaks native addons or uses changed built-ins; a different package-manager version regenerates the lockfile differently; `engines` is advisory by default so drift is silent unless `engine-strict`. **Detect:** `engines`/`packageManager`, `.nvmrc`/`.tool-versions`/volta, Docker `FROM node:` tag, CI `node-version`, `engine-strict=true`. **Safe-change:** keep `engines`, `.nvmrc`, Docker tag, CI version in lockstep; pin the package manager via Corepack `packageManager`; set `engine-strict` if load-bearing; test on the lowest supported runtime. *(Own home — the declared-engine↔installed-runtime contract is its own source-of-truth; cross-ref `lockfile-resolution-contract` and `ci-pipeline-config-contract`.)* *(This repo: Node 22 LTS, pnpm/yarn/npm detected from lockfile — `.claude/rules/general.md`.)*
+The contract that the runtime/package-manager present matches what the code + lockfile were built against. **Where:** `package.json` `engines`+`packageManager` (Corepack), `.nvmrc`/`.node-version`, volta, `.tool-versions`, Docker base tags, CI `setup-node`. **Breaks:** declared engine + installed runtime are separate — a mismatched Node major breaks native addons or uses changed built-ins; a different package-manager version regenerates the lockfile differently; `engines` is advisory by default so drift is silent unless `engine-strict`. **Detect:** `engines`/`packageManager`, `.nvmrc`/`.tool-versions`/volta, Docker `FROM node:` tag, CI `node-version`, `engine-strict=true`. **Safe-change:** keep `engines`, `.nvmrc`, Docker tag, CI version in lockstep; pin the package manager via Corepack `packageManager`; set `engine-strict` if load-bearing; test on the lowest supported runtime. _(Own home — the declared-engine↔installed-runtime contract is its own source-of-truth; cross-ref `lockfile-resolution-contract` and `ci-pipeline-config-contract`.)_ _(This repo: Node 22 LTS, pnpm/yarn/npm detected from lockfile — `.claude/rules/general.md`.)_
 #### `lockfile-resolution-contract` — HIGH · point
-The contract that the committed lockfile pins the exact, reproducible dependency tree everyone + CI installs. **Where:** `pnpm-lock.yaml`/`package-lock.json`/`yarn.lock`/`bun.lockb`, `npm ci`/`--frozen-lockfile`, `overrides`/`resolutions`, integrity hashes. **Breaks:** the lockfile is the contract between what ranges allow + what installs — editing `package.json` without updating the lock, mixing managers, or CI installing without `--frozen-lockfile` drifts the installed tree from what was tested (untested transitive versions, silently). **Detect:** exactly one lockfile (multiple = mixed-manager hazard), `--frozen-lockfile`/`npm ci` in CI, `overrides`/`resolutions`, `lockfileVersion`, out-of-sync `package.json` vs lock. **Safe-change:** commit the lockfile with every `package.json` change (never hand-edit); `--frozen-lockfile`/`npm ci` in CI; one manager per repo (delete stray lockfiles); encode forced versions in `overrides`/`resolutions` + re-lock. *(Own home — the lockfile-pinned dependency tree is its own source-of-truth; cross-ref `peer-dependency-contract` and `node-engines-runtime-contract`.)*
+The contract that the committed lockfile pins the exact, reproducible dependency tree everyone + CI installs. **Where:** `pnpm-lock.yaml`/`package-lock.json`/`yarn.lock`/`bun.lockb`, `npm ci`/`--frozen-lockfile`, `overrides`/`resolutions`, integrity hashes. **Breaks:** the lockfile is the contract between what ranges allow + what installs — editing `package.json` without updating the lock, mixing managers, or CI installing without `--frozen-lockfile` drifts the installed tree from what was tested (untested transitive versions, silently). **Detect:** exactly one lockfile (multiple = mixed-manager hazard), `--frozen-lockfile`/`npm ci` in CI, `overrides`/`resolutions`, `lockfileVersion`, out-of-sync `package.json` vs lock. **Safe-change:** commit the lockfile with every `package.json` change (never hand-edit); `--frozen-lockfile`/`npm ci` in CI; one manager per repo (delete stray lockfiles); encode forced versions in `overrides`/`resolutions` + re-lock. _(Own home — the lockfile-pinned dependency tree is its own source-of-truth; cross-ref `peer-dependency-contract` and `node-engines-runtime-contract`.)_
 #### `monorepo-task-pipeline` — HIGH · point
-The contract describing inter-package task deps, inputs/outputs, and cache keys determining build/test ordering + cache validity. **Where:** Turborepo (`turbo.json` `pipeline`/`dependsOn`/`inputs`/`outputs`), Nx (`nx.json` `targetDefaults`/`namedInputs`), remote caching. **Breaks:** the config declares what depends on what + which files invalidate cache — mis-declared `inputs`/`outputs` means a changed file doesn't bust the cache (a stale artifact served as fresh) or a downstream task runs before its dependency; the dep graph is config, decoupled from the import graph. **Detect:** `turbo.json`/`nx.json`/`project.json` `targets`, `dependsOn`/`inputs`/`outputs`/`namedInputs`, `cache: true`, `.turbo`/`.nx/cache`. **Safe-change:** declare all real inputs (source globs + env via `env`/`passThroughEnv`); declare `outputs` accurately; keep `dependsOn` aligned with the package dep graph; treat env-var inputs explicitly. *(Own home — the task-pipeline/cache-key graph is its own source-of-truth; cross-ref `workspace-package-graph` (the import graph it tracks).)*
+The contract describing inter-package task deps, inputs/outputs, and cache keys determining build/test ordering + cache validity. **Where:** Turborepo (`turbo.json` `pipeline`/`dependsOn`/`inputs`/`outputs`), Nx (`nx.json` `targetDefaults`/`namedInputs`), remote caching. **Breaks:** the config declares what depends on what + which files invalidate cache — mis-declared `inputs`/`outputs` means a changed file doesn't bust the cache (a stale artifact served as fresh) or a downstream task runs before its dependency; the dep graph is config, decoupled from the import graph. **Detect:** `turbo.json`/`nx.json`/`project.json` `targets`, `dependsOn`/`inputs`/`outputs`/`namedInputs`, `cache: true`, `.turbo`/`.nx/cache`. **Safe-change:** declare all real inputs (source globs + env via `env`/`passThroughEnv`); declare `outputs` accurately; keep `dependsOn` aligned with the package dep graph; treat env-var inputs explicitly. _(Own home — the task-pipeline/cache-key graph is its own source-of-truth; cross-ref `workspace-package-graph` (the import graph it tracks).)_
 #### `css-design-token-contract` — MED · transcribe
-The build/import facet of design tokens — shared CSS custom-property names, Tailwind theme config, and style-import order components depend on. **Where:** Tailwind 4 `@theme`/CSS-first config, CSS custom properties, CSS Modules, `@nurix/components` styles import, PostCSS, Style Dictionary. **Breaks:** components reference token names defined elsewhere + the app must import the styles + provide the tokens — rename a token, change Tailwind config, or forget the styles import and components render unstyled with no JS error; Tailwind v4 content-scanning silently drops unseen classes. **Detect:** `@theme`/`tailwind.config`/`@tailwind`/`@import` of a package's styles, `var(--*)`, CSS Module imports, `import '@nurix/components/styles'`. **Safe-change:** treat token names as public (deprecate before rename); ensure consuming apps import the library styles + Tailwind sees the classes; one token source generated per platform; verify rendered UI. *(Folds into frontend `design-token-contract` — same design-token source-of-truth, same `transcribe` doc-mode; this is its build/import facet.)*
+The build/import facet of design tokens — shared CSS custom-property names, Tailwind theme config, and style-import order components depend on. **Where:** Tailwind 4 `@theme`/CSS-first config, CSS custom properties, CSS Modules, `@nurix/components` styles import, PostCSS, Style Dictionary. **Breaks:** components reference token names defined elsewhere + the app must import the styles + provide the tokens — rename a token, change Tailwind config, or forget the styles import and components render unstyled with no JS error; Tailwind v4 content-scanning silently drops unseen classes. **Detect:** `@theme`/`tailwind.config`/`@tailwind`/`@import` of a package's styles, `var(--*)`, CSS Module imports, `import '@nurix/components/styles'`. **Safe-change:** treat token names as public (deprecate before rename); ensure consuming apps import the library styles + Tailwind sees the classes; one token source generated per platform; verify rendered UI. _(Folds into frontend `design-token-contract` — same design-token source-of-truth, same `transcribe` doc-mode; this is its build/import facet.)_
 ---
 ## 7 · RUNTIME, PROCESS, NETWORK & INFRA
 #### `edge-binding` — CRITICAL · point
-The named-capability contract between an edge/serverless function + its platform resources (KV, R2, D1, queues, secrets, service bindings), declared at deploy. **Where:** Cloudflare Workers/Pages (`wrangler.toml` `[[kv_namespaces]]`/`[[r2_buckets]]`/`[[d1_databases]]`/`[[services]]`/`[vars]`/`[[durable_objects.bindings]]`), accessed as `env.BINDING_NAME`. **Breaks:** code references `env.MY_KV`/`env.MY_DO` — rename/remove the binding in config and the runtime hands `undefined`, calls throw at request time with no compile error; bindings are *not* inherited across environments, so one present in `[env.staging]` but missing in production silently 500s only in prod. **Detect:** `**/wrangler.{toml,jsonc,json}`, `env\.[A-Z_]+` in `src/`, cross-referenced against declared bindings, `[env.*]` sub-tables. **Safe-change:** rename the binding in config AND every `env.X` ref together; verify the binding in *every* named environment; for service bindings confirm the target Worker exists; for DO bindings match `class_name` to an exported class. *(Own home — the wrangler binding↔`env.X` contract is its own source-of-truth; cross-ref `do-class-contract` for DO bindings.)*
+The named-capability contract between an edge/serverless function + its platform resources (KV, R2, D1, queues, secrets, service bindings), declared at deploy. **Where:** Cloudflare Workers/Pages (`wrangler.toml` `[[kv_namespaces]]`/`[[r2_buckets]]`/`[[d1_databases]]`/`[[services]]`/`[vars]`/`[[durable_objects.bindings]]`), accessed as `env.BINDING_NAME`. **Breaks:** code references `env.MY_KV`/`env.MY_DO` — rename/remove the binding in config and the runtime hands `undefined`, calls throw at request time with no compile error; bindings are _not_ inherited across environments, so one present in `[env.staging]` but missing in production silently 500s only in prod. **Detect:** `**/wrangler.{toml,jsonc,json}`, `env\.[A-Z_]+` in `src/`, cross-referenced against declared bindings, `[env.*]` sub-tables. **Safe-change:** rename the binding in config AND every `env.X` ref together; verify the binding in _every_ named environment; for service bindings confirm the target Worker exists; for DO bindings match `class_name` to an exported class. _(Own home — the wrangler binding↔`env.X` contract is its own source-of-truth; cross-ref `do-class-contract` for DO bindings.)_
 #### `do-class-contract` — CRITICAL · point
-The binding between a Durable Object's exported class name, RPC method surface, and persisted storage shape across deploys. **Where:** Cloudflare Durable Objects — `wrangler.toml` `[[migrations]]` (`new_classes`/`renamed_classes`/`deleted_classes`), `class MyDO extends DurableObject`, `state.storage`/SQLite. **Breaks:** renaming/deleting a DO class without a `[[migrations]]` entry orphans live stateful objects (stored data unreachable); changing an RPC signature breaks callers holding stubs; changing persisted storage schema breaks objects that outlive a deploy. **Detect:** `extends DurableObject`, `idFromName`/`get(id)`, the `[[migrations]]` tag sequence, `state.storage.get/put` keys + DO-internal SQL. **Safe-change:** every class rename/delete needs a matching `[[migrations]]` entry with an incremented tag; never reuse a migration tag (append-only, ordered); treat persisted keys/SQL as versioned + read-tolerate old shapes; roll RPC changes additively. *(Own home — the DO class↔RPC↔storage contract is its own source-of-truth; cross-ref `edge-binding` (the binding that resolves the class) and async `realtime-channel-naming` (DO rooms).)* *(This repo's cf-realtime L1 uses Durable Object rooms.)*
+The binding between a Durable Object's exported class name, RPC method surface, and persisted storage shape across deploys. **Where:** Cloudflare Durable Objects — `wrangler.toml` `[[migrations]]` (`new_classes`/`renamed_classes`/`deleted_classes`), `class MyDO extends DurableObject`, `state.storage`/SQLite. **Breaks:** renaming/deleting a DO class without a `[[migrations]]` entry orphans live stateful objects (stored data unreachable); changing an RPC signature breaks callers holding stubs; changing persisted storage schema breaks objects that outlive a deploy. **Detect:** `extends DurableObject`, `idFromName`/`get(id)`, the `[[migrations]]` tag sequence, `state.storage.get/put` keys + DO-internal SQL. **Safe-change:** every class rename/delete needs a matching `[[migrations]]` entry with an incremented tag; never reuse a migration tag (append-only, ordered); treat persisted keys/SQL as versioned + read-tolerate old shapes; roll RPC changes additively. _(Own home — the DO class↔RPC↔storage contract is its own source-of-truth; cross-ref `edge-binding` (the binding that resolves the class) and async `realtime-channel-naming` (DO rooms).)_ _(This repo's cf-realtime L1 uses Durable Object rooms.)_
 #### `lambda-handler-contract` — HIGH · point
-The fixed handler signature + event/context payload shape the FaaS platform invokes. **Where:** AWS Lambda (`exports.handler = async (event, context)`), API Gateway proxy event (v1 vs v2 payload format), SQS/SNS/S3/EventBridge trigger envelopes; Azure/GCP equivalents. **Breaks:** the platform owns one side — switching API Gateway payload v1→v2 moves `event.httpMethod` to `event.requestContext.http.method` (existing parsing reads `undefined`); changing the trigger type changes the whole envelope; renaming the handler without updating the `Handler` config makes it un-invocable. **Detect:** `exports.handler`/`def handler`, IaC `Handler:`/`handler =` strings, `event.requestContext`/`event.Records`/`event.httpMethod`. **Safe-change:** pin the API Gateway payload format version; validate the event shape with Zod at the handler; keep the `Handler:` string in lockstep with the exported symbol; treat each new trigger's envelope as a new contract. *(Own home — the FaaS handler signature + event-envelope contract is its own source-of-truth.)*
+The fixed handler signature + event/context payload shape the FaaS platform invokes. **Where:** AWS Lambda (`exports.handler = async (event, context)`), API Gateway proxy event (v1 vs v2 payload format), SQS/SNS/S3/EventBridge trigger envelopes; Azure/GCP equivalents. **Breaks:** the platform owns one side — switching API Gateway payload v1→v2 moves `event.httpMethod` to `event.requestContext.http.method` (existing parsing reads `undefined`); changing the trigger type changes the whole envelope; renaming the handler without updating the `Handler` config makes it un-invocable. **Detect:** `exports.handler`/`def handler`, IaC `Handler:`/`handler =` strings, `event.requestContext`/`event.Records`/`event.httpMethod`. **Safe-change:** pin the API Gateway payload format version; validate the event shape with Zod at the handler; keep the `Handler:` string in lockstep with the exported symbol; treat each new trigger's envelope as a new contract. _(Own home — the FaaS handler signature + event-envelope contract is its own source-of-truth.)_
 #### `cold-start-assumption` — HIGH · transcribe
-The implicit contract about what runs at module/init scope vs per-invocation, and the latency/state budget of a fresh execution environment. **Where:** Lambda init phase (top-level `await`, provisioned concurrency, SnapStart), Cloudflare Workers global scope (no persistent globals guaranteed; isolate reuse not guaranteed), serverless containers. **Breaks:** code assuming a module-scope DB pool/secret persists across invocations breaks when the platform recycles isolates or scales out; un-awaited init work runs on the *first* invocation (latency); mutating module-global state assuming single-tenancy leaks data across requests in a reused isolate. **Detect:** top-level mutable state/pools/caches in handler modules, `let cache = {}` at module scope, missing top-level `await`, `globalThis` mutation tied to a request. **Safe-change:** treat module-global state as per-isolate cache never request storage; `await` init side-effects at module top-level (Lambda); don't assume warm reuse for correctness; bound init work against the init timeout. *(Own home — the init-scope-vs-per-invocation assumption is its own transcribed contract.)*
+The implicit contract about what runs at module/init scope vs per-invocation, and the latency/state budget of a fresh execution environment. **Where:** Lambda init phase (top-level `await`, provisioned concurrency, SnapStart), Cloudflare Workers global scope (no persistent globals guaranteed; isolate reuse not guaranteed), serverless containers. **Breaks:** code assuming a module-scope DB pool/secret persists across invocations breaks when the platform recycles isolates or scales out; un-awaited init work runs on the _first_ invocation (latency); mutating module-global state assuming single-tenancy leaks data across requests in a reused isolate. **Detect:** top-level mutable state/pools/caches in handler modules, `let cache = {}` at module scope, missing top-level `await`, `globalThis` mutation tied to a request. **Safe-change:** treat module-global state as per-isolate cache never request storage; `await` init side-effects at module top-level (Lambda); don't assume warm reuse for correctness; bound init work against the init timeout. _(Own home — the init-scope-vs-per-invocation assumption is its own transcribed contract.)_
 #### `worker-thread-boundary` — MED · transcribe
-The structured-clone / transferable / `SharedArrayBuffer` contract for data crossing a thread or process boundary. **Where:** Node `worker_threads` (`postMessage`, `transferList`), browser Web Workers, `Atomics`/`SharedArrayBuffer`, `child_process` IPC (`process.send`). **Breaks:** only structured-cloneable values cross — functions, class instances (methods lost), closures don't survive `postMessage`; passing a non-transferable as transferable throws; mutating after transfer touches a detached buffer; prototype/class identity is lost (`instanceof` fails). **Detect:** `new Worker(`, `postMessage(`, `parentPort`, `MessageChannel`, `process.send(`, `Atomics.`, `SharedArrayBuffer`. **Safe-change:** pass plain data + reconstruct rich objects on receipt; version the message envelope (`{type,payload}`) + validate; don't reuse a buffer after `transferList`; share a TS type for the protocol. *(Own home — the thread/process structured-clone contract; cross-ref frontend `state-serialization-contract` (the server→client facet of the same hazard).)*
+The structured-clone / transferable / `SharedArrayBuffer` contract for data crossing a thread or process boundary. **Where:** Node `worker_threads` (`postMessage`, `transferList`), browser Web Workers, `Atomics`/`SharedArrayBuffer`, `child_process` IPC (`process.send`). **Breaks:** only structured-cloneable values cross — functions, class instances (methods lost), closures don't survive `postMessage`; passing a non-transferable as transferable throws; mutating after transfer touches a detached buffer; prototype/class identity is lost (`instanceof` fails). **Detect:** `new Worker(`, `postMessage(`, `parentPort`, `MessageChannel`, `process.send(`, `Atomics.`, `SharedArrayBuffer`. **Safe-change:** pass plain data + reconstruct rich objects on receipt; version the message envelope (`{type,payload}`) + validate; don't reuse a buffer after `transferList`; share a TS type for the protocol. _(Own home — the thread/process structured-clone contract; cross-ref frontend `state-serialization-contract` (the server→client facet of the same hazard).)_
 #### `container-image-contract` — HIGH · point
-The runtime contract baked into a container image — entrypoint/CMD, exposed ports, workdir, user, env defaults, required volumes. **Where:** Dockerfile (`ENTRYPOINT`/`CMD`/`EXPOSE`/`USER`/`WORKDIR`/`VOLUME`/`ENV`), OCI metadata, consuming compose/K8s pod spec. **Breaks:** the orchestrator + other containers depend on these — changing `EXPOSE`/the listen port without updating compose/K8s `containerPort`/Service breaks routing; switching `USER` to non-root breaks mounted-volume writes; `ENTRYPOINT` shell vs exec form changes signal delivery; removing a `VOLUME` loses persistence. **Detect:** `**/Dockerfile*`, `**/docker-compose*.yml`, diff `EXPOSE`/`ENV`/`USER`/`ENTRYPOINT` against compose `ports:`/`environment:` + K8s `containerPort`/`securityContext`. **Safe-change:** keep `EXPOSE` == listen port == compose/K8s `containerPort` == Service target; prefer exec-form `ENTRYPOINT` so signals reach PID 1; document required volumes + env as the interface; verify volume permissions if changing `USER`. *(Own home — the image runtime interface (entrypoint/ports/user/volumes) is its own source-of-truth; cross-ref `exposed-port-contract`, `graceful-shutdown`, `process-lifecycle-contract`, `docker-build-arg-env`.)*
+The runtime contract baked into a container image — entrypoint/CMD, exposed ports, workdir, user, env defaults, required volumes. **Where:** Dockerfile (`ENTRYPOINT`/`CMD`/`EXPOSE`/`USER`/`WORKDIR`/`VOLUME`/`ENV`), OCI metadata, consuming compose/K8s pod spec. **Breaks:** the orchestrator + other containers depend on these — changing `EXPOSE`/the listen port without updating compose/K8s `containerPort`/Service breaks routing; switching `USER` to non-root breaks mounted-volume writes; `ENTRYPOINT` shell vs exec form changes signal delivery; removing a `VOLUME` loses persistence. **Detect:** `**/Dockerfile*`, `**/docker-compose*.yml`, diff `EXPOSE`/`ENV`/`USER`/`ENTRYPOINT` against compose `ports:`/`environment:` + K8s `containerPort`/`securityContext`. **Safe-change:** keep `EXPOSE` == listen port == compose/K8s `containerPort` == Service target; prefer exec-form `ENTRYPOINT` so signals reach PID 1; document required volumes + env as the interface; verify volume permissions if changing `USER`. _(Own home — the image runtime interface (entrypoint/ports/user/volumes) is its own source-of-truth; cross-ref `exposed-port-contract`, `graceful-shutdown`, `process-lifecycle-contract`, `docker-build-arg-env`.)_
 #### `exposed-port-contract` — HIGH · point
-The agreement on which port a process listens on + how upstream routers reach it. **Where:** app `listen(PORT)`, `Dockerfile EXPOSE`, compose `ports:`/`expose:`, K8s `containerPort`+Service `targetPort`, reverse-proxy `upstream`/`proxy_pass`. **Breaks:** a port is referenced in 3–5 disconnected places — change the app's listen port + forget the Service `targetPort` and traffic black-holes with connection-refused, no app-log error. **Detect:** `listen(`, `PORT`, `EXPOSE`, `targetPort`, `containerPort`, `proxy_pass`, `upstream`. **Safe-change:** source the port from one env var everywhere; update proxy/Service/compose mappings in the same change; verify the health-check probe targets the new port. *(Own home — the listen-port↔router wiring is its own source-of-truth; cross-ref `container-image-contract` (`EXPOSE`), `ingress-routing-rule`, `health-check-contract`.)*
+The agreement on which port a process listens on + how upstream routers reach it. **Where:** app `listen(PORT)`, `Dockerfile EXPOSE`, compose `ports:`/`expose:`, K8s `containerPort`+Service `targetPort`, reverse-proxy `upstream`/`proxy_pass`. **Breaks:** a port is referenced in 3–5 disconnected places — change the app's listen port + forget the Service `targetPort` and traffic black-holes with connection-refused, no app-log error. **Detect:** `listen(`, `PORT`, `EXPOSE`, `targetPort`, `containerPort`, `proxy_pass`, `upstream`. **Safe-change:** source the port from one env var everywhere; update proxy/Service/compose mappings in the same change; verify the health-check probe targets the new port. _(Own home — the listen-port↔router wiring is its own source-of-truth; cross-ref `container-image-contract` (`EXPOSE`), `ingress-routing-rule`, `health-check-contract`.)_
 #### `ingress-routing-rule` — HIGH · point
-The host/path → backend mapping enforced by an ingress/reverse-proxy/gateway. **Where:** nginx `location`/`server_name`, K8s `Ingress`/Gateway API `HTTPRoute`, Envoy `route_config`, Traefik `IngressRoute`, Cloudflare/Caddy, API Gateway paths. **Breaks:** route matching is order- + specificity-sensitive — renaming an app route prefix without updating the ingress rule → 404 at the edge while the app is healthy; a path-rewrite/strip-prefix mismatch sends the backend an unrecognized path; a broader catch-all above a specific route shadows it. **Detect:** `**/*.conf` (nginx), `kind: Ingress|HTTPRoute|VirtualService`, Envoy `route` YAML, Traefik labels; match `path`/`prefix`/`rewrite` against mounted routes. **Safe-change:** change app route prefix + ingress rule together (verify rewrite/strip-prefix); check rule ordering for shadowing; confirm host + TLS SNI align. *(Own home — the host/path→backend mapping is its own source-of-truth; cross-ref `exposed-port-contract`, `dns-tls-san`, `service-discovery-contract`.)*
+The host/path → backend mapping enforced by an ingress/reverse-proxy/gateway. **Where:** nginx `location`/`server_name`, K8s `Ingress`/Gateway API `HTTPRoute`, Envoy `route_config`, Traefik `IngressRoute`, Cloudflare/Caddy, API Gateway paths. **Breaks:** route matching is order- + specificity-sensitive — renaming an app route prefix without updating the ingress rule → 404 at the edge while the app is healthy; a path-rewrite/strip-prefix mismatch sends the backend an unrecognized path; a broader catch-all above a specific route shadows it. **Detect:** `**/*.conf` (nginx), `kind: Ingress|HTTPRoute|VirtualService`, Envoy `route` YAML, Traefik labels; match `path`/`prefix`/`rewrite` against mounted routes. **Safe-change:** change app route prefix + ingress rule together (verify rewrite/strip-prefix); check rule ordering for shadowing; confirm host + TLS SNI align. _(Own home — the host/path→backend mapping is its own source-of-truth; cross-ref `exposed-port-contract`, `dns-tls-san`, `service-discovery-contract`.)_
 #### `cors-policy` — HIGH · transcribe
-The allowed-origins/methods/headers/credentials contract the server advertises + the browser enforces (infra-layer view of `cors-preflight-contract`). **Where:** Express `cors({ origin })`, server `Access-Control-Allow-*`, preflight `OPTIONS`, CDN/edge CORS rules, K8s ingress annotations. **Breaks:** the browser is the enforcer — move the frontend to a new domain + forget the allow-list and all XHR/fetch fails CORS in the browser only (curl/server-to-server works, so backend tests pass); adding `Authorization` without `Allow-Headers` breaks preflight; `Allow-Credentials: true` is incompatible with `Allow-Origin: *`. **Detect:** `cors(`, `Access-Control-Allow-`, `FRONTEND_URL`, `origin:`, edge/CDN + ingress CORS. **Safe-change:** update the allow-list on any frontend-origin change (every env); list every custom request header in `Allow-Headers`; never pair credentials with wildcard origin; verify preflight `OPTIONS` returns 2xx. *(Folds into API `cors-preflight-contract` — same CORS contract, same `transcribe` doc-mode; this is its infra-layer view.)*
+The allowed-origins/methods/headers/credentials contract the server advertises + the browser enforces (infra-layer view of `cors-preflight-contract`). **Where:** Express `cors({ origin })`, server `Access-Control-Allow-*`, preflight `OPTIONS`, CDN/edge CORS rules, K8s ingress annotations. **Breaks:** the browser is the enforcer — move the frontend to a new domain + forget the allow-list and all XHR/fetch fails CORS in the browser only (curl/server-to-server works, so backend tests pass); adding `Authorization` without `Allow-Headers` breaks preflight; `Allow-Credentials: true` is incompatible with `Allow-Origin: *`. **Detect:** `cors(`, `Access-Control-Allow-`, `FRONTEND_URL`, `origin:`, edge/CDN + ingress CORS. **Safe-change:** update the allow-list on any frontend-origin change (every env); list every custom request header in `Allow-Headers`; never pair credentials with wildcard origin; verify preflight `OPTIONS` returns 2xx. _(Folds into API `cors-preflight-contract` — same CORS contract, same `transcribe` doc-mode; this is its infra-layer view.)_
 #### `cache-header-contract` — HIGH · transcribe
-The `Cache-Control`/`ETag`/`Expires`/`Last-Modified` directives deciding how long every cache (browser/CDN/proxy) holds a response. **Where:** origin response headers, CDN config (Cloudflare/Fastly/CloudFront), `s-maxage`/`stale-while-revalidate`, asset-hashing strategy. **Breaks:** the cache obeys the header you sent — ship a bugfix while a `max-age=300` response is cached and users see the broken version for 5 min; `immutable` on a non-hashed asset means users never update; caching a personalized response publicly leaks one user's data to another. **Detect:** `Cache-Control`, `setHeader('ETag'`, `s-maxage`, `immutable`, `stale-while-revalidate`, CDN config + asset hashing. **Safe-change:** `immutable`/long-max-age only on content-hashed assets, short TTL for HTML/API; never cache personalized responses in a shared/CDN cache; add a cache-purge step to deploys; lower TTL before a risky release. *(Own home — the `Cache-Control`/TTL/CDN-duration contract (`transcribe`); the ETag/`If-Match` concurrency facet is API `conditional-request-caching-contract` (`point`), the cache-key facet is `vary-header-contract`.)*
+The `Cache-Control`/`ETag`/`Expires`/`Last-Modified` directives deciding how long every cache (browser/CDN/proxy) holds a response. **Where:** origin response headers, CDN config (Cloudflare/Fastly/CloudFront), `s-maxage`/`stale-while-revalidate`, asset-hashing strategy. **Breaks:** the cache obeys the header you sent — ship a bugfix while a `max-age=300` response is cached and users see the broken version for 5 min; `immutable` on a non-hashed asset means users never update; caching a personalized response publicly leaks one user's data to another. **Detect:** `Cache-Control`, `setHeader('ETag'`, `s-maxage`, `immutable`, `stale-while-revalidate`, CDN config + asset hashing. **Safe-change:** `immutable`/long-max-age only on content-hashed assets, short TTL for HTML/API; never cache personalized responses in a shared/CDN cache; add a cache-purge step to deploys; lower TTL before a risky release. _(Own home — the `Cache-Control`/TTL/CDN-duration contract (`transcribe`); the ETag/`If-Match` concurrency facet is API `conditional-request-caching-contract` (`point`), the cache-key facet is `vary-header-contract`.)_
 #### `vary-header-contract` — HIGH · point
-The request headers a cache must factor into its cache key, declared via `Vary` (+ CDN custom keys). **Where:** `Vary: Accept-Encoding, Accept-Language`, CDN cache-key config (Cloudflare Cache Rules, Fastly VCL), content negotiation. **Breaks:** return language- or auth-dependent content without listing the header in `Vary` and the CDN serves a French user the cached English page — or one logged-in user's response to another; conversely `Vary: Authorization` on a public CDN explodes cache cardinality. **Detect:** `Vary`, `Accept-Language`/`Accept-Encoding` branching, CDN cache-key settings, responses branching on request headers. **Safe-change:** any header the response branches on must appear in `Vary` (or the CDN key); never `Vary: Authorization`/cache personalized content on a shared cache; keep `Vary` + CDN key config consistent. *(Own home — the cache-key (`Vary`) contract is `point`, a different doc-mode/concern from the `transcribe` `cache-header-contract`.)*
+The request headers a cache must factor into its cache key, declared via `Vary` (+ CDN custom keys). **Where:** `Vary: Accept-Encoding, Accept-Language`, CDN cache-key config (Cloudflare Cache Rules, Fastly VCL), content negotiation. **Breaks:** return language- or auth-dependent content without listing the header in `Vary` and the CDN serves a French user the cached English page — or one logged-in user's response to another; conversely `Vary: Authorization` on a public CDN explodes cache cardinality. **Detect:** `Vary`, `Accept-Language`/`Accept-Encoding` branching, CDN cache-key settings, responses branching on request headers. **Safe-change:** any header the response branches on must appear in `Vary` (or the CDN key); never `Vary: Authorization`/cache personalized content on a shared cache; keep `Vary` + CDN key config consistent. _(Own home — the cache-key (`Vary`) contract is `point`, a different doc-mode/concern from the `transcribe` `cache-header-contract`.)_
 #### `dns-tls-san` — HIGH · point
-The binding between hostnames clients dial, DNS records, and the SANs/CN on the presented TLS cert. **Where:** DNS records, Let's Encrypt/ACM/cert-manager `Certificate` `dnsNames`, ingress `tls.hosts`, SNI routing, service hostnames. **Breaks:** a cert is valid only for its SANs — add a subdomain/route a service under a new host without adding it to the cert and the TLS handshake fails (`ERR_CERT_COMMON_NAME_INVALID`) for that host only; rename a service's DNS without updating consumers → NXDOMAIN; SNI mismatch routes to the wrong backend. **Detect:** `dnsNames`, `tls:`/`hosts:`, `server_name`, hardcoded hostnames in client config, cert-manager `Certificate`, ingress `tls`. **Safe-change:** add any new hostname to the cert SAN list before routing traffic; keep DNS + ingress `tls.hosts` + cert `dnsNames` synced; verify SNI/Host alignment; mind wildcard scope (`*.example.com` ≠ `a.b.example.com`). *(Own home — the hostname↔DNS↔cert-SAN binding is its own source-of-truth; cross-ref `ingress-routing-rule`.)*
+The binding between hostnames clients dial, DNS records, and the SANs/CN on the presented TLS cert. **Where:** DNS records, Let's Encrypt/ACM/cert-manager `Certificate` `dnsNames`, ingress `tls.hosts`, SNI routing, service hostnames. **Breaks:** a cert is valid only for its SANs — add a subdomain/route a service under a new host without adding it to the cert and the TLS handshake fails (`ERR_CERT_COMMON_NAME_INVALID`) for that host only; rename a service's DNS without updating consumers → NXDOMAIN; SNI mismatch routes to the wrong backend. **Detect:** `dnsNames`, `tls:`/`hosts:`, `server_name`, hardcoded hostnames in client config, cert-manager `Certificate`, ingress `tls`. **Safe-change:** add any new hostname to the cert SAN list before routing traffic; keep DNS + ingress `tls.hosts` + cert `dnsNames` synced; verify SNI/Host alignment; mind wildcard scope (`*.example.com` ≠ `a.b.example.com`). _(Own home — the hostname↔DNS↔cert-SAN binding is its own source-of-truth; cross-ref `ingress-routing-rule`.)_
 #### `iac-output-contract` — HIGH · point
-The named outputs of one infra stack consumed by another stack or app config. **Where:** Terraform `output` + `terraform_remote_state`/`tfe_outputs`, Pulumi `StackReference`, CloudFormation `Exports`/`Fn::ImportValue`, CDK cross-stack refs. **Breaks:** a consuming stack reads `data.terraform_remote_state.x.outputs.vpc_id` — rename/remove that output + every consumer fails to plan/apply; changing the producer's backend bucket/key/region means consumers can't find the state; `terraform_remote_state` exposes the *entire* state (secret leak). **Detect:** `**/*.tf`, `output "`, `terraform_remote_state`, `tfe_outputs`, `StackReference`, `Fn::ImportValue`. **Safe-change:** treat output names as public (deprecate, don't rename); prefer SSM/`tfe_outputs` over full-state reads (least privilege); don't move the producer's backend without coordinating; grep all consumers before removing. *(Own home — the cross-stack IaC output contract is its own source-of-truth.)*
+The named outputs of one infra stack consumed by another stack or app config. **Where:** Terraform `output` + `terraform_remote_state`/`tfe_outputs`, Pulumi `StackReference`, CloudFormation `Exports`/`Fn::ImportValue`, CDK cross-stack refs. **Breaks:** a consuming stack reads `data.terraform_remote_state.x.outputs.vpc_id` — rename/remove that output + every consumer fails to plan/apply; changing the producer's backend bucket/key/region means consumers can't find the state; `terraform_remote_state` exposes the _entire_ state (secret leak). **Detect:** `**/*.tf`, `output "`, `terraform_remote_state`, `tfe_outputs`, `StackReference`, `Fn::ImportValue`. **Safe-change:** treat output names as public (deprecate, don't rename); prefer SSM/`tfe_outputs` over full-state reads (least privilege); don't move the producer's backend without coordinating; grep all consumers before removing. _(Own home — the cross-stack IaC output contract is its own source-of-truth.)_
 #### `inter-service-resilience-contract` — HIGH · transcribe
-The agreed timeout/retry/circuit-breaker/connection-pool budget between a caller + a downstream service. **Where:** Istio `DestinationRule`+`VirtualService`, Envoy `retry_policy`/`circuit_breakers`, client libs (axios timeout, gRPC deadlines), resilience4j/Polly. **Breaks:** timeouts must form a coherent hierarchy — a caller timeout shorter than the callee's makes the callee finish work the caller abandoned; lowering a downstream timeout while callers retry 3× triggers a retry storm that takes down a recovering service; tightening `maxConnections` trips the breaker under normal load; these configs live in a different repo/layer than the calling code. **Detect:** `timeout`, `retries`/`retry_policy`, `circuit_breaker`/`outlierDetection`, `maxConnections`, `deadline`, mesh `DestinationRule`/`VirtualService`. **Safe-change:** keep caller timeout > callee timeout + retries; cap total retry amplification + jittered backoff; tune breaker/pool limits against measured load; change mesh policy + client expectations together. *(Own home — the timeout/retry/breaker budget between services is its own transcribed contract.)*
+The agreed timeout/retry/circuit-breaker/connection-pool budget between a caller + a downstream service. **Where:** Istio `DestinationRule`+`VirtualService`, Envoy `retry_policy`/`circuit_breakers`, client libs (axios timeout, gRPC deadlines), resilience4j/Polly. **Breaks:** timeouts must form a coherent hierarchy — a caller timeout shorter than the callee's makes the callee finish work the caller abandoned; lowering a downstream timeout while callers retry 3× triggers a retry storm that takes down a recovering service; tightening `maxConnections` trips the breaker under normal load; these configs live in a different repo/layer than the calling code. **Detect:** `timeout`, `retries`/`retry_policy`, `circuit_breaker`/`outlierDetection`, `maxConnections`, `deadline`, mesh `DestinationRule`/`VirtualService`. **Safe-change:** keep caller timeout > callee timeout + retries; cap total retry amplification + jittered backoff; tune breaker/pool limits against measured load; change mesh policy + client expectations together. _(Own home — the timeout/retry/breaker budget between services is its own transcribed contract.)_
 #### `trace-context-propagation` — MED · point
-The wire headers carrying distributed-trace identity across a hop (`traceparent`/`tracestate`, B3, X-Ray). **Where:** W3C Trace Context, OpenTelemetry propagators, Zipkin B3, `baggage`, AWS `X-Amzn-Trace-Id`. **Breaks:** both services must agree on the format — A injects W3C `traceparent` but B's propagator only reads B3 and the trace breaks into two disconnected traces (observability silently degrades, no error); a proxy dropping the header (allow-lists, size limits) severs the trace; misconfigured propagators break `baggage`-based tenant/feature context. **Detect:** `traceparent`/`tracestate`, `X-B3-`, `baggage`, `propagator`/`TextMapPropagator`, OTel setup, proxy/ingress header allow-lists, CORS `Allow-Headers`. **Safe-change:** standardize on one propagator (W3C) across services; ensure proxies forward `traceparent`/`tracestate`/`baggage`; add trace headers to browser CORS `Allow-Headers`; don't put security-sensitive data in `baggage`. *(Own home — the trace-context wire-header contract is its own source-of-truth.)* *(HIGH if `baggage` carries functional context.)*
+The wire headers carrying distributed-trace identity across a hop (`traceparent`/`tracestate`, B3, X-Ray). **Where:** W3C Trace Context, OpenTelemetry propagators, Zipkin B3, `baggage`, AWS `X-Amzn-Trace-Id`. **Breaks:** both services must agree on the format — A injects W3C `traceparent` but B's propagator only reads B3 and the trace breaks into two disconnected traces (observability silently degrades, no error); a proxy dropping the header (allow-lists, size limits) severs the trace; misconfigured propagators break `baggage`-based tenant/feature context. **Detect:** `traceparent`/`tracestate`, `X-B3-`, `baggage`, `propagator`/`TextMapPropagator`, OTel setup, proxy/ingress header allow-lists, CORS `Allow-Headers`. **Safe-change:** standardize on one propagator (W3C) across services; ensure proxies forward `traceparent`/`tracestate`/`baggage`; add trace headers to browser CORS `Allow-Headers`; don't put security-sensitive data in `baggage`. _(Own home — the trace-context wire-header contract is its own source-of-truth.)_ _(HIGH if `baggage` carries functional context.)_
 #### `log-schema` — MED · transcribe
-The structured-log field-name/type contract every producer emits + every consumer (queries/dashboards/alerts) depends on. **Where:** pino/winston/zap/structlog JSON, shared logger wrappers, Loki/Elasticsearch/Datadog parsing, alert rules keyed on field names. **Breaks:** dashboards, saved queries, + alerts are pinned to exact field names — rename `userId`→`user_id` in one service + the cross-service "all logs for a user" query silently returns nothing; the alert on `level: "error"` goes quiet if you switch to `severity`; a type change (string→object) breaks the index mapping. **Detect:** `logger.info(`/`log.error(` field keys, the shared logger config (pino `base`/`formatters`/`redact`), cross-referenced with alert/dashboard defs. **Safe-change:** treat field names/types as versioned (add new, deprecate old); standardize core fields (`level`/`timestamp`/`service`/`trace_id`/`user_id`); update dashboards/alerts in the same change as a rename; keep `pino.redact` paths synced to renamed fields. *(Own home — the structured-log field contract (`transcribe`) is distinct from the metric-name contract.)* *(This repo uses pino — `.claude/rules/general.md`.)*
+The structured-log field-name/type contract every producer emits + every consumer (queries/dashboards/alerts) depends on. **Where:** pino/winston/zap/structlog JSON, shared logger wrappers, Loki/Elasticsearch/Datadog parsing, alert rules keyed on field names. **Breaks:** dashboards, saved queries, + alerts are pinned to exact field names — rename `userId`→`user_id` in one service + the cross-service "all logs for a user" query silently returns nothing; the alert on `level: "error"` goes quiet if you switch to `severity`; a type change (string→object) breaks the index mapping. **Detect:** `logger.info(`/`log.error(` field keys, the shared logger config (pino `base`/`formatters`/`redact`), cross-referenced with alert/dashboard defs. **Safe-change:** treat field names/types as versioned (add new, deprecate old); standardize core fields (`level`/`timestamp`/`service`/`trace_id`/`user_id`); update dashboards/alerts in the same change as a rename; keep `pino.redact` paths synced to renamed fields. _(Own home — the structured-log field contract (`transcribe`) is distinct from the metric-name contract.)_ _(This repo uses pino — `.claude/rules/general.md`.)_
 #### `metric-name-contract` — MED · point
-Metric names, label/tag keys, and cardinality emitters publish + dashboards/alerts/SLOs consume. **Where:** Prometheus metric names+labels, OpenTelemetry instruments, StatsD/Datadog tags, Grafana dashboards, alerting/recording rules, SLOs. **Breaks:** rename `http_requests_total`→`http_request_count` + every dashboard panel/alert referencing the old name goes blank/silent (no error); adding a high-cardinality label (user-id) explodes the time-series count + can OOM the backend; changing a label key breaks `by(label)` aggregations. **Detect:** `Counter(`/`Histogram(`/`Gauge(`, `meter.create`, metric-name literals, label/tag maps, vendored dashboard/alert JSON. **Safe-change:** treat metric + label names as a contract (deprecate, don't rename); never put unbounded-cardinality values in labels; update dashboards/alerts/SLOs alongside a rename; follow OTel/Prometheus naming. *(Own home — the metric/label-name contract (`point`) is distinct from the structured-log field contract.)*
+Metric names, label/tag keys, and cardinality emitters publish + dashboards/alerts/SLOs consume. **Where:** Prometheus metric names+labels, OpenTelemetry instruments, StatsD/Datadog tags, Grafana dashboards, alerting/recording rules, SLOs. **Breaks:** rename `http_requests_total`→`http_request_count` + every dashboard panel/alert referencing the old name goes blank/silent (no error); adding a high-cardinality label (user-id) explodes the time-series count + can OOM the backend; changing a label key breaks `by(label)` aggregations. **Detect:** `Counter(`/`Histogram(`/`Gauge(`, `meter.create`, metric-name literals, label/tag maps, vendored dashboard/alert JSON. **Safe-change:** treat metric + label names as a contract (deprecate, don't rename); never put unbounded-cardinality values in labels; update dashboards/alerts/SLOs alongside a rename; follow OTel/Prometheus naming. _(Own home — the metric/label-name contract (`point`) is distinct from the structured-log field contract.)_
 #### `health-check-contract` — HIGH · point
-The path, status semantics, and timing of liveness vs readiness vs startup endpoints orchestrators poll. **Where:** K8s `livenessProbe`/`readinessProbe`/`startupProbe`, LB health checks, `/healthz`/`/readyz`/`/livez`, gRPC health service, Spring Actuator. **Breaks:** the orchestrator owns polling, the app owns the endpoint — rename `/healthz`→`/health` without updating the probe + K8s thinks the pod is dead and CrashLoopBackOffs a healthy app; conflating liveness with readiness (checking DB in liveness) kills the pod on a transient DB blip; a readiness probe that doesn't fail fast on shutdown causes 502s during rolling deploys. **Detect:** `/healthz`/`/readyz`/`/livez`/`/health`, `livenessProbe`/`readinessProbe`/`startupProbe`, `app.get('/health'`. **Safe-change:** keep probe path/port in lockstep with the route; liveness = process-only/cheap, readiness = critical deps; readiness fails immediately on SIGTERM; tune `initialDelaySeconds`/`failureThreshold` to real startup. *(Own home — the liveness/readiness/startup-probe contract is its own source-of-truth; cross-ref `graceful-shutdown`, `exposed-port-contract`.)*
+The path, status semantics, and timing of liveness vs readiness vs startup endpoints orchestrators poll. **Where:** K8s `livenessProbe`/`readinessProbe`/`startupProbe`, LB health checks, `/healthz`/`/readyz`/`/livez`, gRPC health service, Spring Actuator. **Breaks:** the orchestrator owns polling, the app owns the endpoint — rename `/healthz`→`/health` without updating the probe + K8s thinks the pod is dead and CrashLoopBackOffs a healthy app; conflating liveness with readiness (checking DB in liveness) kills the pod on a transient DB blip; a readiness probe that doesn't fail fast on shutdown causes 502s during rolling deploys. **Detect:** `/healthz`/`/readyz`/`/livez`/`/health`, `livenessProbe`/`readinessProbe`/`startupProbe`, `app.get('/health'`. **Safe-change:** keep probe path/port in lockstep with the route; liveness = process-only/cheap, readiness = critical deps; readiness fails immediately on SIGTERM; tune `initialDelaySeconds`/`failureThreshold` to real startup. _(Own home — the liveness/readiness/startup-probe contract is its own source-of-truth; cross-ref `graceful-shutdown`, `exposed-port-contract`.)_
 #### `graceful-shutdown` — HIGH · point
-The contract for how a process receives termination signals + drains in-flight work before force-kill. **Where:** K8s `terminationGracePeriodSeconds`+`preStop`+SIGTERM→SIGKILL, `process.on('SIGTERM')`, Docker exec-form ENTRYPOINT (PID 1 signal delivery), connection draining. **Breaks:** the platform sends SIGTERM then SIGKILLs after the grace period — shell-form `ENTRYPOINT` means signals hit the shell not your app (PID 1), so SIGTERM is swallowed + the app is hard-killed; failing readiness fast without a `preStop` sleep races kube-proxy still routing to the terminating pod → 502s; exiting before finishing in-flight requests drops them. **Detect:** `SIGTERM`/`SIGINT`, `process.on(`, `terminationGracePeriodSeconds`, `preStop`, `server.close(`, Dockerfile ENTRYPOINT form, `tini`/`dumb-init`. **Safe-change:** exec-form ENTRYPOINT (or `tini`) so SIGTERM reaches the app as PID 1; on SIGTERM fail readiness → stop new conns → drain → exit; `terminationGracePeriodSeconds` ≥ max request + `preStop` sleep; add a `preStop` sleep for endpoint-propagation delay. *(Own home — the SIGTERM/drain contract is its own source-of-truth; cross-ref `health-check-contract`, `process-lifecycle-contract`, `container-image-contract` (ENTRYPOINT form).)*
+The contract for how a process receives termination signals + drains in-flight work before force-kill. **Where:** K8s `terminationGracePeriodSeconds`+`preStop`+SIGTERM→SIGKILL, `process.on('SIGTERM')`, Docker exec-form ENTRYPOINT (PID 1 signal delivery), connection draining. **Breaks:** the platform sends SIGTERM then SIGKILLs after the grace period — shell-form `ENTRYPOINT` means signals hit the shell not your app (PID 1), so SIGTERM is swallowed + the app is hard-killed; failing readiness fast without a `preStop` sleep races kube-proxy still routing to the terminating pod → 502s; exiting before finishing in-flight requests drops them. **Detect:** `SIGTERM`/`SIGINT`, `process.on(`, `terminationGracePeriodSeconds`, `preStop`, `server.close(`, Dockerfile ENTRYPOINT form, `tini`/`dumb-init`. **Safe-change:** exec-form ENTRYPOINT (or `tini`) so SIGTERM reaches the app as PID 1; on SIGTERM fail readiness → stop new conns → drain → exit; `terminationGracePeriodSeconds` ≥ max request + `preStop` sleep; add a `preStop` sleep for endpoint-propagation delay. _(Own home — the SIGTERM/drain contract is its own source-of-truth; cross-ref `health-check-contract`, `process-lifecycle-contract`, `container-image-contract` (ENTRYPOINT form).)_
 #### `resource-limit-contract` — HIGH · point
-The CPU/memory (+ ephemeral-storage) requests/limits the platform enforces against actual consumption. **Where:** K8s `resources.requests`/`limits`, Docker `--memory`/`--cpus`, Lambda `MemorySize`(+CPU)+`timeout`, Cloudflare Workers CPU-time limit + 128MB cap, OOMKiller. **Breaks:** the limit is enforced by the kernel/platform not the app — raise heap past the memory `limit` (bigger cache, new dep) → OOMKilled (exit 137) with no app error; JVM/Node heap ignoring the cgroup limit OOMs under load; a Worker adding CPU-heavy work exceeds the CPU-ms limit; CPU `limit` throttling adds silent latency. **Detect:** `resources:`/`limits:`/`requests:`, `--memory`/`--cpus`, `MemorySize`, `cpu_ms`, `--max-old-space-size`, `NODE_OPTIONS`. **Safe-change:** re-evaluate limits when adding caches/deps/concurrency; make heap settings cgroup-aware; set requests/limits from measured P99; budget against CPU-time/timeout caps for Workers/Lambda. *(Own home — the CPU/memory requests/limits contract is its own source-of-truth.)*
+The CPU/memory (+ ephemeral-storage) requests/limits the platform enforces against actual consumption. **Where:** K8s `resources.requests`/`limits`, Docker `--memory`/`--cpus`, Lambda `MemorySize`(+CPU)+`timeout`, Cloudflare Workers CPU-time limit + 128MB cap, OOMKiller. **Breaks:** the limit is enforced by the kernel/platform not the app — raise heap past the memory `limit` (bigger cache, new dep) → OOMKilled (exit 137) with no app error; JVM/Node heap ignoring the cgroup limit OOMs under load; a Worker adding CPU-heavy work exceeds the CPU-ms limit; CPU `limit` throttling adds silent latency. **Detect:** `resources:`/`limits:`/`requests:`, `--memory`/`--cpus`, `MemorySize`, `cpu_ms`, `--max-old-space-size`, `NODE_OPTIONS`. **Safe-change:** re-evaluate limits when adding caches/deps/concurrency; make heap settings cgroup-aware; set requests/limits from measured P99; budget against CPU-time/timeout caps for Workers/Lambda. _(Own home — the CPU/memory requests/limits contract is its own source-of-truth.)_
 #### `ipc-protocol-contract` — MED · point
-The message framing/serialization protocol over an in-host IPC transport (sockets/pipes/shared memory), distinct from a public network API. **Where:** Unix domain sockets, named pipes, gRPC over UDS, Node `cluster`/`child_process` IPC, sidecar↔app sockets, Electron `ipcMain`/`ipcRenderer`. **Breaks:** both ends must agree on framing + message shape but are often versioned independently (a sidecar updated separately) — change the schema/channel name/socket path on one side + messages are dropped/misparsed with no network error; Electron `ipcRenderer.invoke('channel')` silently no-ops if `ipcMain.handle('channel')` was renamed. **Detect:** `unix:`/`.sock`, `ipcMain`/`ipcRenderer`, `child.send`/`process.on('message'`, `createServer` on a socket path, gRPC over UDS. **Safe-change:** version the IPC envelope + validate on receipt; keep channel names/socket paths in a shared constant; coordinate sidecar/app upgrades; don't reuse a socket path across protocol versions. *(Own home — the in-host IPC framing/transport is its own source-of-truth; cross-ref `worker-thread-boundary` (the thread variant).)*
+The message framing/serialization protocol over an in-host IPC transport (sockets/pipes/shared memory), distinct from a public network API. **Where:** Unix domain sockets, named pipes, gRPC over UDS, Node `cluster`/`child_process` IPC, sidecar↔app sockets, Electron `ipcMain`/`ipcRenderer`. **Breaks:** both ends must agree on framing + message shape but are often versioned independently (a sidecar updated separately) — change the schema/channel name/socket path on one side + messages are dropped/misparsed with no network error; Electron `ipcRenderer.invoke('channel')` silently no-ops if `ipcMain.handle('channel')` was renamed. **Detect:** `unix:`/`.sock`, `ipcMain`/`ipcRenderer`, `child.send`/`process.on('message'`, `createServer` on a socket path, gRPC over UDS. **Safe-change:** version the IPC envelope + validate on receipt; keep channel names/socket paths in a shared constant; coordinate sidecar/app upgrades; don't reuse a socket path across protocol versions. _(Own home — the in-host IPC framing/transport is its own source-of-truth; cross-ref `worker-thread-boundary` (the thread variant).)_
 #### `cron-timezone-contract` — MED · point
-The schedule expression + its assumed timezone at the infra/scheduler layer + the runtime TZ. **Where:** K8s `CronJob.spec.schedule`(+`timeZone`), Cloudflare Workers Cron Triggers (always UTC), EventBridge `ScheduleExpression`, system crontab, `TZ` env. **Breaks:** a cron expression has no meaning without a timezone, + the scheduler's TZ often differs from the developer's + the container's — `0 0 * * *` runs at UTC midnight not local, so DST shifts + date-boundary logic (daily rollups, billing cutoffs) run on the wrong day; Cloudflare cron is always UTC; unset container `TZ` defaults to UTC so date-based filenames drift. **Detect:** `schedule:`/`crons`/`ScheduleExpression`/cron expressions, `timeZone`, `TZ=`, `new Date()`/`toISOString` in scheduled jobs. **Safe-change:** pin an explicit `timeZone` on CronJobs; remember most cloud schedulers fire in UTC; set `TZ` explicitly if logic is local-time-sensitive (else standardize UTC end-to-end); re-check date-boundary jobs across DST. *(Folds into async `cron-schedule-contract` — same cron contract; this is its scheduler-TZ/infra facet.)*
+The schedule expression + its assumed timezone at the infra/scheduler layer + the runtime TZ. **Where:** K8s `CronJob.spec.schedule`(+`timeZone`), Cloudflare Workers Cron Triggers (always UTC), EventBridge `ScheduleExpression`, system crontab, `TZ` env. **Breaks:** a cron expression has no meaning without a timezone, + the scheduler's TZ often differs from the developer's + the container's — `0 0 * * *` runs at UTC midnight not local, so DST shifts + date-boundary logic (daily rollups, billing cutoffs) run on the wrong day; Cloudflare cron is always UTC; unset container `TZ` defaults to UTC so date-based filenames drift. **Detect:** `schedule:`/`crons`/`ScheduleExpression`/cron expressions, `timeZone`, `TZ=`, `new Date()`/`toISOString` in scheduled jobs. **Safe-change:** pin an explicit `timeZone` on CronJobs; remember most cloud schedulers fire in UTC; set `TZ` explicitly if logic is local-time-sensitive (else standardize UTC end-to-end); re-check date-boundary jobs across DST. _(Folds into async `cron-schedule-contract` — same cron contract; this is its scheduler-TZ/infra facet.)_
 #### `process-lifecycle-contract` — MED · point
-The init-system/supervisor contract around PID 1, zombie reaping, restart policy, exit-code semantics. **Where:** Docker PID 1 (`tini`/`dumb-init`), K8s `restartPolicy`+exit-code handling, systemd `Restart=`, supervisord, pm2. **Breaks:** PID 1 in a container has special signal semantics + must reap zombies — a Node/Python app as PID 1 without an init shim leaks zombies + mishandles signals; the orchestrator interprets exit codes (0=success, 137=SIGKILL/OOM, 143=SIGTERM) to decide restart, so exiting 0 on a fatal error makes K8s think the job succeeded; changing `restartPolicy` changes crash-recovery silently. **Detect:** `tini`/`dumb-init`/`ENTRYPOINT`, `restartPolicy`, `process.exit(`, systemd `Restart=`, `pm2`, apps spawning children as PID 1. **Safe-change:** use an init shim if the main process spawns children; exit non-zero on fatal errors; match `restartPolicy` to workload type (`Always` services, `OnFailure`/`Never` jobs); don't swallow SIGTERM/SIGCHLD as PID 1. *(Own home — the PID-1/reaping/restart-policy contract is its own source-of-truth; cross-ref `graceful-shutdown`, `container-image-contract`.)*
+The init-system/supervisor contract around PID 1, zombie reaping, restart policy, exit-code semantics. **Where:** Docker PID 1 (`tini`/`dumb-init`), K8s `restartPolicy`+exit-code handling, systemd `Restart=`, supervisord, pm2. **Breaks:** PID 1 in a container has special signal semantics + must reap zombies — a Node/Python app as PID 1 without an init shim leaks zombies + mishandles signals; the orchestrator interprets exit codes (0=success, 137=SIGKILL/OOM, 143=SIGTERM) to decide restart, so exiting 0 on a fatal error makes K8s think the job succeeded; changing `restartPolicy` changes crash-recovery silently. **Detect:** `tini`/`dumb-init`/`ENTRYPOINT`, `restartPolicy`, `process.exit(`, systemd `Restart=`, `pm2`, apps spawning children as PID 1. **Safe-change:** use an init shim if the main process spawns children; exit non-zero on fatal errors; match `restartPolicy` to workload type (`Always` services, `OnFailure`/`Never` jobs); don't swallow SIGTERM/SIGCHLD as PID 1. _(Own home — the PID-1/reaping/restart-policy contract is its own source-of-truth; cross-ref `graceful-shutdown`, `container-image-contract`.)_
 #### `proxy-header-forwarding-contract` — MED · point
-The forwarded/trust headers (`X-Forwarded-For`/`-Proto`/`-Host`, `Forwarded`, `X-Real-IP`) + the `trust proxy` setting binding a proxy to the app. **Where:** nginx/Envoy/ALB/Cloudflare adding `X-Forwarded-*`, Express `app.set('trust proxy', …)`, rate-limiters/auth keyed on client IP, HTTPS-redirect reading `X-Forwarded-Proto`. **Breaks:** the app trusts headers the proxy sets — misconfigured `trust proxy` makes the app see the proxy's IP for everyone (rate-limit-by-IP becomes global; audit logs wrong); trusting `X-Forwarded-For` without a trusted proxy lets clients spoof their IP; adding/removing a proxy hop shifts which XFF entry is the real client. **Detect:** `X-Forwarded-`, `trust proxy`, `req.ip`/`req.ips`, `X-Real-IP`, `proxy_set_header`, proxy-hop count. **Safe-change:** set `trust proxy` to the exact hop count/CIDR (never blanket-trust); re-verify client-IP extraction when adding/removing a proxy/CDN; ensure the edge strips client-supplied `X-Forwarded-*`; keep HTTPS-redirect reading the proxy-set `X-Forwarded-Proto`. *(Own home — the forwarded/trust-header + `trust proxy` contract is its own source-of-truth.)* *(HIGH if it enables spoofing of security controls.)*
+The forwarded/trust headers (`X-Forwarded-For`/`-Proto`/`-Host`, `Forwarded`, `X-Real-IP`) + the `trust proxy` setting binding a proxy to the app. **Where:** nginx/Envoy/ALB/Cloudflare adding `X-Forwarded-*`, Express `app.set('trust proxy', …)`, rate-limiters/auth keyed on client IP, HTTPS-redirect reading `X-Forwarded-Proto`. **Breaks:** the app trusts headers the proxy sets — misconfigured `trust proxy` makes the app see the proxy's IP for everyone (rate-limit-by-IP becomes global; audit logs wrong); trusting `X-Forwarded-For` without a trusted proxy lets clients spoof their IP; adding/removing a proxy hop shifts which XFF entry is the real client. **Detect:** `X-Forwarded-`, `trust proxy`, `req.ip`/`req.ips`, `X-Real-IP`, `proxy_set_header`, proxy-hop count. **Safe-change:** set `trust proxy` to the exact hop count/CIDR (never blanket-trust); re-verify client-IP extraction when adding/removing a proxy/CDN; ensure the edge strips client-supplied `X-Forwarded-*`; keep HTTPS-redirect reading the proxy-set `X-Forwarded-Proto`. _(Own home — the forwarded/trust-header + `trust proxy` contract is its own source-of-truth.)_ _(HIGH if it enables spoofing of security controls.)_
 #### `service-discovery-contract` — HIGH · point
-The name/address resolution by which a client locates a service instance (DNS name, env-injected URL, registry entry). **Where:** K8s Service DNS (`svc.namespace.svc.cluster.local`), Consul/Eureka, Docker Compose service names, env-injected `*_SERVICE_HOST`/`_PORT`, connection strings. **Breaks:** clients hardcode/env-reference a service name — rename the K8s Service or compose service and consumers get DNS resolution failures; moving to a new namespace changes the FQDN; changing a connection-string env-var name breaks every consumer reading the old name. **Detect:** service hostnames, `*.svc.cluster.local`, `_SERVICE_HOST`, compose `depends_on`/service names, connection-string env vars. **Safe-change:** treat Service names + FQDNs as a stable contract; coordinate namespace moves with all consumers; keep connection-string env-var names stable (deprecate before rename); verify `depends_on`/startup-order assumptions. *(Own home — the service name/address resolution contract is its own source-of-truth; cross-ref `dns-tls-san`, `ingress-routing-rule`, `env-var-contract`.)*
+The name/address resolution by which a client locates a service instance (DNS name, env-injected URL, registry entry). **Where:** K8s Service DNS (`svc.namespace.svc.cluster.local`), Consul/Eureka, Docker Compose service names, env-injected `*_SERVICE_HOST`/`_PORT`, connection strings. **Breaks:** clients hardcode/env-reference a service name — rename the K8s Service or compose service and consumers get DNS resolution failures; moving to a new namespace changes the FQDN; changing a connection-string env-var name breaks every consumer reading the old name. **Detect:** service hostnames, `*.svc.cluster.local`, `_SERVICE_HOST`, compose `depends_on`/service names, connection-string env vars. **Safe-change:** treat Service names + FQDNs as a stable contract; coordinate namespace moves with all consumers; keep connection-string env-var names stable (deprecate before rename); verify `depends_on`/startup-order assumptions. _(Own home — the service name/address resolution contract is its own source-of-truth; cross-ref `dns-tls-san`, `ingress-routing-rule`, `env-var-contract`.)_
 ---
 ## Default severity, at a glance
 | Tier | Boundary types (defaults — adjust per repo) |
-|---|---|
-| **CRITICAL** | information-architecture, tenancy, db-schema, db-migration, row-level-* / RLS, vector-search-index*, encryption-at-rest-key-boundary, wire-response-envelope, graphql-schema / federation, grpc-protobuf-wire, auth-token-wire / auth-contract / jwt-claims / signing-key-rotation, redirect-uri-allowlist, object-level-authorization, event-schema, cdc-stream, workflow-determinism, schema-registry, client-exposed-env, secrets-management, package-public-api, module-federation-remotes, edge-binding, do-class-contract |
+| --- | --- |
+| **CRITICAL** | information-architecture, tenancy, db-schema, db-migration, row-level-_ / RLS, vector-search-index_, encryption-at-rest-key-boundary, wire-response-envelope, graphql-schema / federation, grpc-protobuf-wire, auth-token-wire / auth-contract / jwt-claims / signing-key-rotation, redirect-uri-allowlist, object-level-authorization, event-schema, cdc-stream, workflow-determinism, schema-registry, client-exposed-env, secrets-management, package-public-api, module-federation-remotes, edge-binding, do-class-contract |
 | **HIGH** | orm-mapping, foreign-keys, index-and-constraint, jsonb-shape, soft-delete, audit/event-sourcing tables, db-view/proc, connection-pool, db-extension/collation, auth-managed-tables, rest-endpoint, error-envelope, http-status, openapi, request-validation, response-dto, persisted-query, grpc-method, trpc-router, api-versioning, cors, inbound/outbound-webhook, store-shape, rtk-query-tags, route-table, url-param, component-props, form-schema, client-storage, ssr-hydration, state-serialization, deep-link, query-cache-key, rbac, abac, oauth-oidc, api-key, sso-saml, impersonation, consent-scope, pii-classification, account-linking, mfa-step-up, workload-identity, password-policy, message-queue-payload, topic-naming, command-event, workflow-signal/activity, delivery-semantics, ordering-key, outbox, saga-step, stream-offset, realtime-channel, websocket-envelope, env-var, env-parity, build-vs-runtime, feature-flag, workspace-graph, peer-dependency, di-container, code-generation, lockfile, monorepo-pipeline, container-image, exposed-port, ingress, cache-header, vary, dns-tls-san, iac-output, inter-service-resilience, health-check, graceful-shutdown, resource-limit, service-discovery, lambda-handler, cold-start |
 | **MED** | db-enum, fulltext-index, cache-key/ttl, read-model/matview, blob-key, selector, react-context, design-token, i18n-keys, feature-flag-gating, asset-path, custom-element, analytics-event, per-identity-rate-limit, content-negotiation, file-upload, conditional-request-caching, idempotency-key, pagination, job-name, cron-schedule, dead-letter, retry-backoff, presence-state, pubsub-channel, batch-window, import-layering, tsconfig-paths/refs, bundler-externals, config-defaults, ci-pipeline, node-engines, css-design-token, worker-thread, trace-context, log-schema, metric-name, ipc-protocol, cron-timezone, process-lifecycle, proxy-header |
 | **LOW** | hateoas-links, dom-event, theme-mode (folded into design-token), shadcn/ui generated primitives |
@@ -723,12 +793,4 @@ The name/address resolution by which a client locates a service instance (DNS na
 ## Extending the taxonomy
-Add a row here — and all four modes inherit it. For a **new technology**, add a
-short pack: where its boundaries live + the safe-change checklist. Keep
-instructions **technology-specific, never vague** — "middleware order is
-parsers→custom→routes→error-handler-last" beats "be careful with middleware."
-Only instantiate the types the detected stack/IA actually exhibits; `log()` what
-you skip and why. When a type genuinely spans two categories, give it one
-**canonical home** and a one-line cross-reference in the other (as done above for
-`cors`, `idempotency-key`, `websocket-envelope`, `design-token`,
-`package-public-api`, `row-level-security`).
+Add a row here — and all four modes inherit it. For a **new technology**, add a short pack: where its boundaries live + the safe-change checklist. Keep instructions **technology-specific, never vague** — "middleware order is parsers→custom→routes→error-handler-last" beats "be careful with middleware." Only instantiate the types the detected stack/IA actually exhibits; `log()` what you skip and why. When a type genuinely spans two categories, give it one **canonical home** and a one-line cross-reference in the other (as done above for `cors`, `idempotency-key`, `websocket-envelope`, `design-token`, `package-public-api`, `row-level-security`).