@terpjs/spec 0.26.1 → 0.29.1

package/VERSION

@@ -1 +1 @@
-0.26.1
+0.29.1

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/catalog/backend/operations_reference_catalog.json

@@ -0,0 +1,19 @@
+{
+  "id": "backend/operations_reference_catalog",
+  "surface": "backend",
+  "title": "A route's declared operation is a typed catalog constant, never a bare value",
+  "intent": "A route can say what it does for the person calling it, but only by citing a typed definition from one shared catalog -- never a string literal or a value built inline at the call site. Without this, a route's stated purpose could drift from what the catalog documents, or two routes could describe the same action in two different words with no way to tell they were ever meant to agree.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    { "kind": "build-time", "tool": "terp.arch", "ref": "check_operations_reference_catalog" },
+    { "kind": "runtime", "tool": "terp.core", "ref": "_validate_declared_operations" }
+  ],
+  "reference": "OperationDefinition constants from the control-plane operations catalog, cited via the operation(...) route-level marker and the *_operation= keywords a canonical CRUD factory accepts.",
+  "opt_out": "# arch-allow-operations-reference-catalog: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Boot resolves every declared operation against the registered catalog by value (id and wording together), so an unknown id or a same-id entry with different wording fails closed before the app ever serves a request."
+  },
+  "guide_topic": "operations",
+  "corpus": true
+}

package/catalog/backend/routes_declare_operation.json

@@ -0,0 +1,19 @@
+{
+  "id": "backend/routes_declare_operation",
+  "surface": "backend",
+  "title": "Every route declares the operation it performs",
+  "intent": "A route's method and path say how to call it; nothing about them says what it does for the person calling it. Under this app's chosen coverage level, a route that declares no operation leaves that question permanently unanswered for anyone reading the permission surface rather than the source.",
+  "layer": "static-bespoke",
+  "enforcement": [
+    { "kind": "build-time", "tool": "terp.arch", "ref": "check_routes_declare_operation" },
+    { "kind": "runtime", "tool": "terp.core", "ref": "_validate_declared_operations" }
+  ],
+  "reference": "the operation(...) route-level marker, or for a canonical CRUD factory its *_operation= keywords, checked once the app's operations catalog opts into strict coverage.",
+  "opt_out": "# arch-allow-routes-declare-operation: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "Boot refuses a mounted route with no declared operation once the app's operations catalog opts into strict coverage; a lighter warn mode records the same gap without refusing the boot, and the coverage choice itself is optional, so an app that has not adopted it boots unchanged."
+  },
+  "guide_topic": "operations",
+  "corpus": true
+}

package/catalog/frontend/locale-catalogs-complete.json

@@ -0,0 +1,26 @@
+{
+  "id": "frontend/locale-catalogs-complete",
+  "surface": "frontend",
+  "title": "Every declared target locale translates every authored message",
+  "intent": "Every stable user-interface message identifier must have a non-empty translation in every declared target locale. A missing or malformed catalog, empty entries, and undocumented source-language copies fail the gate instead of silently rendering source-language text after a user switches locale.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "@terpjs/eslint-boundaries",
+      "ref": "terp/locale-catalogs-complete"
+    },
+    {
+      "kind": "runtime",
+      "tool": "@terpjs/react-core",
+      "ref": "LocaleProvider"
+    }
+  ],
+  "reference": "Declare sourceLocale and locale message maps in frontend/i18n.json; the boundary rule and defineAppLocales validate that declaration, while LocaleProvider refuses missing target entries at render time.",
+  "opt_out": "// terp-allow-locale-catalogs-complete: <reason>",
+  "runtime": {
+    "applicability": "required",
+    "rationale": "The locale provider owns descriptor resolution and can distinguish source fallback from a missing target entry, including dynamically assembled identifiers that a static check cannot see."
+  },
+  "corpus": true
+}

package/catalog/frontend/no-untranslated-ui.json

@@ -0,0 +1,21 @@
+{
+  "id": "frontend/no-untranslated-ui",
+  "surface": "frontend",
+  "title": "Static user-facing text participates in localization",
+  "intent": "Static user-facing text anywhere in app-authored frontend source must use the translation seam. Bare visible copy, accessibility labels, component text properties, labels stored in data, and standard toast feedback are otherwise absent from every translation catalog and silently remain in the source language.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "@terpjs/eslint-boundaries",
+      "ref": "terp/no-untranslated-ui"
+    }
+  ],
+  "reference": "Use UiText descriptors and Trans from @terpjs/react-core throughout app-authored frontend source.",
+  "opt_out": "// terp-allow-no-untranslated-ui: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "The rendered value cannot prove whether it originated from a descriptor or a bare literal, while dynamic business data legitimately remains untranslated."
+  },
+  "corpus": true
+}

package/corpus/RESIDUALS.json

@@ -4,6 +4,14 @@
     "backend/no_dynamic_sql": [
       "an alias-renamed symbol import (`from sqlalchemy import text as sql_text`) is not required to be resolved to `text`"
     ],
+    "backend/no_manual_lease_columns": [
+      "a holder/heartbeat pair under other column names (`worker_id` + `last_seen_at`) is not required to be recognised as a hand-rolled lease: the check matches a fixed set of column spellings on a table model, not the custody shape"
+    ],
+    "backend/no_manual_ownership_checks": [
+      "a jobs declaration bound to a name (`ModuleSpec(jobs=MODULE_JOBS)`) is not required to be seen as declaring background work: the build-time background-work clause matches a list or tuple LITERAL",
+      "`OwnedMixin` reached indirectly — through an intermediate base, or on a model declared in another package — is not required to be recognised as ownership by the build-time background-work clause, which matches a direct base name within the same module directory",
+      "a ModuleSpec that omits `services=` is not required to be caught by the composition-time twin, which iterates the declared services"
+    ],
     "backend/no_raw_outbound_http": [
       "dynamic import (`importlib.import_module(\"httpx\")`) is not required to be seen as an import"
     ],

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

@@ -0,0 +1,16 @@
+from control_plane.operations import NOTES_DELETE
+from terp.core import operation
+
+
+@router.delete('/{note_id}', status_code=204)
+@operation(NOTES_DELETE)
+def delete_note(note_id, session) -> None:
+    _service.delete(session, note_id)
+
+
+# A route with no declared operation at all is not this rule's concern -- an
+# absent declaration is coverage's question (backend/routes_declare_operation),
+# not a drifted one.
+@router.get('/{note_id}')
+def get_note(note_id, session):
+    return _service.get(session, note_id)

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

@@ -0,0 +1,10 @@
+from control_plane.operations import NOTES_LIST
+from terp.core import build_crud_router
+
+router = build_crud_router(
+    NoteService(),
+    read_schema=NoteRead,
+    create_schema=NoteCreate,
+    update_schema=NoteUpdate,
+    list_operation=NOTES_LIST,
+)

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

@@ -0,0 +1,13 @@
+from terp.core import OperationDefinition, operation
+
+
+@router.delete('/{note_id}', status_code=204)
+@operation("notes.delete")
+def delete_note(note_id, session) -> None:
+    _service.delete(session, note_id)
+
+
+@router.get('/{note_id}')
+@operation(OperationDefinition(id="notes.get", label="View a note"))
+def get_note(note_id, session):
+    return _service.get(session, note_id)

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

@@ -0,0 +1,9 @@
+from terp.core import build_crud_router
+
+router = build_crud_router(
+    NoteService(),
+    read_schema=NoteRead,
+    create_schema=NoteCreate,
+    update_schema=NoteUpdate,
+    list_operation="notes.list",
+)

package/corpus/backend/routes_declare_operation/compliant-01/control_plane/operations.py

@@ -0,0 +1,7 @@
+from terp.core import OperationCatalog, OperationCoverage, OperationDefinition
+
+NOTES_LIST = OperationDefinition(id="notes.list", label="List every note")
+
+operation_catalog = OperationCatalog(
+    operations=(NOTES_LIST,), coverage=OperationCoverage.STRICT
+)

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

@@ -0,0 +1,8 @@
+from control_plane.operations import NOTES_LIST
+from terp.core import operation
+
+
+@router.get('/')
+@operation(NOTES_LIST)
+def list_notes():
+    return notes

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

@@ -0,0 +1,5 @@
+# No control_plane/operations.py at all: this app has not opted into operation
+# coverage (the default), so an undeclared route is not this rule's concern.
+@router.get('/')
+def list_notes():
+    return notes

package/corpus/backend/routes_declare_operation/compliant-03/control_plane/operations.py

@@ -0,0 +1,12 @@
+from terp.core import OperationCatalog, OperationCoverage, OperationDefinition
+
+NOTES_LIST = OperationDefinition(id="notes.list", label="List every note")
+NOTES_CREATE = OperationDefinition(id="notes.create", label="Write a new note")
+NOTES_GET = OperationDefinition(id="notes.get", label="View a note")
+NOTES_UPDATE = OperationDefinition(id="notes.update", label="Edit a note")
+NOTES_DELETE = OperationDefinition(id="notes.delete", label="Delete a note")
+
+operation_catalog = OperationCatalog(
+    operations=(NOTES_LIST, NOTES_CREATE, NOTES_GET, NOTES_UPDATE, NOTES_DELETE),
+    coverage=OperationCoverage.STRICT,
+)

package/corpus/backend/routes_declare_operation/compliant-03/modules/notes/router.py

@@ -0,0 +1,20 @@
+from control_plane.operations import (
+    NOTES_CREATE,
+    NOTES_DELETE,
+    NOTES_GET,
+    NOTES_LIST,
+    NOTES_UPDATE,
+)
+from terp.core import build_crud_router
+
+router = build_crud_router(
+    NoteService(),
+    read_schema=NoteRead,
+    create_schema=NoteCreate,
+    update_schema=NoteUpdate,
+    list_operation=NOTES_LIST,
+    create_operation=NOTES_CREATE,
+    get_operation=NOTES_GET,
+    update_operation=NOTES_UPDATE,
+    delete_operation=NOTES_DELETE,
+)

package/corpus/backend/routes_declare_operation/violation-01/control_plane/operations.py

@@ -0,0 +1,3 @@
+from terp.core import OperationCatalog, OperationCoverage
+
+operation_catalog = OperationCatalog(coverage=OperationCoverage.STRICT)

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

@@ -0,0 +1,3 @@
+@router.get('/')
+def list_notes():
+    return notes

package/corpus/backend/routes_declare_operation/violation-02/control_plane/operations.py

@@ -0,0 +1,3 @@
+from terp.core import OperationCatalog, OperationCoverage
+
+operation_catalog = OperationCatalog(coverage=OperationCoverage.STRICT)

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

@@ -0,0 +1,8 @@
+from terp.core import build_crud_router
+
+router = build_crud_router(
+    NoteService(),
+    read_schema=NoteRead,
+    create_schema=NoteCreate,
+    update_schema=NoteUpdate,
+)

package/corpus/frontend/escape-hatch/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.save":"Opslaan"}}}}

package/corpus/frontend/escape-hatch/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,6 @@
+import { Trans } from "@terpjs/react-core";
+
 export function Widget() {
   // terp-allow-token-styled-elements: native button needed for a browser extension host
-  return <button>save</button>;
+  return <button><Trans id="widget.save" message="Save" /></button>;
 }

package/corpus/frontend/generated-client-only/compliant-04/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"realtime.waiting":"Wachten"}}}}

package/corpus/frontend/generated-client-only/compliant-04/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { useRealtimeChannel } from "@terpjs/react-core";
+import { Trans, useRealtimeChannel } from "@terpjs/react-core";
 
 type Notice = { sequence: number; text: string };
 
@@ -13,5 +13,9 @@ export function Widget() {
     channel: "system.notices",
     validate: isNotice,
   });
-  return <p>{notices.lastMessage?.text ?? "Waiting"}</p>;
+  return (
+    <p>
+      {notices.lastMessage?.text ?? <Trans id="realtime.waiting" message="Waiting" />}
+    </p>
+  );
 }

package/corpus/frontend/layout-contract/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"nl","locales":{"nl":{},"en":{"messages":{"notes.title":"Notes","notes.all":"All notes"}}}}

package/corpus/frontend/layout-contract/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,8 +1,8 @@
 import { HubCard, HubPage } from "@terpjs/react-core";
 export function Widget() {
   return (
-    <HubPage title="Notes">
-      <HubCard title="All notes" to="/notes" />
+    <HubPage title={{ id: "notes.title", message: "Notities" }}>
+      <HubCard title={{ id: "notes.all", message: "Alle notities" }} to="/notes" />
     </HubPage>
   );
 }

package/corpus/frontend/locale-catalogs-complete/compliant-01/i18n.json

@@ -0,0 +1,11 @@
+{
+  "sourceLocale": "en",
+  "locales": {
+    "en": { "label": "English" },
+    "nl": {
+      "label": "Nederlands",
+      "messages": { "widgets.title": "Widgets" },
+      "allowIdentical": ["widgets.title"]
+    }
+  }
+}

package/corpus/frontend/locale-catalogs-complete/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,5 @@
+import { Page } from "@terpjs/react-core";
+
+export function Widget() {
+  return <Page title={{ id: "widgets.title", message: "Widgets" }} />;
+}

package/corpus/frontend/locale-catalogs-complete/violation-01/i18n.json

@@ -0,0 +1,7 @@
+{
+  "sourceLocale": "en",
+  "locales": {
+    "en": { "label": "English" },
+    "nl": { "label": "Nederlands", "messages": {} }
+  }
+}

package/corpus/frontend/locale-catalogs-complete/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,5 @@
+import { Page } from "@terpjs/react-core";
+
+export function Widget() {
+  return <Page title={{ id: "widgets.title", message: "Widgets" }} />;
+}

package/corpus/frontend/locale-catalogs-complete/violation-02/src/modules/widgets/Widget.tsx

@@ -0,0 +1,5 @@
+import { Page } from "@terpjs/react-core";
+
+export function Widget() {
+  return <Page title={{ id: "widgets.title", message: "Widgets" }} />;
+}

package/corpus/frontend/locale-catalogs-complete/violation-03/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widgets.title":""}}}}

package/corpus/frontend/locale-catalogs-complete/violation-03/src/modules/widgets/Widget.tsx

@@ -0,0 +1 @@
+export const widget = { id: "widget-1" };

package/corpus/frontend/locale-catalogs-complete/violation-04/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widgets.title":"Onderdelen"}}}}

package/corpus/frontend/locale-catalogs-complete/violation-04/src/modules/widgets/Widget.tsx

@@ -0,0 +1,5 @@
+import { Page } from "@terpjs/react-core";
+
+export function Widget({ messageId }: { messageId: string }) {
+  return <Page title={{ id: messageId, message: "Widgets" }} />;
+}

package/corpus/frontend/no-cross-module-imports/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.ok":"OK"},"allowIdentical":["widget.ok"]}}}

package/corpus/frontend/no-cross-module-imports/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { Button } from "@terpjs/react-core";
+import { Button, Trans } from "@terpjs/react-core";
 export function Widget() {
-  return <Button>ok</Button>;
+  return <Button><Trans id="widget.ok" message="OK" /></Button>;
 }

package/corpus/frontend/no-deep-imports/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.ok":"OK"},"allowIdentical":["widget.ok"]}}}

package/corpus/frontend/no-deep-imports/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { Button } from "@terpjs/react-core";
+import { Button, Trans } from "@terpjs/react-core";
 export function Widget() {
-  return <Button>ok</Button>;
+  return <Button><Trans id="widget.ok" message="OK" /></Button>;
 }

package/corpus/frontend/no-dom-html-injection/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.ok":"OK"},"allowIdentical":["widget.ok"]}}}

package/corpus/frontend/no-dom-html-injection/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { Button } from "@terpjs/react-core";
+import { Button, Trans } from "@terpjs/react-core";
 export function Widget() {
-  return <Button>ok</Button>;
+  return <Button><Trans id="widget.ok" message="OK" /></Button>;
 }

package/corpus/frontend/no-eval/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.ok":"OK"},"allowIdentical":["widget.ok"]}}}

package/corpus/frontend/no-eval/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { Button } from "@terpjs/react-core";
+import { Button, Trans } from "@terpjs/react-core";
 export function Widget() {
-  return <Button>ok</Button>;
+  return <Button><Trans id="widget.ok" message="OK" /></Button>;
 }

package/corpus/frontend/no-inline-styling/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.ok":"OK"},"allowIdentical":["widget.ok"]}}}

package/corpus/frontend/no-inline-styling/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { Button } from "@terpjs/react-core";
+import { Button, Trans } from "@terpjs/react-core";
 export function Widget() {
-  return <Button>ok</Button>;
+  return <Button><Trans id="widget.ok" message="OK" /></Button>;
 }

package/corpus/frontend/no-style-imports/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.ok":"OK"},"allowIdentical":["widget.ok"]}}}

package/corpus/frontend/no-style-imports/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { Button } from "@terpjs/react-core";
+import { Button, Trans } from "@terpjs/react-core";
 export function Widget() {
-  return <Button>ok</Button>;
+  return <Button><Trans id="widget.ok" message="OK" /></Button>;
 }

package/corpus/frontend/no-unsafe-href/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.docs":"Documentatie"}}}}

package/corpus/frontend/no-unsafe-href/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,3 +1,5 @@
+import { Trans } from "@terpjs/react-core";
+
 export function Widget() {
-  return <a href="https://example.com" rel="noopener">docs</a>;
+  return <a href="https://example.com" rel="noopener"><Trans id="widget.docs" message="Docs" /></a>;
 }

package/corpus/frontend/no-unsafe-target-blank/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.docs":"Documentatie"}}}}

package/corpus/frontend/no-unsafe-target-blank/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,3 +1,5 @@
+import { Trans } from "@terpjs/react-core";
+
 export function Widget() {
-  return <a href="https://example.com" target="_blank" rel="noopener">docs</a>;
+  return <a href="https://example.com" target="_blank" rel="noopener"><Trans id="widget.docs" message="Docs" /></a>;
 }

package/corpus/frontend/no-untranslated-ui/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widgets.title":"Onderdelen","widgets.empty":"Nog niets te zien."}}}}

package/corpus/frontend/no-untranslated-ui/compliant-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,11 @@
+import { Page, Trans } from "@terpjs/react-core";
+
+const title = { id: "widgets.title", message: "Widgets" };
+
+export function Widget() {
+  return (
+    <Page title={title}>
+      <Trans id="widgets.empty" message="Nothing here yet." />
+    </Page>
+  );
+}

package/corpus/frontend/no-untranslated-ui/violation-01/src/modules/widgets/Widget.tsx

@@ -0,0 +1,9 @@
+import { Page, Text } from "@terpjs/react-core";
+
+export function Widget() {
+  return (
+    <Page title="Widgets">
+      <Text>Nothing here yet.</Text>
+    </Page>
+  );
+}

package/corpus/frontend/no-untranslated-ui/violation-02/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{}}}

package/corpus/frontend/no-untranslated-ui/violation-02/src/main.tsx

@@ -0,0 +1 @@
+export const ssoProviders = [{ name: "sso", label: "Single sign-on" }];

package/corpus/frontend/no-untranslated-ui/violation-03/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{}}}

package/corpus/frontend/no-untranslated-ui/violation-03/src/modules/widgets/Widget.tsx

@@ -0,0 +1,5 @@
+import { ModuleNav } from "@terpjs/react-core";
+
+export function Widget() {
+  return <ModuleNav ariaLabel="Widget sections" items={[]} />;
+}

package/corpus/frontend/no-untranslated-ui/violation-04/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{}}}

package/corpus/frontend/no-untranslated-ui/violation-04/src/main.tsx

@@ -0,0 +1,10 @@
+export function Status({ ready }: { ready: boolean }) {
+  return (
+    <>
+      {ready ? "Ready" : "Waiting"}
+      {ready && "Start now"}
+      {["First item", "Second item"]}
+      {{ primary: "Save changes", fallback: "Cancel changes" }}
+    </>
+  );
+}

package/corpus/frontend/no-untranslated-ui/violation-05/i18n.json

@@ -0,0 +1,9 @@
+{
+  "sourceLocale": "en",
+  "locales": {
+    "en": {},
+    "nl": {
+      "messages": {}
+    }
+  }
+}

package/corpus/frontend/no-untranslated-ui/violation-05/src/main.tsx

@@ -0,0 +1,7 @@
+import { useToast } from "@terpjs/react-core";
+
+export function SaveAction() {
+  const toast = useToast();
+  toast.success("Changes saved");
+  return null;
+}

package/corpus/frontend/router-links/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.notes":"Notities"}}}}

package/corpus/frontend/router-links/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { Link } from "@terpjs/react-core";
+import { Link, Trans } from "@terpjs/react-core";
 export function Widget() {
-  return <Link to="/notes">notes</Link>;
+  return <Link to="/notes"><Trans id="widget.notes" message="Notes" /></Link>;
 }

package/corpus/frontend/token-styled-elements/compliant-01/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.ok":"OK"},"allowIdentical":["widget.ok"]}}}

package/corpus/frontend/token-styled-elements/compliant-01/src/modules/widgets/Widget.tsx

@@ -1,4 +1,4 @@
-import { Button } from "@terpjs/react-core";
+import { Button, Trans } from "@terpjs/react-core";
 export function Widget() {
-  return <Button>ok</Button>;
+  return <Button><Trans id="widget.ok" message="OK" /></Button>;
 }

package/corpus/frontend/token-styled-elements/compliant-02/i18n.json

@@ -0,0 +1 @@
+{"sourceLocale":"en","locales":{"en":{},"nl":{"messages":{"widget.save":"Opslaan"}}}}

package/corpus/frontend/token-styled-elements/compliant-02/src/modules/widgets/Widget.tsx

@@ -1,4 +1,6 @@
+import { Trans } from "@terpjs/react-core";
+
 export function Widget() {
   // terp-allow-token-styled-elements: native button needed for a browser extension host
-  return <button>save</button>;
+  return <button><Trans id="widget.save" message="Save" /></button>;
 }

package/package.json

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