@terpjs/spec 0.23.0 → 0.25.0

package/VERSION

@@ -1 +1 @@
-0.23.0
+0.25.0

package/catalog/backend/no_manual_lease_columns.json

@@ -0,0 +1,22 @@
+{
+  "id": "backend/no_manual_lease_columns",
+  "surface": "backend",
+  "title": "Application tables do not re-derive leases; expiring custody of work is a platform primitive",
+  "intent": "Exclusive, time-bounded custody of a unit of work belongs to the platform, not to each table that needs it. An application table must not declare its own lease bookkeeping \u2014 a holder column paired with an expiry, a heartbeat stamp, or an equivalent claim deadline \u2014 because the hand-rolled form reliably omits the part that makes a lease safe. Expiry alone establishes that a holder may have died; it does not prevent that holder, if it merely paused, from waking after its deadline and completing work a successor has already taken over. A conformant platform supplies custody that is fenced (a monotonic grant token every write is matched against, so a superseded holder is refused rather than trusted), taken atomically with the state change it guards, renewable by a heartbeat that fails closed when the grant is lost, and recoverable \u2014 an expired grant must trigger the owning domain's declared recovery, so work a crashed holder abandoned returns to a retryable state instead of requiring manual repair. Platform-owned delivery infrastructure that claims batches of its own rows, and needs no domain recovery, is a reviewed exception rather than an application pattern.",
+  "layer": "static-portable",
+  "enforcement": [
+    {
+      "kind": "build-time",
+      "tool": "terp.arch",
+      "ref": "check_no_manual_lease_columns"
+    }
+  ],
+  "reference": "LeaseResource names the leased row or domain mutex; hold_lease / acquire_lease take it through the configured LeaseStore, LeaseGuard.heartbeat renews it and raises when the grant was lost, and register_lease_reaper declares the per-kind recovery an expiry triggers. terp-cap-leases keeps the grants in the app's own database so a claim commits with the row change it protects.",
+  "opt_out": "# arch-allow-no-manual-lease-columns: <reason>",
+  "runtime": {
+    "applicability": "not-applicable",
+    "rationale": "Column presence is observable at runtime but not attributable. Composition shares one model-metadata registry across every installed distribution, and the platform's own durable-delivery table legitimately declares exactly these columns for its batch claim \u2014 so a running app cannot tell an application's hand-rolled lease from the framework's sanctioned one (the same non-attribution as the import-form egress and background-runtime rules). Nor can a module manifest close the gap: it carries routers and jobs, never a model reference to attribute a column through. The lease seam's own fail-closed controls \u2014 the fence that refuses a superseded holder's write, the heartbeat that raises rather than returning a flag, and the boot guard that refuses a store whose grants die with their holder \u2014 protect the sanctioned path; they cannot see a table that never joined it. The paired protection is therefore constructive rather than preventive: a maintained primitive that is strictly better than the hand-rolled shape, offered where the hand-rolled shape used to be the only option."
+  },
+  "guide_topic": "leases",
+  "corpus": true
+}

package/catalog/backend/schemas_avoid_positional_tuples.json

@@ -2,7 +2,7 @@
   "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.",
+  "intent": "A fixed-length tuple annotation (tuple[str, str], list[tuple[str, int]]) 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 fixed 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 when they do not. Scope is the positional shape only: a variadic tuple[X, ...] serialises byte-identically to list[X] — it is the immutable spelling of a homogeneous sequence, the natural annotation for a frozen value object — so it is compliant, and refusing it would force a source rewrite with zero wire effect. A fixed tuple nested inside one (tuple[tuple[str, int], ...]) is still refused.",
   "layer": "static-bespoke",
   "enforcement": [
     {
@@ -18,9 +18,9 @@
   ],
   "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."
+    "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 the generated document and refuses a positional array shape (prefixItems, or items as a list) fail-closed, reporting every offending location in one pass rather than raising on the first. Judging the document rather than the annotations is what makes the scope exact in both directions: a variadic tuple emits nothing positional and passes, while a tuple reaching the contract through a discriminated-union member, a type alias, a generic parameter, or a custom __get_pydantic_core_schema__ is in the document no matter what the annotation walk could see — 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.",
+  "reference": "Schema fields annotated with a nested BaseSchema model or a homogeneous sequence (list[...], or the variadic tuple[X, ...] which serialises identically); fixed-length 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/no_manual_lease_columns/compliant-01/modules/requests/models.py

@@ -0,0 +1,13 @@
+import uuid
+
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class RunRequest(BaseTable, table=True):
+    """The row records its own lifecycle; custody is the platform's, keyed on the row."""
+
+    __tablename__ = "run_request"
+
+    connection_id: uuid.UUID = Field(index=True)
+    status: str = Field(max_length=16, index=True)

package/corpus/backend/no_manual_lease_columns/compliant-01/modules/requests/service.py

@@ -0,0 +1,44 @@
+from terp.core import (
+    AuditAction,
+    BaseService,
+    LeaseResource,
+    hold_lease,
+    register_lease_reaper,
+)
+
+from app.modules.requests.models import RunRequest
+from app.modules.requests.schemas import RunRequestCreate, RunRequestUpdate
+
+CLAIMED = "claimed"
+QUEUED = "queued"
+
+
+class RunRequestService(BaseService[RunRequest, RunRequestCreate, RunRequestUpdate]):
+    model = RunRequest
+
+    def __init__(self, holder: str) -> None:
+        self._holder = holder
+
+    def _after_write(self, session, entity, action):
+        """Take the lease inside the write that claims the row, so the two agree.
+
+        A resource somebody else holds raises here, before the write commits, so the row
+        never reaches ``claimed`` at all — there is no compensating update to forget.
+        """
+        if entity.status == CLAIMED:
+            hold_lease(
+                session,
+                LeaseResource.for_row(entity),
+                holder=self._holder,
+                ttl_seconds=60,
+            )
+
+
+def requeue_stale_request(session, lease) -> None:
+    """The recovery an expired lease triggers: put the abandoned row back in the queue."""
+    service = RunRequestService(holder="reaper")
+    row = service.get(session, lease.resource.key)
+    service.update(session, row.id, RunRequestUpdate(status=QUEUED, version=row.version))
+
+
+register_lease_reaper("run_request", requeue_stale_request)

package/corpus/backend/no_manual_lease_columns/compliant-02/modules/requests/schemas.py

@@ -0,0 +1,15 @@
+from datetime import datetime
+
+from terp.core import BaseSchema
+
+
+class LeaseRead(BaseSchema):
+    """A read DTO may surface who holds a lease and until when — it declares no column.
+
+    Only a persisted column on a table model is refused; showing an operator what is
+    stuck is exactly what the primitive is for.
+    """
+
+    holder: str | None
+    locked_until: datetime | None
+    heartbeat_at: datetime | None

package/corpus/backend/no_manual_lease_columns/violation-01/modules/requests/models.py

@@ -0,0 +1,19 @@
+from datetime import datetime
+
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class RunRequest(BaseTable, table=True):
+    """A queue row that re-derives custody on itself: a holder plus a deadline.
+
+    Nothing here can refuse a holder that merely paused: it wakes past its deadline,
+    finds its own name still in ``locked_by``, and finishes over the successor that
+    already took the work.
+    """
+
+    __tablename__ = "run_request"
+
+    status: str = Field(max_length=16, index=True)
+    locked_by: str | None = Field(default=None, max_length=128)
+    locked_until: datetime | None = None

package/corpus/backend/no_manual_lease_columns/violation-02/modules/pipelines/models.py

@@ -0,0 +1,17 @@
+from datetime import datetime
+
+from sqlmodel import Field
+from terp.core import BaseTable
+
+
+class PipelineRun(BaseTable, table=True):
+    """The same defect in its other common spelling: a heartbeat stamp on the row.
+
+    A reader still cannot tell "working" from "died", because nothing declares how long
+    a gap in the heartbeat is allowed to be, and nothing walks the run back when it is.
+    """
+
+    __tablename__ = "pipeline_run"
+
+    status: str = Field(max_length=16, index=True)
+    heartbeat_at: datetime | None = None

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

@@ -0,0 +1,2 @@
+class NoteRead(BaseSchema):
+    fingerprint: tuple[str, ...]

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

@@ -0,0 +1,2 @@
+class NoteRead(BaseSchema):
+    spans: tuple[tuple[int, int], ...]

package/package.json

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