@terpjs/spec 0.21.0 → 0.22.0

package/VERSION

@@ -1 +1 @@
-0.21.0
+0.22.0

package/catalog/backend/declared_read_only_routes_do_not_write.json

@@ -0,0 +1,26 @@
+{
+  "id": "backend/declared_read_only_routes_do_not_write",
+  "surface": "backend",
+  "title": "A route that declares itself read-only must not mutate",
+  "intent": "Write authority is derived from the HTTP method, which is right for almost every route and blind to one: the handler that uses an unsafe method because its input is a body, not because it writes — validating a candidate document, previewing an import, costing a plan. Undeclared, such a route is pure only by the absence of a write: a guarantee made of missing code, which holds until an edit adds a line and which no rule and no reviewer is prompted to check. Declaring the intent makes it enforceable in both layers: the build-time rule refuses a declared handler that calls a mutating service method, and the runtime binder marks the request read-only so the write chokepoint refuses a write the rule cannot see statically (through a helper, a subscriber, a capability). Fix a violation by removing the write — putting it behind its own route — or by removing the declaration, whichever the route was meant to be; never both, because a declared handler that writes leaves the platform holding two answers to the same promise. Authorization is deliberately unchanged: a declared route is still authorized at the write tier, because declaring purity narrows what the handler may do, never what the caller must hold.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_declared_read_only_routes_do_not_write"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "build_read_only_request_binder"
+    }
+  ],
+  "opt_out": "# arch-allow-declared-read-only-routes-do-not-write: <reason>",
+  "runtime": {
+    "applicability": "required"
+  },
+  "reference": "Mutating BaseService calls (create/update/delete/_save/_remove) inside a handler decorated with terp.core.read_only are flagged; create_app binds a declared route's request read-only (build_read_only_request_binder).",
+  "guide_topic": "module",
+  "corpus": true
+}

package/corpus/backend/declared_read_only_routes_do_not_write/compliant-01/modules/notes/router.py

@@ -0,0 +1,4 @@
+@router.post('/validation', response_model=NoteVerdict)
+@read_only
+def validate_candidate(payload) -> NoteVerdict:
+    return service.validate(payload)

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

@@ -0,0 +1,8 @@
+@router.post('/preview', response_model=NotePreview)
+@read_only
+def preview_import(payload) -> NotePreview:
+    existing = service.list(skip=0, limit=10)
+    return NotePreview(rows=payload.rows, existing=existing)
+@router.post('/', response_model=NoteRead)
+def create_note(payload) -> NoteRead:
+    return service.create(payload)

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

@@ -0,0 +1,7 @@
+[
+  {
+    "rule": "backend/declared_read_only_routes_do_not_write",
+    "path": "modules/notes/router.py",
+    "line": 4
+  }
+]

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

@@ -0,0 +1,4 @@
+@router.post('/validation', response_model=NoteVerdict)
+@read_only
+def validate_candidate(payload) -> NoteVerdict:
+    return service.create(payload)

package/corpus/backend/declared_read_only_routes_do_not_write/violation-02/expected-findings.json

@@ -0,0 +1,7 @@
+[
+  {
+    "rule": "backend/declared_read_only_routes_do_not_write",
+    "path": "modules/notes/router.py",
+    "line": 4
+  }
+]

package/corpus/backend/declared_read_only_routes_do_not_write/violation-02/modules/notes/router.py

@@ -0,0 +1,5 @@
+@router.post('/preview', response_model=NotePreview)
+@core.read_only
+def preview_import(payload) -> NotePreview:
+    service._save(payload)
+    return NotePreview(rows=payload.rows)

package/package.json

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