@terpjs/spec 0.26.0 → 0.27.0

package/VERSION

@@ -1 +1 @@
-0.26.0
+0.27.0

package/catalog/backend/declared_read_controls_are_forwarded.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/declared_read_controls_are_forwarded",
+  "surface": "backend",
+  "title": "A declared filter or sort must be reachable from an endpoint that forwards it",
+  "intent": "A read layer declares which fields a caller may narrow or order by, and an endpoint reaches those declarations by forwarding the caller's request into the read. A declaration no endpoint forwards is inert: the capability is described in the source, absent from the API, and silent about the difference. The failure is worse than an unimplemented feature because it presents as an implemented one — a client generated from the contract offers no way to sort, a screen built against it ships with every column's sorting disabled, and nothing in the read layer is wrong. Each declared filter and sort must therefore be reachable: a module that declares one and forwards none is rejected on the source, rather than discovered by a user who cannot order a list the code says is orderable.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_declared_read_controls_are_forwarded"
+    }
+  ],
+  "reference": "Judged per module and per control kind by PRESENCE, never by name: a module that declares a filter is required to forward a filters mapping somewhere within itself, and a module that declares a sort is required to forward a sort. The keyword is visible in the source even when the value handed to it is computed, which is what makes presence decidable where a per-name comparison is not — a mapping built elsewhere hides its names but not its existence, so requiring a specific declared name to appear at a call site would reject correct code. The pairing of one declaration to one endpoint is not statically knowable either, which is why the unit is the module that owns both.",
+  "opt_out": "# arch-allow-declared-read-controls-are-forwarded: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "There is nothing for a runtime check to observe. The defect is the ABSENCE of a call: a request that would have carried a filter or a sort never arrives, because the endpoint exposes no parameter for it, so no code path runs and no fail-closed control can fire. This is a build-time-only invariant by nature, not by omission — the counterpart rule that judges a forwarded name against the declarations is enforced at runtime precisely because there a request does reach the read layer."
+  },
+  "guide_topic": "service",
+  "corpus": true
+}

package/catalog/backend/frozen_values_hold_no_mutable_collection.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/frozen_values_hold_no_mutable_collection",
+  "surface": "backend",
+  "title": "A frozen value object must not hold a mutable collection",
+  "intent": "Freezing a value object announces that it cannot change after construction, and callers rely on that: they share it between requests, cache it, use it as a registry key, and skip defensive copies because the type says none are needed. Freezing binds the ATTRIBUTES, not what they point at — a frozen object holding a list or a dict or a set is immutable only one level deep, so anyone holding it can append to its contents while every guarantee the type advertises still appears to hold. The mutation is invisible at the call site that performs it and arrives somewhere else entirely, in another request or another worker, as state that changed without an assignment. A frozen field must therefore be typed as an immutable sequence or mapping, so the promise the type makes is the promise it keeps.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_frozen_values_hold_no_mutable_collection"
+    }
+  ],
+  "reference": "Flagged on the field of a frozen value object whose annotation is a mutable built-in collection — list, dict or set, including their typing spellings and parameterised forms — with the immutable counterpart named in the message: a tuple for a sequence, a Mapping or frozen mapping for a dict, a frozenset for a set. A frozen object is recognised by its declaration, not by convention: a dataclass frozen at the decorator, a NamedTuple, or a model configured immutable. An annotation that is not statically a mutable collection is not judged, because the shape of an aliased or computed type is not knowable here and guessing would reject correct code.",
+  "opt_out": "# arch-allow-frozen-values-hold-no-mutable-collection: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "A runtime control would have to intercept mutation of an object the frozen value merely references, which is the thing the language does not offer: the list belongs to whoever else holds it, its mutating methods are not the frozen object's to override, and a deep-freeze on construction would change the value's semantics rather than check them. This is the shape of invariant only a build-time reading of the declaration can hold — which is exactly why declaring a frozen field as immutable is the control, rather than watching what happens to it later."
+  },
+  "guide_topic": "module",
+  "corpus": true
+}

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

@@ -0,0 +1,8 @@
+# Both declarations are reachable: the endpoint exposes a parameter for each and
+# forwards it, so what the read layer says is narrowable and orderable is.
+def list_notes(session, author_id=None, sort=None):
+    return service.list(
+        session,
+        filters={"author_id": author_id},
+        sort=sort,
+    )

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

@@ -0,0 +1,7 @@
+from terp.core import BaseService, FilterField, SortField
+
+
+class NoteService(BaseService):
+    model = Note
+    filterable = (FilterField("author_id", Note.author_id),)
+    sortable = (SortField("created_at", Note.created_at),)

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

@@ -0,0 +1,6 @@
+# The mapping is built rather than written out, and that is still compliant: the
+# rule judges whether the module forwards a filters mapping at all, never which
+# names the mapping happens to contain. A computed mapping hides its names from a
+# reader of the source; it does not hide its existence.
+def list_notes(session, **query):
+    return service.list(session, filters=_requested_filters(query), sort=query.get("sort"))

package/corpus/backend/declared_read_controls_are_forwarded/compliant-02/modules/notes/service.py

@@ -0,0 +1,7 @@
+from terp.core import BaseService, FilterField, SortField
+
+
+class NoteService(BaseService):
+    model = Note
+    filterable = (FilterField("author_id", Note.author_id),)
+    sortable = (SortField("created_at", Note.created_at),)

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

@@ -0,0 +1,6 @@
+# Two sorts are declared and no endpoint forwards one, so the read is never
+# ordered by anything a caller asked for. Nothing here is wrong and nothing
+# fails: a client generated from this contract simply has no way to sort, and a
+# screen built on it ships with every column's sorting disabled.
+def list_notes(session, author_id=None):
+    return service.list(session, filters={"author_id": author_id})

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

@@ -0,0 +1,9 @@
+from terp.core import BaseService, SortField
+
+
+class NoteService(BaseService):
+    model = Note
+    sortable = (
+        SortField("name", Note.name),
+        SortField("created_at", Note.created_at),
+    )

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

@@ -0,0 +1,6 @@
+# The same absence on the filter side: a declared filter that no endpoint
+# forwards describes a narrowing the API cannot perform. The list is always
+# unnarrowed, which is also the shape a reader is most likely to mistake for a
+# permission problem rather than a missing parameter.
+def list_notes(session, sort=None):
+    return service.list(session, sort=sort)

package/corpus/backend/declared_read_controls_are_forwarded/violation-02/modules/notes/service.py

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

package/corpus/backend/frozen_values_hold_no_mutable_collection/compliant-01/modules/notes/values.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from collections.abc import Mapping
+
+
+@dataclass(frozen=True)
+class ImportPlan:
+    """Frozen all the way down: the promise the type makes is the one it keeps."""
+
+    name: str
+    columns: tuple[str, ...]
+    defaults: Mapping[str, str]
+    tags: frozenset[str]

package/corpus/backend/frozen_values_hold_no_mutable_collection/compliant-02/modules/notes/values.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+
+
+# Not frozen, so nothing is promised and a list is an honest field. The rule is
+# about a claim that does not hold, never about mutability itself.
+@dataclass
+class ImportDraft:
+    name: str
+    columns: list[str]

package/corpus/backend/frozen_values_hold_no_mutable_collection/violation-01/modules/notes/values.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ImportPlan:
+    """Immutable one level deep, which is the level nobody checks.
+
+    `plan.columns.append("x")` succeeds on a frozen object. Callers share this
+    between requests and skip defensive copies because the type says they can,
+    so the mutation arrives somewhere else entirely as state that changed with
+    no assignment anywhere near it.
+    """
+
+    name: str
+    columns: list[str]

package/corpus/backend/frozen_values_hold_no_mutable_collection/violation-02/modules/notes/values.py

@@ -0,0 +1,13 @@
+from typing import NamedTuple
+
+
+class RouteSpec(NamedTuple):
+    """A NamedTuple is frozen by construction, and holds a mutable dict anyway.
+
+    Worse than the dataclass case in practice: a tuple is the shape people reach
+    for precisely BECAUSE it is safe to use as a key or share freely, so the
+    false guarantee travels further.
+    """
+
+    path: str
+    handlers: dict[str, str]

package/layout-declaration.schema.json

@@ -0,0 +1,78 @@
+{
+  "title": "Terp Standard - the app's layout declaration",
+  "description": "The normative, stack-neutral schema for the document an app checks in to declare its layout: which slot-typed page contract it opts into, which palette it starts on, and how its application shell is shaped. One document, so a build-time checker and a running app read the same bytes and neither can hold a different answer - and so a tool that edits files, rather than code, can read and rewrite these choices. Naming the contract and naming a palette are the app's to do and the values are per-stack, hence plain strings; the shell's vocabulary is fixed here, because a density or a navigation placement means the same thing on any stack. Every key is optional: an absent key is not a default, it is the app declining to declare, and a consumer must leave whatever was already in force alone. A key a consumer does not recognise must be refused rather than ignored, or a declaration that does nothing looks like one that works.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "contract": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The named slot-typed page contract this app opts into. Which contracts exist, and which components each of their page slots admits, is per-stack configuration recorded non-normatively in the catalog entry's reference field - the portable part is that the opt-in is declared here, once, for every consumer that enforces it."
+    },
+    "defaultTheme": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The palette the app starts on, until a person chooses another and for as long as they have not. Declared here rather than in the app's own code for the reason the shell's shape is: a choice reachable only by editing code is out of reach of anything that edits files, and which palette an app opens on is among the most visible choices its operator makes. Which palettes exist is per-stack configuration recorded non-normatively in the catalog entry's reference field, hence a plain string rather than an enum - the portable part is that the choice is declared here, once. The one reserved name is \"system\", which declares that the app opens on whatever light or dark preference the viewer's own platform reports; every other value names a palette the stack ships, and a consumer must refuse a name it does not ship rather than fall back to one it does."
+    },
+    "shell": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How the application shell is shaped. Separate from the contract above because that governs the inside of a page and this governs the frame around it. Everything in here has a vocabulary this schema fixes, which is what separates it from the two keys above: a density, a navigation placement, the parts of a navigation group and the parts of a brand mark all mean the same thing on any stack, while which page contracts and which palettes exist do not.",
+      "properties": {
+        "brand": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The app's own mark, as paths a consumer resolves the way it resolves any other static asset the app ships. Declared here for the reason everything else in this document is: a mark is among the most visible things about an app and it was reachable only by editing that app's source, which put it out of reach of anything that edits files. Both keys are optional, and an app that declares neither shows whatever placeholder its stack ships.",
+          "properties": {
+            "logo": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The mark shown inside the app's own frame. A consumer sizes it to the frame rather than to itself, so an oversized asset is scaled down rather than clipped."
+            },
+            "logoDark": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The mark for a dark palette, declared separately rather than derived. A mark with fixed colours cannot survive a dark background and no consumer can tell whether this one can, so an app that has a second asset says so and an app that does not says nothing and keeps one mark everywhere. A consumer that has both must choose by the appearance of the palette actually in force, not by the viewer's platform preference: an app may open on a dark palette on a light platform, and a mark chosen by the platform would then be the wrong one."
+            }
+          }
+        },
+        "contentWidth": {
+          "enum": ["full", "measured"],
+          "description": "Whether routed content is capped at the shell's declared reading measure or spans the full track."
+        },
+        "density": {
+          "enum": ["comfortable", "compact"],
+          "description": "The app-wide control height and cell padding, declared once for the whole shell rather than per screen."
+        },
+        "navGroups": {
+          "type": "array",
+          "description": "The navigation groups this app declares, which is the only place they can be declared: a group spans modules, so no module can own one. A module's navigation item names a group by id, an item naming a group this list does not declare is not an error but the normal state of an app mid-adoption, and every such item falls into a trailing group with no label. Declaring two groups with the same id is an authoring error a consumer must refuse.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "label"],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The group's own name, referenced by a navigation item to say which group it belongs to. Non-empty: a consumer may well treat the empty string as a usable key at render time, where being total matters more than being strict, but declaring one is an authoring error with no legitimate transient form - it is a group nothing can name on purpose."
+              },
+              "label": {
+                "type": "string",
+                "description": "What a consumer renders above the group's list. The empty string declares a positioning-only group: no label element at all, which is how an app places otherwise ungrouped items somewhere other than the end without inventing a heading for them. Required rather than optional, so that having no label is a decision this document states rather than a key someone forgot."
+              },
+              "order": {
+                "type": "integer",
+                "description": "Sort key against sibling groups, ascending. Absent is the same as zero and the sort is stable, so groups that tie keep the order they are declared in - which means an app that wants only a sequence can write the groups in that sequence and set this on none of them. An integer, because a sort key is an ordinal."
+              }
+            }
+          }
+        },
+        "navPlacement": {
+          "enum": ["header", "sidebar"],
+          "description": "Where the primary navigation sits on a wide viewport: a full-height rail beside the content, or a row within the header."
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/spec",
-  "version": "0.26.0",
+  "version": "0.27.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",
@@ -8,6 +8,7 @@
     "app-check-report.schema.json",
     "scorecard.schema.json",
     "assurance-profile.schema.json",
+    "layout-declaration.schema.json",
     "restricted-surface.json",
     "catalog",
     "corpus"