@terpjs/spec 0.14.0

package/catalog/backend/no_adhoc_middleware.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/no_adhoc_middleware",
+  "surface": "backend",
+  "title": "App code never wires HTTP middleware itself; security is centralized",
+  "intent": "Cross-cutting HTTP security (headers, CORS, rate-limit, body-size, request-id) is declared once as central security configuration and installed at composition. A module that registers middleware itself — by call, decorator, or subclassing — is assembling a security posture outside that single control plane.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_adhoc_middleware"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_freeze_app_middleware_registration"
+    }
+  ],
+  "reference": "SecurityConfig declared once and installed by create_app; add_middleware(...), the @app.middleware(\"http\") decorator, and BaseHTTPMiddleware subclasses are refused in app modules. On the composed app both registration spellings raise BootError at runtime; create_app's middleware parameter is the one sanctioned composition seam.",
+  "opt_out": "# arch-allow-no-adhoc-middleware: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The composition freeze covers the middleware seam: on the composed app, add_middleware(...) and the @app.middleware(...) decorator are replaced by refusers that raise a BootError naming this rule and the sanctioned alternative (create_app's middleware parameter) -- so middleware registered between composition and serving is refused fail-closed, not just flagged at build time."
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}

package/catalog/backend/no_adhoc_permission_literals.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/no_adhoc_permission_literals",
+  "surface": "backend",
+  "title": "Modules reference typed authority objects, never bare permission strings",
+  "intent": "An authority named as a bare string is invisible to the control plane: it cannot be resolved against the app's declared registry, so a typo or a stale name silently grants nothing (or the wrong thing) instead of failing the build. Citing typed authority objects keeps every permission reference greppable and verifiable against the registry, and lets the runtime normalization chokepoint refuse anything unregistered.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_adhoc_permission_literals"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "requirement_from"
+    }
+  ],
+  "reference": "Role / Permission objects from the control-plane registry; requirement_from raises TypeError on a bare string.",
+  "opt_out": "# arch-allow-no-adhoc-permission-literals: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The typed normalization chokepoint refuses a bare string outright (requirement_from raises TypeError for anything but Role / Permission / the legacy enum), and boot refuses a Policy citing an authority the control plane does not declare."
+  },
+  "guide_topic": "policy",
+  "corpus": true
+}

package/catalog/backend/no_app_instantiation.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_app_instantiation",
+  "surface": "backend",
+  "title": "App code never constructs the web application object directly",
+  "intent": "The framework's composer owns app composition (deny-by-default guards, the control plane, the error envelope). A hand-built application object is an application assembled outside the framework — it acquires none of those controls.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_app_instantiation"
+    }
+  ],
+  "reference": "terp.core.create_app composes the app; a bare FastAPI() constructor call is refused.",
+  "opt_out": "# arch-allow-no-app-instantiation: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "A raw FastAPI() is an ordinary object the framework never sees: it acquires no guard, middleware, or error envelope -- and offers no seam through which terp.core could refuse its construction. Only composition through create_app passes framework-owned surface; the rule keeps authorship inside it."
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}

package/catalog/backend/no_blocking_sleep.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_blocking_sleep",
+  "surface": "backend",
+  "title": "Never block the thread with a synchronous sleep",
+  "intent": "A synchronous sleep parks the thread that is serving the request or running the job, so the whole worker sits idle and the pool starves under load. Waiting must yield the thread — poll with an awaitable, schedule a delayed job, or let the runtime back off — never freeze it.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_blocking_sleep"
+    }
+  ],
+  "reference": "A call to the standard library's time.sleep() is refused; use a non-blocking wait or a scheduled job.",
+  "opt_out": "# arch-allow-no-blocking-sleep: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored call. At execution time a blocking sleep is a normal function call on the stack, and by the time it runs the thread is already parked — no seam upstream can turn a blocking wait into a yielding one, so the only faithful check refuses the construct in source."
+  },
+  "guide_topic": "jobs",
+  "corpus": true
+}

package/catalog/backend/no_cross_module_imports.json

@@ -0,0 +1,21 @@
+{
+  "id": "backend/no_cross_module_imports",
+  "surface": "backend",
+  "title": "A module never imports a sibling module (leaf domains stay independent)",
+  "intent": "Modules couple only through the platform surface and their own files — a sibling import creates hidden coupling that breaks module isolation and independent evolution. Both absolute and relative sibling imports are caught: a relative import is resolved to its absolute module first, so renaming the import style does not re-couple two leaf modules.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_cross_module_imports"
+    }
+  ],
+  "opt_out": "# arch-allow-no-cross-module-imports: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Module independence is an import-graph property of the source tree. At runtime the composed app legitimately holds every module in one process, so a cross-module reference is indistinguishable from composition itself."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/no_dependency_overrides.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/no_dependency_overrides",
+  "surface": "backend",
+  "title": "App code never rebinds the composed app's dependency injections",
+  "intent": "Composition binds the authentication and session seams once. Rebinding the app's dependency-override map in app code (e.g. replacing the principal provider) silently disables authentication or swaps the database session outside every guard. Overrides are a TEST-ONLY seam; application code has no legitimate use.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_dependency_overrides"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_freeze_dependency_overrides"
+    }
+  ],
+  "reference": "app.dependency_overrides on the create_app-composed app is the refused surface; composition binds the seams (create_app(principal_provider=...)) before the freeze.",
+  "opt_out": "# arch-allow-no-dependency-overrides: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Outside the local environment the composed app's dependency-override map is replaced by a refusing mapping: every mutating spelling raises a BootError naming this rule while per-request override reads keep working. The local environment deliberately keeps the map writable -- overrides are the sanctioned test-only seam (a local test suite rebinding the session against a scratch engine), which is exactly the legitimate use the rule's intent carves out; a deployed app can never rebind its auth or session seams post-composition."
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}

package/catalog/backend/no_destructive_migrations.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_destructive_migrations",
+  "surface": "backend",
+  "title": "Destructive migration operations require a reason-bearing marker",
+  "intent": "Dropping a table or column, changing a column's type, and executing raw destructive statements in an upgrade can destroy data or make rollback unsafe — whether spelled directly, on a batch block, through an alias, or smuggled into a raw statement. Each destructive operation is a violation; a reviewed one is justified through the standard governed escape hatch — a justified marker on (or immediately above) the operation, counted against the app's budget ratchet — so every accepted risk is explicit, reviewable, greppable, and ratcheted like any other opt-out.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_destructive_migrations"
+    }
+  ],
+  "reference": "drop_table / drop_column / type-changing alter_column and execute(...) of DROP TABLE / DROP COLUMN / TRUNCATE / DELETE FROM / ALTER TABLE ... DROP in upgrade() are flagged per operation; the standard # arch-allow-no-destructive-migrations marker (budgeted) justifies a reviewed one. The pre-0.6.0 file-level terp-allow-destructive-migration waiver is retired.",
+  "opt_out": "# arch-allow-no-destructive-migrations: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is reviewability of the authored revision: a reason-bearing marker is a comment, invisible to Alembic when the DDL executes. What could be checked at apply time is a different (op-classification) control; the justified-marker contract itself only exists in source."
+  },
+  "guide_topic": "migrations",
+  "corpus": true
+}

package/catalog/backend/no_dynamic_sql.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_dynamic_sql",
+  "surface": "backend",
+  "title": "Raw SQL text in app modules must be a static literal, never dynamically built",
+  "intent": "A raw-SQL construct built dynamically — through interpolation, concatenation, format calls, or a variable — is not statically reviewable and is easy to turn into SQL injection. Keep SQL as a literal and pass data through bound parameters / the query builder's typed expressions instead. 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_dynamic_sql"
+    }
+  ],
+  "reference": "text(...) / sqlalchemy.text(...) with an f-string, concatenation, .format, % formatting, or a variable is refused; SQLAlchemy bound parameters / ORM expressions are the compliant path.",
+  "opt_out": "# arch-allow-no-dynamic-sql: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored source: whether SQL text was written as a static, reviewable literal. At execution time every statement is just a string \u2014 how it was built is erased, so no runtime seam can distinguish a vetted literal from concatenated input. The adjacent runtime protections are different controls: the write guard refuses smuggled DML (mutations_emit_audit) and parameter binding is the compliant data path."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/no_empty_tests.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_empty_tests",
+  "surface": "backend",
+  "title": "Every test must assert a real outcome",
+  "intent": "A test whose body is empty, is only a docstring or a bare pass, or asserts a constant that can never fail, passes unconditionally — it exercises nothing yet reports green, giving false confidence that the behaviour it names is covered. A test must drive real behaviour and assert a real result.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_empty_tests"
+    }
+  ],
+  "reference": "A test_* function with an empty body, a lone pass, or a single assertion of a constant truthy value is refused. The scan covers every test_*.py file — the test tree the other source rules deliberately skip.",
+  "opt_out": "# arch-allow-no-empty-tests: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored test source, evaluated at build time in the test suite itself; there is no production runtime seam that observes whether a test asserts anything. Only a source-form check can see the empty body."
+  },
+  "guide_topic": "rules",
+  "corpus": true
+}

package/catalog/backend/no_eval_or_exec.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_eval_or_exec",
+  "surface": "backend",
+  "title": "Never execute a string as code",
+  "intent": "Turning a runtime string into executed code is a code-injection hole: any value an attacker can influence on its way into the evaluator becomes arbitrary code the process runs. There is no safe in-app use — parse the data into a structure, dispatch on a lookup table, or import a real module instead of evaluating text.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_eval_or_exec"
+    }
+  ],
+  "reference": "Calls to the eval() and exec() builtins are refused. The scan covers the whole importable tree — including tests and migrations — because any Python that runs is in scope.",
+  "opt_out": "# arch-allow-no-eval-or-exec: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored source: whether a dynamic-execution builtin was written. By the time the process runs, an evaluated string is indistinguishable from ordinary control flow, and no runtime seam upstream can tell a vetted call from an injected one — the only faithful check is refusing the construct in source."
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}

package/catalog/backend/no_hardcoded_credentials.json

@@ -0,0 +1,21 @@
+{
+  "id": "backend/no_hardcoded_credentials",
+  "surface": "backend",
+  "title": "App modules do not hard-code credentials or recognizable secret tokens",
+  "intent": "A credential-shaped assignment to a non-empty string literal is almost always a secret that should come from sealed config / environment wiring, not source. The rule also rejects common high-confidence secret literal formats anywhere in a module so leaked keys are caught even when assigned to a bland variable name. As a security rule this also scans test and migration files inside a module — a real secret is a leak wherever it is committed.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_hardcoded_credentials"
+    }
+  ],
+  "opt_out": "# arch-allow-no-hardcoded-credentials: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "At runtime a credential is a string wherever it came from: a source literal and an injected environment value are indistinguishable once loaded. 'It was committed to the repository' is a source-tree fact only a source scan can state."
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}

package/catalog/backend/no_internal_imports.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_internal_imports",
+  "surface": "backend",
+  "title": "Modules import only the platform's public surface, never its internal namespaces",
+  "intent": "The public surface is the platform's contract: it is documented, versioned, and stable. An internal namespace is free to move or change shape at any release, and it exposes seams (raw session plumbing, guard internals) whose direct use bypasses the framework's controls — so a module that reaches into it is coupled to undocumented internals and can silently sidestep the secure defaults.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_internal_imports"
+    }
+  ],
+  "reference": "Import from the terp.core public surface; terp.core._internal imports are refused.",
+  "opt_out": "# arch-allow-no-internal-imports: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Python has no enforced import visibility: at runtime _internal objects are ordinary attributes, reachable through the public modules that legitimately use them. The underscore contract is source-form; the runtime controls live in what _internal implements, not in refusing its import."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/no_manual_actor_stamping.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/no_manual_actor_stamping",
+  "surface": "backend",
+  "title": "Modules never set the framework-managed actor-stamp columns by hand",
+  "intent": "Who created and last modified a row is provenance, applied centrally: the audited write chokepoint fills created_by_id (on insert) and modified_by_id (on every write) from the request actor. A module that assigns those columns is forging or clobbering that trail — the actor must come from the authenticated request, never from caller-supplied data. As with the scope columns, a read DTO may still expose the column (an annotation is fine); only attribute access (set / compare) is policed.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_manual_actor_stamping"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_save"
+    }
+  ],
+  "reference": "ActorStampedMixin columns are stamped by BaseService._save (ADR 0012); assignments to created_by_id / modified_by_id in module code are refused.",
+  "opt_out": "# arch-allow-no-manual-actor-stamping: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The audited write chokepoint (_save) stamps created_by_id on insert and modified_by_id on every save from the request actor, unconditionally for a stamped model -- a hand-written stamp never survives the write, and inbound payloads have the stamp columns stripped (_without_managed_columns)."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/no_manual_ownership_checks.json

@@ -0,0 +1,32 @@
+{
+  "id": "backend/no_manual_ownership_checks",
+  "surface": "backend",
+  "title": "Modules preserve structural row ownership and never reimplement it by hand",
+  "intent": "Object-level authorization belongs to the platform's write boundary: user-owned rows retain their ownership declaration across request and background workflows, and a worker identity never becomes a blanket cross-owner authority. Application code must not compare, filter or assign the managed owner column, nor remove ownership merely to let unattended maintenance mutate every user's rows. Cross-owner maintenance requires a separately reviewed authority mechanism whose scope is explicit; ordinary background work remains subject to the same row ownership as interactive writes.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_manual_ownership_checks"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "apply_object_authz"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_validate_background_jobs_preserve_ownership"
+    }
+  ],
+  "reference": "OwnedMixin declares ownership; BaseService stamps owner_id and apply_object_authz gates writes. create_app refuses a job-bearing ModuleSpec whose declared service model omits OwnedMixin. A custom object-authz predicate can be registered.",
+  "opt_out": "# arch-allow-no-manual-ownership-checks: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Every update/delete of an owned row is authorized per-row at the write chokepoint and owner identity is stamped centrally on create. Composition also rejects job-bearing modules that bind an unowned service model, so an application cannot remove the ownership trait to grant background work blanket cross-owner authority."
+  },
+  "guide_topic": "ownership",
+  "corpus": true
+}

package/catalog/backend/no_manual_scope_filtering.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/no_manual_scope_filtering",
+  "surface": "backend",
+  "title": "Modules never touch the framework-managed scope columns",
+  "intent": "Soft-delete and tenant scoping are applied centrally: the composed base read query filters out soft-deleted rows and applies every registered row predicate (e.g. the tenant filter), and the audited delete chokepoint stamps the deletion. A module that references deleted_at / tenant_id — to filter, set, or compare — is re-implementing that scope predicate by hand, which can leak or destroy scoped rows. The composed scoped read is the only path; expose the column in a read DTO if you must surface it, but never filter or assign it in module code.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_manual_scope_filtering"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "apply_row_scope"
+    }
+  ],
+  "reference": "BaseService.base_query composes the scope (deleted_at IS NULL + registered predicates); deleted_at / tenant_id attribute access in module code is refused.",
+  "opt_out": "# arch-allow-no-manual-scope-filtering: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Row scope is applied centrally and non-droppably: apply_row_scope composes the soft-delete filter and every registered predicate into each read (including raw selects, re-scoped by the request session), the delete chokepoint stamps deleted_at, and the managed scope columns are stripped from inbound payloads."
+  },
+  "guide_topic": "tenancy",
+  "corpus": true
+}

package/catalog/backend/no_manual_table_schema.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_manual_table_schema",
+  "surface": "backend",
+  "title": "Table models never hand-write a physical schema placement (the layout is managed)",
+  "intent": "The physical schema layout is a deployment decision: under the flat layout every table lives in the default schema, and under the per-module layout the migration runtime routes each package's tables into its own database schema — in both layouts the model metadata stays schema-free. A hand-written schema placement pins one table to a fixed schema, silently escaping the managed layout (and breaking lightweight dev/test databases that parse a schema prefix differently).",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_manual_table_schema"
+    }
+  ],
+  "reference": "DB_SCHEMA_LAYOUT (flat / per-module via search_path, ADR 0070) owns placement; __table_args__ = {\"schema\": ...} is refused.",
+  "opt_out": "# arch-allow-no-manual-table-schema: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "schema= placement is materialised into DDL by the packaged migrations; by the time the app serves, tables live where the migrations put them. The managed-layout guarantee is enforced where the DDL is authored, not against an already-created schema."
+  },
+  "guide_topic": "migrations",
+  "corpus": true
+}

package/catalog/backend/no_manual_version_assignment.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_manual_version_assignment",
+  "surface": "backend",
+  "title": "The optimistic-concurrency token is never assigned by hand",
+  "intent": "Every row carries an integer concurrency token that the persistence layer increments on each update and matches against the value the caller loaded, so two writers racing on the same row cannot silently clobber each other. Writing that token by hand does not fail — it overwrites the loaded value with the caller's own, so the concurrency check ends up comparing the row against itself and a lost update slips through undetected. Application code must never assign the token; the persistence layer owns it end to end.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_manual_version_assignment"
+    }
+  ],
+  "reference": "db_obj.version = data.version, row.version += 1, and setattr(db_obj, \"version\", ...) are refused; the update seam bumps and checks the token, so application code leaves it untouched.",
+  "opt_out": "# arch-allow-no-manual-version-assignment: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The concurrency control itself is a live runtime seam — the persistence layer appends the loaded token to every update's WHERE clause and raises a conflict when zero rows match. But this rule guards the inverse breach, and that breach is not runtime-observable: a hand-written token assignment is an ordinary attribute write that succeeds, then quietly defeats the check by making the loaded and compared values identical. Nothing downstream can distinguish a caller-supplied token from a genuinely loaded one, so the only place to catch it is the authored source that performs the assignment."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/no_mutable_default_args.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_mutable_default_args",
+  "surface": "backend",
+  "title": "No mutable default argument values",
+  "intent": "A default argument value is evaluated once when the function is defined and then shared by every call that omits it, so a mutable default (a list, dict, or set) accumulates state across calls — a classic aliasing bug that leaks data between otherwise independent invocations. Default to a sentinel and build the container inside the body.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_mutable_default_args"
+    }
+  ],
+  "reference": "A list, dict, or set literal used as a parameter default (positional or keyword-only) is refused; default to None and construct the container in the body when the argument is omitted.",
+  "opt_out": "# arch-allow-no-mutable-default-args: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored signature. The shared default object is created at definition time, before any request runs, so by execution the aliasing is already baked in and no runtime seam can un-share it — the only faithful check reads the signature in source."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/no_naive_datetime.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_naive_datetime",
+  "surface": "backend",
+  "title": "Timestamps must be timezone-aware, never naive",
+  "intent": "A timestamp captured without a timezone silently assumes the process's local zone, so it cannot be stored, compared, or ordered correctly once more than one zone is involved — a classic source of off-by-hours bugs. Every timestamp the app produces must carry an explicit timezone (UTC), so the moment it names is unambiguous.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_naive_datetime"
+    }
+  ],
+  "reference": "datetime.utcnow() (deprecated, naive) and a bare datetime.now() (no tz) are refused; datetime.now(UTC) is the compliant, timezone-aware path.",
+  "opt_out": "# arch-allow-no-naive-datetime: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored source: which constructor was written. At execution time a naive and an aware timestamp are both just datetime values, and a naive one has already lost its zone at the point it was built — no runtime seam upstream of that call can reconstruct the intended zone or distinguish a vetted aware call from a naive one. The compliant path is the explicit-zone constructor itself."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/no_oversized_python_files.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_oversized_python_files",
+  "surface": "backend",
+  "title": "No source file grows past the line-count cap",
+  "intent": "A file that keeps growing stops being reviewable: it hides more than one responsibility, is harder to reason about in one sitting, and is exactly what an automated author tends to produce when it appends to an existing file instead of factoring the work into a new one. Capping the line count of every hand-authored source file forces the cohesive-file discipline the rest of the layout assumes — a responsibility that outgrows its file is split into its own file, not piled onto the current one. Generated and machine-owned trees (dependency caches, database migration history, the test suite) are out of scope: their size is not an authoring decision the cap should second-guess.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_oversized_python_files"
+    }
+  ],
+  "reference": "Every scanned *.py file must stay at or under 500 physical lines; generated/vendored caches, the migration history and the test tree are excluded from the scan. Split a file that grows past the cap into smaller, cohesive modules (extract helpers or sub-services into their own files).",
+  "opt_out": "# arch-allow-no-oversized-python-files: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored source tree — how many physical lines a file has. By the time the app runs, each module has been imported as a code object that carries no memory of its file's length, so no runtime seam can observe or enforce the cap. The build-time line count is the only faithful control."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/no_print.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_print",
+  "surface": "backend",
+  "title": "Emit diagnostics through the logger, never a bare print",
+  "intent": "Printing straight to standard output bypasses log levels, structure, and routing, so the message escapes the platform's logging pipeline and cannot be filtered, correlated, or shipped to a sink. Every diagnostic must go through the structured logger so it carries a level and is captured.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_print"
+    }
+  ],
+  "reference": "A call to the print() builtin is refused; obtain a logger and call it at the appropriate level.",
+  "opt_out": "# arch-allow-no-print: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant is a property of the authored call: which output function was written. Once the app runs, a print and a log call are both just function invocations, and the output has already left the structured pipeline — no runtime seam can retro-route it, so the only faithful check reads the source."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/no_raw_app_routes.json

@@ -0,0 +1,26 @@
+{
+  "id": "backend/no_raw_app_routes",
+  "surface": "backend",
+  "title": "App code never registers HTTP surface on the composed app object",
+  "intent": "Composition mounts every module router behind the deny-by-default policy guard. Surface registered on the composed app itself — a mount, an included router, a directly added route, a verb decorator on the composed app, or a lifecycle hook — is served or executed WITHOUT that guard and is invisible to the module permission model. Modules declare one flat router in their manifest; composition mounts it.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_raw_app_routes"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_freeze_app_route_registration"
+    }
+  ],
+  "reference": "app.mount / app.include_router / app.add_route / verb decorators / app.on_event / app.add_event_handler on the create_app-produced app are refused; modules declare one router on their ModuleSpec.",
+  "opt_out": "# arch-allow-no-raw-app-routes: <reason>",
+  "runtime": {
+    "applicability": "required"
+  },
+  "guide_topic": "capability",
+  "corpus": true
+}

package/catalog/backend/no_raw_connection_access.json

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

package/catalog/backend/no_raw_file_references.json

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