@intentius/behold 0.11.0 → 0.13.0

package/AGENTS.md

@@ -53,7 +53,20 @@ preview-locked, and one load runs at a time (409 otherwise).
    `?env=`, `/api/overlay` is the live entity overlay; `/api/diff?env=` slices
    per-node observed state, drift and field ownership; `/api/reconcile?env=`
    summarizes the pending change set; `/api/substrates` reports substrate
-   readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`pr`.
+   readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`.
+   `?ops=1` is the ops lens — the project's declared Ops as a phase track, read
+   from each emitted `dist/ops/<name>/op.json`, with the current run painted
+   over it (`meta.run`, `meta.gate`); `/api/ops/<name>/status` reads that Op's
+   durable run status and pending gate (`chant run status --temporal`). A
+   `ConvergeOp` also gets one card per rule from its `convergeTick` step's
+   `args.rules` (`attrs._step: "rule"`), carrying `when` (chant's JSON predicate,
+   rendered as the condition it states), `then`, and the `why` chant requires of
+   every rule, verbatim. `then: run(<op>)` is an edge to that Op's first step
+   when the Op is in the rendered set, and `attrs.dangling` when it isn't.
+   `meta.operator` on that same lens names the ConvergeOps the project declares
+   (chant's own `searchAttributes.Converge === "true"`, read from op.json — no
+   subprocess), and `/api/operator/status` fills the strip in from
+   `chant operator status --json`.
 2. **focus** — narrow with chant graph options as query params: `?detail=0..3`,
    `?components=1`, `?logical=1`, `?lens=blast:<id>&down=1`, `?lens=lexicon:aws`,
    `?env=`, `?stack=`, `?tier=`, `?target=`.
@@ -74,6 +87,32 @@ To move a resource: confirm its band on `/api/carve`, then run chant's own
 applying the generated survivor rewrites stay a human gate — behold has no
 endpoint that writes Terraform, and adding one would break the invariant below.
 
+### Carve state, from chant's manifests (#230 M3)
+
+chant ≥ 0.52.2 writes `<address>.carve.json` into `carve emit --output`; `carve
+bridge` and `carve apply` add their own records to the same file. behold reads
+those and never writes one, so the progression is on disk rather than in a
+session.
+
+`GET /api/project`'s `carve.state` publishes it: `{manifests, progress:
+{applied, bridged, emitted, inFlight, total, label, detail}, states[], apply:
+{human, note}}`. Each entry carries `target`, `stage`
+(`emitted`/`bridged`/`applied`), `graduated`, `note` and a retypeable
+`applyCommand`. The same field appears on an ordinary `behold serve` whose
+project directory carries a carveout — no report and no demo needed — and is
+absent entirely when nothing has been carved.
+
+In the graph, an `applied` address draws inside the chant member box (keeping
+its Terraform address as its node id) instead of in a band; `emitted` and
+`bridged` stay banded with `attrs._status: "accent"` and the stage in
+`attrs.carve`. Only `applied` means ownership moved.
+
+**There is no `/api/carve/apply`.** `chant carve apply` graduates ownership;
+behold renders what the manifest records and echoes the command. Do not add the
+endpoint — src/carve-manifest.ts `APPLY_IS_HUMAN` is the statement of it, and
+src/carve-actions.ts and src/server.ts both carry the refusal where the route
+would go.
+
 ### The walkthrough (`behold demo carve`, #254)
 
 `behold demo carve` copies a bundled half-migrated estate (a chant project
@@ -117,6 +156,42 @@ behold does not apply. To change the estate:
 Every mutation is a gated, durable Temporal workflow with a human-confirmable gate
 and saga rollback. There is no behold endpoint that mutates the cloud.
 
+A run behold triggered is asked for structured per-step records (chant#1676:
+`--progress-json` on the durable path, `--json` on the local one), so the ops
+lens paints the run over the declared track and a pending gate renders as a card
+with an Approve button. That button is `op-signal` — the same delegated write —
+and nothing else about the run is behold's to decide: a stream that dies leaves
+the playhead at the last settled step and says so, and a gate paints as pending
+only when chant's `gateState` query named it.
+
+## The operating loop (a strip, and a gate that is not the run gate)
+
+A project that declares a `ConvergeOp` gets an operator strip on the ops lens:
+per loop, the last tick's own log line (verbatim, with its instant), the lease,
+and how many gates are pending. **One** tick — `chant operator status` keeps only
+`records.at(-1)` and no CLI exposes the history (chant#2029), so this is a strip
+and never a timeline; the statusbar says so rather than leaving you to assume.
+
+Two gate cards exist and they are **different acts**:
+
+- The **run gate** — `POST /api/ops/:name/signal/:gate` → `chant run signal`.
+  Releases the waiting Temporal workflow.
+- The **converge gate** — `POST /api/operator/approve/:op/:gate` →
+  `chant approve <op> <gate>`. **Records a fact and unblocks nothing.** chant's
+  gate ledger says it outright: the local executor still refuses a gated op,
+  resolution or not. The next tick reads the fact. The card says this in its
+  body, and the toast after the click says "recorded; the next tick acts on it".
+
+A pending gate fact carries no URL (chant#2028), so the card renders no link and
+no placeholder for one. A gate someone already resolved simply leaves
+`pendingGates` — the status read carries no `resolvedBy`/`when` — so behold shows
+no resolved-by line rather than attributing an approval to nobody.
+
+An `OperatorStack` (chant#1940) declares the loop as a k8s estate, so it already
+appears in the entity graph. behold names it there — the Namespace as the loop's
+home, each CronJob as a converge tick — off chant's own
+`app.kubernetes.io/component: converge-tick` labels, never a naming convention.
+
 ## Invariant
 
 If a request would have behold write to a cloud or to source directly, it's wrong.