@terpjs/spec 0.22.0 → 0.23.0

package/VERSION

@@ -1 +1 @@
-0.22.0
+0.23.0

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/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.22.0",
+  "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",