@terpjs/spec 0.14.0 → 0.16.0

package/catalog/backend/escape_hatch_budget.json

@@ -1,21 +1,21 @@
-{
-  "id": "backend/escape_hatch_budget",
-  "surface": "backend",
-  "title": "Opt-out marker counts must exactly match the checked-in budget (a ratchet)",
-  "intent": "The budget is a checked-in per-app object mapping each opt-out marker to its count. Actual usage must equal it exactly: a marker that rose needs a justified budget bump in the same change; one that dropped must be lowered to lock in the win; an unbudgeted marker must be added with a justified count. This keeps every secure-by-default opt-out visible, greppable, and governed.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_escape_hatch_budget"
-    }
-  ],
-  "reference": "# arch-allow-<rule>: <reason> markers reconciled against the app's checked-in escape-hatch budget JSON (design §8). The rule carries no opt_out: governance cannot be waived by the mechanism it governs.",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "The budget ratchet reconciles a checked-in governance file against source markers -- both sides are repository artifacts with no runtime counterpart. The controls the markers opt out of keep their own runtime halves regardless."
-  },
-  "guide_topic": "rules",
-  "corpus": true
-}
+{
+  "id": "backend/escape_hatch_budget",
+  "surface": "backend",
+  "title": "Opt-out marker counts must exactly match the checked-in budget (a ratchet)",
+  "intent": "The budget is a checked-in per-app object mapping each opt-out marker to its count. Actual usage must equal it exactly: a marker that rose needs a justified budget bump in the same change; one that dropped must be lowered to lock in the win; an unbudgeted marker must be added with a justified count. This keeps every secure-by-default opt-out visible, greppable, and governed.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_escape_hatch_budget"
+    }
+  ],
+  "reference": "# arch-allow-<rule>: <reason> markers reconciled against the app's checked-in escape-hatch budget JSON (design §8). The rule carries no opt_out: governance cannot be waived by the mechanism it governs.",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The budget ratchet reconciles a checked-in governance file against source markers -- both sides are repository artifacts with no runtime counterpart. The controls the markers opt out of keep their own runtime halves regardless."
+  },
+  "guide_topic": "rules",
+  "corpus": true
+}

package/catalog/backend/events_reference_catalog.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/events_reference_catalog",
-  "surface": "backend",
-  "title": "Emitted / subscribed events are typed catalog constants, never bare strings",
-  "intent": "The event bus carries the same no-drift guarantee as the permission model: every event a module emits or subscribes to is a typed definition from the control-plane catalog. The rule forbids a bare string (or an inline, ad hoc definition) wherever an event is named — the event argument of an emit call, the argument of a subscribe decorator, the emits / subscribes lists of the module manifest, and the lifecycle event map — so an event name can never drift in outside the catalog.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_events_reference_catalog"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "emit"
-    }
-  ],
-  "reference": "EventDefinition constants from the control-plane catalog, cited in emit(...) / subscribe(...) / ModuleSpec(emits=..., subscribes=...) / LifecycleEventMap(...); the runtime half is terp.core.emit.",
-  "opt_out": "# arch-allow-events-reference-catalog: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "emit() is the single producer chokepoint and fails closed on an event that is unknown to -- or shadows -- the registered EventCatalog entry; boot additionally refuses a ModuleSpec whose declared emits/subscribes miss the catalog (ControlPlane.validation_errors)."
-  },
-  "guide_topic": "events",
-  "corpus": true
-}
+{
+  "id": "backend/events_reference_catalog",
+  "surface": "backend",
+  "title": "Emitted / subscribed events are typed catalog constants, never bare strings",
+  "intent": "The event bus carries the same no-drift guarantee as the permission model: every event a module emits or subscribes to is a typed definition from the control-plane catalog. The rule forbids a bare string (or an inline, ad hoc definition) wherever an event is named — the event argument of an emit call, the argument of a subscribe decorator, the emits / subscribes lists of the module manifest, and the lifecycle event map — so an event name can never drift in outside the catalog.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_events_reference_catalog"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "emit"
+    }
+  ],
+  "reference": "EventDefinition constants from the control-plane catalog, cited in emit(...) / subscribe(...) / ModuleSpec(emits=..., subscribes=...) / LifecycleEventMap(...); the runtime half is terp.core.emit.",
+  "opt_out": "# arch-allow-events-reference-catalog: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "emit() is the single producer chokepoint and fails closed on an event that is unknown to -- or shadows -- the registered EventCatalog entry; boot additionally refuses a ModuleSpec whose declared emits/subscribes miss the catalog (ControlPlane.validation_errors)."
+  },
+  "guide_topic": "events",
+  "corpus": true
+}

package/catalog/backend/input_schemas_exclude_managed_columns.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/input_schemas_exclude_managed_columns",
-  "surface": "backend",
-  "title": "No input schema declares a framework-managed column",
-  "intent": "An input schema is a *Create / *Update or any class used as a request body (a route handler's body parameter, or a generated CRUD router's create/update schema) — the same role-based definition the input-cap rule uses, so an off-convention DTO (UserProvision, LoginRequest) is covered too. The write chokepoint copies a schema's fields onto the model, so a client-settable id / version / tenant_id / created_by_id is an over-posting (mass-assignment) hole — a client could forge the primary key, defeat optimistic concurrency, or cross a tenant boundary. The framework assigns every managed column centrally; an input schema must never expose one. (The write chokepoint also strips the same set at runtime — this rule is the build-time half of that two-layer control.)",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_input_schemas_exclude_managed_columns"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "_without_managed_columns"
-    }
-  ],
-  "reference": "BaseService.create/update strip the managed set via _without_managed_columns; build_crud_router create/update schemas are scanned too.",
-  "opt_out": "# arch-allow-input-schemas-exclude-managed-columns: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "BaseService.create/update strip every framework-managed column from the inbound payload at the write chokepoint (_without_managed_columns), so even an over-wide schema that ships cannot mass-assign id / version / scope / actor columns."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/input_schemas_exclude_managed_columns",
+  "surface": "backend",
+  "title": "No input schema declares a framework-managed column",
+  "intent": "An input schema is a *Create / *Update or any class used as a request body (a route handler's body parameter, or a generated CRUD router's create/update schema) — the same role-based definition the input-cap rule uses, so an off-convention DTO (UserProvision, LoginRequest) is covered too. The write chokepoint copies a schema's fields onto the model, so a client-settable id / version / tenant_id / created_by_id is an over-posting (mass-assignment) hole — a client could forge the primary key, defeat optimistic concurrency, or cross a tenant boundary. The framework assigns every managed column centrally; an input schema must never expose one. (The write chokepoint also strips the same set at runtime — this rule is the build-time half of that two-layer control.)",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_input_schemas_exclude_managed_columns"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_without_managed_columns"
+    }
+  ],
+  "reference": "BaseService.create/update strip the managed set via _without_managed_columns; build_crud_router create/update schemas are scanned too.",
+  "opt_out": "# arch-allow-input-schemas-exclude-managed-columns: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "BaseService.create/update strip every framework-managed column from the inbound payload at the write chokepoint (_without_managed_columns), so even an over-wide schema that ships cannot mass-assign id / version / scope / actor columns."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/input_str_fields_have_max_length.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/input_str_fields_have_max_length",
-  "surface": "backend",
-  "title": "Every string a client can supply caps its length",
-  "intent": "A field is client-supplied when it lives on a table model, on a *Create / *Update schema, or on any class used as a request body (a route handler's body parameter, or a generated CRUD router's create/update schema) — so an input DTO named off-convention (LoginRequest, UserProvision) is capped too, not only the *Create / *Update ones. Plain strings, optional strings, and sequence containers of strings all count; an uncapped one is an unbounded-input (DoS / abuse) hole.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_input_str_fields_have_max_length"
-    }
-  ],
-  "reference": "str / str | None / list[str] fields declare max_length; build_crud_router create/update schemas are scanned too.",
-  "opt_out": "# arch-allow-input-str-fields-have-max-length: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "The rule's job is to force the cap into the authored schema -- and a declared cap is then enforced at request time by validation itself, so compliance creates its own runtime control. No shipped seam can supply a missing per-field cap; the per-module request-size middleware bounds the payload wholesale as a distinct Tier-A control."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/input_str_fields_have_max_length",
+  "surface": "backend",
+  "title": "Every string a client can supply caps its length",
+  "intent": "A field is client-supplied when it lives on a table model, on a *Create / *Update schema, or on any class used as a request body (a route handler's body parameter, or a generated CRUD router's create/update schema) — so an input DTO named off-convention (LoginRequest, UserProvision) is capped too, not only the *Create / *Update ones. Plain strings, optional strings, and sequence containers of strings all count; an uncapped one is an unbounded-input (DoS / abuse) hole.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_input_str_fields_have_max_length"
+    }
+  ],
+  "reference": "str / str | None / list[str] fields declare max_length; build_crud_router create/update schemas are scanned too.",
+  "opt_out": "# arch-allow-input-str-fields-have-max-length: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The rule's job is to force the cap into the authored schema -- and a declared cap is then enforced at request time by validation itself, so compliance creates its own runtime control. No shipped seam can supply a missing per-field cap; the per-module request-size middleware bounds the payload wholesale as a distinct Tier-A control."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/jobs_reference_catalog.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/jobs_reference_catalog",
-  "surface": "backend",
-  "title": "Enqueued / declared jobs are typed catalog constants, never bare strings",
-  "intent": "Background work carries the same no-drift guarantee as the event bus: every job a module enqueues or declares is a typed definition from the control-plane catalog. The rule forbids a bare string (or an inline, ad hoc definition) wherever a job is named — the job argument of an enqueue call and the jobs list of the module manifest — so a job name can never drift in outside the catalog. The runtime half is the enqueue chokepoint, which rejects a job not registered in the active catalog.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_jobs_reference_catalog"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "enqueue"
-    }
-  ],
-  "reference": "JobDefinition constants from the control-plane catalog, cited in enqueue(job=...) / ModuleSpec(jobs=[...]); the runtime half is terp.core.enqueue.",
-  "opt_out": "# arch-allow-jobs-reference-catalog: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "enqueue is the single producer chokepoint and fails closed on a job the active JobCatalog does not register (the job analogue of emit); execution re-checks (run_job raises JobError on a stale envelope), and boot refuses a ModuleSpec whose declared jobs miss the catalog (ControlPlane.validation_errors)."
-  },
-  "guide_topic": "jobs",
-  "corpus": true
-}
+{
+  "id": "backend/jobs_reference_catalog",
+  "surface": "backend",
+  "title": "Enqueued / declared jobs are typed catalog constants, never bare strings",
+  "intent": "Background work carries the same no-drift guarantee as the event bus: every job a module enqueues or declares is a typed definition from the control-plane catalog. The rule forbids a bare string (or an inline, ad hoc definition) wherever a job is named — the job argument of an enqueue call and the jobs list of the module manifest — so a job name can never drift in outside the catalog. The runtime half is the enqueue chokepoint, which rejects a job not registered in the active catalog.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_jobs_reference_catalog"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "enqueue"
+    }
+  ],
+  "reference": "JobDefinition constants from the control-plane catalog, cited in enqueue(job=...) / ModuleSpec(jobs=[...]); the runtime half is terp.core.enqueue.",
+  "opt_out": "# arch-allow-jobs-reference-catalog: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "enqueue is the single producer chokepoint and fails closed on a job the active JobCatalog does not register (the job analogue of emit); execution re-checks (run_job raises JobError on a stale envelope), and boot refuses a ModuleSpec whose declared jobs miss the catalog (ControlPlane.validation_errors)."
+  },
+  "guide_topic": "jobs",
+  "corpus": true
+}

package/catalog/backend/list_routes_paginate.json

@@ -1,32 +1,32 @@
-{
-  "id": "backend/list_routes_paginate",
-  "surface": "backend",
-  "title": "A list route returns a capped page envelope, never a bare unbounded collection",
-  "intent": "Pagination is a mandatory cross-cutting control: a route whose declared response type is a bare collection serializes an unbounded result — a resource-exhaustion and over-exposure footgun on a large table, and a page-envelope guarantee that was previously only a convention. Wrap the read DTO in the framework's capped page envelope so every list is bounded and uniformly shaped. A single-object response is unaffected; both decorator routes and imperative route registration are checked.",
-  "layer": "black-box",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_list_routes_paginate"
-    },
-    {
-      "kind": "black-box",
-      "tool": "@terp/conformance",
-      "ref": "standard: list routes return a capped Page envelope"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "_validate_list_routes_paginate"
-    }
-  ],
-  "reference": "response_model=Page[ReadDTO] returned via Page.of(...) with PaginationDep (ADR 0006, Tier A); bare list[...] / Sequence[...] response models are refused.",
-  "opt_out": "# arch-allow-list-routes-paginate: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "At boot, the route scan on the composition seam (the same seam as _validate_router_response_models) walks every composed route \u2014 decorator, imperative add_api_route, and nested included routers alike \u2014 and raises a BootError naming this rule and the route when a route declares a bare list[...] / Sequence[...] response_model instead of Page[T]. PaginationDep's fail-closed skip/limit caps and the @terp/conformance Page-envelope probe remain in place on top of this in-app refusal."
-  },
-  "guide_topic": "service",
-  "corpus": true
-}
+{
+  "id": "backend/list_routes_paginate",
+  "surface": "backend",
+  "title": "A list route returns a capped page envelope, never a bare unbounded collection",
+  "intent": "Pagination is a mandatory cross-cutting control: a route whose declared response type is a bare collection serializes an unbounded result — a resource-exhaustion and over-exposure footgun on a large table, and a page-envelope guarantee that was previously only a convention. Wrap the read DTO in the framework's capped page envelope so every list is bounded and uniformly shaped. A single-object response is unaffected; both decorator routes and imperative route registration are checked.",
+  "layer": "black-box",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_list_routes_paginate"
+    },
+    {
+      "kind": "black-box",
+      "tool": "@terpjs/conformance",
+      "ref": "standard: list routes return a capped Page envelope"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_validate_list_routes_paginate"
+    }
+  ],
+  "reference": "response_model=Page[ReadDTO] returned via Page.of(...) with PaginationDep (ADR 0006, Tier A); bare list[...] / Sequence[...] response models are refused.",
+  "opt_out": "# arch-allow-list-routes-paginate: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "At boot, the route scan on the composition seam (the same seam as _validate_router_response_models) walks every composed route \u2014 decorator, imperative add_api_route, and nested included routers alike \u2014 and raises a BootError naming this rule and the route when a route declares a bare list[...] / Sequence[...] response_model instead of Page[T]. PaginationDep's fail-closed skip/limit caps and the @terpjs/conformance Page-envelope probe remain in place on top of this in-app refusal."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/modules_declare_policy.json

@@ -1,26 +1,26 @@
-{
-  "id": "backend/modules_declare_policy",
-  "surface": "backend",
-  "title": "Every module manifest declares an access policy",
-  "intent": "The deny-by-default posture hangs on the declaration: composition mounts a module's routes behind the guard its declared policy configures, so a module without one has no stated authority model at all — there is nothing to authorize against, and the framework refuses to guess. Requiring the declaration in the manifest keeps every module's access decision explicit, reviewable, and in one predictable place.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_modules_declare_policy"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "build_guard"
-    }
-  ],
-  "runtime": {
-    "applicability": "required"
-  },
-  "reference": "modules/<name>/module.py declares ModuleSpec(policy=Policy(...)); create_app mounts the router behind the guard built from it (build_guard).",
-  "opt_out": "# arch-allow-modules-declare-policy: <reason>",
-  "guide_topic": "policy",
-  "corpus": true
-}
+{
+  "id": "backend/modules_declare_policy",
+  "surface": "backend",
+  "title": "Every module manifest declares an access policy",
+  "intent": "The deny-by-default posture hangs on the declaration: composition mounts a module's routes behind the guard its declared policy configures, so a module without one has no stated authority model at all — there is nothing to authorize against, and the framework refuses to guess. Requiring the declaration in the manifest keeps every module's access decision explicit, reviewable, and in one predictable place.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_modules_declare_policy"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "build_guard"
+    }
+  ],
+  "runtime": {
+    "applicability": "required"
+  },
+  "reference": "modules/<name>/module.py declares ModuleSpec(policy=Policy(...)); create_app mounts the router behind the guard built from it (build_guard).",
+  "opt_out": "# arch-allow-modules-declare-policy: <reason>",
+  "guide_topic": "policy",
+  "corpus": true
+}

package/catalog/backend/mutations_emit_audit.json

@@ -1,26 +1,26 @@
-{
-  "id": "backend/mutations_emit_audit",
-  "surface": "backend",
-  "title": "Modules never write to the session directly; mutations go through the audited chokepoint",
-  "intent": "Audit is auto-emitted from the single audited write chokepoint of the model's service, inside the write's transaction. A module that calls the session's persistence methods itself — or smuggles a write through a session-executed data-modification statement — bypasses that chokepoint and would persist a mutation with no audit trail. The receiver is recognised by the conventional session names and by any parameter annotated with the session type (so renaming the variable does not evade the rule). Routing every write through the service keeps the trail structural — a method call on the model's service is fine; a raw session write is not.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_mutations_emit_audit"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "WriteGuardedSession"
-    }
-  ],
-  "reference": "BaseService.create/update/delete (_save/_remove) is the audited chokepoint; session.add/delete/merge/commit/flush, bulk_* helpers, and DML via session.execute/exec are refused, on conventional names and Session/SessionDep-annotated parameters alike.",
-  "opt_out": "# arch-allow-mutations-emit-audit: <reason>",
-  "runtime": {
-    "applicability": "required"
-  },
-  "guide_topic": "service",
-  "corpus": true
-}
+{
+  "id": "backend/mutations_emit_audit",
+  "surface": "backend",
+  "title": "Modules never write to the session directly; mutations go through the audited chokepoint",
+  "intent": "Audit is auto-emitted from the single audited write chokepoint of the model's service, inside the write's transaction. A module that calls the session's persistence methods itself — or smuggles a write through a session-executed data-modification statement — bypasses that chokepoint and would persist a mutation with no audit trail. The receiver is recognised by the conventional session names and by any parameter annotated with the session type (so renaming the variable does not evade the rule). Routing every write through the service keeps the trail structural — a method call on the model's service is fine; a raw session write is not.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_mutations_emit_audit"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "WriteGuardedSession"
+    }
+  ],
+  "reference": "BaseService.create/update/delete (_save/_remove) is the audited chokepoint; session.add/delete/merge/commit/flush, bulk_* helpers, and DML via session.execute/exec are refused, on conventional names and Session/SessionDep-annotated parameters alike.",
+  "opt_out": "# arch-allow-mutations-emit-audit: <reason>",
+  "runtime": {
+    "applicability": "required"
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/mutations_require_write_role.json

@@ -1,32 +1,32 @@
-{
-  "id": "backend/mutations_require_write_role",
-  "surface": "backend",
-  "title": "A module with a mutating route must not gate writes below its read tier",
-  "intent": "A module that exposes a mutating route is a write surface, so its declared policy must gate writes at or above the read tier — otherwise anyone who can read can also mutate (privilege inversion). Two shapes are caught statically: the write tier set to the read floor, and a default-ladder inversion where the write rank is below the read rank (including a raised read tier whose write tier is left at the lower default). The framework's default policy is the safe shape. A custom role ladder's ranks are not knowable from a source scan, so those are enforced by the boot-time check — this rule is the early-warning build-time half. A public module is governed by public_modules_are_read_only instead. The check is tied to the policy bound in the module's manifest.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_mutations_require_write_role"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "build_guard"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "_validate_policy_write_tiers"
-    }
-  ],
-  "runtime": {
-    "applicability": "required",
-    "rationale": "Two runtime halves: the request guard authorizes every mutating method at the policy's write tier (build_guard), and boot refuses a Policy whose write rank sits below its read rank for any role ladder, including custom ranks a source scan cannot know (_validate_policy_write_tiers)."
-  },
-  "opt_out": "# arch-allow-mutations-require-write-role: <reason>",
-  "reference": "Policy(write=Roles.VIEWER), Policy.tiers(write=...) at the read floor, and default-ladder inversions like Policy(read=Roles.ADMIN, write=Roles.EDITOR) are refused; Policy.default() is the safe shape, and create_app -> _validate_policy_write_tiers covers custom ladders at boot.",
-  "guide_topic": "policy",
-  "corpus": true
-}
+{
+  "id": "backend/mutations_require_write_role",
+  "surface": "backend",
+  "title": "A module with a mutating route must not gate writes below its read tier",
+  "intent": "A module that exposes a mutating route is a write surface, so its declared policy must gate writes at or above the read tier — otherwise anyone who can read can also mutate (privilege inversion). Two shapes are caught statically: the write tier set to the read floor, and a default-ladder inversion where the write rank is below the read rank (including a raised read tier whose write tier is left at the lower default). The framework's default policy is the safe shape. A custom role ladder's ranks are not knowable from a source scan, so those are enforced by the boot-time check — this rule is the early-warning build-time half. A public module is governed by public_modules_are_read_only instead. The check is tied to the policy bound in the module's manifest.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_mutations_require_write_role"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "build_guard"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_validate_policy_write_tiers"
+    }
+  ],
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Two runtime halves: the request guard authorizes every mutating method at the policy's write tier (build_guard), and boot refuses a Policy whose write rank sits below its read rank for any role ladder, including custom ranks a source scan cannot know (_validate_policy_write_tiers)."
+  },
+  "opt_out": "# arch-allow-mutations-require-write-role: <reason>",
+  "reference": "Policy(write=Roles.VIEWER), Policy.tiers(write=...) at the read floor, and default-ladder inversions like Policy(read=Roles.ADMIN, write=Roles.EDITOR) are refused; Policy.default() is the safe shape, and create_app -> _validate_policy_write_tiers covers custom ladders at boot.",
+  "guide_topic": "policy",
+  "corpus": true
+}

package/catalog/backend/no_adhoc_background_runtime.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/no_adhoc_background_runtime",
-  "surface": "backend",
-  "title": "App modules don't import a background engine / runtime directly \u2014 only adapter caps do",
-  "intent": "Background work (a scheduled sync, an export, a webhook) goes through the typed enqueue chokepoint and the context-binding kernel runner, so the engine that actually runs it stays a composition-root choice wired into an opt-in adapter capability, never an import baked into domain code. The rule forbids importing broker / scheduler engines (and a raw thread- or process-execution construct, or a bare import that can reach one) anywhere in an app module; an explicit synchronization primitive is a correctness tool, not background execution, and stays allowed. The constructive counterpart is the jobs seam itself: every job runs through the enqueue chokepoint and the active queue, so an adapter swap never touches a call site. An adapter capability legitimately imports its engine under a budgeted opt-out marker.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_adhoc_background_runtime"
-    }
-  ],
-  "reference": "terp.core.enqueue + the active JobQueue are the sanctioned seam; Celery / Azure Service Bus / Redis / APScheduler imports and threading/multiprocessing execution constructs (Thread, Process, pools) are refused, while primitives like RLock stay allowed.",
-  "opt_out": "# arch-allow-no-adhoc-background-runtime: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "Import-form rule: which package imported an engine is a source fact, and at runtime the sanctioned adapter capability legitimately holds the same engine in the same process, so engine presence cannot be attributed to an app module. The constructive counterpart is the jobs seam itself (enqueue + the active JobQueue) -- it makes ad hoc runtimes unnecessary, but nothing can refuse a hand-spawned thread fail-closed."
-  },
-  "guide_topic": "jobs",
-  "corpus": true
-}
+{
+  "id": "backend/no_adhoc_background_runtime",
+  "surface": "backend",
+  "title": "App modules don't import a background engine / runtime directly \u2014 only adapter caps do",
+  "intent": "Background work (a scheduled sync, an export, a webhook) goes through the typed enqueue chokepoint and the context-binding kernel runner, so the engine that actually runs it stays a composition-root choice wired into an opt-in adapter capability, never an import baked into domain code. The rule forbids importing broker / scheduler engines (and a raw thread- or process-execution construct, or a bare import that can reach one) anywhere in an app module; an explicit synchronization primitive is a correctness tool, not background execution, and stays allowed. The constructive counterpart is the jobs seam itself: every job runs through the enqueue chokepoint and the active queue, so an adapter swap never touches a call site. An adapter capability legitimately imports its engine under a budgeted opt-out marker.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_adhoc_background_runtime"
+    }
+  ],
+  "reference": "terp.core.enqueue + the active JobQueue are the sanctioned seam; Celery / Azure Service Bus / Redis / APScheduler imports and threading/multiprocessing execution constructs (Thread, Process, pools) are refused, while primitives like RLock stay allowed.",
+  "opt_out": "# arch-allow-no-adhoc-background-runtime: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Import-form rule: which package imported an engine is a source fact, and at runtime the sanctioned adapter capability legitimately holds the same engine in the same process, so engine presence cannot be attributed to an app module. The constructive counterpart is the jobs seam itself (enqueue + the active JobQueue) -- it makes ad hoc runtimes unnecessary, but nothing can refuse a hand-spawned thread fail-closed."
+  },
+  "guide_topic": "jobs",
+  "corpus": true
+}

package/catalog/backend/no_adhoc_config_decrypt.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/no_adhoc_config_decrypt",
-  "surface": "backend",
-  "title": "Sealed config is never decrypted ad hoc; one budgeted call site only",
-  "intent": "A sealed configuration value stays opaque in app code: a module renders the masked form and never unseals a value itself. The single sanctioned decrypt site carries a justified opt-out marker counted against the app's escape-hatch budget. The runtime half is the decrypt chokepoint itself, which fails closed unless called from the one registered call site.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_adhoc_config_decrypt"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "decrypt_config"
-    }
-  ],
-  "reference": "mask_config renders sealed values (enc:v1:...); terp.core.secrets.decrypt_config fails closed unless called from the site registered via register_decrypt_call_site (design §5.4).",
-  "opt_out": "# arch-allow-no-adhoc-config-decrypt: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "decrypt_config itself fails closed on every path unless invoked from the single call site registered via register_decrypt_call_site -- an ad hoc decrypt raises SecretsError at runtime; the budgeted marker governs which site that is."
-  },
-  "guide_topic": "capability",
-  "corpus": true
-}
+{
+  "id": "backend/no_adhoc_config_decrypt",
+  "surface": "backend",
+  "title": "Sealed config is never decrypted ad hoc; one budgeted call site only",
+  "intent": "A sealed configuration value stays opaque in app code: a module renders the masked form and never unseals a value itself. The single sanctioned decrypt site carries a justified opt-out marker counted against the app's escape-hatch budget. The runtime half is the decrypt chokepoint itself, which fails closed unless called from the one registered call site.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_adhoc_config_decrypt"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "decrypt_config"
+    }
+  ],
+  "reference": "mask_config renders sealed values (enc:v1:...); terp.core.secrets.decrypt_config fails closed unless called from the site registered via register_decrypt_call_site (design §5.4).",
+  "opt_out": "# arch-allow-no-adhoc-config-decrypt: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "decrypt_config itself fails closed on every path unless invoked from the single call site registered via register_decrypt_call_site -- an ad hoc decrypt raises SecretsError at runtime; the budgeted marker governs which site that is."
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}