@terpjs/spec 0.14.0

package/app-check-report.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terp.dev/spec/app-check-report.schema.json",
+  "title": "Terp Standard application check report",
+  "description": "The complete, self-describing result of ONE checker invocation over ONE application tree. Findings alone cannot support per-rule verdicts: a rule with zero findings is only passing if the run actually evaluated it, and a consumer must never supply that knowledge itself — its own catalog copy can be newer or older than the checked app's pinned toolchain. So the report carries its own evaluated-rule inventory, the spec version its rule ids resolve against, and the checker's identity: everything a driving tool needs to join verdicts to the catalog fail-closed. A rule absent from `rules` and `not_applicable` was not evaluated and can never render as passing. A multi-surface toolchain emits one report per checker run; a consumer merges reports through their inventories.",
+  "type": "object",
+  "required": ["terp_check_report", "spec_version", "checker", "ok", "rules", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "terp_check_report": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Format marker and major version of this envelope. A consumer refuses an unknown marker value rather than guessing the shape."
+    },
+    "spec_version": {
+      "type": "string",
+      "description": "The spec semver (VERSION) whose catalog the rule ids in this report resolve against — the checked app's own pinned standard, which may differ from any consumer-side catalog copy.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "checker": {
+      "type": "object",
+      "description": "The checker's identity: tool name and its own version — the same identity the checker's certification scorecard (scorecard.schema.json) carries, so a consumer can tie a report to a verifiable certification claim.",
+      "required": ["tool", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "tool": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "ok": {
+      "type": "boolean",
+      "description": "The run's overall verdict: true only when the checker completed and attributed no findings. Overall only — per-rule verdicts are always derived from `rules` + `findings`, never from this flag."
+    },
+    "error": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Present when the run failed to complete (a crash, a timeout, an unreadable tree): what went wrong, for humans. An erroring report is never ok, and it must not claim rules it did not fully evaluate — fail visible, never a silent pass."
+    },
+    "rules": {
+      "type": "array",
+      "description": "The evaluated-rule inventory: every catalog rule id this run actually held the tree to. Zero findings for a listed rule means pass; an unlisted rule has NO verdict from this run (a consumer renders it unknown, never green). A finding's rule is normally listed here; a consumer treats an attributed finding as a failure regardless.",
+      "items": {
+        "type": "string",
+        "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
+      }
+    },
+    "not_applicable": {
+      "type": "array",
+      "description": "Opt-in rules the checked tree has not enabled (for example a slot-typed layout contract without its checked-in configuration): published as their own state so a consumer renders them as not applicable — never as passing, never as unknown.",
+      "items": {
+        "type": "string",
+        "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
+      }
+    },
+    "findings": {
+      "type": "array",
+      "description": "The findings this run attributed to catalog rule ids. Each item is exactly the finding format's shape (findings.schema.json items — the spec suite holds the two identical), so a findings consumer and a report consumer read one shape.",
+      "items": {
+        "type": "object",
+        "required": ["rule", "path"],
+        "additionalProperties": false,
+        "properties": {
+          "rule": {
+            "type": "string",
+            "description": "The Terp Standard catalog id the finding realises (catalog/<surface>/<rule>.json).",
+            "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
+          },
+          "path": {
+            "type": "string",
+            "description": "File path relative to the checked tree's root (the corpus case root, or the app root), with forward slashes."
+          },
+          "line": {
+            "type": "integer",
+            "description": "1-based line of the violation, when the checker can locate it.",
+            "minimum": 1
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable explanation; ideally directive (states the compliant fix)."
+          },
+          "fix_hint": {
+            "type": "string",
+            "description": "Agent-oriented remediation metadata: the compliant construct that replaces the violating one, sourced from the catalog entry's non-normative `reference` field (or the checker's own knowledge of the sanctioned pattern). Optional — a consumer must not require it."
+          },
+          "fingerprint": {
+            "type": "string",
+            "description": "A stable, checker-chosen identifier for THIS violation instance (e.g. a hash over rule + path + violating source construct), so consumers can track a finding across line-shifting edits. Optional; the fingerprint scheme is checker-internal — only stability across reformatting is expected."
+          }
+        }
+      }
+    },
+    "unattributed": {
+      "type": "array",
+      "description": "Messages the run produced OUTSIDE the standard's rules (another configured tool's diagnostics sharing the run, a parse error): surfaced, never dropped — and never attributable to a catalog id, which the finding format's rule pattern refuses by construction.",
+      "items": {
+        "type": "object",
+        "required": ["path", "message"],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "File path relative to the checked tree's root, with forward slashes."
+          },
+          "line": {
+            "type": "integer",
+            "description": "1-based line of the message, when the producer located one.",
+            "minimum": 1
+          },
+          "message": {
+            "type": "string",
+            "description": "The diagnostic text, verbatim."
+          },
+          "reported_as": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The tool-internal rule id the message surfaced as, when one exists — omitted (never null) otherwise."
+          }
+        }
+      }
+    }
+  }
+}

package/assurance-profile.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terp.dev/spec/assurance-profile.schema.json",
+  "title": "Terp assurance profile",
+  "description": "The machine-readable release-assurance claim a Terp toolchain emits after running its release verification profile: one document composing the named evidence lanes of the standard. The lane vocabulary and each lane's requirement level are normative and fixed by the spec (see the README's assurance-profile section): terp-standard, appsec-baseline and dependency-audit are REQUIRED - the claim ('ok') is true only when every required lane passed; a11y and blackbox-conformance are RECOMMENDED - they inform the reader but never carry the claim. Requirement levels are deliberately NOT a field of the document: an emitter cannot demote a required lane, and a consumer joins the document to the spec (via spec_version) for the canonical mapping. Every lane of the vocabulary must appear exactly once - omitting a lane would hide it. A lane's verdict is composed from the named verification checks ('checks', the check ids of the toolchain's release profile); a lane the toolchain does not realise yet is reported 'not-run' with no checks, never silently dropped and never counted as passed.",
+  "type": "object",
+  "required": ["terp_assurance", "spec_version", "toolchain", "profile", "ok", "lanes"],
+  "additionalProperties": false,
+  "properties": {
+    "terp_assurance": {
+      "description": "The assurance-profile document format version.",
+      "enum": [1]
+    },
+    "spec_version": {
+      "type": "string",
+      "description": "The spec semver (VERSION) whose lane vocabulary and requirement mapping this document claims against.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "toolchain": {
+      "type": "object",
+      "description": "The emitting toolchain's identity: tool name and its own version.",
+      "required": ["tool", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "tool": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "profile": {
+      "type": "string",
+      "description": "The verification profile the toolchain realised the lanes from (the reference toolchain: 'release').",
+      "minLength": 1
+    },
+    "ok": {
+      "type": "boolean",
+      "description": "The claim: true exactly when every REQUIRED lane has status 'passed'. Recommended lanes never affect it."
+    },
+    "lanes": {
+      "type": "array",
+      "description": "One entry per lane of the spec's vocabulary, each exactly once.",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "status", "checks"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "description": "The lane, from the spec's fixed vocabulary.",
+            "enum": [
+              "terp-standard",
+              "appsec-baseline",
+              "dependency-audit",
+              "a11y",
+              "blackbox-conformance"
+            ]
+          },
+          "status": {
+            "description": "'passed' (every composing check green), 'failed' (any composing check red), or 'not-run' (the toolchain does not realise the lane, or its precondition was unmet). 'not-run' is never a pass.",
+            "enum": ["passed", "failed", "not-run"]
+          },
+          "checks": {
+            "type": "array",
+            "description": "The verification-check ids whose verdicts compose this lane (evidence pointers into the toolchain's verification envelope). Non-empty for 'passed'/'failed'; empty for 'not-run' - a verdict without evidence is not a verdict.",
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  }
+}

package/catalog/backend/alembic_downgrades_not_empty.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/alembic_downgrades_not_empty",
+  "surface": "backend",
+  "title": "A migration's downgrade must reverse the change, not be an empty stub",
+  "intent": "A migration that leaves its downgrade step empty (a bare no-op with no operations) cannot be rolled back: reversing the revision silently leaves the schema mismatched instead of restoring the previous state. Each migration's downgrade must either perform the reverse operations or, for a deliberately irreversible step, carry a comment explaining why the no-op is intentional.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_alembic_downgrades_not_empty"
+    }
+  ],
+  "reference": "In each revision file under migrations/versions, a downgrade function whose body (after any docstring) is a lone pass / ellipsis or is empty, with no explanatory comment, is flagged; a reverse operation or an in-body '#' comment clears it.",
+  "opt_out": "# arch-allow-alembic-downgrades-not-empty: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "An empty downgrade is a property of the authored revision file; a forward deploy never executes downgrade, so the emptiness is invisible at runtime until a rollback is attempted, and the reversibility guarantee exists only in source."
+  },
+  "guide_topic": "migrations",
+  "corpus": true
+}

package/catalog/backend/base_query_not_overridden.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/base_query_not_overridden",
+  "surface": "backend",
+  "title": "A service never overrides the scoped base read query — read filters compose through the declared filter seam",
+  "intent": "The base read query composes the non-droppable row scope (soft-delete plus every registered capability predicate, e.g. tenancy) with the service's declared business filters. Overriding that composition point — the old, footgun-y seam — can silently drop soft-delete or tenant scoping the moment the override forgets to delegate up the chain, leaking soft-deleted or cross-tenant rows. Add static read conditions through the declared filter seam (it returns conditions, not a query, so scope cannot be dropped); a per-call filter belongs in a bespoke read built on the scoped base query.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_base_query_not_overridden"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "apply_row_scope"
+    }
+  ],
+  "reference": "BaseService.base_query composes the scope; add filters via business_filters(), or build bespoke reads on base_query().where(...) (ADR 0017).",
+  "opt_out": "# arch-allow-base-query-not-overridden: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The request session re-scopes every user-facing ORM read idempotently (apply_row_scope in the write-guarded session), so even a query built by an override that dropped super().base_query() is filtered again before execution."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/canonical_module_shape.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/canonical_module_shape",
+  "surface": "backend",
+  "title": "Every wired module directory carries the canonical parts: models, schemas, service, router, manifest",
+  "intent": "Terp modules are uniform on purpose: the table lives in models, the DTOs in schemas, the logic in service, the routes in router, and the manifest declares the module — so the shape is predictable to discover and the other rules (response models, input caps, audited writes, the declared policy) have the surface they scan. A directory is treated as a module once it ships a manifest or a mounted router; it must then carry all of the canonical parts, and the rule names each missing one. Requiring the manifest is deliberate: a directory that ships a router with no manifest would otherwise be invisible to this rule and to modules_declare_policy (which only scans manifests), so it could mount a router with no declared policy unnoticed. A directory with neither signal (a partial or a shared-asset / helper directory) is left alone.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_canonical_module_shape"
+    }
+  ],
+  "reference": "modules/<name>/ carries models.py, schemas.py, service.py, router.py and module.py (the ModuleSpec manifest).",
+  "opt_out": "# arch-allow-canonical-module-shape: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Repository-layout governance: the module directory's file shape exists only in the source tree. Composition consumes the ModuleSpec object, which carries no memory of which files declared it, so no runtime seam can observe the layout."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/datetime_columns_are_timezone_aware.json

@@ -0,0 +1,23 @@
+{
+  "id": "backend/datetime_columns_are_timezone_aware",
+  "surface": "backend",
+  "title": "Stored timestamp columns must keep their timezone",
+  "intent": "A timestamp column declared without an explicit timezone maps to a naive database type, which discards the zone of even a correctly-built aware value on the way in — so the moment the row records is ambiguous, and ordering or comparison across zones is silently wrong on read. This is the storage half of the hole whose in-memory half the naive-timestamp rule closes: capturing an aware value is worth nothing if the column cannot keep it. Every persisted timestamp column must declare timezone-aware storage.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_datetime_columns_are_timezone_aware"
+    }
+  ],
+  "reference": "On a table model, a datetime (or datetime | None) field is refused unless its declaration pins a timezone-aware column type — Field(sa_type=DateTime(timezone=True)) or Field(sa_column=Column(DateTime(timezone=True), ...)); the TIMESTAMP spelling and a qualified name (sa.DateTime) count equally. A bare annotation, a Field() that never names the column type, and an explicit timezone=False are all naive storage. Fields a table inherits from a mixin declared in the same file are in scope, since the column lands on the table either way. Classes no table inherits (DTOs, unrelated payloads) declare no columns and are out of scope.",
+  "opt_out": "# arch-allow-datetime-columns-are-timezone-aware: <reason>",
+  "runtime": {
+    "applicability": "deferred",
+    "rationale": "Unlike the in-memory naive-timestamp rule — where the zone is already lost at the point the value is built, so no seam downstream can recover it — this invariant survives into the running system: the mapped column type is inspectable on the ORM metadata the framework already collects at boot, and a naive timestamp column is decidable there without ambiguity. A fail-closed boot check over the collected table metadata would therefore add independent fidelity, catching a column whose naive type arrives from a path the source scan cannot follow: a dynamically built column, a mixin imported from another package, or a table contributed by an installed capability. The framework owns that seam (its create_app boot validations) but has not yet shipped this control.",
+    "tracking": "terp-framework reference implementation: the create_app boot-validation seam in terp.core.app (alongside the existing _validate_* boot checks) — to walk the collected table metadata and refuse a timestamp column whose mapped type is not timezone-aware."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/escape_hatch_budget.json

@@ -0,0 +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
+}

package/catalog/backend/events_reference_catalog.json

@@ -0,0 +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
+}

package/catalog/backend/input_schemas_exclude_managed_columns.json

@@ -0,0 +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
+}

package/catalog/backend/input_str_fields_have_max_length.json

@@ -0,0 +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
+}

package/catalog/backend/jobs_reference_catalog.json

@@ -0,0 +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
+}

package/catalog/backend/list_routes_paginate.json

@@ -0,0 +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
+}

package/catalog/backend/modules_declare_policy.json

@@ -0,0 +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
+}

package/catalog/backend/mutations_emit_audit.json

@@ -0,0 +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
+}

package/catalog/backend/mutations_require_write_role.json

@@ -0,0 +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
+}

package/catalog/backend/no_adhoc_background_runtime.json

@@ -0,0 +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
+}

package/catalog/backend/no_adhoc_config_decrypt.json

@@ -0,0 +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
+}

package/catalog/backend/no_adhoc_logging_config.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_adhoc_logging_config",
+  "surface": "backend",
+  "title": "App code never configures logging globally; redaction is centralized",
+  "intent": "Structured logging plus secret/PII redaction is installed once, centrally, at composition. A module that re-points the global logging configuration itself can silently bypass the central redaction filter.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_adhoc_logging_config"
+    }
+  ],
+  "reference": "configure_logging (called by create_app) installs the redacting handlers; logging.basicConfig / dictConfig / fileConfig calls in app modules are refused.",
+  "opt_out": "# arch-allow-no-adhoc-logging-config: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Global logging mutation is ambient interpreter state with no framework chokepoint to refuse it. The paired protection is constructive rather than preventive: the framework installs redaction on every handler it configures, but cannot intercept a module calling logging.basicConfig at import time."
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}