@terpjs/spec 0.14.0 → 0.15.0

package/catalog/backend/response_model_not_table_model.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/response_model_not_table_model",
-  "surface": "backend",
-  "title": "A route's declared response type is a read DTO, never the persisted table model",
-  "intent": "routes_declare_response_model proves a response type is declared; this rule proves it is not the persisted table itself. A declared response type set to a table model — directly or wrapped in a page envelope or collection — serializes the stored row, so a column such as a password hash leaks straight through the boundary. Return a read DTO listing exactly the safe fields instead.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_response_model_not_table_model"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "_validate_router_response_models"
-    }
-  ],
-  "reference": "response_model set to a table=True model, directly or wrapped in Page[...] / list[...] (the Page[User] footgun), is refused; return a *Read schema on terp.core.BaseSchema.",
-  "opt_out": "# arch-allow-response-model-not-table-model: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "Boot refuses a route whose response_model is (or wraps) a table=True ORM model (_validate_router_response_models -> BootError), with cross-package and nested-router fidelity a source scan cannot have."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/response_model_not_table_model",
+  "surface": "backend",
+  "title": "A route's declared response type is a read DTO, never the persisted table model",
+  "intent": "routes_declare_response_model proves a response type is declared; this rule proves it is not the persisted table itself. A declared response type set to a table model — directly or wrapped in a page envelope or collection — serializes the stored row, so a column such as a password hash leaks straight through the boundary. Return a read DTO listing exactly the safe fields instead.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_response_model_not_table_model"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_validate_router_response_models"
+    }
+  ],
+  "reference": "response_model set to a table=True model, directly or wrapped in Page[...] / list[...] (the Page[User] footgun), is refused; return a *Read schema on terp.core.BaseSchema.",
+  "opt_out": "# arch-allow-response-model-not-table-model: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Boot refuses a route whose response_model is (or wraps) a table=True ORM model (_validate_router_response_models -> BootError), with cross-package and nested-router fidelity a source scan cannot have."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/routes_declare_response_model.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/routes_declare_response_model",
-  "surface": "backend",
-  "title": "Every content route declares its response type (no bare data out)",
-  "intent": "A route with neither a declared response type nor a no-body status code can serialize a bare stored object out of the boundary — whatever the handler happens to return, including columns that were never meant to leave the app. Declaring the response type makes the boundary shape explicit and reviewable; both decorator routes and imperative route registration are checked.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_routes_declare_response_model"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "_validate_routes_declare_response_model"
-    }
-  ],
-  "reference": "response_model= on @router.<verb>(...) decorators and router.add_api_route(...); a no-body status_code (204/205/304) is the accepted alternative.",
-  "opt_out": "# arch-allow-routes-declare-response-model: <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 content route declares no response_model. No-body 204/205/304 statuses and Response-subclass-annotated non-content routes stay exempt, so the control refuses exactly the routes that would serialize a bare object out of the boundary."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/routes_declare_response_model",
+  "surface": "backend",
+  "title": "Every content route declares its response type (no bare data out)",
+  "intent": "A route with neither a declared response type nor a no-body status code can serialize a bare stored object out of the boundary — whatever the handler happens to return, including columns that were never meant to leave the app. Declaring the response type makes the boundary shape explicit and reviewable; both decorator routes and imperative route registration are checked.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_routes_declare_response_model"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_validate_routes_declare_response_model"
+    }
+  ],
+  "reference": "response_model= on @router.<verb>(...) decorators and router.add_api_route(...); a no-body status_code (204/205/304) is the accepted alternative.",
+  "opt_out": "# arch-allow-routes-declare-response-model: <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 content route declares no response_model. No-body 204/205/304 statuses and Response-subclass-annotated non-content routes stay exempt, so the control refuses exactly the routes that would serialize a bare object out of the boundary."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/safe_methods_are_read_only.json

@@ -1,31 +1,31 @@
-{
-  "id": "backend/safe_methods_are_read_only",
-  "surface": "backend",
-  "title": "A handler reachable via a safe HTTP method must not mutate",
-  "intent": "The deny-by-default guard derives the required role tier from the HTTP method: a safe method (GET / HEAD / OPTIONS) is authorized against the policy's read requirement, a mutating one against the write requirement. So a handler reachable through a safe method that calls a mutating service method performs a write a read-tier caller cleared — a privilege-tier escape (a viewer triggering an editor/admin write via a read request). This holds for a mixed-method route too: the safe-method invocation runs at the read tier, so a handler that always mutates is flagged (split it, or branch on the method behind a mutating route). Both decorator and imperative route registration are checked. Put the write behind a mutating method so it is authorized at the write tier. The runtime half marks a safe-method request read-only, so the write chokepoint refuses the write.",
-  "layer": "black-box",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_safe_methods_are_read_only"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "build_read_only_request_binder"
-    },
-    {
-      "kind": "black-box",
-      "tool": "@terp/conformance",
-      "ref": "standard: safe methods observably mutate nothing"
-    }
-  ],
-  "opt_out": "# arch-allow-safe-methods-are-read-only: <reason>",
-  "runtime": {
-    "applicability": "required"
-  },
-  "reference": "Mutating BaseService calls (create/update/delete/_save/_remove) in safe-method handlers are flagged; create_app binds safe-method requests read-only (build_read_only_request_binder).",
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/safe_methods_are_read_only",
+  "surface": "backend",
+  "title": "A handler reachable via a safe HTTP method must not mutate",
+  "intent": "The deny-by-default guard derives the required role tier from the HTTP method: a safe method (GET / HEAD / OPTIONS) is authorized against the policy's read requirement, a mutating one against the write requirement. So a handler reachable through a safe method that calls a mutating service method performs a write a read-tier caller cleared — a privilege-tier escape (a viewer triggering an editor/admin write via a read request). This holds for a mixed-method route too: the safe-method invocation runs at the read tier, so a handler that always mutates is flagged (split it, or branch on the method behind a mutating route). Both decorator and imperative route registration are checked. Put the write behind a mutating method so it is authorized at the write tier. The runtime half marks a safe-method request read-only, so the write chokepoint refuses the write.",
+  "layer": "black-box",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_safe_methods_are_read_only"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "build_read_only_request_binder"
+    },
+    {
+      "kind": "black-box",
+      "tool": "@terp/conformance",
+      "ref": "standard: safe methods observably mutate nothing"
+    }
+  ],
+  "opt_out": "# arch-allow-safe-methods-are-read-only: <reason>",
+  "runtime": {
+    "applicability": "required"
+  },
+  "reference": "Mutating BaseService calls (create/update/delete/_save/_remove) in safe-method handlers are flagged; create_app binds safe-method requests read-only (build_read_only_request_binder).",
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/schemas_exclude_sensitive_fields.json

@@ -1,32 +1,32 @@
-{
-  "id": "backend/schemas_exclude_sensitive_fields",
-  "surface": "backend",
-  "title": "A read / response DTO never exposes a credential-shaped field",
-  "intent": "Routes serialize a response DTO out of the boundary, so a field whose name reads like a secret — a password, a password hash, or a *secret / *api_key / *token suffix — would leak the credential to every caller. A response DTO is a schema in the response role: a read/response base schema or any class wired as a route's declared response type (so an input DTO mistakenly reused as a response is caught), excluding the inputs that are only ever request bodies (a client supplies a password) and table models (a table may store the hash). Plain helper classes are not policed. This guards the gap response_model_not_table_model leaves: a hand-rolled read DTO that copies the stored hash. (Version counters are integers, not secrets.)",
-  "layer": "black-box",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_schemas_exclude_sensitive_fields"
-    },
-    {
-      "kind": "black-box",
-      "tool": "@terp/conformance",
-      "ref": "standard: responses never expose credential-shaped fields"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "_validate_schemas_exclude_sensitive_fields"
-    }
-  ],
-  "reference": "BaseSchema / BaseUpdateSchema models and response_model= classes are scanned for password / hashed_password / *secret / *api_key / *token field names; request-body-only inputs and table=True models are excluded.",
-  "opt_out": "# arch-allow-schemas-exclude-sensitive-fields: <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 declared response DTO carries a credential-shaped field (the same underscore-delimited word match, with the token_version / version / trailing-token exclusions, as the build-time rule; framework-vetted terp.* DTOs exempt). The black-box probe remains a conformance-suite observation on top of this in-app fail-closed control."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/schemas_exclude_sensitive_fields",
+  "surface": "backend",
+  "title": "A read / response DTO never exposes a credential-shaped field",
+  "intent": "Routes serialize a response DTO out of the boundary, so a field whose name reads like a secret — a password, a password hash, or a *secret / *api_key / *token suffix — would leak the credential to every caller. A response DTO is a schema in the response role: a read/response base schema or any class wired as a route's declared response type (so an input DTO mistakenly reused as a response is caught), excluding the inputs that are only ever request bodies (a client supplies a password) and table models (a table may store the hash). Plain helper classes are not policed. This guards the gap response_model_not_table_model leaves: a hand-rolled read DTO that copies the stored hash. (Version counters are integers, not secrets.)",
+  "layer": "black-box",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_schemas_exclude_sensitive_fields"
+    },
+    {
+      "kind": "black-box",
+      "tool": "@terp/conformance",
+      "ref": "standard: responses never expose credential-shaped fields"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_validate_schemas_exclude_sensitive_fields"
+    }
+  ],
+  "reference": "BaseSchema / BaseUpdateSchema models and response_model= classes are scanned for password / hashed_password / *secret / *api_key / *token field names; request-body-only inputs and table=True models are excluded.",
+  "opt_out": "# arch-allow-schemas-exclude-sensitive-fields: <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 declared response DTO carries a credential-shaped field (the same underscore-delimited word match, with the token_version / version / trailing-token exclusions, as the build-time rule; framework-vetted terp.* DTOs exempt). The black-box probe remains a conformance-suite observation on top of this in-app fail-closed control."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/session_imported_from_sqlmodel.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/session_imported_from_sqlmodel",
-  "surface": "backend",
-  "title": "The ORM session type is imported from the framework's canonical source, never the underlying library",
-  "intent": "The framework standardises on one session type everywhere — the injected request session, the service layer, the write guard, and the migrations all speak the same type, re-exported from one canonical source. Importing the session type from the underlying ORM library instead quietly forks the app onto a second session type, so the rule names the one canonical import. (Constructing a session is separately banned by no_raw_session_construction — this only fixes the spelling.)",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_session_imported_from_sqlmodel"
-    }
-  ],
-  "reference": "from sqlmodel import Session is canonical (SQLModel re-exports SQLAlchemy's); imports from sqlalchemy / sqlalchemy.orm are refused.",
-  "opt_out": "# arch-allow-session-imported-from-sqlmodel: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "Which module a symbol was imported from is erased at runtime: sqlmodel's Session subclasses SQLAlchemy's, and the object in play is the framework-provided session either way. The typed exec/scoping benefits are carried by the session the framework hands out."
-  },
-  "guide_topic": "service",
-  "corpus": true
-}
+{
+  "id": "backend/session_imported_from_sqlmodel",
+  "surface": "backend",
+  "title": "The ORM session type is imported from the framework's canonical source, never the underlying library",
+  "intent": "The framework standardises on one session type everywhere — the injected request session, the service layer, the write guard, and the migrations all speak the same type, re-exported from one canonical source. Importing the session type from the underlying ORM library instead quietly forks the app onto a second session type, so the rule names the one canonical import. (Constructing a session is separately banned by no_raw_session_construction — this only fixes the spelling.)",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_session_imported_from_sqlmodel"
+    }
+  ],
+  "reference": "from sqlmodel import Session is canonical (SQLModel re-exports SQLAlchemy's); imports from sqlalchemy / sqlalchemy.orm are refused.",
+  "opt_out": "# arch-allow-session-imported-from-sqlmodel: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Which module a symbol was imported from is erased at runtime: sqlmodel's Session subclasses SQLAlchemy's, and the object in play is the framework-provided session either way. The typed exec/scoping benefits are carried by the session the framework hands out."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/table_models_use_base_table.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/table_models_use_base_table",
-  "surface": "backend",
-  "title": "Every ORM table model inherits the platform base table (no bare tables)",
-  "intent": "A table model that skips the platform base table bypasses the framework's managed identity, timestamps, and optimistic-concurrency version — a model living outside the control-plane contract, which every chokepoint (the service layer, audit, concurrency) presupposes.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_table_models_use_base_table"
-    }
-  ],
-  "reference": "BaseTable supplies the UUID id, created_at/updated_at and the OCC version; a bare SQLModel table=True model is refused.",
-  "opt_out": "# arch-allow-table-models-use-base-table: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "Inheritance is an authoring-shape fact, and Python generics are not runtime-enforced. The chokepoint contracts that matter at runtime (OCC version, managed columns, audit identity) presuppose BaseTable rather than police it -- a bare SQLModel table simply never fits the service seam."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/table_models_use_base_table",
+  "surface": "backend",
+  "title": "Every ORM table model inherits the platform base table (no bare tables)",
+  "intent": "A table model that skips the platform base table bypasses the framework's managed identity, timestamps, and optimistic-concurrency version — a model living outside the control-plane contract, which every chokepoint (the service layer, audit, concurrency) presupposes.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_table_models_use_base_table"
+    }
+  ],
+  "reference": "BaseTable supplies the UUID id, created_at/updated_at and the OCC version; a bare SQLModel table=True model is refused.",
+  "opt_out": "# arch-allow-table-models-use-base-table: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Inheritance is an authoring-shape fact, and Python generics are not runtime-enforced. The chokepoint contracts that matter at runtime (OCC version, managed columns, audit identity) presuppose BaseTable rather than police it -- a bare SQLModel table simply never fits the service seam."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/tables_have_migrations.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/tables_have_migrations",
-  "surface": "backend",
-  "title": "Every app module that defines a table model ships a packaged migration history",
-  "intent": "A deployed Terp app builds its schema from packaged migrations, never from dev-time schema auto-creation — so a module that declares a table model but ships no migration revision would deploy with that table missing, and the first request would fail on a nonexistent table. This rule fails the build first, and the running system's migration guard refuses the same violation at boot (the two halves of the migration control). Generate and commit the module's migration revision.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_tables_have_migrations"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.migrations",
-      "ref": "assert_no_missing_histories"
-    }
-  ],
-  "reference": "terp migrate make <name> generates the module's migrations/versions/ revision; assert_migrations_current is the production boot guard (it runs assert_no_missing_histories, so a table-owning package without any history refuses to boot), create_all the refused dev shortcut.",
-  "opt_out": "# arch-allow-tables-have-migrations: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "The boot guard refuses the standalone missing-history case this rule exists for: a declared package that defines table models but ships no migration history at all raises a MissingMigrationsError naming the packages -- fail closed at boot, before a request can hit a table that was never created. The pending-revisions half of the same guard keeps covering histories that exist but are behind head."
-  },
-  "guide_topic": "migrations",
-  "corpus": true
-}
+{
+  "id": "backend/tables_have_migrations",
+  "surface": "backend",
+  "title": "Every app module that defines a table model ships a packaged migration history",
+  "intent": "A deployed Terp app builds its schema from packaged migrations, never from dev-time schema auto-creation — so a module that declares a table model but ships no migration revision would deploy with that table missing, and the first request would fail on a nonexistent table. This rule fails the build first, and the running system's migration guard refuses the same violation at boot (the two halves of the migration control). Generate and commit the module's migration revision.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_tables_have_migrations"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.migrations",
+      "ref": "assert_no_missing_histories"
+    }
+  ],
+  "reference": "terp migrate make <name> generates the module's migrations/versions/ revision; assert_migrations_current is the production boot guard (it runs assert_no_missing_histories, so a table-owning package without any history refuses to boot), create_all the refused dev shortcut.",
+  "opt_out": "# arch-allow-tables-have-migrations: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The boot guard refuses the standalone missing-history case this rule exists for: a declared package that defines table models but ships no migration history at all raises a MissingMigrationsError naming the packages -- fail closed at boot, before a request can hit a table that was never created. The pending-revisions half of the same guard keeps covering histories that exist but are behind head."
+  },
+  "guide_topic": "migrations",
+  "corpus": true
+}

package/catalog/backend/tenant_scoped_models_use_scoped_service.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/tenant_scoped_models_use_scoped_service",
-  "surface": "backend",
-  "title": "A tenant-scoped model's service extends the tenant-scoped service base",
-  "intent": "This makes tenant isolation structural on the write side: reads of a tenant-scoped model are already filtered centrally by the registered tenant scope predicate, but the tenant-scoped service base is what stamps the tenant on create — so a plain service (which would insert an unstamped, never-visible row) is rejected at build time.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_tenant_scoped_models_use_scoped_service"
-    }
-  ],
-  "reference": "A TenantScopedMixin model's service extends TenantScopedService (stamps tenant_id on create, ADR 0017); a plain BaseService is refused.",
-  "opt_out": "# arch-allow-tenant-scoped-models-use-scoped-service: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "Service lineage is an authoring-shape fact. The leak-relevant runtime control is the registered row-scope predicate (apply_row_scope, declared under the scoping rules), which filters reads for the mixin regardless of which service touched the row; extending TenantScopedService is what makes writes stamp tenant_id so rows stay reachable in their tenant."
-  },
-  "guide_topic": "tenancy",
-  "corpus": true
-}
+{
+  "id": "backend/tenant_scoped_models_use_scoped_service",
+  "surface": "backend",
+  "title": "A tenant-scoped model's service extends the tenant-scoped service base",
+  "intent": "This makes tenant isolation structural on the write side: reads of a tenant-scoped model are already filtered centrally by the registered tenant scope predicate, but the tenant-scoped service base is what stamps the tenant on create — so a plain service (which would insert an unstamped, never-visible row) is rejected at build time.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_tenant_scoped_models_use_scoped_service"
+    }
+  ],
+  "reference": "A TenantScopedMixin model's service extends TenantScopedService (stamps tenant_id on create, ADR 0017); a plain BaseService is refused.",
+  "opt_out": "# arch-allow-tenant-scoped-models-use-scoped-service: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Service lineage is an authoring-shape fact. The leak-relevant runtime control is the registered row-scope predicate (apply_row_scope, declared under the scoping rules), which filters reads for the mixin regardless of which service touched the row; extending TenantScopedService is what makes writes stamp tenant_id so rows stay reachable in their tenant."
+  },
+  "guide_topic": "tenancy",
+  "corpus": true
+}

package/catalog/backend/ungoverned_escape_hatch.json

@@ -1,21 +1,21 @@
-{
-  "id": "backend/ungoverned_escape_hatch",
-  "surface": "backend",
-  "title": "The fail-closed ungoverned-opt-out condition, as structured violations",
-  "intent": "An opt-out marker the governance contract does not honour is itself a violation, reported in-band as structured findings (one per marker line) rather than crashing the harness: a marker used with no escape-hatch budget governing it, and a marker whose missing justification means it never suppressed anything. Either way the fix is to govern the opt-out — add the budget and the reason — never to silently honour it.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "ungoverned_marker_violations"
-    }
-  ],
-  "reference": "assert_app_clean raises on an ungoverned # arch-allow-* marker; ungoverned_marker_violations projects the budget-less condition and _apply_suppressions re-reports an unjustified marker under the same rule, for terp check --format json. The rule carries no opt_out: governance cannot be waived by the mechanism it governs.",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "A justification marker is a source comment; compiled bytecode retains neither the marker nor its reason. The escape-hatch contract governs authored source at the gate."
-  },
-  "guide_topic": "rules",
-  "corpus": true
-}
+{
+  "id": "backend/ungoverned_escape_hatch",
+  "surface": "backend",
+  "title": "The fail-closed ungoverned-opt-out condition, as structured violations",
+  "intent": "An opt-out marker the governance contract does not honour is itself a violation, reported in-band as structured findings (one per marker line) rather than crashing the harness: a marker used with no escape-hatch budget governing it, and a marker whose missing justification means it never suppressed anything. Either way the fix is to govern the opt-out — add the budget and the reason — never to silently honour it.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "ungoverned_marker_violations"
+    }
+  ],
+  "reference": "assert_app_clean raises on an ungoverned # arch-allow-* marker; ungoverned_marker_violations projects the budget-less condition and _apply_suppressions re-reports an unjustified marker under the same rule, for terp check --format json. The rule carries no opt_out: governance cannot be waived by the mechanism it governs.",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "A justification marker is a source comment; compiled bytecode retains neither the marker nor its reason. The escape-hatch contract governs authored source at the gate."
+  },
+  "guide_topic": "rules",
+  "corpus": true
+}

package/catalog/backend/update_schemas_inherit_base_update_schema.json

@@ -1,32 +1,32 @@
-{
-  "id": "backend/update_schemas_inherit_base_update_schema",
-  "surface": "backend",
-  "title": "An update request contract must require the optimistic-concurrency token",
-  "intent": "Optimistic concurrency only protects a row when the client echoes the version it loaded and the update path checks it before writing. That guarantee hinges on the update request contract demanding the token as a required field: an update contract that omits it lets a client send a blind write, so the check has nothing to compare and a concurrent edit is silently overwritten (a lost update). Every update request contract must inherit the shared concurrency-bearing base that makes the token a required field, rather than an ordinary contract that leaves it out. The token is not redeclared on the contract — it is a managed field that arrives by inheritance.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_update_schemas_inherit_base_update_schema"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "BaseUpdateSchema"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "StaleDataError"
-    }
-  ],
-  "runtime": {
-    "applicability": "required",
-    "rationale": "Two runtime halves back the source contract: BaseUpdateSchema makes the version token a required field, so a client that omits it is rejected at request validation (422); and BaseService.update matches the echoed token against the loaded row and raises a conflict (409) when they diverge. The build-time rule is the early-warning half — it ensures every update DTO actually inherits that base so it opts into both runtime checks, since a source scan is where an off-base update DTO is visible before it ever reaches a request."
-  },
-  "opt_out": "# arch-allow-update-schemas-inherit-base-update-schema: <reason>",
-  "reference": "class NoteUpdate(BaseSchema) is refused; class NoteUpdate(BaseUpdateSchema) (directly or transitively) is compliant, as is a class wired as build_crud_router(update_schema=...). BaseUpdateSchema supplies the required version field; BaseService.update checks it.",
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/update_schemas_inherit_base_update_schema",
+  "surface": "backend",
+  "title": "An update request contract must require the optimistic-concurrency token",
+  "intent": "Optimistic concurrency only protects a row when the client echoes the version it loaded and the update path checks it before writing. That guarantee hinges on the update request contract demanding the token as a required field: an update contract that omits it lets a client send a blind write, so the check has nothing to compare and a concurrent edit is silently overwritten (a lost update). Every update request contract must inherit the shared concurrency-bearing base that makes the token a required field, rather than an ordinary contract that leaves it out. The token is not redeclared on the contract — it is a managed field that arrives by inheritance.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_update_schemas_inherit_base_update_schema"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "BaseUpdateSchema"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "StaleDataError"
+    }
+  ],
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Two runtime halves back the source contract: BaseUpdateSchema makes the version token a required field, so a client that omits it is rejected at request validation (422); and BaseService.update matches the echoed token against the loaded row and raises a conflict (409) when they diverge. The build-time rule is the early-warning half — it ensures every update DTO actually inherits that base so it opts into both runtime checks, since a source scan is where an off-base update DTO is visible before it ever reaches a request."
+  },
+  "opt_out": "# arch-allow-update-schemas-inherit-base-update-schema: <reason>",
+  "reference": "class NoteUpdate(BaseSchema) is refused; class NoteUpdate(BaseUpdateSchema) (directly or transitively) is compliant, as is a class wired as build_crud_router(update_schema=...). BaseUpdateSchema supplies the required version field; BaseService.update checks it.",
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/frontend/escape-hatch.json

@@ -1,21 +1,21 @@
-{
-  "id": "frontend/escape-hatch",
-  "surface": "frontend",
-  "title": "Every opt-out marker is justified and governed by the budget ratchet",
-  "intent": "The one opt-out is a justified inline marker naming the rule; an unjustified marker is itself an error, and marker counts must exactly match the app's checked-in escape-hatch budget so opt-outs stay visible and can only shrink.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "@terp/eslint-boundaries",
-      "ref": "terp/escape-hatch",
-      "reported_as": "terp/escape-hatch"
-    }
-  ],
-  "reference": "// terp-allow-<rule>: <reason> markers reconciled against the app's checked-in escape-hatch-budget.json (ADR 0059). The rule carries no opt_out: governance cannot be waived by the mechanism it governs.",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "Markers and budgets are source/repository artifacts; the built bundle retains neither. The controls the markers opt out of keep their own runtime halves regardless."
-  },
-  "corpus": true
-}
+{
+  "id": "frontend/escape-hatch",
+  "surface": "frontend",
+  "title": "Every opt-out marker is justified and governed by the budget ratchet",
+  "intent": "The one opt-out is a justified inline marker naming the rule; an unjustified marker is itself an error, and marker counts must exactly match the app's checked-in escape-hatch budget so opt-outs stay visible and can only shrink.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "@terp/eslint-boundaries",
+      "ref": "terp/escape-hatch",
+      "reported_as": "terp/escape-hatch"
+    }
+  ],
+  "reference": "// terp-allow-<rule>: <reason> markers reconciled against the app's checked-in escape-hatch-budget.json (ADR 0059). The rule carries no opt_out: governance cannot be waived by the mechanism it governs.",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Markers and budgets are source/repository artifacts; the built bundle retains neither. The controls the markers opt out of keep their own runtime halves regardless."
+  },
+  "corpus": true
+}