@terpjs/spec 0.14.0

package/catalog/backend/no_raw_outbound_http.json

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

package/catalog/backend/no_raw_session_construction.json

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

package/catalog/backend/no_star_imports.json

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

package/catalog/backend/no_todo_fixme.json

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

package/catalog/backend/no_unique_columns_on_soft_delete_models.json

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

package/catalog/backend/offset_queries_declare_ordering.json

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

package/catalog/backend/path_id_params_are_uuid.json

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

package/catalog/backend/policy_refs_resolve.json

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

package/catalog/backend/public_modules_are_read_only.json

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

package/catalog/backend/reads_use_base_query.json

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

package/catalog/backend/response_model_not_table_model.json

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

package/catalog/backend/routes_declare_response_model.json

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

package/catalog/backend/safe_methods_are_read_only.json

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

package/catalog/backend/schemas_exclude_sensitive_fields.json

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

package/catalog/backend/session_imported_from_sqlmodel.json

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

package/catalog/backend/table_models_use_base_table.json

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

package/catalog/backend/tables_have_migrations.json

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

package/catalog/backend/tenant_scoped_models_use_scoped_service.json

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

package/catalog/backend/ungoverned_escape_hatch.json

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

package/catalog/backend/update_schemas_inherit_base_update_schema.json

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

package/catalog/frontend/escape-hatch.json

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

package/catalog/frontend/generated-client-only.json

@@ -0,0 +1,26 @@
+{
+  "id": "frontend/generated-client-only",
+  "surface": "frontend",
+  "title": "All network egress goes through the generated, typed client",
+  "intent": "Raw fetch / XMLHttpRequest / WebSocket / EventSource (and navigator.sendBeacon) bypass the app's single audited, typed egress path. One client means one place for auth, errors, and contract types. The refused globals and member calls are declared in restricted-surface.json (restrictedGlobals, restrictedMemberCalls).",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "@terp/eslint-boundaries",
+      "ref": "BOUNDARY_SPEC.restrictedGlobals",
+      "reported_as": "no-restricted-globals"
+    }
+  ],
+  "reference": "useTerpClient() + unwrap from @terp/react-core for request/response; useRealtimeChannel() from @terp/react-core for typed SSE/WebSocket subscriptions (one-use ticket minted through the generated client).",
+  "opt_out": "// terp-allow-generated-client-only: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "In the running bundle the sanctioned generated client is itself built on fetch, so egress-primitive use cannot be attributed to an app module from inside the app. One typed egress path is an authoring contract; network policy beyond it (CSP connect-src) is deployment configuration the framework does not own per module."
+  },
+  "restricted_surface": [
+    "restrictedGlobals",
+    "restrictedMemberCalls"
+  ],
+  "corpus": true
+}

package/catalog/frontend/layout-contract.json

@@ -0,0 +1,26 @@
+{
+  "id": "frontend/layout-contract",
+  "surface": "frontend",
+  "title": "An opted-in app's archetype body slots accept only the contract's components",
+  "intent": "With a checked-in layout contract, each page archetype's body slot is constrained to the contract's sanctioned components, so screens stay structurally consistent and the failure message tells an agent exactly how to build the screen. Paired with the fail-closed runtime check on the rendered slot.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "@terp/eslint-boundaries",
+      "ref": "terp/layout-contract",
+      "reported_as": "terp/layout-contract"
+    },
+    {
+      "kind": "runtime",
+      "tool": "@terp/react-core",
+      "ref": "verifySlotChildren"
+    }
+  ],
+  "opt_out": "// terp-allow-layout-contract: <reason>",
+  "reference": "frontend/layout-contract.json + the layoutContract bootstrap option (ADR 0079); verifySlotChildren in @terp/react-core is the runtime DOM check.",
+  "runtime": {
+    "applicability": "required"
+  },
+  "corpus": true
+}