@terpjs/spec 0.24.0 → 0.26.0

package/README.md

@@ -67,17 +67,28 @@ The artifacts:
    extensions, deep-import segments). The portable prohibition rules cite it
    structurally (the `restricted_surface` catalog field); which sanctioned
    component answers each primitive is per-stack configuration.
-7. **The residual ratchet** (`corpus/RESIDUALS.json`) — the statically-erased
+7. **The layout declaration** (`layout-declaration.schema.json`) — the
+   stack-neutral, normative schema for the document an app checks in to declare
+   which slot-typed page contract it opts into, which palette it starts on, and
+   how its application shell is shaped (content measure, density, navigation
+   placement, the navigation groups a module's items name by id, and the mark
+   the app is recognised by). One document, so a build-time checker and the 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 those choices. Naming the contract
+   and naming a palette are the app's to do and their values are per-stack, hence
+   plain strings; the shell's vocabulary is fixed normatively, and the reference
+   stack's resolver is parity-tested against it.
+8. **The residual ratchet** (`corpus/RESIDUALS.json`) — the statically-erased
    or renamed forms deliberately outside the corpus contract, per rule, as
    shrink-only data (see "Detector boundaries" below).
-8. **The scorecard format** (`scorecard.schema.json`) — the machine-readable
+9. **The scorecard format** (`scorecard.schema.json`) — the machine-readable
    certification summary a conformant checker emits (spec version, per-rule
    verdicts over the corpus, residuals claimed), so "certified against spec
    X.Y.Z" is a verifiable artifact instead of a claim.
-9. **The changelog** (`CHANGELOG.md`) — the change history keyed to `VERSION`
+10. **The changelog** (`CHANGELOG.md`) — the change history keyed to `VERSION`
    (the top entry must match, held by the spec suite), so a checker certified
    against an earlier version can see exactly what changed since.
-10. **The rule pages** (`docs/rules/`) — plain-language documentation generated
+11. **The rule pages** (`docs/rules/`) — plain-language documentation generated
     from the catalog (`tools/generate_rule_docs.py`; regenerate-and-compare
     parity in the spec suite, so the pages cannot drift from the data).
 

package/VERSION

@@ -1 +1 @@
-0.24.0
+0.26.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/frontend/layout-contract.json

@@ -2,7 +2,7 @@
   "id": "frontend/layout-contract",
   "surface": "frontend",
   "title": "An opted-in app's archetype body slots accept only the contract's components",
-  "intent": "With a checked-in layout contract, each page archetype's body slot is constrained to the contract's sanctioned components, so screens stay structurally consistent and the failure message tells an agent exactly how to build the screen. Paired with the fail-closed runtime check on the rendered slot.",
+  "intent": "With a checked-in layout declaration, each page archetype's body slot is constrained to the contract's sanctioned components, so screens stay structurally consistent and the failure message tells an agent exactly how to build the screen. Paired with the fail-closed runtime check on the rendered slot. The declaration is the single source for the opt-in, for the palette the app opens on, and for the shell's own shape down to the navigation groups a module's items name by id and the mark the app is recognised by (layout-declaration.schema.json): a build-time checker and the running app read the same document, so neither can enforce a contract the other does not, and a key declared both in the document and in the app's own code is refused rather than resolved by an invisible precedence.",
   "layer": "static-bespoke",
   "enforcement": [
     {
@@ -18,7 +18,7 @@
     }
   ],
   "opt_out": "// terp-allow-layout-contract: <reason>",
-  "reference": "frontend/layout-contract.json + the layoutContract bootstrap option (ADR 0079); verifySlotChildren in @terpjs/react-core is the runtime DOM check.",
+  "reference": "frontend/layout-contract.json, the document layout-declaration.schema.json describes (ADR 0079); the app imports it and the reference stack's bootstrap resolves it, refusing an unknown key, a value outside its enum, and any key declared twice. The per-stack values: contracts are the keys of LAYOUT_CONTRACTS in @terpjs/react-core, and defaultTheme names one of the palettes @terpjs/contract compiles or the reserved system. Neither list is written out here: the contract ids and the palette names both live in @terpjs/react-core's published layout.manifest.json, with the values filled in for the release an app is pinned to, and every copy of them in that stack is gated against it. A fourth copy in this field would be the one nothing checks, and it would sit in the very field this schema points a reader at for the truth. shell.navGroups is groupNav's group table in @terpjs/react-core, whose NavItem.group references it; shell.brand names paths Vite serves from the app's own frontend/public, rendered into AppShell's logo and logoDark slots. verifySlotChildren in @terpjs/react-core is the runtime DOM check.",
   "runtime": {
     "applicability": "required"
   },

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/package.json

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