@terpjs/spec 0.19.0 → 0.21.0

package/VERSION

@@ -1 +1 @@
-0.19.0
+0.21.0

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/forwarded_filters_are_declared.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/forwarded_filters_are_declared",
+  "surface": "backend",
+  "title": "Every filter name a read endpoint forwards must be a declared filter",
+  "intent": "An endpoint that narrows a read forwards its optional query parameters unchanged, so a filter name that matches no declaration carries no value on any request that omits that parameter. The narrowing appears to be applied while the read stays unnarrowed, and no test that omits the parameter can observe the difference. Each forwarded filter name must correspond to a filter the read layer declares, so a name that no declaration backs is rejected on the source rather than on the one request that happens to supply a value for it.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_forwarded_filters_are_declared"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "resolve_filters"
+    }
+  ],
+  "reference": "A literal filter name forwarded from an endpoint that matches no declared filter is flagged at that name, and the message lists the declared names so a misspelling is visible against its intended target. Names that are not statically knowable — a filter mapping built elsewhere, or a computed name — are not judged, because a guess there would reject correct code.",
+  "opt_out": "# arch-allow-forwarded-filters-are-declared: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The read layer resolves each forwarded name against the declarations while serving the request, and rejects an undeclared name before the read is built, so the invariant is observable and enforced fail-closed at runtime. The name is resolved before an absent value is discarded — checking the value first would leave an undeclared name both unreachable and unreported for as long as callers omit it, which is the defect this rule exists for. The build-time check is the earlier half: it holds for endpoints no request has exercised."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

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/forwarded_filters_are_declared/compliant-01/modules/notes/router.py

@@ -0,0 +1,5 @@
+def list_notes(session, author_id=None, created_from=None):
+    return service.list(
+        session,
+        filters={"author_id": author_id, "created_from": created_from},
+    )

package/corpus/backend/forwarded_filters_are_declared/compliant-01/modules/notes/service.py

@@ -0,0 +1,9 @@
+from terp.core import BaseService, FilterField
+
+
+class NoteService(BaseService):
+    model = Note
+    filterable = (
+        FilterField("author_id", Note.author_id),
+        FilterField("created_from", Note.created_at, op="gte"),
+    )

package/corpus/backend/forwarded_filters_are_declared/compliant-02/modules/notes/router.py

@@ -0,0 +1,5 @@
+# A filter mapping built elsewhere, and a computed name, are not statically
+# knowable. Neither is judged: a guess there would reject correct code.
+def list_notes(session, chosen, prepared):
+    service.list(session, filters=prepared)
+    return service.list(session, filters={chosen: 1})

package/corpus/backend/forwarded_filters_are_declared/violation-01/modules/notes/router.py

@@ -0,0 +1,7 @@
+# "created_form" matches no declared filter, so it never narrows the read — and
+# stays silent for every request that omits the parameter.
+def list_notes(session, author_id=None, created_from=None):
+    return service.list(
+        session,
+        filters={"author_id": author_id, "created_form": created_from},
+    )

package/corpus/backend/forwarded_filters_are_declared/violation-01/modules/notes/service.py

@@ -0,0 +1,9 @@
+from terp.core import BaseService, FilterField
+
+
+class NoteService(BaseService):
+    model = Note
+    filterable = (
+        FilterField("author_id", Note.author_id),
+        FilterField("created_from", Note.created_at, op="gte"),
+    )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/spec",
-  "version": "0.19.0",
+  "version": "0.21.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",