@terpjs/spec 0.21.1 → 0.23.0

package/VERSION

@@ -1 +1 @@
-0.21.1
+0.23.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/catalog/backend/schemas_avoid_positional_tuples.json

@@ -0,0 +1,27 @@
+{
+  "id": "backend/schemas_avoid_positional_tuples",
+  "surface": "backend",
+  "title": "A schema field never crosses the wire as a positional tuple",
+  "intent": "A fixed-length tuple annotation (tuple[str, str], list[tuple[str, int]], tuple[str, ...]) on a schema a client can see or send serialises into the contract as an array whose element types are positional (prefixItems, or the list form of items). Client generators do not agree on that shape: one emits the positional form and another the widened element array, so the two descriptions of the same field are structurally unrelated and the app cannot type its own calls against its own API — the failure surfaces at the call site as an opaque generic-instantiation mismatch, far from the field that caused it, and only with error truncation disabled. A tuple is also a poor contract in its own right: the positions carry meaning that no name records. Name the shape instead — a nested model with named fields when the positions differ in meaning, or a homogeneous sequence (list[str]) when they do not.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_schemas_avoid_positional_tuples"
+    },
+    {
+      "kind": "runtime",
+      "tool": "terp.core",
+      "ref": "_reject_positional_tuple_schemas"
+    }
+  ],
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The invariant survives into the running app: the generated OpenAPI document is the artifact the client is built from, so the boot-time contract validation walks every component schema and refuses a positional array shape (prefixItems, or items as a list) fail-closed. This catches the vector the source check cannot see — a tuple reaching the contract through a type alias, a generic parameter, or a custom __get_pydantic_core_schema__ — and both halves name the same fix."
+  },
+  "reference": "Schema fields annotated with a nested BaseSchema model or a homogeneous list[...]; tuple[...] annotations on BaseSchema subclasses and on any class used as a route body or response_model are refused.",
+  "opt_out": "# arch-allow-schemas-avoid-positional-tuples: <reason>",
+  "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/corpus/backend/schemas_avoid_positional_tuples/compliant-01/modules/notes/schemas.py

@@ -0,0 +1,6 @@
+class Point(BaseSchema):
+    lat: float
+    lon: float
+class NoteRead(BaseSchema):
+    coordinates: Point
+    tag_names: list[str]

package/corpus/backend/schemas_avoid_positional_tuples/violation-01/modules/notes/schemas.py

@@ -0,0 +1,2 @@
+class NoteRead(BaseSchema):
+    coordinates: tuple[float, float]

package/corpus/backend/schemas_avoid_positional_tuples/violation-02/modules/notes/schemas.py

@@ -0,0 +1,2 @@
+class NoteCreate(BaseSchema):
+    tags: list[tuple[str, str]]

package/package.json

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