@terpjs/spec 0.18.0 → 0.20.0

package/VERSION

@@ -1 +1 @@
-0.18.0
+0.20.0

package/catalog/backend/cross_module_imports_use_public_surface.json

@@ -0,0 +1,21 @@
+{
+  "id": "backend/cross_module_imports_use_public_surface",
+  "surface": "backend",
+  "title": "A declared module edge grants models / schemas / service / events only",
+  "intent": "A declared dependency buys the other module's domain vocabulary, not its delivery surface. Importing another module's router couples the two through HTTP shapes and lets an in-process call walk past the authorization policy that guards those routes; importing an underscore-prefixed submodule takes a dependency on something its owner never published; importing the bare package depends on whatever that package happens to re-export. The edge is therefore bounded to the published surface, so the dependency stays a contract rather than a keyhole into the other module's implementation.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_cross_module_imports_use_public_surface"
+    }
+  ],
+  "opt_out": "# arch-allow-cross-module-imports-use-public-surface: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Which submodule an import names is a source-form property. Once composed, every module's objects are ordinary in-process references and the distinction between a published surface and an internal one no longer exists."
+  },
+  "guide_topic": "dependencies",
+  "corpus": true
+}

package/catalog/backend/emitted_events_are_declared.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/emitted_events_are_declared",
+  "surface": "backend",
+  "title": "A module emits only the events its manifest declares",
+  "intent": "The manifest's emits list is the module's published contract: it is what the control plane validates, what an operator reads to know what a module produces, and what another team subscribes against. An emit the manifest never declared makes that contract quietly untrue — the event really does go out, so nothing fails, while the document everyone reasons from says it cannot happen. The rule compares every event constant an emit call or lifecycle event map names inside a module package against that module's declared emits.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_emitted_events_are_declared"
+    }
+  ],
+  "reference": "ModuleSpec(emits=[...]) in modules/<name>/module.py, compared against emit(event=...) and LifecycleEventMap(created=/updated=/deleted=...) references in the same module package.",
+  "opt_out": "# arch-allow-emitted-events-are-declared: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "emit() carries no module identity at the call site, so the running system cannot attribute an emit to the manifest that should have declared it; the association exists only in the source layout (which module package the call lives in). Adding a module handle to emit() to make it runtime-checkable would put the answer in the caller's hands, which is exactly what the rule is verifying."
+  },
+  "guide_topic": "events",
+  "corpus": true
+}

package/catalog/backend/module_dependency_graph_is_acyclic.json

@@ -0,0 +1,26 @@
+{
+  "id": "backend/module_dependency_graph_is_acyclic",
+  "surface": "backend",
+  "title": "Declared module dependency edges form a DAG",
+  "intent": "A cycle is the point at which two 'independent' modules have quietly become one: neither can be read, tested, deployed or removed without the other, and the direction that would say which owns the shared concept no longer exists. Refusing the cycle rather than the coupling keeps the available fixes the real ones — extract the shared concept into a module both depend on, or invert the weaker direction into an event subscription.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_module_dependency_graph_is_acyclic"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_validate_requires"
+    }
+  ],
+  "opt_out": "# arch-allow-module-dependency-graph-is-acyclic: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The composition root receives every ModuleSpec, so the declared graph is fully observable at boot. create_app validates it and raises BootError on a cycle, fail closed — the build-time check is the earlier, better-located half of the same control, not its only one."
+  },
+  "guide_topic": "dependencies",
+  "corpus": true
+}

package/catalog/backend/no_cross_module_imports.json

@@ -1,8 +1,8 @@
 {
   "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.",
+  "title": "A module imports a sibling only across an edge it declared",
+  "intent": "Modules are independent by default; a real dependency is DECLARED, never implicit. The depending module names the sibling as a dependency edge in its own manifest, which puts the coupling where a reader already looks; an undeclared sibling import is refused. 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. The declaration is read from source, so one a static reader cannot resolve grants nothing (fail closed).",
   "layer": "static-portable",
   "enforcement": [
     {
@@ -14,8 +14,8 @@
   "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."
+    "rationale": "Whether an edge was declared 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",
+  "guide_topic": "dependencies",
   "corpus": true
 }

package/catalog/backend/table_ownership_is_not_split.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/table_ownership_is_not_split",
+  "surface": "backend",
+  "title": "The package whose models own a table is the package whose history creates it",
+  "intent": "Moving a model between packages splits table ownership from history ownership, and nothing visible happens: the losing package no longer owns the table so its scoped autogenerate cannot propose a drop, and the gaining package diffs against a database where the table already exists so it proposes no create. No DDL is emitted, every existing database keeps upgrading, and the build stays green. The damage lands later: the next ordinary schema change to that model is authored into the gaining package's independent history, which — absent a foreign key between the two packages — a fresh install may run before the history that creates the table, failing with 'no such table'. Only fresh installs break (a new environment, a new developer, a restore, a disaster-recovery rebuild), months after the causing commit, and the blame falls on an innocent add_column. A table is therefore created by exactly the package whose models declare it; moving a table between packages uses expand/contract (new table, copy the rows, retire the old one in a later release under a reviewed destructive-migration marker).",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_table_ownership_is_not_split"
+    },
+    {
+      "kind": "build-time",
+      "tool": "terp.migrations",
+      "ref": "assert_no_split_table_ownership"
+    }
+  ],
+  "reference": "For each migration tree, the tables its models own (the mapped classes under its import path) are compared against the tables that other trees' revision files literally create with create_table('<name>') inside upgrade(). A table owned by one package and created by another is a violation. A table owned but created by no package is not (that is the normal state before `terp migrate make` authors the revision), and neither is a table created under one name and later renamed (no literal create under the current name), so the check only fires on an exact, statically provable foreign creator. Enforced at authoring time (terp migrate make) and in the build-time drift guard (assert_migrations_match_models). The opt-out lives in the owning package's models module, for a move that has already shipped and whose expand/contract is planned for a later release.",
+  "opt_out": "# arch-allow-table-ownership-is-not-split: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The invariant relates the source tree's model ownership to its authored revision files; both inputs exist only in source. At apply time the split is unobservable — an already-provisioned database upgrades cleanly, which is precisely why the failure escapes to fresh installs. The complementary runtime controls (assert_migrations_current, assert_no_orphaned_revisions) enforce different invariants about a live database."
+  },
+  "guide_topic": "migrations",
+  "corpus": true
+}

package/corpus/backend/cross_module_imports_use_public_surface/compliant-01/modules/a/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="a", router=router, policy=Policy.default(), requires=("b",))

package/corpus/backend/cross_module_imports_use_public_surface/compliant-01/modules/a/service.py

@@ -0,0 +1 @@
+from app.modules.b.service import ConnectionProfileService

package/corpus/backend/cross_module_imports_use_public_surface/compliant-01/modules/b/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="b", router=router, policy=Policy.default())

package/corpus/backend/cross_module_imports_use_public_surface/violation-01/modules/a/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="a", router=router, policy=Policy.default(), requires=("b",))

package/corpus/backend/cross_module_imports_use_public_surface/violation-01/modules/a/service.py

@@ -0,0 +1 @@
+from app.modules.b.router import router as b_router

package/corpus/backend/cross_module_imports_use_public_surface/violation-01/modules/b/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="b", router=router, policy=Policy.default())

package/corpus/backend/cross_module_imports_use_public_surface/violation-02/modules/a/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="a", router=router, policy=Policy.default(), requires=("b",))

package/corpus/backend/cross_module_imports_use_public_surface/violation-02/modules/a/service.py

@@ -0,0 +1 @@
+from app.modules.b._internal import secret_helper

package/corpus/backend/cross_module_imports_use_public_surface/violation-02/modules/b/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="b", router=router, policy=Policy.default())

package/corpus/backend/emitted_events_are_declared/compliant-01/modules/notes/module.py

@@ -0,0 +1,13 @@
+from control_plane.events import NOTE_CREATED, NOTE_DELETED
+from terp.core import ModuleSpec, Policy, Roles, emit
+
+spec = ModuleSpec(
+    name="notes",
+    router=router,
+    policy=Policy(read=Roles.VIEWER, write=Roles.EDITOR),
+    emits=[NOTE_CREATED, NOTE_DELETED],
+)
+
+
+def archive(session, note):
+    emit(session, event=NOTE_DELETED, payload={"id": str(note.id)})

package/corpus/backend/emitted_events_are_declared/violation-01/modules/notes/module.py

@@ -0,0 +1,14 @@
+from control_plane.events import NOTE_CREATED, NOTE_DELETED
+from terp.core import ModuleSpec, Policy, Roles, emit
+
+spec = ModuleSpec(
+    name="notes",
+    router=router,
+    policy=Policy(read=Roles.VIEWER, write=Roles.EDITOR),
+    emits=[NOTE_CREATED],
+)
+
+
+def archive(session, note):
+    # Declared nowhere: the manifest above says this module emits only NOTE_CREATED.
+    emit(session, event=NOTE_DELETED, payload={"id": str(note.id)})

package/corpus/backend/module_dependency_graph_is_acyclic/compliant-01/modules/a/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="a", router=router, policy=Policy.default(), requires=("b",))

package/corpus/backend/module_dependency_graph_is_acyclic/compliant-01/modules/b/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="b", router=router, policy=Policy.default())

package/corpus/backend/module_dependency_graph_is_acyclic/violation-01/modules/a/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="a", router=router, policy=Policy.default(), requires=("b",))

package/corpus/backend/module_dependency_graph_is_acyclic/violation-01/modules/b/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="b", router=router, policy=Policy.default(), requires=("a",))

package/corpus/backend/no_cross_module_imports/compliant-02/modules/a/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="a", router=router, policy=Policy.default(), requires=("b",))

package/corpus/backend/no_cross_module_imports/compliant-02/modules/a/service.py

@@ -0,0 +1 @@
+from app.modules.b.service import ConnectionProfileService

package/corpus/backend/no_cross_module_imports/compliant-02/modules/b/module.py

@@ -0,0 +1 @@
+module = ModuleSpec(name="b", router=router, policy=Policy.default())

package/corpus/backend/table_ownership_is_not_split/compliant-01/modules/notes/migrations/versions/0a1b2c3d4e5f_create_notes_tables.py

@@ -0,0 +1,22 @@
+"""create the notes table
+
+Revision ID: 0a1b2c3d4e5f
+Revises:
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0a1b2c3d4e5f"
+down_revision = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "notes_note",
+        sa.Column("id", sa.Uuid(), primary_key=True),
+        sa.Column("title", sa.String(length=200), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("notes_note")

package/corpus/backend/table_ownership_is_not_split/compliant-01/modules/notes/models.py

@@ -0,0 +1,8 @@
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class Note(BaseTable, table=True):
+    __tablename__ = "notes_note"
+
+    title: str = Field(max_length=200)

package/corpus/backend/table_ownership_is_not_split/violation-01/expected-findings.json

@@ -0,0 +1,7 @@
+[
+  {
+    "rule": "backend/table_ownership_is_not_split",
+    "path": "modules/tasks/models.py",
+    "line": 6
+  }
+]

package/corpus/backend/table_ownership_is_not_split/violation-01/modules/notes/migrations/versions/0a1b2c3d4e5f_create_notes_tables.py

@@ -0,0 +1,22 @@
+"""create the notes table
+
+Revision ID: 0a1b2c3d4e5f
+Revises:
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0a1b2c3d4e5f"
+down_revision = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "notes_note",
+        sa.Column("id", sa.Uuid(), primary_key=True),
+        sa.Column("title", sa.String(length=200), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("notes_note")

package/corpus/backend/table_ownership_is_not_split/violation-01/modules/tasks/models.py

@@ -0,0 +1,8 @@
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class Note(BaseTable, table=True):
+    __tablename__ = "notes_note"
+
+    title: str = Field(max_length=200)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@terpjs/spec",
-  "version": "0.18.0",
-  "description": "The Terp Standard — stack-neutral rule catalog, violation corpus, finding format, and refused-surface declaration (ADRs 0080/0081; packaged per ADR 0082, published per ADR 0086). Data only: consumers resolve the spec root via require.resolve('@terpjs/spec/package.json').",
+  "version": "0.20.0",
+  "description": "The Terp Standard — stack-neutral rule catalog, violation corpus, finding format, and refused-surface declaration (ADRs 0080/0081; packaged per ADR 0082, published per ADR 0086). Data only: consumers resolve the spec root via require.resolve('@terpjs/spec/package.json').",
   "files": [
     "VERSION",
     "findings.schema.json",