@terpjs/spec 0.14.0 → 0.15.0

package/VERSION

@@ -1 +1 @@
-0.14.0
+0.15.0

package/app-check-report.schema.json

@@ -1,122 +1,122 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://terp.dev/spec/app-check-report.schema.json",
-  "title": "Terp Standard application check report",
-  "description": "The complete, self-describing result of ONE checker invocation over ONE application tree. Findings alone cannot support per-rule verdicts: a rule with zero findings is only passing if the run actually evaluated it, and a consumer must never supply that knowledge itself — its own catalog copy can be newer or older than the checked app's pinned toolchain. So the report carries its own evaluated-rule inventory, the spec version its rule ids resolve against, and the checker's identity: everything a driving tool needs to join verdicts to the catalog fail-closed. A rule absent from `rules` and `not_applicable` was not evaluated and can never render as passing. A multi-surface toolchain emits one report per checker run; a consumer merges reports through their inventories.",
-  "type": "object",
-  "required": ["terp_check_report", "spec_version", "checker", "ok", "rules", "findings"],
-  "additionalProperties": false,
-  "properties": {
-    "terp_check_report": {
-      "type": "integer",
-      "enum": [1],
-      "description": "Format marker and major version of this envelope. A consumer refuses an unknown marker value rather than guessing the shape."
-    },
-    "spec_version": {
-      "type": "string",
-      "description": "The spec semver (VERSION) whose catalog the rule ids in this report resolve against — the checked app's own pinned standard, which may differ from any consumer-side catalog copy.",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$"
-    },
-    "checker": {
-      "type": "object",
-      "description": "The checker's identity: tool name and its own version — the same identity the checker's certification scorecard (scorecard.schema.json) carries, so a consumer can tie a report to a verifiable certification claim.",
-      "required": ["tool", "version"],
-      "additionalProperties": false,
-      "properties": {
-        "tool": { "type": "string", "minLength": 1 },
-        "version": { "type": "string", "minLength": 1 }
-      }
-    },
-    "ok": {
-      "type": "boolean",
-      "description": "The run's overall verdict: true only when the checker completed and attributed no findings. Overall only — per-rule verdicts are always derived from `rules` + `findings`, never from this flag."
-    },
-    "error": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Present when the run failed to complete (a crash, a timeout, an unreadable tree): what went wrong, for humans. An erroring report is never ok, and it must not claim rules it did not fully evaluate — fail visible, never a silent pass."
-    },
-    "rules": {
-      "type": "array",
-      "description": "The evaluated-rule inventory: every catalog rule id this run actually held the tree to. Zero findings for a listed rule means pass; an unlisted rule has NO verdict from this run (a consumer renders it unknown, never green). A finding's rule is normally listed here; a consumer treats an attributed finding as a failure regardless.",
-      "items": {
-        "type": "string",
-        "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
-      }
-    },
-    "not_applicable": {
-      "type": "array",
-      "description": "Opt-in rules the checked tree has not enabled (for example a slot-typed layout contract without its checked-in configuration): published as their own state so a consumer renders them as not applicable — never as passing, never as unknown.",
-      "items": {
-        "type": "string",
-        "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
-      }
-    },
-    "findings": {
-      "type": "array",
-      "description": "The findings this run attributed to catalog rule ids. Each item is exactly the finding format's shape (findings.schema.json items — the spec suite holds the two identical), so a findings consumer and a report consumer read one shape.",
-      "items": {
-        "type": "object",
-        "required": ["rule", "path"],
-        "additionalProperties": false,
-        "properties": {
-          "rule": {
-            "type": "string",
-            "description": "The Terp Standard catalog id the finding realises (catalog/<surface>/<rule>.json).",
-            "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
-          },
-          "path": {
-            "type": "string",
-            "description": "File path relative to the checked tree's root (the corpus case root, or the app root), with forward slashes."
-          },
-          "line": {
-            "type": "integer",
-            "description": "1-based line of the violation, when the checker can locate it.",
-            "minimum": 1
-          },
-          "message": {
-            "type": "string",
-            "description": "Human-readable explanation; ideally directive (states the compliant fix)."
-          },
-          "fix_hint": {
-            "type": "string",
-            "description": "Agent-oriented remediation metadata: the compliant construct that replaces the violating one, sourced from the catalog entry's non-normative `reference` field (or the checker's own knowledge of the sanctioned pattern). Optional — a consumer must not require it."
-          },
-          "fingerprint": {
-            "type": "string",
-            "description": "A stable, checker-chosen identifier for THIS violation instance (e.g. a hash over rule + path + violating source construct), so consumers can track a finding across line-shifting edits. Optional; the fingerprint scheme is checker-internal — only stability across reformatting is expected."
-          }
-        }
-      }
-    },
-    "unattributed": {
-      "type": "array",
-      "description": "Messages the run produced OUTSIDE the standard's rules (another configured tool's diagnostics sharing the run, a parse error): surfaced, never dropped — and never attributable to a catalog id, which the finding format's rule pattern refuses by construction.",
-      "items": {
-        "type": "object",
-        "required": ["path", "message"],
-        "additionalProperties": false,
-        "properties": {
-          "path": {
-            "type": "string",
-            "description": "File path relative to the checked tree's root, with forward slashes."
-          },
-          "line": {
-            "type": "integer",
-            "description": "1-based line of the message, when the producer located one.",
-            "minimum": 1
-          },
-          "message": {
-            "type": "string",
-            "description": "The diagnostic text, verbatim."
-          },
-          "reported_as": {
-            "type": "string",
-            "minLength": 1,
-            "description": "The tool-internal rule id the message surfaced as, when one exists — omitted (never null) otherwise."
-          }
-        }
-      }
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terp.dev/spec/app-check-report.schema.json",
+  "title": "Terp Standard application check report",
+  "description": "The complete, self-describing result of ONE checker invocation over ONE application tree. Findings alone cannot support per-rule verdicts: a rule with zero findings is only passing if the run actually evaluated it, and a consumer must never supply that knowledge itself — its own catalog copy can be newer or older than the checked app's pinned toolchain. So the report carries its own evaluated-rule inventory, the spec version its rule ids resolve against, and the checker's identity: everything a driving tool needs to join verdicts to the catalog fail-closed. A rule absent from `rules` and `not_applicable` was not evaluated and can never render as passing. A multi-surface toolchain emits one report per checker run; a consumer merges reports through their inventories.",
+  "type": "object",
+  "required": ["terp_check_report", "spec_version", "checker", "ok", "rules", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "terp_check_report": {
+      "type": "integer",
+      "enum": [1],
+      "description": "Format marker and major version of this envelope. A consumer refuses an unknown marker value rather than guessing the shape."
+    },
+    "spec_version": {
+      "type": "string",
+      "description": "The spec semver (VERSION) whose catalog the rule ids in this report resolve against — the checked app's own pinned standard, which may differ from any consumer-side catalog copy.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "checker": {
+      "type": "object",
+      "description": "The checker's identity: tool name and its own version — the same identity the checker's certification scorecard (scorecard.schema.json) carries, so a consumer can tie a report to a verifiable certification claim.",
+      "required": ["tool", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "tool": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "ok": {
+      "type": "boolean",
+      "description": "The run's overall verdict: true only when the checker completed and attributed no findings. Overall only — per-rule verdicts are always derived from `rules` + `findings`, never from this flag."
+    },
+    "error": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Present when the run failed to complete (a crash, a timeout, an unreadable tree): what went wrong, for humans. An erroring report is never ok, and it must not claim rules it did not fully evaluate — fail visible, never a silent pass."
+    },
+    "rules": {
+      "type": "array",
+      "description": "The evaluated-rule inventory: every catalog rule id this run actually held the tree to. Zero findings for a listed rule means pass; an unlisted rule has NO verdict from this run (a consumer renders it unknown, never green). A finding's rule is normally listed here; a consumer treats an attributed finding as a failure regardless.",
+      "items": {
+        "type": "string",
+        "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
+      }
+    },
+    "not_applicable": {
+      "type": "array",
+      "description": "Opt-in rules the checked tree has not enabled (for example a slot-typed layout contract without its checked-in configuration): published as their own state so a consumer renders them as not applicable — never as passing, never as unknown.",
+      "items": {
+        "type": "string",
+        "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
+      }
+    },
+    "findings": {
+      "type": "array",
+      "description": "The findings this run attributed to catalog rule ids. Each item is exactly the finding format's shape (findings.schema.json items — the spec suite holds the two identical), so a findings consumer and a report consumer read one shape.",
+      "items": {
+        "type": "object",
+        "required": ["rule", "path"],
+        "additionalProperties": false,
+        "properties": {
+          "rule": {
+            "type": "string",
+            "description": "The Terp Standard catalog id the finding realises (catalog/<surface>/<rule>.json).",
+            "pattern": "^(backend/[a-z0-9_]+|frontend/[a-z0-9-]+)$"
+          },
+          "path": {
+            "type": "string",
+            "description": "File path relative to the checked tree's root (the corpus case root, or the app root), with forward slashes."
+          },
+          "line": {
+            "type": "integer",
+            "description": "1-based line of the violation, when the checker can locate it.",
+            "minimum": 1
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable explanation; ideally directive (states the compliant fix)."
+          },
+          "fix_hint": {
+            "type": "string",
+            "description": "Agent-oriented remediation metadata: the compliant construct that replaces the violating one, sourced from the catalog entry's non-normative `reference` field (or the checker's own knowledge of the sanctioned pattern). Optional — a consumer must not require it."
+          },
+          "fingerprint": {
+            "type": "string",
+            "description": "A stable, checker-chosen identifier for THIS violation instance (e.g. a hash over rule + path + violating source construct), so consumers can track a finding across line-shifting edits. Optional; the fingerprint scheme is checker-internal — only stability across reformatting is expected."
+          }
+        }
+      }
+    },
+    "unattributed": {
+      "type": "array",
+      "description": "Messages the run produced OUTSIDE the standard's rules (another configured tool's diagnostics sharing the run, a parse error): surfaced, never dropped — and never attributable to a catalog id, which the finding format's rule pattern refuses by construction.",
+      "items": {
+        "type": "object",
+        "required": ["path", "message"],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "File path relative to the checked tree's root, with forward slashes."
+          },
+          "line": {
+            "type": "integer",
+            "description": "1-based line of the message, when the producer located one.",
+            "minimum": 1
+          },
+          "message": {
+            "type": "string",
+            "description": "The diagnostic text, verbatim."
+          },
+          "reported_as": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The tool-internal rule id the message surfaced as, when one exists — omitted (never null) otherwise."
+          }
+        }
+      }
+    }
+  }
+}

package/assurance-profile.schema.json

@@ -1,70 +1,70 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://terp.dev/spec/assurance-profile.schema.json",
-  "title": "Terp assurance profile",
-  "description": "The machine-readable release-assurance claim a Terp toolchain emits after running its release verification profile: one document composing the named evidence lanes of the standard. The lane vocabulary and each lane's requirement level are normative and fixed by the spec (see the README's assurance-profile section): terp-standard, appsec-baseline and dependency-audit are REQUIRED - the claim ('ok') is true only when every required lane passed; a11y and blackbox-conformance are RECOMMENDED - they inform the reader but never carry the claim. Requirement levels are deliberately NOT a field of the document: an emitter cannot demote a required lane, and a consumer joins the document to the spec (via spec_version) for the canonical mapping. Every lane of the vocabulary must appear exactly once - omitting a lane would hide it. A lane's verdict is composed from the named verification checks ('checks', the check ids of the toolchain's release profile); a lane the toolchain does not realise yet is reported 'not-run' with no checks, never silently dropped and never counted as passed.",
-  "type": "object",
-  "required": ["terp_assurance", "spec_version", "toolchain", "profile", "ok", "lanes"],
-  "additionalProperties": false,
-  "properties": {
-    "terp_assurance": {
-      "description": "The assurance-profile document format version.",
-      "enum": [1]
-    },
-    "spec_version": {
-      "type": "string",
-      "description": "The spec semver (VERSION) whose lane vocabulary and requirement mapping this document claims against.",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$"
-    },
-    "toolchain": {
-      "type": "object",
-      "description": "The emitting toolchain's identity: tool name and its own version.",
-      "required": ["tool", "version"],
-      "additionalProperties": false,
-      "properties": {
-        "tool": { "type": "string", "minLength": 1 },
-        "version": { "type": "string", "minLength": 1 }
-      }
-    },
-    "profile": {
-      "type": "string",
-      "description": "The verification profile the toolchain realised the lanes from (the reference toolchain: 'release').",
-      "minLength": 1
-    },
-    "ok": {
-      "type": "boolean",
-      "description": "The claim: true exactly when every REQUIRED lane has status 'passed'. Recommended lanes never affect it."
-    },
-    "lanes": {
-      "type": "array",
-      "description": "One entry per lane of the spec's vocabulary, each exactly once.",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "required": ["id", "status", "checks"],
-        "additionalProperties": false,
-        "properties": {
-          "id": {
-            "description": "The lane, from the spec's fixed vocabulary.",
-            "enum": [
-              "terp-standard",
-              "appsec-baseline",
-              "dependency-audit",
-              "a11y",
-              "blackbox-conformance"
-            ]
-          },
-          "status": {
-            "description": "'passed' (every composing check green), 'failed' (any composing check red), or 'not-run' (the toolchain does not realise the lane, or its precondition was unmet). 'not-run' is never a pass.",
-            "enum": ["passed", "failed", "not-run"]
-          },
-          "checks": {
-            "type": "array",
-            "description": "The verification-check ids whose verdicts compose this lane (evidence pointers into the toolchain's verification envelope). Non-empty for 'passed'/'failed'; empty for 'not-run' - a verdict without evidence is not a verdict.",
-            "items": { "type": "string", "minLength": 1 }
-          }
-        }
-      }
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://terp.dev/spec/assurance-profile.schema.json",
+  "title": "Terp assurance profile",
+  "description": "The machine-readable release-assurance claim a Terp toolchain emits after running its release verification profile: one document composing the named evidence lanes of the standard. The lane vocabulary and each lane's requirement level are normative and fixed by the spec (see the README's assurance-profile section): terp-standard, appsec-baseline and dependency-audit are REQUIRED - the claim ('ok') is true only when every required lane passed; a11y and blackbox-conformance are RECOMMENDED - they inform the reader but never carry the claim. Requirement levels are deliberately NOT a field of the document: an emitter cannot demote a required lane, and a consumer joins the document to the spec (via spec_version) for the canonical mapping. Every lane of the vocabulary must appear exactly once - omitting a lane would hide it. A lane's verdict is composed from the named verification checks ('checks', the check ids of the toolchain's release profile); a lane the toolchain does not realise yet is reported 'not-run' with no checks, never silently dropped and never counted as passed.",
+  "type": "object",
+  "required": ["terp_assurance", "spec_version", "toolchain", "profile", "ok", "lanes"],
+  "additionalProperties": false,
+  "properties": {
+    "terp_assurance": {
+      "description": "The assurance-profile document format version.",
+      "enum": [1]
+    },
+    "spec_version": {
+      "type": "string",
+      "description": "The spec semver (VERSION) whose lane vocabulary and requirement mapping this document claims against.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "toolchain": {
+      "type": "object",
+      "description": "The emitting toolchain's identity: tool name and its own version.",
+      "required": ["tool", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "tool": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "profile": {
+      "type": "string",
+      "description": "The verification profile the toolchain realised the lanes from (the reference toolchain: 'release').",
+      "minLength": 1
+    },
+    "ok": {
+      "type": "boolean",
+      "description": "The claim: true exactly when every REQUIRED lane has status 'passed'. Recommended lanes never affect it."
+    },
+    "lanes": {
+      "type": "array",
+      "description": "One entry per lane of the spec's vocabulary, each exactly once.",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "status", "checks"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "description": "The lane, from the spec's fixed vocabulary.",
+            "enum": [
+              "terp-standard",
+              "appsec-baseline",
+              "dependency-audit",
+              "a11y",
+              "blackbox-conformance"
+            ]
+          },
+          "status": {
+            "description": "'passed' (every composing check green), 'failed' (any composing check red), or 'not-run' (the toolchain does not realise the lane, or its precondition was unmet). 'not-run' is never a pass.",
+            "enum": ["passed", "failed", "not-run"]
+          },
+          "checks": {
+            "type": "array",
+            "description": "The verification-check ids whose verdicts compose this lane (evidence pointers into the toolchain's verification envelope). Non-empty for 'passed'/'failed'; empty for 'not-run' - a verdict without evidence is not a verdict.",
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  }
+}

package/catalog/backend/alembic_downgrades_not_empty.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/alembic_downgrades_not_empty",
-  "surface": "backend",
-  "title": "A migration's downgrade must reverse the change, not be an empty stub",
-  "intent": "A migration that leaves its downgrade step empty (a bare no-op with no operations) cannot be rolled back: reversing the revision silently leaves the schema mismatched instead of restoring the previous state. Each migration's downgrade must either perform the reverse operations or, for a deliberately irreversible step, carry a comment explaining why the no-op is intentional.",
-  "layer": "static-portable",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_alembic_downgrades_not_empty"
-    }
-  ],
-  "reference": "In each revision file under migrations/versions, a downgrade function whose body (after any docstring) is a lone pass / ellipsis or is empty, with no explanatory comment, is flagged; a reverse operation or an in-body '#' comment clears it.",
-  "opt_out": "# arch-allow-alembic-downgrades-not-empty: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "An empty downgrade is a property of the authored revision file; a forward deploy never executes downgrade, so the emptiness is invisible at runtime until a rollback is attempted, and the reversibility guarantee exists only in source."
-  },
-  "guide_topic": "migrations",
-  "corpus": true
-}
+{
+  "id": "backend/alembic_downgrades_not_empty",
+  "surface": "backend",
+  "title": "A migration's downgrade must reverse the change, not be an empty stub",
+  "intent": "A migration that leaves its downgrade step empty (a bare no-op with no operations) cannot be rolled back: reversing the revision silently leaves the schema mismatched instead of restoring the previous state. Each migration's downgrade must either perform the reverse operations or, for a deliberately irreversible step, carry a comment explaining why the no-op is intentional.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_alembic_downgrades_not_empty"
+    }
+  ],
+  "reference": "In each revision file under migrations/versions, a downgrade function whose body (after any docstring) is a lone pass / ellipsis or is empty, with no explanatory comment, is flagged; a reverse operation or an in-body '#' comment clears it.",
+  "opt_out": "# arch-allow-alembic-downgrades-not-empty: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "An empty downgrade is a property of the authored revision file; a forward deploy never executes downgrade, so the emptiness is invisible at runtime until a rollback is attempted, and the reversibility guarantee exists only in source."
+  },
+  "guide_topic": "migrations",
+  "corpus": true
+}

package/catalog/backend/base_query_not_overridden.json

@@ -1,27 +1,27 @@
-{
-  "id": "backend/base_query_not_overridden",
-  "surface": "backend",
-  "title": "A service never overrides the scoped base read query — read filters compose through the declared filter seam",
-  "intent": "The base read query composes the non-droppable row scope (soft-delete plus every registered capability predicate, e.g. tenancy) with the service's declared business filters. Overriding that composition point — the old, footgun-y seam — can silently drop soft-delete or tenant scoping the moment the override forgets to delegate up the chain, leaking soft-deleted or cross-tenant rows. Add static read conditions through the declared filter seam (it returns conditions, not a query, so scope cannot be dropped); a per-call filter belongs in a bespoke read built on the scoped base query.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_base_query_not_overridden"
-    },
-    {
-      "kind": "runtime",
-      "tool": "terp.core",
-      "ref": "apply_row_scope"
-    }
-  ],
-  "reference": "BaseService.base_query composes the scope; add filters via business_filters(), or build bespoke reads on base_query().where(...) (ADR 0017).",
-  "opt_out": "# arch-allow-base-query-not-overridden: <reason>",
-  "runtime": {
-    "applicability": "required",
-    "rationale": "The request session re-scopes every user-facing ORM read idempotently (apply_row_scope in the write-guarded session), so even a query built by an override that dropped super().base_query() is filtered again before execution."
-  },
-  "guide_topic": "service",
-  "corpus": true
-}
+{
+  "id": "backend/base_query_not_overridden",
+  "surface": "backend",
+  "title": "A service never overrides the scoped base read query — read filters compose through the declared filter seam",
+  "intent": "The base read query composes the non-droppable row scope (soft-delete plus every registered capability predicate, e.g. tenancy) with the service's declared business filters. Overriding that composition point — the old, footgun-y seam — can silently drop soft-delete or tenant scoping the moment the override forgets to delegate up the chain, leaking soft-deleted or cross-tenant rows. Add static read conditions through the declared filter seam (it returns conditions, not a query, so scope cannot be dropped); a per-call filter belongs in a bespoke read built on the scoped base query.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_base_query_not_overridden"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "apply_row_scope"
+    }
+  ],
+  "reference": "BaseService.base_query composes the scope; add filters via business_filters(), or build bespoke reads on base_query().where(...) (ADR 0017).",
+  "opt_out": "# arch-allow-base-query-not-overridden: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The request session re-scopes every user-facing ORM read idempotently (apply_row_scope in the write-guarded session), so even a query built by an override that dropped super().base_query() is filtered again before execution."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/canonical_module_shape.json

@@ -1,22 +1,22 @@
-{
-  "id": "backend/canonical_module_shape",
-  "surface": "backend",
-  "title": "Every wired module directory carries the canonical parts: models, schemas, service, router, manifest",
-  "intent": "Terp modules are uniform on purpose: the table lives in models, the DTOs in schemas, the logic in service, the routes in router, and the manifest declares the module — so the shape is predictable to discover and the other rules (response models, input caps, audited writes, the declared policy) have the surface they scan. A directory is treated as a module once it ships a manifest or a mounted router; it must then carry all of the canonical parts, and the rule names each missing one. Requiring the manifest is deliberate: a directory that ships a router with no manifest would otherwise be invisible to this rule and to modules_declare_policy (which only scans manifests), so it could mount a router with no declared policy unnoticed. A directory with neither signal (a partial or a shared-asset / helper directory) is left alone.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_canonical_module_shape"
-    }
-  ],
-  "reference": "modules/<name>/ carries models.py, schemas.py, service.py, router.py and module.py (the ModuleSpec manifest).",
-  "opt_out": "# arch-allow-canonical-module-shape: <reason>",
-  "runtime": {
-    "applicability": "not-applicable",
-    "rationale": "Repository-layout governance: the module directory's file shape exists only in the source tree. Composition consumes the ModuleSpec object, which carries no memory of which files declared it, so no runtime seam can observe the layout."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/canonical_module_shape",
+  "surface": "backend",
+  "title": "Every wired module directory carries the canonical parts: models, schemas, service, router, manifest",
+  "intent": "Terp modules are uniform on purpose: the table lives in models, the DTOs in schemas, the logic in service, the routes in router, and the manifest declares the module — so the shape is predictable to discover and the other rules (response models, input caps, audited writes, the declared policy) have the surface they scan. A directory is treated as a module once it ships a manifest or a mounted router; it must then carry all of the canonical parts, and the rule names each missing one. Requiring the manifest is deliberate: a directory that ships a router with no manifest would otherwise be invisible to this rule and to modules_declare_policy (which only scans manifests), so it could mount a router with no declared policy unnoticed. A directory with neither signal (a partial or a shared-asset / helper directory) is left alone.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_canonical_module_shape"
+    }
+  ],
+  "reference": "modules/<name>/ carries models.py, schemas.py, service.py, router.py and module.py (the ModuleSpec manifest).",
+  "opt_out": "# arch-allow-canonical-module-shape: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Repository-layout governance: the module directory's file shape exists only in the source tree. Composition consumes the ModuleSpec object, which carries no memory of which files declared it, so no runtime seam can observe the layout."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

package/catalog/backend/datetime_columns_are_timezone_aware.json

@@ -1,23 +1,23 @@
-{
-  "id": "backend/datetime_columns_are_timezone_aware",
-  "surface": "backend",
-  "title": "Stored timestamp columns must keep their timezone",
-  "intent": "A timestamp column declared without an explicit timezone maps to a naive database type, which discards the zone of even a correctly-built aware value on the way in — so the moment the row records is ambiguous, and ordering or comparison across zones is silently wrong on read. This is the storage half of the hole whose in-memory half the naive-timestamp rule closes: capturing an aware value is worth nothing if the column cannot keep it. Every persisted timestamp column must declare timezone-aware storage.",
-  "layer": "static-bespoke",
-  "enforcement": [
-    {
-      "kind": "build-time",
-      "tool": "terp.arch",
-      "ref": "check_datetime_columns_are_timezone_aware"
-    }
-  ],
-  "reference": "On a table model, a datetime (or datetime | None) field is refused unless its declaration pins a timezone-aware column type — Field(sa_type=DateTime(timezone=True)) or Field(sa_column=Column(DateTime(timezone=True), ...)); the TIMESTAMP spelling and a qualified name (sa.DateTime) count equally. A bare annotation, a Field() that never names the column type, and an explicit timezone=False are all naive storage. Fields a table inherits from a mixin declared in the same file are in scope, since the column lands on the table either way. Classes no table inherits (DTOs, unrelated payloads) declare no columns and are out of scope.",
-  "opt_out": "# arch-allow-datetime-columns-are-timezone-aware: <reason>",
-  "runtime": {
-    "applicability": "deferred",
-    "rationale": "Unlike the in-memory naive-timestamp rule — where the zone is already lost at the point the value is built, so no seam downstream can recover it — this invariant survives into the running system: the mapped column type is inspectable on the ORM metadata the framework already collects at boot, and a naive timestamp column is decidable there without ambiguity. A fail-closed boot check over the collected table metadata would therefore add independent fidelity, catching a column whose naive type arrives from a path the source scan cannot follow: a dynamically built column, a mixin imported from another package, or a table contributed by an installed capability. The framework owns that seam (its create_app boot validations) but has not yet shipped this control.",
-    "tracking": "terp-framework reference implementation: the create_app boot-validation seam in terp.core.app (alongside the existing _validate_* boot checks) — to walk the collected table metadata and refuse a timestamp column whose mapped type is not timezone-aware."
-  },
-  "guide_topic": "module",
-  "corpus": true
-}
+{
+  "id": "backend/datetime_columns_are_timezone_aware",
+  "surface": "backend",
+  "title": "Stored timestamp columns must keep their timezone",
+  "intent": "A timestamp column declared without an explicit timezone maps to a naive database type, which discards the zone of even a correctly-built aware value on the way in — so the moment the row records is ambiguous, and ordering or comparison across zones is silently wrong on read. This is the storage half of the hole whose in-memory half the naive-timestamp rule closes: capturing an aware value is worth nothing if the column cannot keep it. Every persisted timestamp column must declare timezone-aware storage.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_datetime_columns_are_timezone_aware"
+    }
+  ],
+  "reference": "On a table model, a datetime (or datetime | None) field is refused unless its declaration pins a timezone-aware column type — Field(sa_type=DateTime(timezone=True)) or Field(sa_column=Column(DateTime(timezone=True), ...)); the TIMESTAMP spelling and a qualified name (sa.DateTime) count equally. A bare annotation, a Field() that never names the column type, and an explicit timezone=False are all naive storage. Fields a table inherits from a mixin declared in the same file are in scope, since the column lands on the table either way. Classes no table inherits (DTOs, unrelated payloads) declare no columns and are out of scope.",
+  "opt_out": "# arch-allow-datetime-columns-are-timezone-aware: <reason>",
+  "runtime": {
+    "applicability": "deferred",
+    "rationale": "Unlike the in-memory naive-timestamp rule — where the zone is already lost at the point the value is built, so no seam downstream can recover it — this invariant survives into the running system: the mapped column type is inspectable on the ORM metadata the framework already collects at boot, and a naive timestamp column is decidable there without ambiguity. A fail-closed boot check over the collected table metadata would therefore add independent fidelity, catching a column whose naive type arrives from a path the source scan cannot follow: a dynamically built column, a mixin imported from another package, or a table contributed by an installed capability. The framework owns that seam (its create_app boot validations) but has not yet shipped this control.",
+    "tracking": "terp-framework reference implementation: the create_app boot-validation seam in terp.core.app (alongside the existing _validate_* boot checks) — to walk the collected table metadata and refuse a timestamp column whose mapped type is not timezone-aware."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}