terp-cli 0.20.0__tar.gz → 0.22.0__tar.gz

{terp_cli-0.20.0 → terp_cli-0.22.0}/PKG-INFO

@@ -1,19 +1,19 @@
 Metadata-Version: 2.5
 Name: terp-cli
-Version: 0.20.0
+Version: 0.22.0
 Summary: Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs.
 Project-URL: Repository, https://github.com/AITT-NL/terp-framework
 Project-URL: Changelog, https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md
 License-Expression: Apache-2.0
 Requires-Python: >=3.13
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: terp-arch==0.20.0
-Requires-Dist: terp-core==0.20.0
-Requires-Dist: terp-migrations==0.20.0
+Requires-Dist: terp-arch==0.22.0
+Requires-Dist: terp-core==0.22.0
+Requires-Dist: terp-migrations==0.22.0
 Provides-Extra: jobs
-Requires-Dist: terp-cap-outbox==0.20.0; extra == 'jobs'
-Requires-Dist: terp-cap-scheduler-apscheduler==0.20.0; extra == 'jobs'
+Requires-Dist: terp-cap-outbox==0.22.0; extra == 'jobs'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.22.0; extra == 'jobs'
 Provides-Extra: scheduler
-Requires-Dist: terp-cap-scheduler-apscheduler==0.20.0; extra == 'scheduler'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.22.0; extra == 'scheduler'
 Provides-Extra: worker
-Requires-Dist: terp-cap-outbox==0.20.0; extra == 'worker'
+Requires-Dist: terp-cap-outbox==0.22.0; extra == 'worker'

{terp_cli-0.20.0 → terp_cli-0.22.0}/pyproject.toml

@@ -4,18 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.20.0"
+version = "0.22.0"
 description = "Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs."
 requires-python = ">=3.13"
 license = "Apache-2.0"
 dependencies = [
-    "terp-core==0.20.0",
+    "terp-core==0.22.0",
     # `terp migrate` delegates to terp-migrations (lazily imported), keeping Alembic
     # off the path for `terp inspect` / `terp guide` while making migrations work.
-    "terp-migrations==0.20.0",
+    "terp-migrations==0.22.0",
     # `terp guide rules` projects the live rule registry; terp-arch is imported lazily
     # (only when that topic is rendered), so it stays off the common `terp guide` path.
-    "terp-arch==0.20.0",
+    "terp-arch==0.22.0",
     # `terp verify --only env-seams` and `terp smoke` read the compose profiles as data
     # (anchors and `<<:` merge keys resolved), so both answer without a Docker daemon or
     # even the `docker` binary. Declared explicitly rather than leant on: every app
@@ -29,11 +29,11 @@ dependencies = [
 # or a scheduler engine into apps that only use inspect/check/migrate. Deployments can select
 # one process role, while `jobs` is the convenient complete jobs-process bundle.
 [project.optional-dependencies]
-worker = ["terp-cap-outbox==0.20.0"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.20.0"]
+worker = ["terp-cap-outbox==0.22.0"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.22.0"]
 jobs = [
-    "terp-cap-outbox==0.20.0",
-    "terp-cap-scheduler-apscheduler==0.20.0",
+    "terp-cap-outbox==0.22.0",
+    "terp-cap-scheduler-apscheduler==0.22.0",
 ]
 
 [project.scripts]

{terp_cli-0.20.0 → terp_cli-0.22.0}/src/terp/cli/__init__.py

@@ -559,6 +559,107 @@ Recoverable deletes (SoftDeleteMixin)
   your own would mean touching deleted_at, which the gate refuses. Today the trait
   preserves the row and the history that cites it; bringing one back is an operator
   action, not an app one.
+""",
+    "references": """\
+Stored references (Ref + OnDelete)
+
+- A foreign key HAS a referential action whether or not you chose one, and the one
+  you get by not choosing (NO ACTION) looks exactly like the one you chose. So
+  declare it. on_delete is a required keyword, so the decision cannot be skipped:
+      from terp.core import BaseTable, OnDelete, Ref
+      class InvoiceLine(BaseTable, table=True):
+          invoice_id: uuid.UUID = Ref("invoice.id", on_delete=OnDelete.CASCADE)
+- WHICH action is yours to pick; the platform does not prefer one, because the right
+  answer is a property of what the reference MEANS:
+      CASCADE      this row is part of its parent (an invoice line, an address)
+      RESTRICT     the parent must not vanish underneath this row (a ledger entry)
+      SET NULL     a pointer allowed to go slack (an optional assignee) -- nullable
+      SET_DEFAULT  point at the column default instead (that default must exist)
+      NO_ACTION    the database takes none; something above it owns this lifecycle
+- NO_ACTION is a real answer, not a cop-out, and it emits NO clause at all. Two
+  consequences worth knowing: adopting the declaration on an existing schema costs
+  no migration (the DDL is unchanged, only the source now says the silence was
+  chosen), and a database reports its default action as absent rather than as the
+  words NO ACTION -- which is why emitting the literal would make every
+  model-versus-database comparison report drift on that constraint forever.
+- Ref() forwards everything else to Field(), and indexes by default: an unindexed
+  foreign key turns every parent delete and every join into a table scan.
+      owner_id: uuid.UUID | None = Ref("user.id", on_delete=OnDelete.SET_NULL,
+                                       default=None)
+- SOFT-DELETE CHANGES THE ANSWER. A SoftDeleteMixin row is never DELETEd, only
+  stamped, so no action declared against it can fire at all: CASCADE never cascades,
+  SET DEFAULT never defaults, and SET NULL is the worst of them -- the children keep
+  a live, non-null pointer to a row the read scope now hides from every query, so the
+  reference reads as broken rather than absent. Those three are refused by the
+  references_declare_delete_behaviour rule. RESTRICT and NO_ACTION are accepted, and
+  the difference is not that they are passive: it is that they only ever described
+  the hard-delete path no request can reach, so they promise nothing that fails to
+  happen. Declare one of those and cascade the STAMP from the owning service, which
+  is the only layer that can see it.
+- A service-owned cascade goes in _after_write, inside the same write unit, so every
+  removal is audited and a failure anywhere rolls the whole thing back. Drain in
+  batches until nothing is left: each pass flushes into the same transaction, so it
+  sees the previous pass's deletes, and no parent size is too large.
+      def _after_write(self, session, entity, action):
+          super()._after_write(session, entity, action)
+          if action is not AuditAction.DELETED:
+              return
+          while True:
+              lines, _total = self._lines.list(session, skip=0, limit=1_000,
+                                               filters={"invoice_id": entity.id})
+              if not lines:
+                  break
+              for line in lines:
+                  self._lines._remove(session, line)
+  (`invoice_id` has to be on the child service's `filterable` declaration for that
+  filter to be accepted -- see `terp guide service`.) The hook runs with raw session
+  writes re-forbidden, so `session.delete(...)` there fails closed on purpose -- `_save` / `_remove` re-open the scope for their own
+  audited write, and they are the only way through. Prefer this over a database
+  CASCADE whenever the removals must appear in the audit trail: the database deletes
+  silently and leaves the trail with a hole in it.
+- AUDIT LIVE METADATA (a consumer test, or a boot check where the model set is known):
+      from terp.core import assert_references_declare_delete_behaviour
+      def test_references_declare_delete_behaviour() -> None:
+          import app.models  # noqa: F401 -- populate the metadata
+          assert_references_declare_delete_behaviour()
+  It is deliberately not wired into create_app: SQLModel.metadata is process-global
+  and accumulates every table any test ever declared, so an unconditional walk at
+  boot would make one ad-hoc test model fail an unrelated later test (ADR 0133).
+- WHAT THIS DOES NOT COVER: ON UPDATE. BaseTable mandates a UUID surrogate primary
+  key, so a key never changes and there is nothing for it to cascade.
+""",
+    "append-only": """\
+Rows that cannot change, and rows that cannot go (append_only)
+
+- A ledger row, an immutable revision, a captured snapshot: the guarantee is real
+  only when it is STATED. Without this, immutability is achieved by not exposing an
+  update route, which is a guarantee made of missing code -- it holds until someone
+  adds a line, and no rule and no review step notices when they do.
+      class LedgerEntryService(BaseService[LedgerEntry, LedgerEntryCreate, Never]):
+          model = LedgerEntry
+          append_only = True
+- The write chokepoint then refuses every non-CREATED write -- update(), delete(),
+  and any bespoke _save() -- with the uniform 409. There is nothing to remember at
+  the call sites, and no route can opt back in.
+- It is a property of the SERVICE, so it covers the API, a worker, a job and a
+  fixture equally. It is not a database grant: a migration or a psql session can
+  still write the table. Pair it with the audit trail if you need to know that
+  nothing did.
+- append_only is ALL OR NOTHING per table. "Editable until the invoice is posted"
+  and "set once, then fixed" are narrower questions with no built-in seam yet; they
+  live in the service's own update path today. Write the refusal as a typed
+  ConflictError so it reads like the built-in one:
+      def update(self, session, entity_id, data):
+          entity = self.get(session, entity_id)
+          if entity.posted_at is not None:
+              raise ConflictError("Een geboekte factuur kan niet meer wijzigen.")
+          return super().update(session, entity_id, data)
+- The neighbouring guarantees, so you pick the right one:
+      append_only          the ROW cannot change after insert
+      @read_only           the ROUTE writes nothing, though its verb is unsafe
+      SoftDeleteMixin      the row survives its own delete (see: soft-delete)
+      OnDelete.RESTRICT    another row cannot be deleted while this one points at it
+      BaseUpdateSchema     a concurrent writer cannot lose your edit (OCC, 409)
 """,
     "package-boundaries": """\
 Boundaries for a second top-level package (an ungated worker)
@@ -1070,6 +1171,14 @@ Idempotency (the Idempotency-Key header, terp.core.idempotency)
   CLIENT opts in per request by sending a header:
       Idempotency-Key: <client-generated unique key>
   A request without the header behaves exactly as it did before.
+- GENERATE THE KEY WITH randomUuid() from @terpjs/react-core, not crypto.randomUUID().
+  The browser method exists only in a SECURE CONTEXT while lib.dom declares it
+  unconditionally, so on an http origin -- which is what the compose files publish, so
+  any deployment reached by hostname rather than localhost -- the call is a synchronous
+  TypeError. It type-checks cleanly and it never fires on localhost, so neither tsc nor
+  the test suite ever sees it; the retry-safety this whole feature exists for is what
+  breaks, and only in the deployment. The seam falls back to crypto.getRandomValues,
+  which is not secure-context-gated, for the same entropy.
 - The semantics, all typed envelopes:
       first call                -> executes; the response is stored under the key
       retry, same body          -> the stored response is replayed
@@ -1419,8 +1528,32 @@ Forms (react-core primitives)
   is the layout — never style={} / className / a module stylesheet.
 - Submit through the typed client: const client = useTerpClient();
   await unwrap(client.POST("/api/v1/invoices/", { body })); a failure throws ApiError
-  ({code, status, requestId}) — map codes to copy with useErrorMessage, show transient
-  success/failure with useToast(), and confirm destructive actions with ConfirmDialog.
+  ({code, status, requestId, fields}) — map codes to copy with useErrorMessage, show
+  transient success/failure with useToast(), and confirm destructive actions with
+  ConfirmDialog.
+- WHERE `errors.number` ABOVE COMES FROM: ApiError.fields. The backend's typed envelope
+  carries per-reason `loc` (AppError details, and FastAPI's own 422 entries, which share
+  the shape on purpose), and `unwrap` turns those into `fields` — a plain object keyed by
+  dotted field path, ready to hand straight to Field's `error` prop. That is the whole
+  loop the error envelope opens: a rejected field lights up under its own input instead of
+  degrading to a generic toast. `Object.keys(error.fields).length > 0` is the test for
+  "this belongs on the form".
+      const RENDERED = ["number", "status"];
+      try {
+        await unwrap(client.POST("/api/v1/invoices/", { body }));
+      } catch (error) {
+        const { shown, leftover } = routeFieldErrors(error, RENDERED);
+        setErrors(shown);
+        if (leftover || Object.keys(shown).length === 0) {
+          toast.error(message(error));
+        }
+      }
+- USE routeFieldErrors RATHER THAN A LOOP OF YOUR OWN, and the reason is the `leftover`
+  branch. The naive version — "if fields is non-empty, set them and return" — has a hole
+  that is invisible until it happens: a reason naming a field this form does not render
+  sets state nobody reads AND suppresses the toast on the way out, so the user presses
+  Save and nothing appears. No field lights up, no message, no navigation. A failed write
+  that reports nothing is worse than the toast it replaced.
 - Updates carry the row's `version` (optimistic concurrency): send the version you
   read; a 409 version_conflict means reload-and-retry, surfaced via ErrorState copy.
 - Mirror the backend's input caps client-side (maxLength on Input matching the schema's

{terp_cli-0.20.0 → terp_cli-0.22.0}/src/terp/cli/verify.py

@@ -38,6 +38,7 @@ required lanes.
 
 from __future__ import annotations
 
+import importlib
 import json
 import os
 import pathlib
@@ -183,6 +184,7 @@ class VerifyCheck:
     # "subprocess" | "architecture" | "api-docs-drift" | "routes-drift"
     # | "platform-install" | "env-seams" | "api-client" | "package-boundaries"
     # | "dependency-hygiene" | "workbench" | "deploy-safety"
+    # | "production-readiness"
     runner: str = "subprocess"
 
 
@@ -259,6 +261,20 @@ _DEPLOY_SAFETY = VerifyCheck(
     runner="deploy-safety",
 )
 
+# Runs beside deploy-safety and for the same reason, one layer in. That check reads
+# the deployment artifact for properties a declaration cannot excuse; this one reads
+# the declaration itself for the states the platform's own boot refuses. Both answer
+# "would this actually come up where it matters", which is the question a green gate
+# is otherwise silent about — and both cost a file read or an import, so they can run
+# in every profile including the cheapest.
+_PRODUCTION_READINESS = VerifyCheck(
+    id="production-readiness",
+    category="architecture",
+    command="terp verify --only production-readiness",
+    scope=("control_plane/**/*.py",),
+    runner="production-readiness",
+)
+
 _ARCHITECTURE = VerifyCheck(
     id="architecture",
     category="architecture",
@@ -416,6 +432,7 @@ PROFILES: dict[str, tuple[VerifyCheck, ...]] = {
         _ENV_SEAMS,
         _WORKBENCH,
         _DEPLOY_SAFETY,
+        _PRODUCTION_READINESS,
         _ARCHITECTURE,
         _PACKAGE_BOUNDARIES,
         _FRONTEND_BOUNDARIES,
@@ -428,6 +445,7 @@ PROFILES: dict[str, tuple[VerifyCheck, ...]] = {
         _ENV_SEAMS,
         _WORKBENCH,
         _DEPLOY_SAFETY,
+        _PRODUCTION_READINESS,
         _ARCHITECTURE,
         _PACKAGE_BOUNDARIES,
         _DEPENDENCY_HYGIENE,
@@ -444,6 +462,7 @@ PROFILES: dict[str, tuple[VerifyCheck, ...]] = {
         _ENV_SEAMS,
         _WORKBENCH,
         _DEPLOY_SAFETY,
+        _PRODUCTION_READINESS,
         _ARCHITECTURE,
         _PACKAGE_BOUNDARIES,
         _DEPENDENCY_HYGIENE,
@@ -1006,6 +1025,92 @@ def _frontend_lockstep_problems(project_root: pathlib.Path, platform: str) -> li
     return problems
 
 
+#: A ``terp-*`` requirement string, split into the distribution and its version
+#: specifier. Extras and environment markers are tolerated because the template
+#: writes both (``terp-core[secrets]==0.20.0``, a marker on a dev-group entry), and a
+#: parser that choked on them would silently read such a line as "no Terp dependency
+#: declared here" — a green over exactly the pin this check exists to police.
+_PY_REQUIREMENT = re.compile(
+    r"^(?P<name>[A-Za-z0-9._-]+)\s*(?:\[[^\]]*\])?\s*(?P<spec>[^;]*)"
+)
+#: The one accepted specifier shape: an exact pin. Terp moves in lockstep, so a range
+#: is a resolver invitation rather than a pin.
+_EXACT_PIN = re.compile(r"^==\s*(?P<version>[A-Za-z0-9._+!-]+)$")
+
+
+def _declared_python_requirements(project_root: pathlib.Path) -> list[tuple[str, str]]:
+    """``(where, requirement)`` for every dependency this app's manifest declares.
+
+    Both halves of the manifest, because a forgotten pin in the dev group is the same
+    mixed install as one in the runtime dependencies — ``terp-arch`` lives there, and
+    it is the gate itself.
+    """
+    manifest = project_root / "pyproject.toml"
+    try:
+        data = tomllib.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        # Unreadable or absent: `_run_dependency_hygiene` and the package-graph check
+        # already report a manifest nobody can parse, and a second voice saying it
+        # would bury the one that explains it.
+        return []
+    found: list[tuple[str, str]] = []
+    for requirement in data.get("project", {}).get("dependencies", []) or []:
+        if isinstance(requirement, str):
+            found.append(("dependencies", requirement))
+    for group, requirements in (data.get("dependency-groups", {}) or {}).items():
+        for requirement in requirements or []:
+            if isinstance(requirement, str):
+                found.append((f"dependency-groups.{group}", requirement))
+    return found
+
+
+def _backend_pin_problems(project_root: pathlib.Path, platform: str) -> list[str]:
+    """Every ``terp-*`` pin in ``pyproject.toml`` that disagrees with what is installed.
+
+    The half of the lockstep that was missing, and it was the more consequential half.
+    This check read the *environment* for backend packages and compared it only against
+    itself, while reading *declarations* for the frontend and comparing them against the
+    platform. So a tree whose manifest said ``terp-core==0.20.0`` over an environment
+    installed at 0.13.0 was internally consistent, passed here, and passed the whole
+    profile — a verdict about code that is not the code that will run.
+
+    Two ways an app arrives there, and neither is exotic. Someone repins and has not run
+    ``uv sync`` yet, which is the ordinary middle of an upgrade. Or a container bakes the
+    packages into its image and bind-mounts the source over them, so a rebuilt checkout
+    reloads new code against old libraries and dies on an import nowhere near the cause.
+
+    Silent on a requirement carrying **no** specifier: that is a workspace member or an
+    editable install (the platform's own tree declares all twenty-odd of its packages
+    that way), where the manifest is not where the version lives. A declared specifier,
+    however, is a claim about a version, and this holds it to the installed one.
+    """
+    from terp.cli.version import _INDEPENDENTLY_VERSIONED, _PREFIX
+
+    problems: list[str] = []
+    for where, requirement in _declared_python_requirements(project_root):
+        match = _PY_REQUIREMENT.match(requirement.strip())
+        if match is None:
+            continue
+        name = match.group("name").lower().replace("_", "-")
+        if not name.startswith(_PREFIX) or name in _INDEPENDENTLY_VERSIONED:
+            continue
+        spec = match.group("spec").strip()
+        if not spec:
+            continue  # a workspace source or an editable install; see the docstring
+        pinned = _EXACT_PIN.match(spec)
+        if pinned is None:
+            problems.append(
+                f"{where}: {name} is declared {spec!r} — Terp moves in lockstep, so "
+                f"pin =={platform}"
+            )
+        elif pinned.group("version") != platform:
+            problems.append(
+                f"{where}: {name} is pinned =={pinned.group('version')} but "
+                f"{platform} is installed"
+            )
+    return problems
+
+
 def _run_platform_install(project_root: pathlib.Path) -> tuple[int, str]:
     """Fail when the installed platform disagrees with itself — either half.
 
@@ -1016,7 +1121,10 @@ def _run_platform_install(project_root: pathlib.Path) -> tuple[int, str]:
     either direction, so this refuses rather than reports.
 
     The backend half reads the live environment (never a declared list), so a
-    capability adopted after this was written is policed too. The frontend half
+    capability adopted after this was written is policed too, and then holds that
+    environment against the pins ``pyproject.toml`` declares — a manifest and an
+    install that disagree is the same mixed platform arriving by a third route, and
+    the one that used to pass here green. The frontend half
     reads every app manifest that declares a ``@terpjs/*`` package, plus the
     installed copy under its ``node_modules`` when present — because a frontend
     package left behind is the same mixed install by another route, and a check
@@ -1057,6 +1165,20 @@ def _run_platform_install(project_root: pathlib.Path) -> tuple[int, str]:
             f"  Fix: rename each to its @terpjs/* spelling pinned at ^{platform}, "
             "then reinstall the node_modules of that manifest."
         )
+    backend_problems = _backend_pin_problems(project_root, platform)
+    if backend_problems:
+        return 1, (
+            f"the environment is consistent at terp {platform}, but this app's "
+            "pyproject.toml declares something else:\n"
+            + "".join(f"  {problem}\n" for problem in backend_problems)
+            + "A gate run against packages the manifest does not ask for proves "
+            "nothing about the code that will ship: the tree reloads new source "
+            "against old libraries and fails on an import nowhere near its cause.\n"
+            f"  Fix: uv sync --refresh (or repin to =={platform} if the manifest is "
+            "the half that is wrong).\n"
+            "If this is a container, its image bakes the packages in — rebuild it "
+            "rather than reloading into it (`terp docker dev` does)."
+        )
     frontend_problems = _frontend_lockstep_problems(project_root, platform)
     if frontend_problems:
         return 1, (
@@ -1070,13 +1192,141 @@ def _run_platform_install(project_root: pathlib.Path) -> tuple[int, str]:
             "that declares one, then reinstall that manifest's node_modules."
         )
     manifest_count = len(_terp_frontend_manifests(project_root))
+    pin_count = sum(
+        1
+        for _, requirement in _declared_python_requirements(project_root)
+        if requirement.lower().replace("_", "-").startswith("terp-")
+    )
     return (
         0,
-        f"terp {platform} ({len(versions)} distributions and "
-        f"{manifest_count} frontend manifest(s), consistent)",
+        f"terp {platform} ({len(versions)} distributions, {pin_count} declared "
+        f"pin(s) and {manifest_count} frontend manifest(s), consistent)",
     )
 
 
+#: The reference every other Terp surface already uses for the authority aggregate:
+#: `terp jobs list`, `terp inspect control-plane` and the template's own composition
+#: root all resolve `control_plane:control_plane`. Named here rather than made an
+#: option, because a check that has to be told where to look is a check an app can
+#: leave unaimed.
+_CONTROL_PLANE_REF = "control_plane:control_plane"
+
+
+#: The conventional address a job's system principal arrives at (ADR 0129). An app
+#: that declares this variable has said the value will be supplied, which is the
+#: evidence this check can actually have: the id belongs to a service principal in a
+#: particular database, so the gate's own environment is the last place it would be.
+_JOB_ACTOR_VARIABLE = "JOB_SYSTEM_ACTOR_ID"
+
+
+def _job_actor_arrives_from_the_environment(project_root: pathlib.Path) -> bool:
+    """Whether the app *declares* the job actor as a runtime variable.
+
+    The declaration is the proof, never the value. `create_app` fills an unset
+    `job_system_actor_id` from `JOB_SYSTEM_ACTOR_ID`, so an app whose principal is a
+    deployment fact leaves the field empty on purpose — and reddening it here would
+    punish exactly the delivery mechanism ADR 0129 added. What the app must not be
+    able to do is stay silent: `environment.schema.json` is where a runtime variable
+    is declared, `env-seams` already refuses a declaration the deployment does not
+    deliver, and `terp env file` renders it. So a declared variable is a promise with
+    a gate behind it, which an undeclared one is not.
+    """
+    from terp.cli.envschema import declared_variables
+
+    return _JOB_ACTOR_VARIABLE in declared_variables(project_root)
+
+
+def _run_production_readiness(project_root: pathlib.Path) -> tuple[int, str]:
+    """Refuse a tree whose declared control plane cannot boot in production.
+
+    Three of the platform's boot refusals are decided entirely by what the control
+    plane declares — no environment, no database, no request. `create_app` raises
+    `BootError` on each of them under `ENVIRONMENT == "production"`: an unsafe
+    security config, a password policy with no strength floor, and background work
+    that names no actor to stamp its writes with (ADR 0125). Outside production the
+    same states log a warning and keep booting, on purpose, because a developer who
+    has not wired a system principal yet should not be blocked by one.
+
+    Nothing gated the gap between those two behaviours. An app could declare a job,
+    never set `job_system_actor_id`, and take a green `--profile full` all the way to
+    a deployment that refuses to start — the gate, the machine envelope and CI all
+    agreeing, because none of them asked. This asks, and it is the same argument
+    `platform-install` already makes about mixed installs: a warning inside a command
+    nobody runs before shipping is not a control, so the verdict belongs where it can
+    fail.
+
+    Reads the *declared* plane and never builds the app, so it costs one module import
+    and can sit in every profile. The audit refusal is deliberately not among the
+    three: it turns on `create_app(audit_sink=...)`, a runtime argument this check
+    cannot see, and a check that pretended to cover it would be worse than the gap.
+
+    Skips with a note for a tree with no importable control plane — the platform's own
+    checkout, and an app whose authority surface predates the module. A plane that
+    imports and yields no `ControlPlane`, however, is a red: every other Terp command
+    reads the same reference, so the app has adopted the pattern and the file the
+    tooling depends on has stopped answering.
+
+    The job-actor half is satisfied by a *declaration* as well as by a value, because
+    ADR 0129 made `JOB_SYSTEM_ACTOR_ID` the conventional way the principal arrives and
+    the gate's own environment is the last place a production principal's id would be.
+    See `_job_actor_arrives_from_the_environment`.
+    """
+    from terp.core import ControlPlane
+
+    if not (project_root / "control_plane").is_dir():
+        return (
+            0,
+            f"{NOTE_PREFIX}no control_plane/ package - production readiness not "
+            "applicable (the authority surface every other terp command reads)",
+        )
+    root = str(project_root.resolve())
+    restore = root not in sys.path
+    if restore:
+        sys.path.insert(0, root)
+    module_name, _, attr = _CONTROL_PLANE_REF.partition(":")
+    try:
+        importlib.invalidate_caches()
+        module = importlib.import_module(module_name)
+        plane = getattr(module, attr, None)
+    except Exception as exc:  # noqa: BLE001 - any import failure is the app's answer
+        return 1, (
+            f"{_CONTROL_PLANE_REF} could not be imported, so what this app declares "
+            f"cannot be established: {type(exc).__name__}: {exc}"
+        )
+    finally:
+        if restore and root in sys.path:
+            sys.path.remove(root)
+    if not isinstance(plane, ControlPlane):
+        return 1, (
+            f"{_CONTROL_PLANE_REF} did not resolve to a terp.core.ControlPlane "
+            f"(found {type(plane).__name__}). Every terp command reads that reference "
+            "- `terp jobs list`, `terp inspect control-plane` and the app's own "
+            "composition root - so this is not a layout choice, it is a surface that "
+            "has stopped answering."
+        )
+    problems = [
+        *(f"security: {problem}" for problem in plane.security.production_problems()),
+        *(f"passwords: {problem}" for problem in plane.passwords.production_problems()),
+        *(
+            f"jobs: {problem}"
+            for problem in plane.production_problems()
+            if not _job_actor_arrives_from_the_environment(project_root)
+        ),
+    ]
+    if problems:
+        return 1, (
+            "this app's control plane refuses a production boot:\n"
+            + "".join(f"  {problem}\n" for problem in problems)
+            + "Each of these raises BootError under ENVIRONMENT=production and only "
+            "logs a warning outside it, so a green gate over this state is a gate "
+            "that agrees with a deployment that will not start.\n"
+            "  A job actor that is a deployment fact rather than a source constant is "
+            "declared, not hard-coded: put JOB_SYSTEM_ACTOR_ID in "
+            "environment.schema.json and create_app will resolve it (ADR 0129)."
+        )
+    return 0, "the declared control plane boots in production (security, passwords, jobs)"
+
+
 def _run_routes_drift(root: pathlib.Path) -> tuple[int, str]:
     """Refuse a committed route table that no longer matches the module manifests.
 
@@ -1492,6 +1742,8 @@ def run_verify_command(
             from terp.cli.deploy_safety import run_deploy_safety_check
 
             exit_code, output = run_deploy_safety_check(project_root)
+        elif check.runner == "production-readiness":
+            exit_code, output = _run_production_readiness(project_root)
         else:
             exit_code, output = _run_subprocess(check, project_root)
             reports = _reports_in(output)

{terp_cli-0.20.0 → terp_cli-0.22.0}/src/terp/cli/version.py

@@ -223,6 +223,7 @@ def scaffold_ref(root: pathlib.Path) -> str | None:
 #: ``test_the_app_owned_scaffold_list_matches_copier`` — the same treatment the theme
 #: bootstrap's three duplicated facts get, so this list cannot rot into a wrong answer.
 _APP_OWNED_SCAFFOLD_FILES = (
+    "control_plane/app_operations.py",
     "environment.schema.json",
     "escape-hatch-budget.json",
     "frontend/layout-contract.json",
@@ -233,7 +234,9 @@ _APP_OWNED_SCAFFOLD_FILES = (
 )
 
 
-def _scaffold_lines(root: pathlib.Path, platform: str) -> list[str]:
+def _scaffold_lines(
+    root: pathlib.Path, platform: str, *, include_command: bool = True
+) -> list[str]:
     """Report how far the app's *scaffolding* is behind its *packages*.
 
     The two move independently and only one of them is gated. Package drift already fails
@@ -268,15 +271,124 @@ def _scaffold_lines(root: pathlib.Path, platform: str) -> list[str]:
         f"{platform}.",
         "A re-render rewrites EVERY file the template owns — main.tsx, index.html,",
         "AGENTS.md, the Dockerfiles, docker-compose.yml, the CI workflows — so any fix a",
-        "release made to one of them is still waiting here. Nothing gates this, so it",
-        "stays green; a stale AGENTS.md in particular briefs every agent from the wrong",
-        "rulebook, and a stale docker-compose.yml can serve a dev stack that disagrees",
-        "with the checkout the boundary lint reads.",
+        "release made to one of them may still be waiting here. WHICH of them actually",
+        "differ is not something this can say: it compares two version numbers, and a",
+        "file no release has touched since is already current. Nothing gates any of it,",
+        "so it stays green either way — and the two that cost the most when they are",
+        "behind are AGENTS.md, which briefs every agent working here, and",
+        "docker-compose.yml, which can serve a dev stack that disagrees with the",
+        "checkout the boundary lint reads.",
         "These are seeded once and then the app's, so a re-render leaves them alone:",
         *(f"  {name}" for name in _APP_OWNED_SCAFFOLD_FILES),
+        # Suppressed when a recipe above already numbered the re-render as a step: the
+        # same command printed twice in one report reads as two different things to do,
+        # and the recipe's copy is the one with the tree-cleaning step before it.
+        *(
+            [
+                "",
+                "  Re-render:  copier update  (or the Studio's upgrade flow, which "
+                "records the",
+                "              answers file it needs).",
+            ]
+            if include_command
+            else []
+        ),
+    ]
+
+
+def _has_template_provenance(root: pathlib.Path) -> bool:
+    """Whether ``copier update`` can run here at all.
+
+    It needs the answers file copier writes at render time; without one there is no
+    recorded template and no answers to re-render from, so the only way to move an app
+    forward is by hand. That is the whole reason the recipe below has two shapes.
+    """
+    return scaffold_ref(root) is not None
+
+
+def _rerender_recipe(target: str, current: str, count: int) -> list[str]:
+    """The upgrade for an app the template rendered: re-render first, sync once.
+
+    The order used to be the other way round and could not be followed as printed.
+    Steps 2 to 4 were "edit the pins, uv sync, npm install", and the re-render came
+    after them — but ``copier update`` refuses a dirty tree, so the recipe's own
+    earlier steps made its last step impossible, and whoever followed it had to stash
+    halfway through.
+
+    Worse, those pin edits were work the re-render does. The template owns
+    ``pyproject.toml``, ``frontend/package.json`` and ``conformance/package.json``, so
+    a re-render writes every one of those pins itself. The old recipe even warned that
+    "a recipe that names only one is how the other goes stale" — which is an admission
+    that the hand-pinning step was a footgun, for a job already done one step later.
+
+    So: read, clean the tree, re-render, resolve, sync once, confirm, verify.
+    """
+    return [
+        "",
+        f"All {count} packages can move to {target} together. Re-render FIRST — the",
+        "template owns pyproject.toml and both npm manifests, so the re-render writes",
+        "every pin itself, and it refuses to run on a tree with uncommitted changes:",
+        "",
+        f"  1. Read what changed:  uvx --from terp-cli=={target} terp guide changelog",
+        f"     (the {target} notes; the copy installed here ends at {current}).",
+        "  2. Commit or discard what you have. A re-render on a dirty tree is refused,",
+        "     and its own diff is much easier to review on its own.",
+        "  3. copier update          (or the Studio's upgrade flow, which records the",
+        "     answers file it needs). This rewrites EVERY file the template owns and",
+        "     writes the terp-* and @terpjs/* pins for you.",
+        "  4. Resolve what it reports. Two conflicts are structural rather than bad luck,",
+        "     because the template owns the file and your app also writes to it:",
+        "       pyproject.toml            keep your dependencies, take the terp-* pins.",
+        "       control_plane/operations.py  the capability folding is the template's;",
+        "                                 your own operations belong in",
+        "                                 control_plane/app_operations.py, which no",
+        "                                 re-render touches (ADR 0130).",
+        "  5. uv sync --refresh && npm --prefix frontend install",
+        "     (once, now that the manifests are final — not before the re-render.)",
+        "  6. uv run terp --version          (confirm the set agrees)",
+        "  7. uv run terp verify --profile full",
+        "",
+        "  Running the dev stack in containers?",
+        "  Rebuild it rather than reloading into it: the images bake the terp packages",
+        "  in while the source is bind-mounted, so correct new code reloads against old",
+        "  libraries and dies on an import nowhere near its cause. `terp docker dev`",
+        "  rebuilds on a pyproject.toml change; a plain `docker compose up` does not,",
+        "  and `terp verify` now refuses the skew either way.",
         "",
-        "  Re-render:  copier update  (or the Studio's upgrade flow, which records the",
-        "              answers file it needs).",
+        "A green gate proves the upgrade did not break this app. It cannot prove the",
+        "release did not change something this app should adopt — step 1 is the only",
+        "thing that answers that.",
+    ]
+
+
+def _hand_pin_recipe(target: str, current: str, count: int) -> list[str]:
+    """The upgrade for an app with no recorded template: every pin by hand.
+
+    No answers file means ``copier update`` has nothing to re-render from, so the pins
+    the template would have written have to be written here instead. Kept in full for
+    exactly that case and printed nowhere else — an app the template rendered is told
+    to re-render, because doing both is what produced two needless installs.
+    """
+    return [
+        "",
+        f"All {count} packages can move to {target} together. This app records no",
+        "template answers file, so `copier update` has nothing to re-render from and",
+        "the pins have to be written by hand:",
+        "",
+        f"  1. Read what changed:  uvx --from terp-cli=={target} terp guide changelog",
+        f"     (the {target} notes; the copy installed here ends at {current}).",
+        f"  2. Pin every terp-* dependency to =={target} in pyproject.toml",
+        "     (including the dev group — a forgotten pin is a mixed install).",
+        f"  3. Pin every @terpjs/* package to ^{target} in EVERY manifest that",
+        "     declares one — frontend/package.json AND conformance/package.json",
+        "     (a recipe that names only one is how the other goes stale).",
+        "  4. uv sync --refresh && npm --prefix frontend install",
+        "  5. uv run terp --version          (confirm the set agrees)",
+        "  6. uv run terp verify --profile full",
+        "",
+        "A green gate proves the upgrade did not break this app. It cannot prove the",
+        "release did not change something this app should adopt — step 1 is the only",
+        "thing that answers that.",
     ]
 
 
@@ -337,24 +449,16 @@ def render_upgrade_check(root: pathlib.Path | None = None) -> str:
     # to help judge. `uvx --from terp-cli==target` resolves an ephemeral CLI from
     # the same index (terp-cli pins terp-core exactly, so the right CHANGELOG
     # comes with it) without touching this app's environment or its pins.
-    lines += [
-        "",
-        f"All {len(landing)} packages can move to {target} together:",
-        "",
-        f"  1. Read what changed:  uvx --from terp-cli=={target} terp guide changelog",
-        f"     (the {target} notes; the copy installed here ends at {current}).",
-        f"  2. Pin every terp-* dependency to =={target} in pyproject.toml",
-        "     (including the dev group — a forgotten pin is a mixed install).",
-        f"  3. Pin every @terpjs/* package to ^{target} in EVERY manifest that",
-        "     declares one — frontend/package.json AND conformance/package.json",
-        "     (a recipe that names only one is how the other goes stale).",
-        "  4. uv sync --refresh && npm --prefix frontend install",
-        "  5. uv run terp --version          (confirm the set agrees)",
-        "  6. uv run terp verify --profile full",
-        "",
-        "A green gate proves the upgrade did not break this app. It cannot prove the",
-        "release did not change something this app should adopt — step 1 is the only",
-        "thing that answers that.",
-    ]
-    lines += _scaffold_lines(project_root, target)
+    # Which recipe depends on whether copier can run here at all: an app the
+    # template rendered re-renders and gets its pins written for it, and an app with
+    # no answers file writes them by hand. Printing both, or the hand-pin one to an
+    # app that could re-render, is what produced two needless installs and a stash
+    # halfway through.
+    if _has_template_provenance(project_root):
+        lines += _rerender_recipe(target, current, len(landing))
+    else:
+        lines += _hand_pin_recipe(target, current, len(landing))
+    lines += _scaffold_lines(
+        project_root, target, include_command=not _has_template_provenance(project_root)
+    )
     return "\n".join(lines)