@terpjs/spec 0.14.0 → 0.16.0

package/catalog/backend/no_internal_imports.json

@@ -1,22 +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
-}
+{
+  "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

@@ -1,27 +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
-}
+{
+  "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

@@ -1,32 +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
-}
+{
+  "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

@@ -1,27 +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
-}
+{
+  "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

@@ -1,22 +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
-}
+{
+  "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

@@ -1,22 +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
-}
+{
+  "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

@@ -1,22 +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
-}
+{
+  "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

@@ -1,22 +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
-}
+{
+  "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

@@ -1,22 +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
-}
+{
+  "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

@@ -1,22 +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
-}
+{
+  "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

@@ -1,26 +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
-}
+{
+  "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
+}