@intentius/behold 0.13.1 → 0.15.0

package/AGENTS.md

@@ -54,6 +54,13 @@ preview-locked, and one load runs at a time (409 otherwise).
    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`/`run`/`pr`.
+   With `?components=1&env=`, each component node carries `_liveStatus` (the
+   `chant components status` verdict) and, when the release ledger recorded
+   one, `_release` — `{runId, forge, originSource, url?, gitSha, digest,
+   timestamp, actor, approver?}` (#165). `url` is present only when the record
+   itself carries an address (chant#2045); `originSource: "inferred"` means
+   behold read the id's spelling and nothing more, and a `forge: "unknown"` id
+   is never resolved to a link on behold's guess.
    `?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
@@ -164,13 +171,35 @@ 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)
+## The operating loop (a strip, a timeline, 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.
+`records.at(-1)` — so the strip is never a timeline, and it says so.
+
+The timeline is its own read: `GET /api/operator/log` → `chant operator log
+--json` (chant#2029), the tick records and the gate resolutions against them
+merged oldest-first. It lives in a panel that grows from the strip, and two rules
+hold it there. It is **pulled**, on the click that opens it and never on a timer.
+And it is **bounded** — `--limit` on every invocation, 50 by default and 200 at
+most, `--since` when asked — because the ledger grows one line per tick forever;
+the answer reports the window it used, so a full one can't read as the end of
+history. The route checks the project's chant version *before* it spawns: below
+0.53.1, `chant operator log` resolves to `chant operator`, the tick daemon, and
+behold reading a history must never become behold running an operator.
+
+Since chant 0.53.1 (chant#2027) a tick record carries an `id` and the
+per-component verdicts it derived, and both ride through to
+`[].lastTick.{id,components}`. The strip line names the tick (truncated), and
+the verdicts join onto the component DAG by component name — the same key the
+live `chant components status` read is joined by. They join **under** that read:
+a tick only ever feeds the last tier of `componentStatusColor` (the
+reconciliation verdict), only on a node the live read left unpainted, and only
+while the tick is younger than fifteen of chant's own operator rounds. Past
+that it is named on the node, dated, and painted nothing — a graph fill has
+nowhere to put "as of an hour ago". A chant older than 0.53.1 sends neither
+field and every one of these paths is a no-op.
 
 Two gate cards exist and they are **different acts**:
 
@@ -182,10 +211,16 @@ Two gate cards exist and they are **different acts**:
   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.
+A gate fact carries its address since chant#2028, on both halves, and the card
+links it under chant's own words — `approve at: <url>`. The field is optional by
+design (a local tick with no PR behind it has none) and never synthesized, so a
+fact without one renders no link and no placeholder for one, and a url behold
+would not put behind an `href` reads as no address at all.
+
+A gate someone already resolved simply leaves `pendingGates` — the status read
+carries no `resolvedBy`/`when` — so the strip shows no resolved-by line rather
+than attributing an approval to nobody. The timeline is where resolutions are
+named, because there they are records rather than an inference.
 
 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
@@ -229,3 +264,39 @@ own Terraform is not edited either. The only request-derived value is `select`,
 and it must be an address the served report already ranks — the value that
 reaches the spawn's argv comes from a closed set read off disk. No cloud write,
 no Terraform mutation, no edit to anyone's chant source.
+
+## Changing behold (for agents working on this repo)
+
+The sections above are about driving a running behold. This one is about
+changing it — the working rules that used to live in a handoff note and now
+live here, with the enforceable ones enforced.
+
+- **Branches and merges.** Work on a branch off `main` (an isolated worktree
+  when more than one agent is active). `main` is protected by a ruleset: every
+  change arrives as a PR, and the `check` job in `ci.yml` must be green before
+  it merges. A check that has merely settled is not a pass — read the lines.
+  No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
+  next onto what landed.
+- **The local gate** is `just check` (tsc, tests, build). `just test` keeps
+  the reporter's full output in `vitest.log`, because #334's one-shot
+  first-run failures kept losing the failing file's name — if the suite fails
+  once and passes on rerun, the log from the first run is the evidence; attach
+  it to #334.
+- **Releasing** is `just release`, after the version-bump PR merged: it tags
+  `behold-v<version>`, pushes the tag (which is what runs `release.yml`), and
+  waits for npm to show the version. It refuses in every state where a tag
+  push would be wrong. Never re-push a `behold-v*` tag by hand — a tag push
+  re-fires publish. Tags absent from origin (behold-v0.10.0, 0.10.1) stay
+  absent for that reason.
+- **Scratch infrastructure** is governed by `src/scratch.ts`, asserted by
+  `scratch.test.ts` across every boot site: anything behold boots is named
+  `behold-*`, refuses if the name is taken, tears down only what it created,
+  and never binds the shared emulator ports. The protected names — `floci*`,
+  `chant-floci*`, the kubemicrovm and fountain k3d clusters, :4566 — are
+  listed there, not in prose. A new boot site calls `assertScratch` before
+  its spawn and gets a row in the test.
+- **The write boundary** is the Invariant section above. Apply is never a
+  button; `/api/carve/apply` does not exist and the route test asserts it
+  stays that way.
+- **chant's working rules** (its single-lane checkout, its release path) are
+  chant's and live in chant's repo, not here.