@terpjs/spec 0.14.0 → 0.16.0

package/catalog/backend/no_raw_connection_access.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/no_raw_connection_access",
-  "surface": "backend",
-  "title": "Modules never reach the raw DB connection / engine behind the session",
-  "intent": "The runtime write guard covers the request session's own persistence methods, but the bound engine / connection the session exposes can issue data-modification statements directly, bypassing the audited chokepoint. A module must never reach for the session's underlying bind or connection; persist through the model's service so every write is audited. The escape is caught at the reach itself, and raw session / engine construction is separately banned by no_raw_session_construction — so an unrelated connect call on a domain object (a websocket / cache / search client) is deliberately not flagged.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_raw_connection_access"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "WriteGuardedSession"
-    }
-  ],
-  "reference": "session.get_bind() / session.connection() calls are refused (ADR 0015, F3); BaseService is the audited write path, and WriteGuardedSession gates session.connection() at runtime.",
-  "opt_out": "# arch-allow-no-raw-connection-access: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "The write-guarded request session gates session.connection() itself (WriteGuardedSession), closing the primary in-request escape to unaudited DML; the get_bind()/engine remainder has no construction hook, which is exactly the residual the build-time half covers."
-  },
-  "guide_topic": "service",
-  "corpus": true
-}
+{
+  "id": "backend/no_raw_connection_access",
+  "surface": "backend",
+  "title": "Modules never reach the raw DB connection / engine behind the session",
+  "intent": "The runtime write guard covers the request session's own persistence methods, but the bound engine / connection the session exposes can issue data-modification statements directly, bypassing the audited chokepoint. A module must never reach for the session's underlying bind or connection; persist through the model's service so every write is audited. The escape is caught at the reach itself, and raw session / engine construction is separately banned by no_raw_session_construction — so an unrelated connect call on a domain object (a websocket / cache / search client) is deliberately not flagged.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_raw_connection_access"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "WriteGuardedSession"
+    }
+  ],
+  "reference": "session.get_bind() / session.connection() calls are refused (ADR 0015, F3); BaseService is the audited write path, and WriteGuardedSession gates session.connection() at runtime.",
+  "opt_out": "# arch-allow-no-raw-connection-access: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The write-guarded request session gates session.connection() itself (WriteGuardedSession), closing the primary in-request escape to unaudited DML; the get_bind()/engine remainder has no construction hook, which is exactly the residual the build-time half covers."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/no_raw_file_references.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/no_raw_file_references",
-  "surface": "backend",
-  "title": "A table model's file-pointer column is a declared file reference, never a bare id column",
-  "intent": "A stored pointer to a file object carries authorization semantics: the files capability serves delegated reads only through a declared reference, failing closed on an undeclared column. A bare id-typed file-pointer column on a table model is an undeclared reference: nothing ties the file's access to the referencing row, which is the classic object-level (BOLA) drift. Declare the column with the files capability's reference type so the pointer is greppable, verified at runtime, and served through the module's own already-authorized row — never hand-rolled. A non-table schema (a read DTO exposing the pointer) is fine and not policed; only the persisted column is.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_raw_file_references"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.capabilities.files",
-      "ref": "load_for"
-    }
-  ],
-  "reference": "FileRef(...) from terp-cap-files declares the column; FileService.load_for fail-closes on an undeclared *file_id column (ADR 0057).",
-  "opt_out": "# arch-allow-no-raw-file-references: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "Delegated reads fail closed on an undeclared reference column: FileService.load_for serves a file only through a FileRef-declared column (UndeclaredFileReferenceError otherwise, ADR 0057), so a bare uuid column never acquires read-delegation semantics."
-  },
-  "guide_topic": "files",
-  "corpus": true
-}
+{
+  "id": "backend/no_raw_file_references",
+  "surface": "backend",
+  "title": "A table model's file-pointer column is a declared file reference, never a bare id column",
+  "intent": "A stored pointer to a file object carries authorization semantics: the files capability serves delegated reads only through a declared reference, failing closed on an undeclared column. A bare id-typed file-pointer column on a table model is an undeclared reference: nothing ties the file's access to the referencing row, which is the classic object-level (BOLA) drift. Declare the column with the files capability's reference type so the pointer is greppable, verified at runtime, and served through the module's own already-authorized row — never hand-rolled. A non-table schema (a read DTO exposing the pointer) is fine and not policed; only the persisted column is.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_raw_file_references"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.capabilities.files",
+      "ref": "load_for"
+    }
+  ],
+  "reference": "FileRef(...) from terp-cap-files declares the column; FileService.load_for fail-closes on an undeclared *file_id column (ADR 0057).",
+  "opt_out": "# arch-allow-no-raw-file-references: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Delegated reads fail closed on an undeclared reference column: FileService.load_for serves a file only through a FileRef-declared column (UndeclaredFileReferenceError otherwise, ADR 0057), so a bare uuid column never acquires read-delegation semantics."
+  },
+  "guide_topic": "files",
+  "corpus": true
+}

package/catalog/backend/no_raw_outbound_http.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/no_raw_outbound_http",
-  "surface": "backend",
-  "title": "App modules do not import raw HTTP clients; outbound calls use a capability",
-  "intent": "Directly importing an HTTP client library — or the lower-level socket / protocol primitives that reach the same network — makes SSRF protection, allowlists, egress auditing, and timeout policy a per-call-site choice. Outbound traffic belongs behind a declared capability that centralizes those controls. As a security rule this also scans test and migration files inside a module — they are importable code, so they are application surface too.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_raw_outbound_http"
-    }
-  ],
-  "reference": "httpx / requests / urllib.request / urllib3 / aiohttp imports and the socket / http.client escape routes are refused in app modules; outbound calls go through a declared egress capability.",
-  "opt_out": "# arch-allow-no-raw-outbound-http: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "Import-form rule: the sanctioned egress capability itself drives an HTTP client at runtime, so client presence and traffic cannot be attributed to an app module from inside the process. Network-level egress policy is deployment configuration, not a per-module framework seam."
-  },
-  "guide_topic": "capability",
-  "corpus": true
-}
+{
+  "id": "backend/no_raw_outbound_http",
+  "surface": "backend",
+  "title": "App modules do not import raw HTTP clients; outbound calls use a capability",
+  "intent": "Directly importing an HTTP client library — or the lower-level socket / protocol primitives that reach the same network — makes SSRF protection, allowlists, egress auditing, and timeout policy a per-call-site choice. Outbound traffic belongs behind a declared capability that centralizes those controls. As a security rule this also scans test and migration files inside a module — they are importable code, so they are application surface too.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_raw_outbound_http"
+    }
+  ],
+  "reference": "httpx / requests / urllib.request / urllib3 / aiohttp imports and the socket / http.client escape routes are refused in app modules; outbound calls go through a declared egress capability.",
+  "opt_out": "# arch-allow-no-raw-outbound-http: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Import-form rule: the sanctioned egress capability itself drives an HTTP client at runtime, so client presence and traffic cannot be attributed to an app module from inside the process. Network-level egress policy is deployment configuration, not a per-module framework seam."
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}

package/catalog/backend/no_raw_session_construction.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/no_raw_session_construction",
-  "surface": "backend",
-  "title": "App code never constructs a database session or engine; it uses the injected request session",
-  "intent": "The injected request session is where the framework's runtime controls live — the write guard, row scoping, and the audit hooks all ride on the session the framework hands out. A hand-constructed session or engine sits outside every one of those chokepoints by definition: its reads are unscoped, its writes are unaudited and unguarded, and it silently forks the app onto a second connection lifecycle.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_raw_session_construction"
-    }
-  ],
-  "reference": "SessionDep injects the guarded request session; Session(...) / create_engine / sessionmaker construction in app code is refused.",
-  "opt_out": "# arch-allow-no-raw-session-construction: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "Nothing in Python lets the framework refuse construction of a third-party class: a hand-built Session or engine never passes through any framework seam -- which is exactly why it must be caught in source. The guarded request session (SessionDep) is the surface the framework does control; an app-constructed one sits outside every chokepoint by definition."
-  },
-  "guide_topic": "service",
-  "corpus": true
-}
+{
+  "id": "backend/no_raw_session_construction",
+  "surface": "backend",
+  "title": "App code never constructs a database session or engine; it uses the injected request session",
+  "intent": "The injected request session is where the framework's runtime controls live — the write guard, row scoping, and the audit hooks all ride on the session the framework hands out. A hand-constructed session or engine sits outside every one of those chokepoints by definition: its reads are unscoped, its writes are unaudited and unguarded, and it silently forks the app onto a second connection lifecycle.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_raw_session_construction"
+    }
+  ],
+  "reference": "SessionDep injects the guarded request session; Session(...) / create_engine / sessionmaker construction in app code is refused.",
+  "opt_out": "# arch-allow-no-raw-session-construction: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Nothing in Python lets the framework refuse construction of a third-party class: a hand-built Session or engine never passes through any framework seam -- which is exactly why it must be caught in source. The guarded request session (SessionDep) is the surface the framework does control; an app-constructed one sits outside every chokepoint by definition."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/no_star_imports.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/no_star_imports",
-  "surface": "backend",
-  "title": "Import names explicitly, never with a wildcard",
-  "intent": "A wildcard import pulls an unknown, changeable set of names into a namespace, so the module's real dependency surface is invisible and one upstream rename can silently shadow a local name. Naming each import keeps the dependency graph legible to readers and to the boundary checks that police it.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_star_imports"
-    }
-  ],
-  "reference": "A 'from <module> import *' statement is refused; list the specific names the module uses instead.",
-  "opt_out": "# arch-allow-no-star-imports: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "The invariant is a property of the authored import statement. Once the module is loaded the wildcard has already been expanded into concrete bindings, indistinguishable from explicit imports, so no runtime seam can reconstruct which spelling was written — the only faithful check reads the source."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/no_star_imports",
+  "surface": "backend",
+  "title": "Import names explicitly, never with a wildcard",
+  "intent": "A wildcard import pulls an unknown, changeable set of names into a namespace, so the module's real dependency surface is invisible and one upstream rename can silently shadow a local name. Naming each import keeps the dependency graph legible to readers and to the boundary checks that police it.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_star_imports"
+    }
+  ],
+  "reference": "A 'from <module> import *' statement is refused; list the specific names the module uses instead.",
+  "opt_out": "# arch-allow-no-star-imports: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored import statement. Once the module is loaded the wildcard has already been expanded into concrete bindings, indistinguishable from explicit imports, so no runtime seam can reconstruct which spelling was written — the only faithful check reads the source."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/no_todo_fixme.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/no_todo_fixme",
-  "surface": "backend",
-  "title": "No placeholder comments for deferred work",
-  "intent": "A TODO, FIXME, HACK, or XXX comment marks unfinished work that ships anyway and is almost never revisited, so the gap it names silently becomes permanent. Finish the behaviour or delete the dead branch — do not leave a note promising a fix that will not come.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_todo_fixme"
-    }
-  ],
-  "reference": "The markers TODO, FIXME, HACK, and XXX are refused when they appear in a real comment token; matching ignores identical text inside strings or docstrings.",
-  "opt_out": "# arch-allow-no-todo-fixme: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "The invariant is a property of the authored comments, which the interpreter discards entirely — there is nothing at runtime to observe. Only a source-form check can see the placeholder."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/no_todo_fixme",
+  "surface": "backend",
+  "title": "No placeholder comments for deferred work",
+  "intent": "A TODO, FIXME, HACK, or XXX comment marks unfinished work that ships anyway and is almost never revisited, so the gap it names silently becomes permanent. Finish the behaviour or delete the dead branch — do not leave a note promising a fix that will not come.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_todo_fixme"
+    }
+  ],
+  "reference": "The markers TODO, FIXME, HACK, and XXX are refused when they appear in a real comment token; matching ignores identical text inside strings or docstrings.",
+  "opt_out": "# arch-allow-no-todo-fixme: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored comments, which the interpreter discards entirely — there is nothing at runtime to observe. Only a source-form check can see the placeholder."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/no_unique_columns_on_soft_delete_models.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/no_unique_columns_on_soft_delete_models",
-  "surface": "backend",
-  "title": "Soft-delete models never declare a full-table unique constraint (dead rows block reuse)",
-  "intent": "A soft-deleted row stays in the table, so it keeps occupying every full-table unique index: the \"deleted\" value (an email, a slug, a code) can never be used again, surfacing as an inexplicable conflict long after the delete. Scope uniqueness to the live rows with a partial unique index that excludes soft-deleted rows — which this rule accepts — or deactivate instead of deleting.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_no_unique_columns_on_soft_delete_models"
-    }
-  ],
-  "reference": "A partial unique index in __table_args__ (unique=True with postgresql_where / sqlite_where on deleted_at IS NULL) is the accepted shape; the identity user table keeps email unique by deactivating instead of deleting.",
-  "opt_out": "# arch-allow-no-unique-columns-on-soft-delete-models: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "The constraint is baked into migration-produced DDL; at runtime the schema already exists, and the failure mode (a dead row blocking reuse) surfaces as the database's own constraint error, mapped to the uniform 409 envelope -- handled, but only preventable when the model is authored."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/no_unique_columns_on_soft_delete_models",
+  "surface": "backend",
+  "title": "Soft-delete models never declare a full-table unique constraint (dead rows block reuse)",
+  "intent": "A soft-deleted row stays in the table, so it keeps occupying every full-table unique index: the \"deleted\" value (an email, a slug, a code) can never be used again, surfacing as an inexplicable conflict long after the delete. Scope uniqueness to the live rows with a partial unique index that excludes soft-deleted rows — which this rule accepts — or deactivate instead of deleting.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_unique_columns_on_soft_delete_models"
+    }
+  ],
+  "reference": "A partial unique index in __table_args__ (unique=True with postgresql_where / sqlite_where on deleted_at IS NULL) is the accepted shape; the identity user table keeps email unique by deactivating instead of deleting.",
+  "opt_out": "# arch-allow-no-unique-columns-on-soft-delete-models: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The constraint is baked into migration-produced DDL; at runtime the schema already exists, and the failure mode (a dead row blocking reuse) surfaces as the database's own constraint error, mapped to the uniform 409 envelope -- handled, but only preventable when the model is authored."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/offset_queries_declare_ordering.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/offset_queries_declare_ordering",
-  "surface": "backend",
-  "title": "An offset-paginated query must declare an explicit ordering",
-  "intent": "Row order without an explicit ordering clause is undefined, so paging a query by a numeric offset over an unordered result can silently skip or repeat rows between pages. A query that skips a number of rows must also declare a deterministic ordering so the page sequence is stable and every row is seen exactly once.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_offset_queries_declare_ordering"
-    }
-  ],
-  "reference": "A function that calls .offset(...) but no .order_by(...) is flagged at the offset call; add an explicit ordering, or page through the framework's ordered pagination helper.",
-  "opt_out": "# arch-allow-offset-queries-declare-ordering: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "The unordered-offset defect is a property of the authored query expression; the database executes an unordered offset without error, so there is no fail-closed runtime signal, and the ordering guarantee exists only by constraining the source."
-  },
-  "guide_topic": "service",
-  "corpus": true
-}
+{
+  "id": "backend/offset_queries_declare_ordering",
+  "surface": "backend",
+  "title": "An offset-paginated query must declare an explicit ordering",
+  "intent": "Row order without an explicit ordering clause is undefined, so paging a query by a numeric offset over an unordered result can silently skip or repeat rows between pages. A query that skips a number of rows must also declare a deterministic ordering so the page sequence is stable and every row is seen exactly once.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_offset_queries_declare_ordering"
+    }
+  ],
+  "reference": "A function that calls .offset(...) but no .order_by(...) is flagged at the offset call; add an explicit ordering, or page through the framework's ordered pagination helper.",
+  "opt_out": "# arch-allow-offset-queries-declare-ordering: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The unordered-offset defect is a property of the authored query expression; the database executes an unordered offset without error, so there is no fail-closed runtime signal, and the ordering guarantee exists only by constraining the source."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/path_id_params_are_uuid.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/path_id_params_are_uuid",
-  "surface": "backend",
-  "title": "A route path parameter naming a resource id must be typed as a UUID",
-  "intent": "A URL path segment that names a resource id (spelled id or ending in _id) identifies a specific row, and the platform issues UUID identifiers. Typing that path parameter as a UUID rejects a malformed identifier at the request boundary, before it reaches the data layer, instead of letting an untyped or wrongly-typed value through. Only path parameters are in scope; query and body parameters are unaffected.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_path_id_params_are_uuid"
-    }
-  ],
-  "reference": "A handler parameter that also appears in the route decorator's URL template and is named id or ends in _id must be annotated uuid.UUID (a uuid.UUID attribute or a bare UUID name); a missing or non-UUID annotation is flagged at the handler.",
-  "opt_out": "# arch-allow-path-id-params-are-uuid: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "The rule constrains the authored route signature (the declared parameter type), a source-form property of the handler rather than an observable runtime event; the framework does not re-derive intended id-parameter types at mount time, so a mis-typed parameter merely validates against the wrong type with no separate signal that a UUID was intended."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/path_id_params_are_uuid",
+  "surface": "backend",
+  "title": "A route path parameter naming a resource id must be typed as a UUID",
+  "intent": "A URL path segment that names a resource id (spelled id or ending in _id) identifies a specific row, and the platform issues UUID identifiers. Typing that path parameter as a UUID rejects a malformed identifier at the request boundary, before it reaches the data layer, instead of letting an untyped or wrongly-typed value through. Only path parameters are in scope; query and body parameters are unaffected.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_path_id_params_are_uuid"
+    }
+  ],
+  "reference": "A handler parameter that also appears in the route decorator's URL template and is named id or ends in _id must be annotated uuid.UUID (a uuid.UUID attribute or a bare UUID name); a missing or non-UUID annotation is flagged at the handler.",
+  "opt_out": "# arch-allow-path-id-params-are-uuid: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The rule constrains the authored route signature (the declared parameter type), a source-form property of the handler rather than an observable runtime event; the framework does not re-derive intended id-parameter types at mount time, so a mis-typed parameter merely validates against the wrong type with no separate signal that a UUID was intended."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/policy_refs_resolve.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/policy_refs_resolve",
-  "surface": "backend",
-  "title": "Every typed authority a policy cites resolves in the app's authority registry",
-  "intent": "The build-time half of control-plane registry resolution: boot validation already refuses an undeclared authority at runtime; this rule catches the same drift at the gate, before the app ever boots. Any reference that traces to the app's authority registry — via a module alias or a name imported from the registry — must name something the registry actually declares. References the scan cannot trace to the registry (kernel default roles, locally built objects) are left to the runtime check, so the rule stays precise, never heuristic.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_policy_refs_resolve"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "validation_errors"
-    }
-  ],
-  "reference": "control_plane/permissions.py is the registry; aliased references like perms.BILLING_READ must resolve there, kernel defaults like Roles.EDITOR are left to ControlPlane.validation_errors at boot.",
-  "opt_out": "# arch-allow-policy-refs-resolve: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "Boot validation refuses an undeclared authority before the app serves (ControlPlane.validation_errors -> BootError); the build-time rule catches the same drift earlier, at the gate."
-  },
-  "guide_topic": "policy",
-  "corpus": true
-}
+{
+  "id": "backend/policy_refs_resolve",
+  "surface": "backend",
+  "title": "Every typed authority a policy cites resolves in the app's authority registry",
+  "intent": "The build-time half of control-plane registry resolution: boot validation already refuses an undeclared authority at runtime; this rule catches the same drift at the gate, before the app ever boots. Any reference that traces to the app's authority registry — via a module alias or a name imported from the registry — must name something the registry actually declares. References the scan cannot trace to the registry (kernel default roles, locally built objects) are left to the runtime check, so the rule stays precise, never heuristic.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_policy_refs_resolve"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "validation_errors"
+    }
+  ],
+  "reference": "control_plane/permissions.py is the registry; aliased references like perms.BILLING_READ must resolve there, kernel defaults like Roles.EDITOR are left to ControlPlane.validation_errors at boot.",
+  "opt_out": "# arch-allow-policy-refs-resolve: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Boot validation refuses an undeclared authority before the app serves (ControlPlane.validation_errors -> BootError); the build-time rule catches the same drift earlier, at the gate."
+  },
+  "guide_topic": "policy",
+  "corpus": true
+}

package/catalog/backend/public_modules_are_read_only.json

@@ -1,26 +1,26 @@
-{
-  "id": "backend/public_modules_are_read_only",
-  "surface": "backend",
-  "title": "A public (unauthenticated) module must not expose a mutating route",
-  "intent": "A public policy drops authentication for the whole module, so a mutating route under it is an unauthenticated write — almost always an accident, and the broken-access-control footgun the deny-by-default posture exists to prevent. A genuinely public write (a sign-up / contact form / webhook receiver) is rare and deliberate, so it stays available through the governed escape hatch: a justified opt-out marker ratcheted by the escape-hatch budget, making the unauthenticated write visible and budgeted rather than silent. Gate the writes behind a policy with a write role, or justify the public write explicitly. The runtime half is the boot refusal of a public module that exposes a mutating route unless its policy opts in explicitly with a reason — each layer carries its own justified opt-out.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_public_modules_are_read_only"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "_validate_public_modules_read_only"
-    }
-  ],
-  "runtime": {
-    "applicability": "required"
-  },
-  "reference": "Policy.public(reason=...) declares the public module; create_app -> _validate_public_modules_read_only refuses public writes unless the policy opts in via Policy.public_write(reason=...).",
-  "opt_out": "# arch-allow-public-modules-are-read-only: <reason>",
-  "guide_topic": "policy",
-  "corpus": true
-}
+{
+  "id": "backend/public_modules_are_read_only",
+  "surface": "backend",
+  "title": "A public (unauthenticated) module must not expose a mutating route",
+  "intent": "A public policy drops authentication for the whole module, so a mutating route under it is an unauthenticated write — almost always an accident, and the broken-access-control footgun the deny-by-default posture exists to prevent. A genuinely public write (a sign-up / contact form / webhook receiver) is rare and deliberate, so it stays available through the governed escape hatch: a justified opt-out marker ratcheted by the escape-hatch budget, making the unauthenticated write visible and budgeted rather than silent. Gate the writes behind a policy with a write role, or justify the public write explicitly. The runtime half is the boot refusal of a public module that exposes a mutating route unless its policy opts in explicitly with a reason — each layer carries its own justified opt-out.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_public_modules_are_read_only"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_validate_public_modules_read_only"
+    }
+  ],
+  "runtime": {
+    "applicability": "required"
+  },
+  "reference": "Policy.public(reason=...) declares the public module; create_app -> _validate_public_modules_read_only refuses public writes unless the policy opts in via Policy.public_write(reason=...).",
+  "opt_out": "# arch-allow-public-modules-are-read-only: <reason>",
+  "guide_topic": "policy",
+  "corpus": true
+}

package/catalog/backend/reads_use_base_query.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/reads_use_base_query",
-  "surface": "backend",
-  "title": "A scope-trait model is read through the composed scoped query, never a raw query built from scratch",
-  "intent": "A model that mixes a soft-delete or tenant-scope trait carries row scope. A bespoke read that queries the model directly — instead of building on the composed scoped query — drops that scope, leaking soft-deleted or cross-tenant rows (closing the composition point to overrides did not close a new read method that never calls it). Build reads on the scoped query and the declared filter seam; the request session re-applies the scope to single-entity reads as the runtime backstop, and this rule is the build-time early warning. The one sanctioned raw query — the scoped composition point itself — lives in the framework, not a module, so it is never scanned here.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_reads_use_base_query"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "apply_row_scope"
-    }
-  ],
-  "reference": "select(Model) on a SoftDeleteMixin / TenantScopedMixin model is refused in modules (ADR 0017, F1); build on base_query() / business_filters(), with apply_row_scope as the runtime backstop.",
-  "opt_out": "# arch-allow-reads-use-base-query: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "The request session re-scopes user-facing ORM reads idempotently (apply_row_scope): a bespoke select(Model) that skipped base_query() is filtered for soft-delete / registered predicates again at execution, so the leak the rule warns about is closed even when the source pattern slips through."
-  },
-  "guide_topic": "service",
-  "corpus": true
-}
+{
+  "id": "backend/reads_use_base_query",
+  "surface": "backend",
+  "title": "A scope-trait model is read through the composed scoped query, never a raw query built from scratch",
+  "intent": "A model that mixes a soft-delete or tenant-scope trait carries row scope. A bespoke read that queries the model directly — instead of building on the composed scoped query — drops that scope, leaking soft-deleted or cross-tenant rows (closing the composition point to overrides did not close a new read method that never calls it). Build reads on the scoped query and the declared filter seam; the request session re-applies the scope to single-entity reads as the runtime backstop, and this rule is the build-time early warning. The one sanctioned raw query — the scoped composition point itself — lives in the framework, not a module, so it is never scanned here.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_reads_use_base_query"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "apply_row_scope"
+    }
+  ],
+  "reference": "select(Model) on a SoftDeleteMixin / TenantScopedMixin model is refused in modules (ADR 0017, F1); build on base_query() / business_filters(), with apply_row_scope as the runtime backstop.",
+  "opt_out": "# arch-allow-reads-use-base-query: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The request session re-scopes user-facing ORM reads idempotently (apply_row_scope): a bespoke select(Model) that skipped base_query() is filtered for soft-delete / registered predicates again at execution, so the leak the rule warns about is closed even when the source pattern slips through."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}