@intentius/behold 0.32.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -1,3155 +1,86 @@
1
- # Driving behold (for agents)
1
+ # behold for agents
2
2
 
3
- behold is a **read-only control plane** over a chant estate, with **delegated,
4
- gated** writes. As an agent you drive it the same way a human does, and the
5
- mutating capabilities are chant's MCP Op tools, not behold's, so nothing here holds
6
- apply creds.
3
+ Working in the INTENTIUS workspace, `../agents/shared.md` applies too.
7
4
 
8
- ## The division of labour
5
+ behold is a read-only control plane over a chant estate. It draws the live,
6
+ mixed-substrate graph and starts delegated, gated commands; it never holds
7
+ apply credentials. This file ships in the npm package and `GET /api` links to
8
+ it, so the first half is for agents driving a running behold and the second
9
+ for agents changing this repo. Route and feature detail lives in
10
+ docs/src/content/docs/using/ (agents.mdx first) and in `GET /api`, not here.
9
11
 
10
- - **behold** serves the live, mixed-substrate graph (and, later, the deployment-lanes
11
- timeline). It reads; every write it offers is a command it starts (an Op, a
12
- `chant run`, a forge dispatch), and on a terragucci or SQL Yodeler repo it
13
- starts none.
14
- - **chant's MCP** is where the real capabilities live. Prefer it over shelling.
15
- - Reads: `lifecycle-diff`, `lifecycle-snapshot`, `build`, `lint`.
16
- - Actions (delegated writes): `op-run` (start an `ApplyOp`/`ReconcileOp`),
17
- `op-signal` (approve a gate), `op-status` / `op-report` (watch it).
12
+ ## Driving a running behold
18
13
 
19
- ## A declared workspace
14
+ - Before a server exists, or when a route errors: `npx @intentius/behold doctor <dir> --json`. Read-only, exits non-zero if a check failed, each check carries a `fix`.
15
+ - Start one with `npx @intentius/behold serve <dir> --port 4600`. `GET /api` lists the routes with a one-line description each.
16
+ - Read with `GET /api/graph` (`{ir, svg, meta}`) and `GET /api/overlay?env=<env>`, the live entity overlay. Each node's `sourceLoc.file` is the source that declared it. A failed precondition answers `{code, error, remedy}`; branch on `code`.
17
+ - To change the estate, edit that chant source or run a committed Op through chant's MCP (`op-run`, `op-signal`, `op-status`). behold's own mutating routes only start Ops the project committed; none writes a cloud or Terraform directly, and none should be added.
20
18
 
21
- A directory with a `chant.workspace.json` is a chant workspace (chant ≥ 0.81.0,
22
- INTENTIUS/chant#2524). `behold serve <root>` serves it from chant's own member
23
- list (`chant workspace ls --json`, read contract 1; any other contract is
24
- refused), and reads each `chant`, `terraform`, `choudoufu` and `pulumi` member through
25
- `chant workspace graph --member <name>`. A `choudoufu` member takes its block
26
- graph from it (the estate's own edges, each block's `file` and `line`) and
27
- joins it onto choudoufu's `live-check` roster, which still names the cards,
28
- the rungs and the cross-estate references: chant's graph is one node per
29
- block, ownership is per instance, and chant carries no rung or reference
30
- (src/choudoufu-workspace.ts, #465). The ids are the roster's, as before, so a
31
- saved layout keeps matching. behold's own lexicon read of a choudoufu
32
- directory stays for a loose view only. A `pulumi` member (#994) is read through
33
- the same `workspace graph --member` and nothing else: chant reads the `pulumi
34
- stack export` checked in beside its Pulumi.yaml as stack-export.json, so its
35
- cards are the export's resources, edged by `parent` and `dependencies`. behold
36
- has no reader of its own for the kind, keys on the kind string and not on the
37
- lexicon that supplies it, and sends it no live read: chant has none, so the
38
- overlay draws it neutral with `_unobserved` saying so (`pulumiWorkspaceVia`,
39
- src/workspace.ts; the fixture is e2e/fixtures/pulumi-workspace, the e2e
40
- `just e2e-pulumi-workspace` and src/pulumi-member.test.ts). Node ids are `<member>/<id>` with the declared member name, the same
41
- form chant composes. A member chant cannot read is drawn as one
42
- `UnreadableMember` node carrying `attrs._unreadable: {code, message}` with
43
- chant's reason code. An `other` member is listed on startup and in doctor and
44
- draws nothing. A declaration with `members: []` (terragucci writes one for its
45
- gates) declares nothing to draw, so serve, export and doctor read the
46
- directory as they would without one, and say so (#489). `.behold.json`'s `members` are ignored beside a declaration;
47
- `behold doctor --fix` writes the declaration for an estate that has only them.
48
- A `kustomize`, `argo-app`, `flux-kustomization`, `helm-chart` or `cloudformation`
49
- member is read the same way (#1056), and the detail tier of a read is passed on
50
- as `--detail` (chant 0.124.35, `WORKSPACE_DETAIL_CHANT_FLOOR`). The kinds come
51
- from the k8s, helm and aws lexicons the workspace pins (chant 0.124.49,
52
- `WORKSPACE_KINDS_CHANT_FLOOR`). At chant's default detail a k8s node carries only
53
- `apiVersion` and `kind`; the Argo and Flux path edges of src/estate-edges.ts need
54
- `spec`, which comes at detail 3. A lens, `up`, `down` and a namespace stay on the
55
- member's own `chant graph`. A kustomize member needs `kustomize` or `kubectl` on
56
- PATH and a helm-chart member needs `helm`. The fixture is
57
- e2e/fixtures/k8s-workspace and the test src/k8s-member.test.ts.
58
- Several directories on the command line (`behold serve a b c`) stay the loose
59
- view behold composes itself.
19
+ ## Changing behold
60
20
 
61
- Every workspace read goes through one module, `src/workspace-reader.ts`: one
62
- chant call per read, the document handed back as chant printed it, any
63
- contract but 1 refused. chant's reader conformance suite
64
- (`@intentius/chant/workspace/conformance`) runs against that module in `npm
65
- test` (`src/workspace-reader-conformance.test.ts`, #468), so a new workspace
66
- read is added to the reader and to the suite's `commands`, never shelled from
67
- somewhere else.
21
+ ### The write boundary
68
22
 
69
- `GET /api/workspace/why?member=<name>` or `?node=<member>/<id>` (#471) answers
70
- why a member or a card is the way it is, from `chant workspace graph --intent
71
- <region> --json` (chant 0.102.0 or newer writes its `why`): the decisions
72
- covering it in chant's order, the agent runs and the commits behind it, and the
73
- gaps chant names. The region is the member's declared directory or the node id,
74
- never a path from the caller. It takes seconds on a small workspace and tens of
75
- seconds on a large one, so the inspect pane reads it only on a click, and it is
76
- a scheduled read: it holds a slot in the read budget, has the read deadline,
77
- and stops when the request does. `serve --hud <url>` (or `BEHOLD_HUD_URL`)
78
- links a proposed decision to its review in hud.
23
+ behold writes nothing in a served project. Its own state (hand layout,
24
+ per-user settings, CI run ids, the serve registry) goes in the user's cache,
25
+ home or temp directory, keyed by project. The only exceptions are
26
+ `behold doctor --fix` writing `chant.workspace.json`, the carve demo steps
27
+ writing inside the demo copy behold made, and `behold export --publish`.
28
+ There is deliberately no `/api/carve/apply` and no `/api/choudoufu/mv`;
29
+ route tests assert they stay absent.
79
30
 
80
- ## A folder with no declaration, read by its kinds' probes (behold#1079)
31
+ On a terragucci repo (`terragucci.yml`) or SQL Yodeler repo
32
+ (`yodel.config.ts`), every non-GET route answers 409 unless it is listed in
33
+ `TERRAGUCCI_ALLOWED_WRITES` (src/terragucci-repo.ts). A new write route is
34
+ refused there until you add it; src/terragucci-repo.test.ts walks every route.
81
35
 
82
- `chant workspace graph <dir> --discover` (INTENTIUS/chant#5095) finds the members
83
- of a directory that has no `chant.workspace.json`: the kinds' probes claim
84
- directories, a directory a local `module` source calls or that sits inside
85
- another member is not a member of its own, and two kinds claiming one directory
86
- at the same precedence is a tie that is not read. The document is a contract 1
87
- graph with one more field, `discovered[]`, one entry per claimed directory
88
- (`dir`, `member`, `kind`, `source`, `probe`, `outcome`, `claims`, `note`).
89
- Member names are the lowercased path with runs of characters a name cannot
90
- hold turned to `-`, and `.` is `root`, so node ids and `member=` links in a
91
- discovered folder carry those names, not the folder's name.
36
+ ### Reading chant
92
37
 
93
- src/discover-read.ts reads it through `src/workspace-reader.ts`, one chant call
94
- per folder, and `readGraph` (src/read-graph.ts, signature unchanged) turns the
95
- document into the `Workspace` a declaration would give. Each member then takes
96
- its part of that one document (`discoveredVia`), so the estate code composes a
97
- discovered folder exactly as it composes a declared workspace, including an
98
- unreadable member drawn as a box with chant's reason. The note names each tied
99
- directory and counts the directories left out as modules or inside a member.
100
- A list of one path is read as that folder, which is how the server hands it
101
- over; `behold serve`, `behold shot` and the server treat a folder this applies
102
- to as an estate (`discoverAppliesToList`). The overlay, search and the other
103
- per-member reads still go to the folder as they did.
104
-
105
- The floor is `WORKSPACE_DISCOVER_CHANT_FLOOR`, 0.124.98 (src/chant-floors.ts):
106
- chant#5095 is on chant's main after the 0.124.97 freeze. Below it, or when the
107
- chant's version is unknown, nothing here runs and a folder is read as before.
108
- `CHANT_RELEASE` (src/chant-release.ts) is not moved by this: that is a
109
- maintainer step once 0.124.98 is on npm.
110
-
111
- Which folders go through it is a measured choice, not "all of them". On the
112
- `infra/` tree of a Kubernetes project checkout (52 Terraform roots, 2
113
- CloudFormation templates, 1 manifests directory), behold's own Terraform reader
114
- takes 3.5 s cold and 72 ms on a reread, because one chant reads one generated
115
- project naming every root. `--discover` runs a reader per member: 44 s cold,
116
- 6.8 s on chant's member cache, 55 members. So the default (`auto`) discovers a
117
- folder behold cannot draw (no member kind claims it: Kubernetes, Helm) or draws
118
- only half of (a Terraform or choudoufu folder that also holds Kubernetes or
119
- Helm files), and leaves a Terraform or choudoufu folder with none on its own
120
- reader. A chant project is never discovered. `BEHOLD_DISCOVER=always|never|auto`
121
- overrides it. Because the Terraform scratch project (`behold-tf-*`) stays the
122
- reader for those folders, and the plan read, choudoufu, behaviour and search
123
- (`behold-tfws-*`) write it too, `writeTerraformScratchProject` and its tests
124
- stay.
125
-
126
- ## Chant version floors (behold#691)
127
-
128
- behold shells each project's own chant, so a read can reach a chant that
129
- predates it. Every read has one floor, and every floor lives in
130
- `src/chant-floors.ts`:
131
-
132
- - one constant per read, named after the read (`WHY_CHANT_FLOOR`) and set to the
133
- chant release that adds it;
134
- - one entry in `CHANT_FLOORS` (the read in words, the floor, what adds it in
135
- chant), which is what `behold doctor` lists with the project's chant version
136
- and whether the floor is met;
137
- - the code that makes the read checks the project's chant first (`floorMet`,
138
- `floorRefusal`) and never sends the read to a chant that would reject it.
139
-
140
- On an older chant the pane that needs the read shows `floorRefusal`'s words
141
- (the read, the chant that adds it, the project's version) and the rest of
142
- behold works. The why route does this: `GET /api/workspace/why` refuses before
143
- spawning the read. A new read adds its constant and entry in the issue that
144
- adds the read, once the chant release is known, and reads through the read
145
- contract (`src/workspace-reader.ts`), never chant's library.
146
-
147
- ### The chant release behold follows (behold#1005)
148
-
149
- `CHANT_RELEASE` in src/chant-release.ts, `{ version, released }`, names the
150
- chant release behold's newest reads need. It says `{ version: "0.124.58",
151
- released: true }`: chant 0.124.58 is on npm (0.124.54 was the first release with the
152
- drift record and its stream, the adoption report, `member-outputs` and
153
- `@intentius/chant-lexicon-pulumi`; 0.124.58 adds the self-service modules). `ADOPTION_REPORT_CHANT_FLOOR`,
154
- `DRIFT_RECORD_CHANT_FLOOR`, `DRIFT_STREAM_CHANT_FLOOR` and
155
- `LEDGER_ROOT_MEMBER_CHANT_FLOOR` are its `version`, which is chant's
156
- `NEXT_RELEASE` (INTENTIUS/chant#4480) at the cut. scripts/chant-release.ts
157
- writes the files the switch decides (src/chant-release-sync.ts lists them):
158
- the exact terraform and pulumi lexicon pins of example-terraform-estate,
159
- example-choudoufu-estate and e2e/fixtures/pulumi-workspace (the published
160
- chant, `PUBLISHED_CHANT`, while unreleased, so a plain `npm ci` meets them,
161
- and `version` once released, moving with the floors; behold#1015), the
162
- three-cloud workspace's pins (by path while unreleased, by package and
163
- version once released) and its package.json, and behold's own chant ranges,
164
- the pulumi lexicon devDependency among them. src/chant-release.test.ts holds
165
- them to the switch, and `npx tsx scripts/chant-release.ts --check` lists any
166
- file out of step.
167
-
168
- With the release out, behold imports what it once copied from chant:
169
- src/drift-line.ts decodes with `@intentius/chant/drift-record` (keeping
170
- behold#995's unknown-status rule on top), src/graph-db/types.ts, listing.ts
171
- and mask.ts re-export chant's engine-facts, index-document, cloud-lister and
172
- mask modules, the investigation templates come from
173
- `@intentius/chant/capabilities/templates` with no stub, the index diff is
174
- `@intentius/chant/lifecycle/index-diff`, and `behold index` calls chant's
175
- `runCloudIndex` statically. src/value-match.ts stays until the pulumi
176
- lexicon has a `referenceCatalog` (chant#4535's note on behold#1005).
177
-
178
- ## chant's reference catalog (behold#1080)
179
-
180
- A declared workspace read by a chant at `REFERENCE_CATALOG_CHANT_FLOOR`
181
- (0.124.98, the release that carries INTENTIUS/chant#5097; 0.124.97 is on npm
182
- today) gets one more read: `chant workspace graph <root>` for the whole
183
- workspace, at the tier the members are read at (src/reference-catalog.ts,
184
- cached under the workspace's source stamp). A read of one member cannot see a
185
- reference into another, so the per-member reads' `dangling` entries that carry
186
- a `rule` are replaced by this read's, and its derived edges, `dangling[]`,
187
- `ambiguous[]` and `catalog.rules` go on the composed IR (`ir.catalog`). The
188
- floor is checked first; below it nothing is sent and the estate is composed as
189
- before. `readGraph` does this, after behold's own edge passes and before the
190
- cluster anchor.
191
-
192
- src/catalog-draw.ts draws it, after the stacking (`graphView` and the estate
193
- branch of `/api/graph` call `drawCatalog`). A catalog edge is weighed "joined"
194
- (web/edge-weight.js, `isCatalogEdge`), apart from "inferred", and the weight
195
- and the rule are stamped on the SVG's edge (`data-edge-weight`,
196
- `data-edge-rule`) with inline strokes, so a static export keeps them. A
197
- dangling reference whose rule is not containment is a dashed placeholder card
198
- (kind of the `targetKind`, lexicon `behold`, `attrs._placeholder` the value, one
199
- per member, kind and value), and an ambiguous one is a dotted edge to each
200
- candidate with `viaAttr` "one of N". The picture ends with the key; the answer's
201
- `meta.catalogLegend` has the same rows for the page, which hides the in-SVG one
202
- and draws its own. The graph document keeps `rule`, the one field: chant's rule
203
- id on a joined edge, and the reference's rule on the placeholder and ambiguous
204
- edges.
205
-
206
- The cluster anchor (src/cluster-anchor.ts) reads the join: a member whose
207
- Applications name a cluster Secret that chant joins to one cluster resource
208
- anchors its objects to that cluster only; a Secret with no match, two matches,
209
- or a member that reaches several clusters anchors nothing and puts the reason
210
- in the note (`ir.anchorNotes`). A member without a cluster Secret keeps the
211
- guess. The fixtures are `chant workspace graph --discover --json` recorded
212
- from a chant checkout at the catalog and its rules (e2e/fixtures/
213
- reference-catalog), the tests src/catalog-draw.test.ts and
214
- src/catalog-route.test.ts.
215
-
216
- ## A pipeline's numbers, from Prometheus (behold#571)
217
-
218
- `behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
219
- /api/metrics?project=<owner>/<name>[&commit=<sha>]` (src/prometheus-metrics.ts).
220
- behold asks a FIXED set of named queries over terragucci's gauges (each a
221
- constant string, nothing from the request in it), shares one read for 30 s,
222
- and picks the repo's series out of the answers: one commit's tf-apply waves
223
- (the wave job's own time first, then each root's init, plan and apply
224
- seconds and any state lock wait, in milliseconds below a second on the
225
- kiosk, the time an approval held the wave at
226
- its gate, the changes it applied, when it started waiting) and the DORA four,
227
- from terragucci estate's gauges or its `dora.json` beside the reports. It
228
- answers numbers, never a proxy, and a public serve keeps it (GET). Without
229
- an address it answers 404. The kiosk's "Pipeline metrics" pane
230
- (web/kiosk-metrics.js) shows only what it returns, and no pane when it
231
- returns nothing for the repo.
232
-
233
- ## Runs from chant's run index (behold#815)
234
-
235
- `behold serve --ci-report-url <url>` (or `BEHOLD_CI_REPORT_URL`) points the
236
- kiosk's runs pane at chant's run index, `<url>/runs/index.json`
237
- (ci-run-index/v1, floor `CI_RUN_INDEX_CHANT_FLOOR`, 0.124.31), instead of the
238
- forge's runs (src/ci-run-index.ts). The text goes through
239
- `ciRunIndexOf` in src/workspace-reader.ts (contract 1), then the floor against
240
- the index's own `chant`, then the vendored schema
241
- (src/ci-run-index-schema/, chant commit in `CI_RUN_INDEX_SCHEMA_SOURCE`) with
242
- its `status` and `job` enums left out, since v1 adds to them. An entry the
243
- schema refuses, or whose key is not `<pr>/<commit>[/<member>]`, is dropped and
244
- listed in `skipped`. `GET /api/chant/ci/runs` answers the runs in demo.runs/v1
245
- shape; `GET /api/chant/ci/runs/:runId` reads that entry's
246
- `pr-<job>.events.jsonl` and `pr-<job>.json` under its key only and builds the
247
- log with `demoRunOf` (src/chant-demo.ts). No events file is one step saying
248
- so. An apply refused with `plan-changed`, `not-approved` or a wave's
249
- equivalent exited 3 and is drawn waiting with "the plan moved or waits:
250
- re-plan and re-approve". So is an apply whose entry has `exitCode: 3` and a
251
- failure that isn't another refusal (#818; the field follows chant#4165, not
252
- merged, and isn't in the vendored schema; absent reads as before). `signer` shows only when it is a string; runOrigin's
253
- URL is the link, named by its host, never by `forge`. The page learns of it
254
- from `<meta name="kiosk-runs" content="chant-ci">` (web/kiosk-source.js
255
- `pageRuns`); only the runs pane switches, the cycle and approval panel read
256
- as before. #818: without the flag, a served workspace's declared
257
- `ci.reportUrl` (s3:// or file://, read from the `workspace ls` behold already
258
- makes, `declaredReportUrl` in src/workspace.ts, floor
259
- `CI_REPORT_URL_CHANT_FLOOR`, 0.124.32, chant#4160) is used, a memberless
260
- declaration included; the flag overrides it, and each answer's `urlFrom` says
261
- `flag` or `declaration`. With neither, nothing changes.
262
-
263
- A member of another kind in an estate's components picture (#997): chant
264
- writes its release ledger per component and a TerraformApplyOp writes no
265
- release, so a `choudoufu` or `terraform` member is one card,
266
- `<member>/<kind>` (lexicon `member-runs`, src/component-releases.ts), with
267
- every resource of the member under it. Its `apply` and `_lastApply` are the
268
- run index's newest `apply` entry for that member that passed (an entry with
269
- no `member` is a run of the whole workspace and is not taken as one), and
270
- its `since` and `_runSince` the newest entry after it, the member's or the
271
- workspace's, when that did not pass. A card the index names nothing of says
272
- `no runs recorded`, or `no run index read` when behold has no report URL;
273
- behold never makes one up. The members are read through the same
274
- `ciRunIndexOf` as the runs pane.
275
-
276
- The same card lists the member's local applies (behold#1010,
277
- src/member-local-applies.ts): the TerraformApplyOp runs that applied a root
278
- in the member's directory, from `chant ledger runs --where
279
- root_member=<member> --json` at the served workspace's root (chant#4482,
280
- chant#4500), as `_localApplies` (newest first, at most five) and `local`, the
281
- newest that passed. The read is sent only to a chant at
282
- `LEDGER_ROOT_MEMBER_CHANT_FLOOR`, and a `runs` table whose `columns` lack
283
- `root_member` reads as "this chant does not say", so the card keeps the run
284
- index alone. A null `root_member` is unknown (chant#4508): such a run is on
285
- no card, the declaring member's included, and the picture's note counts it
286
- as an apply of an unknown root with its `labels.TerraformRoot`, read with
287
- `--where labels.Apply=true`.
288
-
289
- ## Adopting a Pulumi stack into plunge (behold#999)
290
-
291
- A `pulumi` member of a declared workspace is offered adoption into plunge,
292
- the engine tier, through plunge's own `plunge stack adopt` (INTENTIUS/plunge#7,
293
- P-L4). The Adopt tab and `GET /api/adopt` say what it gains (a record per
294
- resource, marker tags, no stack lock, the checkpoint's IDs kept, a recorded
295
- adoption that a re-run leaves alone, a back-out through `plunge stack export`
296
- and `pulumi stack import`) and what it does not (plunge's refusals, bridged
297
- types classed at the first run, record-only ownership for untaggable types).
298
-
299
- - `GET /api/adopt/report?member=<name>[&stack=<name>]` runs `plunge stack
300
- adopt --stack <s> --json --non-interactive` in the member's directory, with
301
- `PULUMI_BACKEND_URL=plunge+<backend.url from Pulumi.yaml>`, no stdin and no
302
- `--yes`. That is plunge's read-only stage, as one v1 JSON document
303
- (INTENTIUS/plunge#17, plunge docs/plunge/ADOPT.md): every resource with its
304
- fate (marker, record, pending, already-adopted), having written nothing.
305
- Each resource gets its fate and why. When plunge refuses the adoption
306
- (pending operations, a provider hiding the markers, an aws-native
307
- create-only-tag type, foreign records), each refusal is listed with its
308
- code and the URN it names. behold reads the JSON view only (behold#1007).
309
- - `POST /api/adopt/start` `{member, stack?}` runs the same classification
310
- through the runner's `track` and answers the confirm command, `cd <dir> &&
311
- PULUMI_BACKEND_URL=<url> plunge stack adopt --stack <s> --yes`. A person
312
- runs it. behold never passes `--yes` or `-y`, drops
313
- `PULUMI_SKIP_CONFIRMATIONS` from the environment it hands plunge, and
314
- refuses any other plunge argv before spawning (`assertClassificationOnly`,
315
- src/pulumi-adoption.ts). After the confirm, point Pulumi.yaml's
316
- `backend.url` at `plunge+<url>` so chant runs the member through plunge.
317
- - The backend comes from the member's Pulumi.yaml only, never login state. A
318
- `file://`, `s3://`, `gs://` or `azblob://` URL is a DIY backend; a
319
- `plunge+` one is already plunge's. No URL, or a Pulumi Cloud URL, gets no
320
- start, and the offer says why. The stack is read off the checked-in
321
- `stack-export.json` URNs unless the request names one.
322
- - A plunge without the `stack adopt --json` view is detected from its answer
323
- (outcome `no-view`), not from a version, and refused with words naming
324
- plunge 968b54748d, the commit that adds the view.
325
- - The table is keyed on member kind (`ADOPTERS`, src/adoption.ts), the same
326
- names the Terraform half uses on integration/choudoufu-engine.
327
- `/api/adopt*` is refused in a public view, and the start goes through the
328
- terragucci and SQL Yodeler write allowlist.
329
- - Tests: src/pulumi-adoption.test.ts, web/adopt-pulumi.test.js, and the e2e
330
- `just e2e-adopt-pulumi` (e2e/adopt-pulumi-e2e.sh with the stand-in
331
- e2e/fixtures/adopt-pulumi/plunge), which asserts nothing is written before
332
- a person runs the confirm line, even with `PULUMI_SKIP_CONFIRMATIONS=true`
333
- in behold's environment.
334
-
335
- ## A plan job run locally (behold#685)
336
-
337
- `POST /api/chant/ci/local` `{job: "plan", commit, pr, env?, base?, member?,
338
- forge?}` starts `chant ci run plan --local --events-json --env <env> --base
339
- <sha> --commit <sha> --pr <n> --forge <forge>` (src/ci-local-run.ts, floor
340
- `CI_RUN_LOCAL_CHANT_FLOOR`, 0.124.32, chant#4161) in the workspace root or the
341
- named member's declared directory. Each value is checked; the commit and base
342
- are resolved by `git rev-parse` in the root, the base defaulting to where the
343
- commit leaves the trunk, the forge to the one workflow directory present. It
344
- runs through the runner's `track`, so it shares the one-command guard and the
345
- now-line, and is refused like an Op run: preview `403`, a terragucci or SQL
346
- Yodeler repo `409` (not allowlisted), `--public` `405` and its GETs `403`.
347
- stdout lines cross `readRunLine`; stderr is the step output, filed under its
348
- `[<phase>]`. `GET /api/chant/ci/local/:id` answers the run in demo.run/v1
349
- (`from: "chant-ci-local"`) and `ci`, CI's run of the same job, commit and
350
- member from the run index (`ciRunsRoutes`' lookup) when `--ci-report-url` is
351
- set. The SSE `local-run` event names a run that moved. The page's **Local** tab
352
- (web/local-run.js) draws both with kiosk-runs.js `renderRun`, and is not drawn
353
- in a public view, an embed, a static export, preview or a guarded repo.
354
-
355
- Apply is never started: `job: "apply"` answers `422 local-apply`.
356
- `--local` does not make an apply safe (it still changes real infrastructure
357
- and pushes release records and gate facts), and behold has no emulator notion
358
- that holds for it: `ci run` gives the job a clean environment that keeps HOME,
359
- so `serve --local`'s emulator env does not reach the job and the operator's
360
- own credentials would. Cached-step marks wait on chant#4015.
361
-
362
- ## Adopting a Terraform root into choudoufu (behold#999)
363
-
364
- A `terraform` member of a declared workspace is offered adoption into
365
- choudoufu, the engine tier, through chant's `chant workspace promote <member>
366
- --state <file>` (src/adoption.ts, floor `ADOPTION_REPORT_CHANT_FLOOR`, which
367
- is `CHANT_RELEASE.version` in src/chant-release.ts until the chant release
368
- carrying the report is cut; see "The coming chant release" below). The panel's
369
- **Adopt** tab (web/adopt.js) shows, per member, what the engine tier gives
370
- and what it does not, the command, and promote's report.
371
-
372
- - `GET /api/adopt`: each adoptable member's offer `{member, kind, dir,
373
- offered, engine, gains, limits, stateHint, state: {file, present},
374
- command, approve, recorded, start: {offered, why?}}`. A `pulumi` member is
375
- listed `offered: false` with `waits` (plunge P-L4, INTENTIUS/plunge#7):
376
- `ADOPTERS` and `ADOPTION_WAITS` are keyed on member kind, and the Pulumi
377
- half adds its adopter there.
378
- - `GET /api/adopt/report?member=<name>[&state=<file>]`: promote's read-only
379
- stage, `workspace promote <member> --state <abs> --dry-run --json`, through
380
- the reader (`readPromoteReport`, `PROMOTE_REPORT_READ`). chant stages in a
381
- throwaway worktree, runs `choudoufu live-check` and `live-import` without
382
- `-approve`, records no gate and leaves the tree as it was. Its `adoption`
383
- field (chant's `adoption-report.ts`, parsed from choudoufu's text) lists
384
- every resource instance; behold gives each a `fate`: `claimed` (VERIFIED,
385
- DRIFTED) or `left-out` (MISSING, UNTAGGABLE, UNADMITTED_TYPE), with a
386
- `why` and choudoufu's `detail`. An unknown status is listed as `unknown`,
387
- never dropped.
388
- - `POST /api/adopt/start` `{member, state?}`: the delegated write. It starts
389
- `workspace promote <member> --state <abs> --json` (never `--dry-run`,
390
- never `-approve`) at the workspace root through the runner's `track`.
391
- chant's gate decides: without an approval of the patch's digest promote
392
- records a pending gate on `chant/lifecycle` and exits 3 (`gated`), and
393
- nothing in the tree or the cloud is written; after `chant approve
394
- workspace-promote <member> --plan <digest>`, the same start applies the
395
- patch and runs `live-import -approve`. behold never approves here; the
396
- approve line is shown to copy. `GET /api/adopt/runs/:id` answers one start
397
- (`outcome`, `digest`, `words`, `approve`, `report`), the last 20 in memory;
398
- the SSE `adopt-run` event names one that moved.
399
- - The state file is a file name in the member's declared directory
400
- (`terraform.tfstate` by default), never a path. A root on a remote backend
401
- pulls one there under a name git ignores first, since promote refuses a
402
- member with uncommitted changes.
403
-
404
- Refusals: no declared workspace `404`, below the floor `409 chant-too-old`,
405
- preview `403` for the start, a kind behold does not adopt `422 adopt-kind`,
406
- no state file `422 adopt-state`, a second command while one runs `409 busy`.
407
- A terragucci or SQL Yodeler repo refuses the start through the write
408
- allowlist (`409`), and `--public` refuses every `/api/adopt` read (`403`)
409
- and the start (`405`). The tab is not drawn in a public view, an embed, a
410
- static export or a guarded repo.
411
-
412
- `behold demo terraform-estate` serves `serve --adopt-recorded
413
- recorded/adoption` (DemoServe `adoptRecorded`): one recorded `<member>.json`
414
- per root in promote's shape, labelled recorded (`RECORDED_NOTE`), and no
415
- start. `just e2e-adopt` (e2e/adopt-terraform-e2e.sh) runs the whole path over
416
- a real chant and serve with choudoufu replaced by
417
- e2e/fixtures/adopt/choudoufu, and asserts the report lists every resource
418
- with its fate and that nothing is written before approval.
419
-
420
- ## A terragucci estate, from its reports (#490)
421
-
422
- `behold serve <repo> --terragucci <dir|s3://bucket/prefix|https://…>`
423
- (`--terragucci-project <host/path>` when the bucket holds several projects
424
- and none is the checkout's git remote) adds two reads, in
425
- `src/terragucci-view.ts`:
426
-
427
- - `GET /api/terragucci`: `{source, project, validation, read, reports, files,
428
- estate?, roots[], cards{}, waiting[], unmatched}`. `roots[]` is every
429
- Terraform root of the checkout with the newest `plan`, `drift` and `apply`
430
- run that held it; a missing stage means no report holds that root, which is
431
- not "no changes". `cards` maps a card id to its marks (`verdict: drift |
432
- plan | wave`, terragucci's words, the instance addresses, the run). Each
433
- mark's `values` gives each changed attribute's `before` and `after`, or
434
- `unknown: true` for a value known only after apply. A sensitive attribute
435
- is never there, and a value longer than 300 characters of JSON is left out
436
- with `long: true`. `applied` maps a card id to what its root's newest
437
- applied wave wrote. The kiosk's popover reads both (behold#571). Nothing
438
- sets `_status`: a report is never painted as live. `waiting[]` carries each
439
- wave's roots, destroys, and the `command` a person runs. `estate` is
440
- terragucci's own counts when the source has `estate.json`. A key such as a
441
- run's `report` opens at `files` + the key. Refusals are `422 {code:
442
- "terragucci-report"}`. `?fresh=1` skips the 30 s cache.
443
- - `GET /api/terragucci/file?key=<key>`: one report file from the source,
444
- sandboxed.
445
- - `GET /api/terragucci/timeline?root=<path>&limit=<n>` (#506): terragucci's
446
- audit record (`audit.jsonl` at the top of the prefix, one GET) as `{source,
447
- project, validation, read, record: {key, present}, absent?, files, root?,
448
- total, limit, entries[]}`, newest first, 200 by default and 1000 at most.
449
- An entry is `{id, kind, at, who, what, wave?, digest, result, roots[], run:
450
- {commit?, job_url?, run_id?, pull_request?, report?}, evidence, detail?}`;
451
- `run.report` opens at `files` + the key. An approval takes the roots and
452
- report of its wave's other entries (same gate and digest). No
453
- `audit.jsonl` is `present: false` plus an `absent` sentence, never an
454
- empty history; a bad line is the `422 terragucci-report` refusal naming it.
455
- #523: an S3 403 on an optional read (`audit.jsonl` here, `run.json` for
456
- `/api/terragucci/progress` and the estate's run views) is not a refusal:
457
- the source throws `TerragucciDenied` (`src/terragucci-source.ts`), and the
458
- answer carries `present: false`, `unreadable: true` and an `absent`
459
- sentence naming the key and `s3:GetObject` (or `s3:ListBucket`). A 403 on
460
- `index.json`, a report or `estate.json` still fails.
461
- `src/terragucci-timeline.ts` holds the read and the check (terragucci's
462
- `dist/audit.schema.json` when it resolves, structural otherwise). The SPA
463
- draws it in the Terragucci tab and, filtered to the card's root, in the
464
- inspect pane (`web/terragucci-timeline.js`); an export carries it as one
465
- snapshot and does not fail on it.
466
- - `GET /api/terragucci/lifecycle` (#505): the repo's `chant/lifecycle` lane,
467
- `{branch, found, via, origin?, fetch: {ok, error?}, commit?: {sha,
468
- committed}, read: {at}, approval?, gates[], locks[], note}`. `gates[]` is one
469
- entry per wave gate (`wave-<k>`, chant op-waves' `<gate>-wave-<k>` or a
470
- product's `<name>-wave-<k>`: `WAVE_GATE`, #521) in `_gates/tf-apply.jsonl` and
471
- `_gates/tf-apply/applied.jsonl`, decided by chant's `decideGateApproval`
472
- (`@intentius/chant/gate-decision`, #520) with spent approvals left out, on
473
- lines parsed by chant's `parseGateLedger` and `parseAppliedGateLines`. The
474
- states:
475
- - `waiting`: no approval of the wave's digest counts; `command` is the
476
- approve line (`--sign` under `sealed`), or `chant workspace points answer
477
- <id>` when the pending fact carries `answer: {point, id}` (#521).
478
- - `expired`: the pending fact's `expiresAt` passed with none.
479
- - `refused`: an unspent approval stands for another digest
480
- (`refused: {digest, by, at}`); no approve line.
481
- - `approved`: an unspent approval of the digest counts, not applied yet.
482
- - `applied` / `failed`: a wave applied under that approval, and how the
483
- apply finished when terragucci recorded it. chant's op waves write no
484
- `finished` line: then `applied.result` is absent and the page says
485
- "applied (outcome not recorded)".
486
- - `refused-by-policy` (#521): a denial on `_gates/policy-override.jsonl`
487
- (chant's `recordedDenials`) newer than anything on the wave's gate, that
488
- no override counts for (chant's `decideOverride`, with the overriders at
489
- base: `.chant/overriders`, or terragucci's `policy.override`) and no run
490
- applied an override of since. `denials[]` carries each run, its plan and
491
- rules, and chant's `overrideCommand` line; no approve line. The wave is
492
- the one the denial's pending fact names (`wave: {number, name, op}`,
493
- typed on chant's `PendingGateRecord`, whose parser drops a wave of the
494
- wrong shape, chant#3887), else, for a fact an older chant wrote, the one
495
- whose pending fact lists the run.
496
- - `held` (#521): a pending fact on another gate (any `_gates/<op>.jsonl`)
497
- that names this op's wave (`wave: {number, name, op}`), with no approval
498
- of its digest that counts under the mode the fact records. `heldOn: {op,
499
- gate, digest, since, heldBy, description}`; `heldBy: {hook, moment,
500
- target?}` is the hook that holds the wave (chant#3886), and the card
501
- (`holderWords` in `web/terragucci-lifecycle.js`) names it from there,
502
- or from `description` for a fact an older chant wrote. `command`
503
- approves that gate (`chant approve <op> <gate> --plan`) or answers its
504
- decision point. A hold fact that names no wave is not read as a hold.
505
- Each entry also carries `digest`, `pending` (with `members` and
506
- `neverOverMcp` when recorded, `description`, `url`, `answer`), `approval`
507
- (by, at, `signed` when the seal has a signature, via (`review` for chant's
508
- `review: {pr, head, approvers}` line), pr, head, reviewers, relayedBy, note), `uncounted` (an
509
- approval of this digest the mode did not count, with chant's reason, such
510
- as an unsealed one under `sealed`), `spent` (an approval of another digest
511
- an apply used), `applied` (with `wave` and `review` when present), the kept
512
- reports under `_gates/tf-apply/wave-<k>/`, and `command`. `approval` on the
513
- answer is the rule read at base, the tip of origin's default branch fetched
514
- depth 1 into the same cache (`refs/behold/base`): `mode` from
515
- terragucci.yml's `approval:` key, else `sealed` when chant.workspace.json
516
- lists `identity.gates`, else `ledger`, and the signers read with chant's
517
- `gateSignersAt`. Each wave is decided under the approval mode its newest
518
- pending fact records (`approvalMode`, `withRecordedModes`), else the mode at
519
- base; the entry carries `approvalMode: {mode, from: "pending" | "base"}`,
520
- and `approval.inferred` is set only when some wave's fact records none. A
521
- gate `identity.gates` names at base is decided with `refuses` from chant's
522
- `identityGateAdmissionAt`, which checks the seal against the signers at
523
- base and, when the gate names a class, the role grants in
524
- `.chant/trust.json` at base, whatever the mode; the entry carries
525
- `identity: {class}`. A class a pinned package supplies is read by chant
526
- from `./workspace-principals` (chant#3888): a path pin's file at base, a
527
- package pin's from the package installed in the served checkout's
528
- node_modules (behold passes the checkout as `packages`, since the bare
529
- cache has none), at the pinned version. When that package is missing or
530
- at another version, a gate naming a domain class or `human` refuses every
531
- approval and chant's reason names the pin. Under `pr-review`, a spec's `headPlans` (the op-waves spec name)
532
- has the newest 50 `_wave-plans/<name>/<head>.json` records read with
533
- chant's `readHeadPlans` (`@intentius/chant/lifecycle/wave-plans`) through
534
- `ledgerPort`, a `LedgerReadPort` over the fetched commit. The op, ledger paths, gate names, approve line and
535
- mode reader are a `GateLaneSpec` (`TERRAGUCCI_LANE` is terragucci's), for
536
- another product's lane: `opWavesLane(op, over?)` gives one with chant's
537
- approve line, mode rule and overriders, and `readLifecycle(checkout, {spec})`
538
- reads it. `terragucciApproveCommand` is the one approve line the reports,
539
- the estate and the lane share, and `gatePolicyName` reads `on-destroy` as
540
- `on-destructive` (terragucci#863). `locks[]` is
541
- `_locks/tf-apply.json`, one per root (`pr, by, at, head, via?, stage?`).
542
- Every gate and lock carries `source: {commit, committed, path}`, the newest
543
- commit of the branch that changed its file. The branch is fetched from the
544
- checkout's origin URL into `<tmpdir>/behold-lifecycle-<hash of the URL>`, a
545
- bare repo behold owns (`assertScratch`), with the person's own git
546
- credentials and no prompt; the checkout is never fetched into and no ref of
547
- it moves. A failed fetch falls back to the checkout's own
548
- `refs/remotes/origin/chant/lifecycle`, read-only (`via: "checkout-ref"`,
549
- `fetch.error`); a remote without the branch is `found: false, via:
550
- "fetch"`, not an error. 30 s cache, `?fresh=1` skips it. Reader:
551
- `src/terragucci-lifecycle.ts`.
552
- - `GET /api/lifecycle/history?op=<op>&gate=<gate>&limit=<n>` (#522): the
553
- gate ledgers' history on `chant/lifecycle`, for any product, registered
554
- whether or not `--terragucci` is given. Same bare cache and fallback as
555
- the lifecycle lane; per `_gates/<op>.jsonl` it runs `git log -p
556
- --unified=0 --no-renames` and hands the text to chant's
557
- `gateLedgerLinesFromLog`, then all ledgers to `deriveGateAudit`
558
- (`@intentius/chant/lifecycle/gate-audit`). behold parses no ledger line
559
- itself. Answer: `{branch, source: "ledger", found, via, origin?, fetch,
560
- commit?, read, ledgers[], op?, gate?, total, limit, entries[], gaps[],
561
- note}`, newest first, 200 by default and 1000 at most. An entry is `{id,
562
- kind, at, op, gate, wave?, digest?, actor?, seal?, note?, rules?, subject?,
563
- source: {path, line?, commit, committer, committed, change}, audit}`;
564
- `kind` is chant's (`approval-requested | approved | override-requested |
565
- override-recorded | revoked`), `audit` is chant's whole entry. A revocation
566
- is a line a commit removed, and its `actor` is that commit's author. The
567
- ledger holds no applies, so `applied` and `override-spent` appear only in
568
- a product's own record (terragucci's `audit.jsonl`). The Terragucci tab's
569
- Timeline draws it under the audit record, labelled "ledger"; when the
570
- source has no `audit.jsonl` the record's lane says so and the ledger is
571
- the history. An export carries it as one snapshot. Reader:
572
- `src/lifecycle-history.ts`.
573
- - `GET /api/terragucci/events` (#505): SSE. While at least one page holds it
574
- open, a timer (`--terragucci-poll <secs>`, default 30, 0 off) asks
575
- whether `index.json` changed (`If-None-Match` with the last ETag for S3 and
576
- http, mtime for a directory) and fetches `chant/lifecycle` again. Events:
577
- `hello {pollSecs}`, `reports {at, tag}` (the page reads `/api/terragucci`
578
- again), `lifecycle <the whole answer>` when the read differs from the last,
579
- and `polled {at, reports, lifecycle}` after every tick. The last page
580
- leaving stops the timer (`src/terragucci-poll.ts`). Neither route writes,
581
- approves, locks or unlocks.
582
- - `GET /api/terragucci/progress` (#511): a choudoufu wave's progress per
583
- resource from the run view of the newest commit `index.json` names a
584
- `tf-apply` run of (one GET of `index.json`, one of
585
- `<project dir>/runs/<commit>/run.json`, the directory taken from the index
586
- row's own path). `{source, kind, project, validation, read, run: {commit,
587
- key, present, updated?, html?} | null, absent?, files, watching, waves[],
588
- cards{}, unmatched[]}`. A wave is `{number, state, gate, read, counts,
589
- resources[]}`, a resource `{root, address, action, status: done | in-flight
590
- | waiting | not-applied, done_at?, card?}`. `cards` is keyed by the same ids
591
- as `/api/terragucci`'s marks (root path to `attrs.root`, instance to block),
592
- one entry per wave with the wave's records `read` time and the card's
593
- status (not applied, else in flight, else waiting, else done). It is a
594
- dated corner tag, never a fill. No `run.json` is `run.present: false` plus
595
- an `absent` sentence. `watching` is true while a wave is applying or a
596
- resource is in flight or waiting; only then does the poll ask whether that
597
- `run.json` changed (`If-None-Match`, mtime for a directory) and push a
598
- `progress` event with the whole answer, and `polled` carries `progress:
599
- {asked, key?, changed?, error?}`. Checked against `dist/run.schema.json`
600
- when `@intentius/terragucci` resolves, structurally otherwise; reader
601
- `src/terragucci-progress.ts`, page `web/terragucci-progress.js`.
602
-
603
- The reads are `src/terragucci-reports.ts` (index, each run's report, estate;
604
- terragucci's JSON Schemas when `@intentius/terragucci` resolves, a structural
605
- check otherwise; the package is looked up on every read and the compiled
606
- schemas cached by its path and files' mtimes, #500) and the join is `src/terragucci-overlay.ts` (root path to
607
- `attrs.root`, instance address to block path). An S3 source shells the
608
- operator's `aws s3 cp <key> -`. There is no approve route, by design: hand the
609
- operator `waiting[].command`.
610
-
611
- A control repo (#509), one whose terragucci config has `projects:` and whose
612
- checkout declares no Terraform root (`controlRepo` in
613
- `src/terragucci-estate.ts`), gets one more read, and `/api/project` carries
614
- `terragucciControl: {config, projects}`:
615
-
616
- - `GET /api/terragucci/estate`: `{source, kind, config, validation: {estate,
617
- run}, read, estate: {key, html, generated}, gets, projects[], edges[],
618
- files}`. It reads `estate.json` and each project's newest run view,
619
- `<project>/runs/<commit>/run.json`, one GET each (the commit is the
620
- project's `run_view.commit`, else its `apply.commit`). A project is
621
- `{project, status, index?, counts: {drifted, failed, waiting, dated},
622
- waiting[], run? | missing? | refused?, checkout?, configured}`. Every
623
- figure carries `dated: {key, at}`: estate.json's `generated`, or the run
624
- view's `updated`. `waiting[].command` is the run view's approve line when it
625
- holds that wave. `edges[]` is `{from, to, cross}`, `to` reading `from`'s
626
- state; a cross edge matches a root's `external` read to another project's
627
- root `state`, as terragucci's `estateGraph` does. A malformed run view is
628
- `refused: {code: "terragucci-report"}` on its project only; a missing or
629
- malformed `estate.json` is a 422. Not a control repo: 404 `code:
630
- "terragucci-not-control"`. Run views are checked against
631
- `@intentius/terragucci`'s `dist/run.schema.json` when it resolves, a
632
- structural check otherwise. The page (`web/terragucci-estate.js`) draws it
633
- in a layer over the graph area.
634
-
635
-
636
- ### The kiosk's prompt pane (#936)
637
-
638
- A step of terragucci's `demo.json` may carry an `ask` (or `asks`, a list of
639
- them played in order), and the file may carry `opening` and `closing` strings
640
- (src/terragucci-demo.ts parses them; a field of the wrong type is null, and an
641
- ask with none of a prompt, an action and a reply is dropped; a reply alone prints with no line of the person's, as an applied step's does). While a step has an ask,
642
- the pane (`#k-ask`, web/kiosk-ask.js) takes the place of `#bar` and
643
- `#k-caption` in Watch: a big monospace block at the foot of the screen. A
644
- `prompt` is typed after `>` at 40 ms a character; an `action` shows at once
645
- after a check mark; the `reply` prints after it, with `{roots}`, `{creates}`,
646
- `{updates}`, `{deletes}` and `{error}` filled from the step's report (an
647
- unknown token, or one without a value, is empty). The last three entries stay
648
- above, faded. `opening` shows once at the scenario's first step
649
- (`pull-request` or `planned`), `closing` at `applied`. While a job runs
650
- (`pull-request`, `approved`, `merged`, `applying`, `resumed`) a status line
651
- gives what is happening, the time since `started_at`, and `next`. With
652
- `prefers-reduced-motion` everything shows at once. The pane's height is fixed
653
- and replaces the caption in `captionRoomPx`, so it never covers the graph. A
654
- step without an ask looks as it always did.
655
-
656
- The pane tells the page through window events, each with detail
657
- `{ ask, step, scenario }`: `behold:ask-start` before a beat is typed,
658
- `behold:ask-done` when its reply has printed, and `behold:ask-clear` on a new
659
- step with no ask. `{dependents}` is left to the lighting: it sets
660
- `window.beholdAskTokens = { dependents: n }` on `behold:ask-start`, and the
661
- reply reads it when it prints.
662
-
663
- ## Releases per environment, from the release ledger (#525)
664
-
665
- `GET /api/lifecycle/releases[?fresh=1]` (src/lifecycle-releases.ts) reads
666
- `<env>/releases.jsonl` on the served checkout's `chant/lifecycle` with chant's
667
- own reader (`listReleaseEnvironments`, `readReleaseLedger`,
668
- `latestPerComponent`, `recordsForDigest`). This one still imports
669
- `@intentius/chant/lifecycle/release-ledger`: no read-contract command lists a
670
- project's per-environment ledger outside a declared workspace (`workspace
671
- status` needs a declaration, and `release list` lists cut releases, not the
672
- `components release` records SQL Yodeler writes), so dropping the import would
673
- blank the tab for every SQL Yodeler project. The trunk lane (#680) reads
674
- releases through the contract only. The branch is fetched into the
675
- same bare cache the terragucci lane uses (`fetchIntoCache` in
676
- src/terragucci-lifecycle.ts). When that fetch fails, the checkout's
677
- `refs/remotes/origin/chant/lifecycle` is fetched into a second cache of
678
- behold's and read there (`via: "checkout-ref"`); the checkout is never
679
- written. Reads are reused for 30s.
680
-
681
- The answer: `environments` (wave order from `yodel-waves.json` when present,
682
- `order: "waves"`, else by name), `components` (a tenant is
683
- `<component>/<tenant>`, as SQL Yodeler records it), and `cells[]`, one per
684
- component and environment that has a release: `digest`, `timestamp`,
685
- `actor`, `approver?`, `gitSha`, `runId`, `runUrl?`, `source` (the newest
686
- commit that changed that environment's ledger), and `differs: {from,
687
- digest?, everHad}` when the environment before it holds another digest or
688
- none. `/api/project` says `releaseLedger: true` for a checkout with a
689
- `yodel.config.ts` or `yodel-waves.json`; the page then opens a Releases tab
690
- (`web/releases.js`), and `behold export` captures the route as a snapshot.
691
-
692
- ## SQL Yodeler's report and drift, from files (#526)
693
-
694
- `behold serve <dir> --yodel-report <file|dir>` adds `GET /api/yodel-report`
695
- (`src/yodel-report.ts`). It reads one `yodel report --json` output and any
696
- `yodel drift <env> --json` output in the same directory, written by the
697
- person or their pipeline. behold never runs `yodel` and never connects to
698
- the database.
699
-
700
- - The answer is `{source, validation, report, environments[], drift[],
701
- marks[], ignored[]}`. Each environment carries its applied migrations, the
702
- rest with their state, its gaps and notes, dated by the report's
703
- `generatedAt`. Each mark is one object a drift file names (`changed` or
704
- `missing`), dated by the file's mtime (drift JSON has no time of its own)
705
- and named by its file.
706
- - Every file is checked against SQL Yodeler's schemas: from
707
- `@intentius/sql-yodeler/schemas/` when the package resolves beside the
708
- served project or behold, otherwise from the copy pinned in
709
- `src/sql-yodeler-schemas/` (sql-yodeler 19ebbff). A file that fails is a
710
- 422 with `code: "yodel-report"` naming the file, and nothing is drawn.
711
- Update the pinned copy by copying the three files from sql-yodeler's
712
- `schemas/` and changing `PINNED_COMMIT`.
713
- - The page (`web/yodel-report.js`) joins a mark to the card whose id is the
714
- object's name, or ends in `/<name>` in a composed estate, and draws a
715
- corner tag with its age; never a fill. Objects no card is are listed in
716
- the SQL Yodeler tab, which also holds the environments and gaps.
717
- - `audit[]` (#537) carries the report's audit entries with the report file
718
- they came from. The tab lists them under their environment, each dated by
719
- its own `at` and named by its source (a ledger's op and gate, or a history
720
- table's row and run).
721
- - `behold export --yodel-report <file|dir>` (#537) captures `/api/yodel-report`
722
- as a snapshot, and a refusal fails the export, as `--terragucci` does. A
723
- SQL Yodeler repo's export also captures `/api/sql-yodeler/lifecycle` and
724
- `/api/lifecycle/history`, so the Pipeline lane draws in static mode,
725
- without its Read again button.
726
-
727
- ## A SQL Yodeler project: kinds and a lifecycle lane (#524)
728
-
729
- A SQL Yodeler project is a chant project with `lexicons: ["sql"]` and a
730
- `yodel.config.ts` (#517's detection, `productRepo` in src/terragucci-repo.ts).
731
- Its graph draws from `chant graph` as any project's does. src/sql-kinds.ts
732
- registers a pinhole pack for the `sql` lexicon: a line glyph per
733
- `Postgres::*` and `ClickHouse::*` kind, and cards that lead with the kind in
734
- words and the qualified name. A `REFERENCES ${other}` foreign key is a `ref`
735
- edge; e2e/fixtures/sql-yodeler-fk holds a project with one, and
736
- src/sql-yodeler-lane.test.ts graphs it. `@intentius/chant-lexicon-sql` is a
737
- devDependency for that test; from 0.124.13 its lint rules use chant's own
738
- TypeScript (chant#3864), so they run beside behold's TypeScript 7.
739
-
740
- `GET /api/sql-yodeler/lifecycle[?fresh=1]` (src/sql-yodeler-lane.ts) reads
741
- `chant/lifecycle` with `readLifecycle` and a spec per op, sharing one fetch:
742
-
743
- - `opWavesLane("yodel-apply")` for the apply pipeline's
744
- `yodel-apply-wave-<k>` gates, with the mode at base from `yodel-waves.json`
745
- when every wave names the same `approval`. When they differ (#537) the
746
- rule carries `waves[]` and each wave is decided under its own mode
747
- (`waveRule`; a gate decided so carries `mode`). Under `pr-review` a gate not
748
- yet approved carries `headPlans[]`: the heads whose
749
- `_wave-plans/yodel-apply/<head>.json` (chant's HeadPlans, newest 50 read)
750
- name its digest.
751
- - `migrateOpLane(env)` for each `migrate-<env>` op that `ops/` or
752
- `yodel-waves.json` names: its one gate `approve-migrate-<env>`, drawn as
753
- wave 1 of that op.
754
-
755
- The answer is the lane's header (branch, via, commit, rule, note) with
756
- `environments[]` in the order of applies (`yodel-waves.json`, then any
757
- environment only `ops/` names), each with its wave (`k`, targets, gate
758
- policy, approval) and `gates[]` (`kind: "wave" | "migrate"`, the GateEntry
759
- of #520/#521). A waiting gate carries `npx yodel approve <env> --plan
760
- <digest>` (`--sign` under sealed). Waves the spec does not name go in
761
- `unplaced`. A served directory that is not SQL Yodeler gets 404 with
762
- `code: "sql-yodeler"`. The page's Pipeline tab (`web/sql-yodeler-lane.js`)
763
- draws it, with `/api/lifecycle/history` (#522) below. Reads are reused 30s.
764
-
765
- A SQL Yodeler project that is a chant workspace member (#537) keeps its
766
- records under `_members/<member>/` on `chant/lifecycle`. src/member-ledger.ts
767
- asks chant's `resolveMemberLedger` (`@intentius/chant/lifecycle/member-ledger`)
768
- for the prefix; the lane passes it as `GateLaneSpec.ledgerPrefix`, which
769
- `readLifecycle` puts before every branch path, and `/api/lifecycle/releases`
770
- hands it to chant's `listReleaseEnvironments` and `readReleaseLedger` as
771
- `ledgerPrefix` (chant#3865), which list and read the environments under it. Both answers then carry
772
- `member: { members, prefix, error? }`, and `yodel-waves.json` at base is read
773
- in the project's own directory.
774
-
775
- ## Getting a server
776
-
777
- ```sh
778
- npx @intentius/behold serve <chant-project-dir> --port 4600 # or: preview / demo / doctor
779
- ```
780
-
781
- `behold demo` needs no project at all — it copies the bundled example and serves
782
- it against a local emulator (Docker). A directory that is not a chant project
783
- gets a structured `{code: "no-project"}` error from `/api/graph`, not a blank
784
- graph.
785
-
786
- In a checkout, `behold demo --list` prints a second block under the bundled
787
- one: the eleven workbench entries from `workbench.json` (this repo's own
788
- catalog of the internal estates behold is developed against), the same
789
- `behold demo <entry>` load, `just example name="<entry>"` to serve one, and
790
- "The workbench catalog" below for what each is and what it boots.
791
-
792
- A running server offers the same catalog over HTTP (#268): `GET /api/demos`
793
- lists every bundled demo with `{name, description, requires, satisfiable,
794
- reason?, fetches, repo?, target, loaded}` — `satisfiable` is doctor's PATH probe
795
- for that demo's `requires`, and `fetches` marks the one kind of entry that
796
- reaches the network (a git demo is cloned). `POST /api/demos/open` with
797
- `{name}` loads it and switches the served project to it: the same copy/clone →
798
- install → setup the CLI runs, then an in-place switch. It takes a catalog
799
- **name** and never a path, so it cannot be aimed outside the install; it is
800
- preview-locked, and one load runs at a time (409 otherwise).
801
-
802
- ## The read loop
803
-
804
- 0. **discover.** GET `/api` lists every route with a one-line description,
805
- plus the server's version and a link back to this guide. Before the server
806
- exists (or when a route answers with an error you'd have to guess at), run
807
- `npx @intentius/behold doctor <dir> --json`: a read-only diagnosis of the
808
- project's kind, its own chant install and version, declared lexicons, the
809
- envs the picker will infer, the bound kube context versus the ambient one,
810
- substrate readiness and committed Ops. Each check is
811
- `{name, status: pass|warn|fail, detail, fix}`; the process exits non-zero
812
- iff something failed. It starts no server and changes nothing.
813
- 1. **observe.** GET `/api/graph` (JSON: `{ ir, svg, meta }`). The mixed graph
814
- of the project, every node with `id`/`kind`/`lexicon`/`attrs`/`sourceLoc`. Drift
815
- status, when present, is `attrs._status` (`good`=managed, `warn`=foreign,
816
- `accent`=pending, `neutral`=unobserved, `runtime`=runtime child). With
817
- `?env=`, `/api/overlay` is the live entity overlay; `/api/diff?env=` slices
818
- per-node observed state, drift and field ownership; `/api/reconcile?env=`
819
- summarizes the pending change set; `/api/substrates` reports substrate
820
- readiness; `/api/events` (SSE) pushes `changed`/`op`/`apply`/`run`/`pr`,
821
- and `view` when an agent moves the tab (below).
822
- With `?components=1&env=`, each component node carries `_liveStatus` (the
823
- `chant components status` verdict) and, when the release ledger recorded
824
- one, `_release` — `{runId, forge, originSource, url?, gitSha, digest,
825
- timestamp, actor, approver?}` (#165). `url` is present only when the record
826
- itself carries an address (chant#2045); `originSource: "inferred"` means
827
- behold read the id's spelling and nothing more, and a `forge: "unknown"` id
828
- is never resolved to a link on behold's guess.
829
- `?stacks=1` is the apply-order lens (#426): the cross-stack ordering chant
830
- computes at synthesis and prints from `chant graph --stacks --json`, which
831
- behold read nowhere and re-derived a subset of. One card per stack (a
832
- lexicon partition), one box per wave, edges consumer to producer;
833
- `meta.stacks` carries `order`, `waves` and `cycles` verbatim. It is
834
- source-only (no env, no credentials, no substrate) and asks chant for the
835
- project ROOT, not `graphPath`, because `runStackGraph` only sees
836
- `ops/*.op.ts` from there (measured: `example-writes` answers `[aws,
837
- temporal]` from `.` and `[aws]` from `src`). Single project only: an estate
838
- is refused with `422 stacks-estate`, since `composeStacks` pools members
839
- into one bucket per bare lexicon name and two members' `aws` stacks are not
840
- one stack. A cycle is NOT a refusal — chant exits 1 with valid JSON and the
841
- entangled stacks absent from `order`/`waves`, so they are drawn unwaved in
842
- their own box and the note says so; nothing invents a wave number for a
843
- stack chant could not order. `/api/project`'s `stacksCapable` gates the
844
- stop. Note that `chant graph --stacks --json` is malformed today on two of
845
- chant's own examples (an edge with no `from`, a `null` in `order` and in a
846
- wave); `sanitizeStackGraph` treats `nodes` as the roster and drops anything
847
- named nowhere else.
848
- `?ops=1` is the ops lens: the project's declared Ops as a phase track, read
849
- from each emitted `dist/ops/<name>/op.json`, with the current run painted
850
- over it (`meta.run`, `meta.gate`); `/api/ops/<name>/status` reads that Op's
851
- newest run status and pending gate (`chant run status <name>`; chant
852
- removed `--temporal`, #459). A
853
- `ConvergeOp` also gets one card per rule from its `convergeTick` step's
854
- `args.rules` (`attrs._step: "rule"`), carrying `when` (chant's JSON predicate,
855
- rendered as the condition it states), `then`, and the `why` chant requires of
856
- every rule, verbatim. `then: run(<op>)` is an edge to that Op's first step
857
- when the Op is in the rendered set, and `attrs.dangling` when it isn't.
858
- `meta.operator` on that same lens names the ConvergeOps the project declares
859
- (chant's own `searchAttributes.Converge === "true"`, read from op.json, no
860
- subprocess), and `/api/operator/status` fills the strip in from
861
- `chant operator status --json`.
862
- 2. **focus.** Narrow with chant graph options as query params: `?detail=0..3`,
863
- `?components=1`, `?logical=1`, `?lens=blast:<id>&down=1`, `?lens=lexicon:aws`,
864
- `?env=`, `?stack=`, `?tier=`, `?target=`, `?collapse=1`.
865
- `?collapse=1` (#393) shuts every member box holding more than 40 cards: the
866
- box is drawn as ONE card carrying the count it was badged with (`301
867
- resources · 84 bound · 85 unowned · 132 neutral`, in the estate's own
868
- words), ids namespaced `box:<member>`, and the returned IR is the collapsed
869
- one so every count and note speaks about the picture on screen — except its
870
- NOTE, which is written about the expanded estate plus one collapse clause
871
- (#396): a shut box hides what the estate references rather than changing it.
872
- ⌘K → "Collapse large boxes" / "Expand all". Below the limit it changes
873
- nothing. **The toggle costs no live read** (#396): a member's overlay
874
- document is cached under its source stamp and the read's own options, the
875
- same key half `memberIr` and #404's plan cache use, so collapse and expand
876
- are re-renders of a document behold already holds. `src/overlay-ir.ts` is
877
- that cache and its header is the stated exception to src/member-ir.ts's
878
- "a live read is never cached"; it names everything that drops an entry —
879
- `POST /api/refresh` ("Re-check live"), `GET /api/overlay?plan=1`
880
- ("Re-check live with plan", which re-checks both halves), the capture that
881
- ends an Op run, and the member's source moving. A change made to the account
882
- by something that is not behold is what the re-check rows are for.
883
- 3. **inspect.** A node's `sourceLoc.file` is the typed source that declared it;
884
- edit there to change the estate (chant is the source of truth, not behold).
885
- 4. **find.** ⌘K also takes an ADDRESS (#393). Two characters in, the palette
886
- matches the ids and addresses of the graph the page is currently showing and
887
- offers up to twelve `node: <address>` rows, prefix matches first, each with
888
- its member and kind on a second line (two members of one estate can declare
889
- the same address). Enter takes the same path a click on the card does (the
890
- inspect pane and the highlight) and pans the graph onto it: `revealNode` in
891
- web/app.js drives the same viewBox the wheel, the drag and "⤢ fit" drive.
892
- Nothing here fetches, so it works in a static export too.
893
-
894
- ### The picture arrives in pieces (#422)
895
-
896
- `GET /api/overlay?progressive=1` answers at once with the estate composed from
897
- every member's SOURCE, each node carrying `attrs._pendingRead`, and then
898
- broadcasts one `member` SSE frame per member as its own live read settles —
899
- `{member, statuses: {<composed id>: <status>}, unobserved?}`, or `{error}` if
900
- the pass itself failed. `meta.mode` is `progressive` and `meta.pending` names
901
- the members not yet read.
902
-
903
- **Opt-in, and never the default.** `/api/overlay` without the flag is byte-for-
904
- byte what it was: the blocking, complete live answer this guide's read loop
905
- names, which is what an agent GETs and what `src/export.ts` captures into a
906
- static bundle. A route that answered with members it had not read would hand an
907
- agent a half-picture it could not know was half, and freeze a bundle with
908
- members permanently still-reading.
909
-
910
- **Pending is a third claim.** `_unobserved` is "behold looked and could not
911
- see"; `neutral` is "the plan did not mention it"; `_pendingRead` is "the read
912
- has not finished". It rides its own attr rather than a fifth `_status` because
913
- a fifth `_status` is not paintable — pinhole's painter takes a closed set and
914
- falls back to `neutral` for anything else, which is `unobserved`, the exact
915
- wrong answer. The SPA draws it dashed and dimmed, never filled: the fill is the
916
- status channel and a pending card has no status yet.
917
-
918
- No live result is cached to build the first picture and none is reused. A
919
- pending member becomes a real one only when its own read completes, and the
920
- live pass a progressive request starts is the same one per member under the
921
- same budget: a progressive load costs the estate no extra spawn.
922
-
923
- ### Drift, streamed card by card (#998)
924
-
925
- `POST /api/workspace/drift/stream {member, addresses?}` (palette: **"Stream
926
- drift card by card: <member>"**) runs `chant workspace drift --member <name>
927
- --stream` at the workspace root and narrates it as `drift` frames on
928
- `/api/events` (src/drift-stream.ts). The stream is chant's drift record in
929
- NDJSON (chant#4451): one `drift-start` with the addresses it expects, one
930
- `drift-record` per instance as its read finishes, one `drift-settle`. Each
931
- line is decoded in `streamDrift` (src/workspace-reader.ts) by
932
- src/drift-line.ts, which uses chant's own `decodeDriftLine` from
933
- `@intentius/chant/drift-record` (behold#1005) and narrows its line to what a
934
- card reads, and each record frame repaints only its own card. The
935
- start is refused below `DRIFT_STREAM_CHANT_FLOOR` (409, the floor's refusal,
936
- nothing spawned), unless `BEHOLD_DRIFT_CHANT` names the chant to run.
937
-
938
- - **Per resource on a choudoufu member.** choudoufu's single-resource path
939
- (`live-plan -resource`, choudoufu#2245) plans one resource and writes its
940
- records when that plan ends, and there is no whole-estate stream. So behold
941
- asks once per resource block (`--resource <addr>`, instance keys dropped,
942
- data sources left out), one after another, from the card addresses the page
943
- sends; the cards change colour resource by resource. Any other member is
944
- asked once without `--resource`.
945
- - **Reading is not a status.** Between a start and its settle, an expected
946
- card that has not reported is `data-drift-reading`: dimmed and dashed, its
947
- fill and `_status` unchanged. Only a record sets `_status`.
948
- - **Not reached.** At settle, every expected address no record answered
949
- becomes `not-observed` with reason `not-reached` (chant's fold rule), sent
950
- as a record frame before the settle frame. A read that fails or prints a
951
- line that does not decode is a `failed` frame: its cards stop reading and
952
- keep the colour they had. A read that never started stops the run.
953
- - **Colour** is `toneFor(record)`, #995's `(status, read)` table
954
- (src/drift-tone.ts, below). A status or read outside it is neutral, and the
955
- card carries `data-drift-unknown` and says so in its tooltip.
956
- - One run at a time (`409 drift-streaming`); `{stop: true}` stops it.
957
- `BEHOLD_DRIFT_CHANT` names the chant the read runs, for a chant built
958
- ahead of the release that adds `workspace drift --stream`, and for
959
- `just e2e-streamed-drift`'s fake (e2e/fixtures/fake-chant-drift); the
960
- floor, `DRIFT_STREAM_CHANT_FLOOR`, is checked only against the root's own
961
- chant, so it does not apply then.
962
-
963
- ### Colour from the drift record (#995)
964
-
965
- Every card's live colour is one fixed table over chant's drift record
966
- (chant#4451), keyed on the record's `status` and the `read` that answered,
967
- and on nothing else: `DRIFT_TONE_TABLE` and `toneFor` in src/drift-tone.ts.
968
- No engine is named there, so a Pulumi member (path 2, chant#4453) colours
969
- through the same cells as the rest. The read limits the claim: an
970
- `ownership` read's `in-sync` is green and labelled "bound (ownership only)"
971
- (#404), a `state` read's `recorded` is neutral, and a state read that says
972
- `in-sync` or `drifted` (a record chant refuses) is neutral and labelled. An
973
- unknown status or read is neutral and labelled unknown, never a guessed
974
- colour.
975
-
976
- - **The drift document.** `chant workspace drift --member <name> [--read
977
- <read>] [--resource <addr>] [--env <env>]` prints one member's drift
978
- document (contract 1, `drift: "v1"`), read by the member's own engine. It is
979
- `read("drift", driftArgs(ask))` on the workspace reader, the sixth
980
- `BEHOLD_READS` entry, held by chant's conformance suite when that suite
981
- lists `drift`. `paintWorkspaceDrift` (src/drift-overlay.ts) reads it per
982
- member and paints `_status`, `_drift: {status, read, label, reason?,
983
- engineCode?, fellBackFrom?, unknown?}` and `_unobserved` on each card.
984
- `/api/overlay` on a declared workspace whose chant meets
985
- `DRIFT_RECORD_CHANT_FLOOR` (`CHANT_RELEASE.version`, the release not cut yet) does this on
986
- every read for the members with no live half of their own (`terraform`,
987
- `pulumi`), and with `?drift=1` for `chant` and `choudoufu` members too, at
988
- the cost of a second live read. `meta.driftRecord` lists each member's
989
- painted and unplaced records and chant's error. With `?plan=1` a terraform
990
- or choudoufu member is asked `--read plan`.
991
- - **The reads behold still makes itself colour through the same table.** A
992
- choudoufu member's `live-plan`/`live-ls` paint (src/choudoufu-live.ts
993
- `verdictFor`) gives each address the status chant's adapter gives it
994
- (`bound` in-sync, `unowned`/`adoptable` unclaimed, `ABSENT` pending, every
995
- other omission not-observed, a listed item nothing declares undeclared) and
996
- takes the table's tone, read `ownership`. A component status row's
997
- reconciliation fallback (src/component-status.ts `reconciliationStatus`) is
998
- chant's `componentStatusDriftRecords` mapping, read `live-read`.
999
- - **UNOWNED, settled with chant.** An `UNOWNED` omission with no `unowned[]`
1000
- row is `not-observed` (`read-failed`, `engineCode: "UNOWNED"`), as chant C1
1001
- decided: neutral, not `warn`. With its `unowned[]` row it is `unclaimed`
1002
- and `warn`, as before.
1003
- - **Which read answered a root** is the IR's `rootReads` (chant#4452):
1004
- `terraform.roots.<root>` with `depth`, `fellBackTo` and `reason`
1005
- (src/terraform-plan.ts `planRootAnswers`, src/choudoufu-chant-read.ts
1006
- `rootAnswerOf`). chant's note text is not parsed. A chant that puts no
1007
- `rootReads` on the IR reports no root: a stock root's cards carry no plan
1008
- answer, and a choudoufu re-check reads as live-plan alone.
1009
- - **choudoufu card ids and chant node ids (the B3 follow-up).** behold keeps
1010
- a choudoufu member's card ids, the roster's `<member>/<address>`, because
1011
- saved layouts are keyed on them, while chant names the same blocks
1012
- `<member>/<root>/<block path>`. One alias table, built from chant's graph
1013
- of the member (`choudoufuCardAliases`, src/drift-overlay.ts), maps a chant
1014
- node and an instance address onto the card (`cardIdFor`), and both the
1015
- change-set overlay (src/change-set-overlay.ts) and drift records use it. A
1016
- node the table does not know lands on no card and is listed.
1017
-
1018
- ### What a read cost (#420, #421)
1019
-
1020
- `GET /api/doctor` serves `diagnose()`, the same report `behold doctor` prints,
1021
- which until #421 only the CLI could ask for — with two extra blocks on it:
1022
-
1023
- - `reads`, the ledger from `src/read-stats.ts`. Every scheduled chant read
1024
- passes through `ReadScheduler`, so each one is filed there with its running
1025
- time, its outcome, and which side of the source/live split it sits on. A bare
1026
- `chant graph` is the member's own TypeScript evaluation; anything with
1027
- `--live`/`--overlay`, and every other verb `isScheduledRead` allows, reaches
1028
- past it. `shared` counts subscribers handed an in-flight spawn, work not
1029
- done, never a run.
1030
- - `cache`, `memberIrCacheStats()`.
1031
-
1032
- `GET /api/doctor?reads=1` is the same two blocks WITHOUT the diagnosis, and it
1033
- is what the SPA asks for. The split is the one #421 states: the full report is
1034
- for a person diagnosing and the panel line is for a person waiting. It is also a
1035
- cost split too: `diagnose()` probes docker, gh, helm and k3d through
1036
- src/substrates.ts, whose `probe` has no timeout and no kill, and the SPA asks
1037
- after every load settles. A static export asks for neither; `refreshReadCost`
1038
- returns on `staticMode` rather than relying on the bundle's own 404.
1039
-
1040
- `reads.inFlight` is `{running, queued}` off the scheduler itself. The ledger
1041
- cannot answer it: a read still in flight has finished nothing, so it has filed
1042
- nothing. "What is queued now" is what someone watching a slow read wants.
1043
-
1044
- Three things to know before reading a number off it. `queuedMs` is contention
1045
- **in the scheduler** (the HTTP-versus-poll-versus-capture competition #367
1046
- bounded) rather than the whole of what a member waits: the estate fan-out bounds
1047
- upstream through `mapPool` (src/estate.ts), so a three-member estate measured
1048
- 3033/3035/2218 ms of running time with `queuedMs` 0 against 5.2 s of wall clock.
1049
- The gap is the upstream wait and #422 is where it gets measured.
1050
-
1051
- `reads.unmeasured` counts the served members the ledger is BLIND to, and the
1052
- panel line prints it rather than quietly excluding them. Only reads that pass
1053
- `ReadScheduler` are filed, which is every chant read and therefore a terraform
1054
- member too (its `via.read` shells `chant graph`, src/terraform-member.ts). A
1055
- choudoufu member spawns its own binary through its own helper and is filed
1056
- nowhere, so on a chant+choudoufu estate the slowest card may be one that never
1057
- reached `recent` — "slowest 3s · 1 not measured" is the honest form of that, and
1058
- an unqualified "slowest 3s" is not.
1059
-
1060
- And preview mode keeps the totals but drops `recent`, whose samples are keyed by
1061
- member directory.
1062
-
1063
- The SPA asks once after each load settles and shows the answer on the loading
1064
- scrim the *next* time one goes up (`web/read-cost.js`, `#loading-cost`): the
1065
- slowest recent member, because an estate read finishes when its last member
1066
- does, so a sum would report a number nobody waits for.
1067
-
1068
- ### The behaviour overlay (#398, M1 of #397)
1069
-
1070
- What the estate costs and where it runs out of headroom, on `/api/overlay`
1071
- only. **behold never calls a behavioural engine**, never holds its key, and
1072
- produces no figure of its own — it renders what a chant lexicon handed it, the
1073
- way it already renders drift and the carve score. The one arithmetic it does is
1074
- addition, and the result is named `sum` so nobody can read it as a bill.
1075
-
1076
- The contract's source of truth is the comment titled "The behaviour block,
1077
- proposed" on INTENTIUS/behold#398 (chant#2356 is the writing half). Field names
1078
- here match it exactly; `src/behaviour.ts` is the implementation and the
1079
- validator.
1080
-
1081
- Per entity, `attrs._behaviour` on the overlay IR node — the channel `_status`,
1082
- `_release` and `_carve` already ride: `{at: {traffic}, cost: {perHour,
1083
- currency}, headroom: {cpu?, latency?}, errorRate, resilience: {failure, verdict:
1084
- survives|degrades|fails, note?}, rightSize?: {suggestion, reason?}, provenance:
1085
- {engine, version, tolerance, basis: modeled|validated}}`. An entity nothing
1086
- priced carries **no `_behaviour` key at all**, never a zeroed block, and a
1087
- missing headroom axis is absent rather than 0. The block stays on the node and
1088
- there is deliberately no top-level `behaviour: {}` map: the SPA already walks
1089
- `ir.nodes` reading `attrs._status`, and a colour-by-cost mode is that same walk,
1090
- with no join.
1091
-
1092
- Two sources, in this order:
1093
-
1094
- 1. `attrs._behaviour` on the nodes, as `chant graph --live --overlay` painted
1095
- them, with `meta._behaviour` beside them for the graph-level half.
1096
- 2. `behaviour.<env>.json` at a member's root — `{meta, entities: {<address>:
1097
- block}}` — read **only** when no node of that member carries the attr and
1098
- the member's read carried no `meta._behaviour` either (#402), and
1099
- **only on the overlay** (`/api/graph` is the source graph; a prediction
1100
- about a live account has no business on it). The file's keys are the
1101
- member's own addresses; behold prefixes them to reach the composed id
1102
- `<member>/<address>`.
1103
-
1104
- `meta.behaviour` carries the graph-level half: `engine`, `version`, `at`, the
1105
- engine's own `total` when it stated one, else behold's `sum` and the same per
1106
- box under `boxes[<boxKey>]` (`{perHour, currency, priced, unpriced}`). Mixed
1107
- currencies produce no sum and a diagnostic — behold converts no currency. A
1108
- malformed block is dropped whole with its reason in `diagnostics`, never
1109
- half-rendered. A member with neither source gets `{absent: "…"}` naming both
1110
- places behold looked; that is an absence, not a refusal, because nothing was
1111
- configured.
1112
-
1113
- `meta.behaviour.refusal` is `{reason, remedy}` in the lexicon's own words,
1114
- printed as it came, and it is present **instead of** everything above: a
1115
- refusal emits no entity block at all and strips any that had arrived. The drift
1116
- overlay is untouched either way: nothing in this pass reads or writes
1117
- `_status`. `?logical=1` projects a different picture and carries no behaviour
1118
- block in M1.
1119
-
1120
- ### Live versus declared (#402, M5)
1121
-
1122
- With a traffic level, `/api/overlay` predicts each member twice and carries
1123
- both figures and their difference. The level is `?traffic=` on the request,
1124
- else the per-user settings' `{"behaviour": {"traffic": "100 rps, p50"}}` (src/user-settings.ts, #470), else none;
1125
- with none nothing is asked for and the payload is exactly M1's. behold never
1126
- defaults a level, because every figure is *at* one.
1127
-
1128
- `meta.behaviour` gains `live`, `declared` (each `{perHour, currency, basis}`,
1129
- where `basis` is `total` for a figure the engine stated and `sum` for behold
1130
- adding the engine's per-entity figures) and `delta` (`{perHour, currency}`,
1131
- live minus declared), plus the same three per member under `members[<name>]`.
1132
- A delta is only ever like with like: one currency, and two totals or two sums.
1133
- Anything else yields no delta and a line in `diagnostics` saying why. A node
1134
- also carries the file's block under `attrs._behaviourDeclared`, including a
1135
- node the account no longer holds, which has no `_behaviour` at all.
1136
-
1137
- Who reads what is `src/behaviour-delta.ts`'s header. A chant member's live
1138
- half is its own overlay read with `--traffic` added (sent only to a chant at
1139
- 0.75.0 or newer; an older one rejects the flag). A choudoufu member is not
1140
- read by chant, so behold predicts it through a generated reader project with
1141
- `binary: "choudoufu"` (the Terraform member's scratch project, under
1142
- `behold-chdf-*`), which needs the optional terraform lexicon. A terraform
1143
- member has no live half and so no delta.
1144
-
1145
- The declared half goes through `memberIr` and is cached under the member's
1146
- source stamp plus the traffic level. The live half goes through `overlayIr`
1147
- and is dropped by whatever drops the overlay. With a level set, the
1148
- `behaviour.<env>.json` documents are not read at all: a fixture's figures
1149
- beside a real prediction would be two answers to one question.
1150
-
1151
- `/api/graph?traffic=` (or the config default) paints the declared side alone
1152
- as `attrs._behaviour` with `meta.behaviour.declared`. The file is the only
1153
- estate that route has, so it carries no live half and no delta.
1154
-
1155
- ### Colour by drift, cost or headroom (#399, M2)
1156
-
1157
- The SPA colours the graph by one of three modes. The mode is **client-side
1158
- state** — `web/app.js`'s `colourMode`, persisted under `behold.colourBy` the way
1159
- the theme is. It is deliberately NOT in `LENS_PARAMS`/`canonicalKey`: a lens
1160
- param means "a different snapshot comes back", and a mode change changes no
1161
- fetch at all. The block is already on every priced card, so a switch is a
1162
- repaint of the SVG on screen.
1163
-
1164
- `drift` keeps the categorical fill and #393's vocabulary legend, unchanged. The
1165
- two behaviour modes replace the card's FILL only, so the drift bar underneath
1166
- keeps saying what chant observed. `cost` is a sequential scale over
1167
- `cost.perHour` between the estate's own min and max; `headroom` is absolute over
1168
- 0..1 and reads **the lower of the axes present**. An entity with no block draws
1169
- the drift overlay's neutral (`pinTokensFor().neutralFill`) and is marked
1170
- `data-unpriced`, never the zero end of the scale — "nothing priced this" and
1171
- "this is free" are opposite claims.
1172
-
1173
- Both ramps are derived from the active palette (`rampFor` in
1174
- `web/behaviour-scale.js`), the way #229 derives the chrome: cost is a single hue
1175
- off the accent walked in lightness away from the background — expensive is not a
1176
- verdict behold gets to paint, and headroom rides the three status hues the
1177
- drift overlay already anchors, degraded → foreign → managed.
1178
-
1179
- One legend per mode, in the Model tab. The Scope tab carries a totals row per
1180
- box and per estate for the active mode: `cost` quotes `meta.behaviour.boxes[key]`
1181
- and `.sum`, or `meta.behaviour.total` when the ENGINE stated one (labelled
1182
- "engine total"); `headroom` has no server-side aggregate, since no engine states one —
1183
- so the SPA takes the scope's min and median itself and the row says "computed".
1184
- Every row carries `n priced · m unpriced`. In drift mode there is no row.
1185
-
1186
- Everything either mode decides is pure in `web/behaviour-scale.js`, with
1187
- `web/behaviour-scale.test.js` beside it; the SPA owns the fetches and the SVG.
1188
-
1189
- ### Provenance on every figure, and the refusal (#401, M4)
1190
-
1191
- Every figure the SPA shows, the totals rows, the legend, and the inspect pane's
1192
- `behaviour` section — carries `{engine} {version} · {tolerance} · {basis}`
1193
- beside it, never once per page. `modeled` is spelled out on hover as "modeled,
1194
- not billed": #397's one prohibition is a prediction presented as a bill, and the
1195
- badge is where that is prevented. Provenance is per ENTITY in #398's contract, so
1196
- a badge over a set (a box, the estate) says `mixed` on any field the set
1197
- disagrees on rather than picking one.
1198
-
1199
- `meta.behaviour.refusal` disables both behaviour modes in the View tab and in
1200
- ⌘K (visibly, with the lexicon's reason and remedy as their tooltip) and prints
1201
- those words verbatim where the legend would be. The drift overlay keeps
1202
- rendering; it never depended on an engine. `meta.behaviour.absent` disables the
1203
- same two modes with the absent line as their tooltip and prints **nothing**:
1204
- nothing was configured, so nothing refused. `meta.behaviour.diagnostics` render
1205
- in the Model tab under the legend.
1206
-
1207
- ## The carve loop (Terraform → chant, #230)
1208
-
1209
- `behold carve <report.json>` serves a `chant carve advise --json` peelability
1210
- report instead of a chant project. Same SPA, same `/api/graph` shape; `attrs.
1211
- _status` carries the band (`good` = carve now, `warn` = has boundary work,
1212
- `neutral` = leave in Terraform) and `attrs` carries the score arithmetic
1213
- (`score`, `arithmetic`, `inbound`, `outbound`, `tier`, `mapsTo`).
1214
- `GET /api/carve` returns the raw report verbatim.
1215
-
1216
- To move a resource: confirm its band on `/api/carve`, then run chant's own
1217
- `carve emit --state` and `carve bridge` in the project. `terraform state rm` and
1218
- applying the generated survivor rewrites stay a human gate — behold has no
1219
- endpoint that writes Terraform, and adding one would break the invariant below.
1220
-
1221
- ### Carve state, from chant's manifests (#230 M3)
1222
-
1223
- chant ≥ 0.52.2 writes `<address>.carve.json` into `carve emit --output`; `carve
1224
- bridge` and `carve apply` add their own records to the same file. behold reads
1225
- those and never writes one, so the progression is on disk rather than in a
1226
- session.
1227
-
1228
- `GET /api/project`'s `carve.state` publishes it: `{manifests, progress:
1229
- {applied, bridged, emitted, inFlight, total, label, detail}, states[], apply:
1230
- {human, note}}`. Each entry carries `target`, `stage`
1231
- (`emitted`/`bridged`/`applied`), `graduated`, `note` and a retypeable
1232
- `applyCommand`. The same field appears on an ordinary `behold serve` whose
1233
- project directory carries a carveout (no report and no demo needed) and is
1234
- absent entirely when nothing has been carved.
1235
-
1236
- In the graph, an `applied` address draws inside the chant member box (keeping
1237
- its Terraform address as its node id) instead of in a band; `emitted` and
1238
- `bridged` stay banded with `attrs._status: "accent"` and the stage in
1239
- `attrs.carve`. Only `applied` means ownership moved.
1240
-
1241
- **There is no `/api/carve/apply`.** `chant carve apply` graduates ownership;
1242
- behold renders what the manifest records and echoes the command. Do not add the
1243
- endpoint — src/carve-manifest.ts `APPLY_IS_HUMAN` is the statement of it, and
1244
- src/carve-actions.ts and src/server.ts both carry the refusal where the route
1245
- would go.
1246
-
1247
- ### The walkthrough (`behold demo carve`, #254)
1248
-
1249
- `behold demo carve` copies a bundled mixed estate (a chant project
1250
- beside a Terraform one), runs the advisor over the copy, and serves the same
1251
- carve view plus a six-step stepper on the panel's Carve tab: advise → pick →
1252
- emit → bridge → handoff → done.
1253
-
1254
- Two of those steps are POST routes, and they exist **only** in a demo copy:
1255
-
1256
- - `POST /api/carve/emit` — body `{select}`; runs `chant carve emit --state
1257
- --select <addr> --output <copy>/app/carveout` and then `chant lint` on the
1258
- result. Answers `{select, command, output, artifacts[], boundary, lint,
1259
- buildCaveat}`.
1260
- - `POST /api/carve/bridge` — body `{select}`; runs `chant carve bridge`
1261
- **without** `--apply-rewrites`. Answers `{select, command, output, runbook,
1262
- proposals[]}`.
1263
-
1264
- `GET /api/project`'s `carve.demo` says whether they can act (`runnable`, plus a
1265
- `reason` when not). `select` must name a resource the served report ranks;
1266
- anything else is a 400. Outside a demo copy both routes answer 403
1267
- `{code: "read-only"}`, and on an ordinary project serve they don't exist at all.
1268
-
1269
- The gate the Emit step reports is `chant lint`, not `chant build` — chant#1637
1270
- means `build` fails on the emitted bucket. Don't read a lint pass as a build
1271
- pass.
1272
-
1273
- There is still **no** endpoint that runs `terraform`. The handoff step hands
1274
- back the runbook's commands as text.
1275
-
1276
- ## A chant search query: `q` and `GET /api/search` (#913)
1277
-
1278
- `q` is a view key holding a query in chant's search grammar. In a link
1279
- (`?q=...`), a `behold:view` message, `POST /api/view` and `behold shot`, it
1280
- draws the same way: the cards chant matched are lit, the cards and edges on
1281
- each match's path (chant's `paths[].hops`, and for a `cap:` term the hops
1282
- in `paths[].because[]` too, INTENTIUS/chant#4375) are drawn at full weight, and the
1283
- rest is dimmed, with nothing hidden. One line at the top left says the query,
1284
- the match count and chant's provenance line. A query with no matches dims
1285
- the whole graph, says "no matches" with the universe count, and outlines the
1286
- near-misses `--explain` names (hover one for the term it fails). A live read
1287
- that failed is said as a failure naming the lexicon, and its rows wear a
1288
- dashed ring. A query chant's grammar refuses lights and dims nothing and
1289
- shows chant's message and hint. A reload keeps `q`.
1290
-
1291
- chant answers and behold draws. Every search goes through the workspace
1292
- reader (`src/workspace-reader.ts`, a fifth `BEHOLD_READS` entry held by
1293
- chant's reader conformance suite):
1294
-
1295
- | Served | chant call |
1296
- |---|---|
1297
- | a declared workspace | `chant workspace search [flags] --json -- <q>` at the root (INTENTIUS/chant#4374). Ids are `<member>/<id>`, as `workspace graph` gives them. A member chant didn't search is named in a "not searched" line with chant's reason code, never shown as no matches |
1298
- | one chant project | `chant search [flags] --json -- <q>` in its directory |
1299
- | a bare Terraform folder | `chant workspace search` at a scratch workspace of one member (#925): `<tmpdir>/behold-tfws-<hash>`, whose `chant.workspace.json` declares one member of kind `chant`, named what the folder's box is named, at a link to the scratch project behold graphs the folder through. chant composes the `<member>/<id>` ids the cards carry; behold prefixes nothing. Nothing is written in the folder. The folder's box is named with a member name chant accepts (`^[a-z0-9][a-z0-9-]{0,39}$`, #927): a folder name that already is one is kept, any other is lowercased, with each run of other characters turned into `-`, and cut to 40 (`MyInfra` -> `myinfra`, `terraform_ec2` -> `terraform-ec2`), for the graph and the search alike. `code: "search-member-name"` is left only as a guard |
1300
- | a loose estate of several dirs | refused, `code: "search-estate"`: declare a workspace |
1301
-
1302
- The mode follows the view: no `env` is the declared source, `env` is a live
1303
- read (`--live --env`), and `env` with `snapshot` replays a recorded snapshot
1304
- (`--snapshot <ref> --env`). `--explain` is always passed.
1305
-
1306
- ```
1307
- GET /api/search?q=->kind:aws_kms_key&env=&snapshot=&show=
1308
- -> 200 {q, env, snapshot,
1309
- document: <chant's search document, unchanged>,
1310
- draw: {lit, onPath, edges, unobserved, nearMisses, provenance, failure, notSearched},
1311
- link}
1312
- ```
1313
-
1314
- A query chant refuses answers 400 `code: "query"` with chant's hint as the
1315
- remedy (and the document). A chant below 0.124.46 answers 422
1316
- `code: "chant-too-old"` (`SEARCH_CONTRACT_CHANT_FLOOR` in
1317
- `src/chant-floors.ts`). A `--public` serve answers declared queries and
1318
- refuses `env` and `snapshot` (403).
1319
-
1320
- `behold export --q "<query>"` (repeatable) captures each query's answer for
1321
- the source graph and every environment, so the bundle draws it with no
1322
- backend. The manifest lists `queries`; a link's `q` that wasn't captured is
1323
- named, with the captured ones, and lights nothing.
1324
-
1325
- ### Groups and the plan: `countBy` and `plan` (#922)
1326
-
1327
- Two more view keys, carried the same way as `q` (a link, `behold:view`,
1328
- `POST /api/view`, `behold shot --view`, the MCP tools, an export):
1329
-
1330
- - `countBy=kind|module|attr:<name>` is chant's `--count-by`. The document is
1331
- chant's counts branch, verbatim: `countBy`, `groups[{group, count, ids}]`
1332
- and `total` (INTENTIUS/chant#4360; `ids` is INTENTIUS/chant#4382). The page
1333
- lights each group's cards from `ids`, outlines them in the group's colour,
1334
- labels the group's first drawn card `<group> · <count>`, and the top-left
1335
- line lists the groups and the total. `draw.counts` is `{by, total, groups}`.
1336
- With `countBy`, `q` may be empty: the whole graph is counted. A chant that
1337
- lists no ids per group lights nothing and the line says so. behold never
1338
- works out a node's group itself.
1339
- - `plan=1` is the plan read. The source graph's cards carry each stock
1340
- Terraform root's plan facts (`/api/graph?plan=1`, #910) on every load, and
1341
- `q` is answered at the plan depth: `CHANT_TERRAFORM_OBSERVE=plan` in the
1342
- environment of that one chant call, with `--live --env <env>`
1343
- (INTENTIUS/chant#4358). A bare Terraform folder needs no env (the plan
1344
- read's placeholder `behold-plan` is used); a chant project or workspace
1345
- needs one (422 `code: "plan-env"`). `plan` with `snapshot` is refused,
1346
- naming both: a 400 on the route, both keys in `refused` on a link or
1347
- `POST /api/view`. A `--public` serve refuses it (403). It runs
1348
- `terraform plan -lock=false` in each root: nothing is changed, but every
1349
- resource is read.
1350
-
1351
- ```
1352
- GET /api/search?q=kind:aws_&countBy=module
1353
- GET /api/search?q=attr:planAction=replace&plan=1&show=planActions,planReplacePaths,planActionReason
1354
- ```
1355
-
1356
- `behold export --count-by <g>` captures each `--q` grouped too (with no
1357
- `--q`, the whole graph's groups); `behold export --plan` captures the plan
1358
- cards on the source graph and each `--q` at the plan depth.
1359
-
1360
- A `cap:` term (INTENTIUS/chant#4375) asks a capability, such as
1361
- `cap:internet-reachable(22)`. Its route is in the path's `because`, one
1362
- entry per capability the match relied on, each with the hops that proved it,
1363
- and `draw.edges` and `draw.onPath` include them (#926). A hop that ends on a
1364
- node inside a resource, `<id>#<attr>[n]` (a security group's ingress rule),
1365
- is drawn on the resource's card.
1366
-
1367
- ### The capability catalog: `GET /api/capabilities` (#926)
1368
-
1369
- Read it before asking a `cap:` question. It answers chant's capabilities
1370
- document byte for byte (capabilities.schema.json, contract 1), read through
1371
- the workspace reader from the same target a search asks:
1372
- `chant workspace search --capabilities --json` at a declared workspace's
1373
- root, `chant search --capabilities --json` in one project or a Terraform
1374
- folder's scratch project. Each capability has its `name`, `meaning`,
1375
- `params`, the `search` term that asks it, the questions it `answers`, what
1376
- it leaves `notEvaluated`, its `rule`, and per lexicon whether it is
1377
- supplied. A chant below 0.124.46 answers 422 `code: "chant-too-old"`
1378
- (`CAPABILITIES_CHANT_FLOOR`). behold mcp's `capabilities` tool returns the
1379
- same text. behold keeps the document per checkout and commit, so a second
1380
- read of an unmoved checkout runs no chant; a `--public` serve refuses the
1381
- route with 403 (#978).
1382
-
1383
- ```
1384
- GET /api/capabilities
1385
- -> 200 {"$schema":".../capabilities/v1/capabilities.schema.json","contract":1,"chant":"0.124.46",
1386
- "capabilities":[{"name":"internet-facing","meaning":...,"search":"cap:internet-facing",...}],
1387
- "helpers":[...]}
1388
- ```
1389
-
1390
- ### The graph pane: Cypher and resolve-from-resource (behold#1027)
1391
-
1392
- Every member's chant IR, every engine graph document (`choudoufu live-graph
1393
- -json`, `plunge graph --json`, read from `engine-graph.json` beside a member
1394
- or `.behold/graph/*.json`), every index version (the latest per scope in
1395
- `.chant/store/index/`, `_index/` on `refs/chant/snapshots`, and behold's
1396
- per-user index directory) and every cloud listing in one LadybugDB per
1397
- session. Tables: `Resource` keyed `<member>/<id>` (or the source's scope
1398
- key), `CloudId` with `KNOWN_AS` from each Resource, and `REF` with `grain`,
1399
- `origin` (`derived` for an identity match, with its `rule`) and `ambiguous`.
1400
- The database is behold's own file under `$XDG_DATA_HOME/behold/graph` and
1401
- read-only once built; a query that writes is refused. Cypher needs the
1402
- optional peer `@ladybugdb/core` and answers 503 `graph-peer-missing` with the
1403
- install line without it; resolve, the template catalog and the path-pattern
1404
- templates work without it. Every answer carries `sources`, each with
1405
- `observedAt` (null for a declared source) and `readAt`. A `--public` serve
1406
- refuses the pane. behold mcp's `ask` takes `cypher` or `resource` (with
1407
- `template` and `inputs`) beside `query`. All GET.
1408
-
1409
- ```
1410
- GET /api/graphdb sources, counts, notes, peer
1411
- GET /api/graphdb/query?cypher=&params= {"columns","rows","keys","draw":{nodes,edges},"link","sources"}
1412
- GET /api/graphdb/resolve?ref= {"candidates":[{key,matchedBy,...}],"templates":[...],"sources"}
1413
- GET /api/graphdb/template?name=&node=&in.<input>=
1414
- GET /graph the pane
1415
- ```
1416
-
1417
- ## Moving the person's open tab (#914)
1418
-
1419
- `POST /api/view` changes what every open tab of this serve draws. It is a
1420
- view change and writes nothing: no infrastructure, no project file, not
1421
- the layout cache, and nothing kept on the server.
1422
-
1423
- ```
1424
- POST /api/view
1425
- {"view": {"q": "attr:internetFacing=true", "env": "prod", "snapshot": "latest", "zoom": "resources"},
1426
- "by": "claude-code via behold mcp"}
1427
- ```
1428
-
1429
- `view` takes the URL's view keys (`member`, `zoom`, `env`, `tier`, `lens`,
1430
- `node`, `radial`, `alike`, `gates`, `focus`, `run`, `pull`, and #922's
1431
- `plan` (a boolean) and `countBy`) plus `q`, a
1432
- question in chant's search grammar, and `snapshot`, a recorded lifecycle
1433
- snapshot (`latest` or a ref) that needs an `env`. They are settled with the
1434
- same checks a link's query gets (`web/view-url.js`: `viewFromObject`,
1435
- `settleView`, `checkQuery`); an env the project doesn't declare, a `q` with a
1436
- control character or over 2000 characters, or a key that isn't a view key is
1437
- named in `refused` and the rest still moves. `at` is refused by name: in
1438
- chant's read contract it is a git revision, so a snapshot is `snapshot`.
1439
- behold does not parse `q`. The tab draws it through `GET /api/search`
1440
- (below): the matches lit, the rest dimmed.
1441
-
1442
- The answer is `200 {id, movedAt, sent, link, view, refused}`, where `sent` is
1443
- the number of open tabs it reached and `link` opens the same view. With no
1444
- tab open it is `409 {code: "no-tab", link}`: hand the person the link. A
1445
- view with nothing that can be applied is `400 {code: "view", refused}`.
1446
-
1447
- Each tab gets a `view` event `{id, movedAt, by, view}` on `/api/events`,
1448
- moves, and shows "Moved by an agent: `<by>` asked `<q>` at <time> (request
1449
- <id>)" with a Back button. An agent's move pushes a browser history entry, so
1450
- the banner's Back and the browser's Back both return to the view from before
1451
- it; up to 20 moves in a row stack this way. The person's own changes keep
1452
- replacing the entry they are on. An embedded frame with a host (`embed=1&host=`)
1453
- ignores the event, because its host owns its view (#476).
1454
-
1455
- `by` is a label of at most 80 printable characters. Without one it is the
1456
- request's User-Agent product token. Anyone who can reach the serve can send
1457
- any name, so `by` says who the caller claims to be and is not authentication.
1458
-
1459
- Refused: under `serve --public` (405 from the request guard, and 403 `code:
1460
- "public"` in the route itself), and under every `behold preview`, with or
1461
- without `--emulator` (403 `code: "preview"`). A terragucci or SQL Yodeler
1462
- repo allows it, since it writes nothing. A static export has no server, so no
1463
- route.
1464
-
1465
- ## A picture of a view (#915)
1466
-
1467
- `behold shot "<query>" [project-dir] -o out.png` and `GET /api/shot` take a
1468
- PNG of a view and give the link to the same view. Both call `src/shot.ts`.
1469
- The page is behold's own, loaded in a headless browser with
1470
- `embed=1&bare=1&frame=matches`: it lights what the view asks for, dims the
1471
- rest, frames the lit cards with the kiosk's arithmetic (`web/kiosk-shot.js`),
1472
- draws one caption line (what was asked, from where, when), and sets
1473
- `data-behold-shot` on `<html>` to `drawn`, `no-matches` or `failed`. Nothing
1474
- is photographed until it does: a page that never reports ready within 60 s,
1475
- or one that draws no cards, is refused and no file is written.
1476
-
1477
- ```
1478
- GET /api/shot?node=aws_vpc.main&env=prod&width=1600&height=1000
1479
- -> 200 image/png, Behold-View-Link: http://127.0.0.1:4600/?env=prod&node=aws_vpc.main,
1480
- Behold-Shot-State: drawn | no-matches | failed
1481
- ```
1482
-
1483
- The browser comes from `playwright-core`, an optional peer behold does not
1484
- install: the system Chrome first, then Playwright's `chromium-headless-shell`.
1485
- Without either the CLI exits 1 with the install line and the route answers
1486
- 501 `code: "no-browser"`. `--env`/`env=` draws the env's live view, and
1487
- `--snapshot <ref>`/`snapshot=` a recorded snapshot of it (`at` is a git
1488
- revision and is not taken). The route answers bytes, never a path, and is
1489
- refused on `serve --public` (403), since each shot starts a browser. The CLI
1490
- uses the serve at `--url`, or starts behold's app for the project on a free
1491
- loopback port and stops it after; without `-o` the PNG goes under the OS temp
1492
- directory. Nothing is written in the served project.
1493
-
1494
- A query's matches are lit and framed (#913). Without a query, a shot frames
1495
- the view's own `node` or `focus` (`behold shot "" --view node=<id>`).
1496
-
1497
- Publishing is opt-in per call (#923, `src/shot-publish.ts`): `--publish
1498
- <remote>[/<branch>]` (branch default `behold-shots`) commits the PNG to that
1499
- branch of the remote, in the repo `--publish-repo <dir>` names (default: the
1500
- current directory's), tracked with Git LFS (`*.png` in the branch's
1501
- `.gitattributes`), pushes it, and prints the raw URL (at the commit, for
1502
- GitHub and GitLab) after the view link. It is git plumbing on a private index:
1503
- no checkout's tree, index or HEAD changes, and the branch checked out in the
1504
- repo or the project, or its upstream, is refused. Without git-lfs, or when the
1505
- remote does not take the LFS object, it refuses with the setup line and exits
1506
- 1 before the branch moves; the local PNG is kept. `behold mcp`, `GET
1507
- /api/shot` and a `--public` serve never publish.
1508
-
1509
- ## The graph document: `behold-graph/1` (#1066)
1510
-
1511
- A graph snapshot (`{ir, meta}`, what `/api/graph` answers and what every
1512
- export snapshot holds) becomes a versioned document through
1513
- `toDocument(snapshot, opts)` (`src/to-document.ts`). The types, the version
1514
- string and `checkGraphDocument` are in `src/graph-document.ts`, which imports
1515
- nothing, so a browser host can load it. The JSON Schema ships in the package
1516
- at `schemas/graph/v1/graph.schema.json` and is published at
1517
- https://intentius.io/behold/schemas/graph/v1/graph.schema.json (its `$id`,
1518
- the same bytes from `docs/public/`; a test holds the two together).
1519
-
1520
- ```
1521
- {schema: "behold-graph/1", generator: {behold, chant?}, origin: {dir, rev?},
1522
- cut: {kind: "whole" | "around" | "changed", ...}, nodes[], edges[], groups[],
1523
- notes[], layout?}
1524
- node: {id, title, subtitle, kind, lexicon, box?, file?, line?, change?,
1525
- status?, color?, mainstat?, secondarystat?, stackOf?, detail__member?,
1526
- detail__root?, detail__namespace?, detail__release?, attrs}
1527
- edge: {id, source, target, kind, inferred, rule?, via?}
1528
- group: {id: "<kind>:<key>", title, kind: stack | wave | pipeline | container, parent?}
1529
- note: {kind, text, short?, box?, count?}
1530
- ```
1531
-
1532
- The node and edge field names are the ones Grafana's node graph panel takes,
1533
- so the panel reads `nodes` and `edges` with no transform. `subtitle` is the
1534
- tool (`k8s` reads `kubernetes`), `status` is `attrs._status`, `color` its
1535
- pinhole bar colour, `mainstat` the drift record's words or the plan's action,
1536
- `change` the plan's action unless it is `no-op` or `read`. `file` is relative
1537
- to the repository root, and absent when behold cannot place it there; an
1538
- absolute `sourceLoc` is dropped. An edge whose end the view does not draw is
1539
- left out and counted in `notes` (`edges-left-out`), so every `source` and
1540
- `target` names a node. Edge ids are `<source>-><target>:<kind>[:<via>]`, with
1541
- `#2`, `#3` on repeats. `rule` names the join behind an inferred edge: chant's
1542
- catalog rule (`origin: "derived"`), or `behold:<join>` from the `join` field
1543
- each behold pass now sets beside `inferred: true` (`value-match`,
1544
- `k8s-declared`, `estate-member`, `cluster-anchor`, `composite-deps`,
1545
- `choudoufu-lexicon`, `choudoufu-estate`). `attrs.source` is left out unless
1546
- `opts.source` asks for it.
1547
-
1548
- `documentOptions({projectDir, projectDirs?, workspace?, behold, rev?})`
1549
- (`src/graph-document-context.ts`) works out what the IR does not carry: the
1550
- served directory relative to its repository (the nearest `.git` above it),
1551
- each member's directory and Terraform roots, and a scrubber that rewrites this
1552
- machine's paths to repository-relative ones, the home directory to `~` and
1553
- the temporary directory to `$TMPDIR`. The same snapshot and options give
1554
- byte-identical JSON. Within `behold-graph/1` fields are only added and a
1555
- reader ignores what it does not know; `checkGraphDocument` refuses any other
1556
- `behold-graph/<n>` by name.
1557
-
1558
- ## The graph from the command line: `behold graph` (#1058)
1559
-
1560
- `behold graph [dir] [--json | --ir] [-o <file>] [--detail 0..3] [--source]
1561
- [--every-card]` reads a directory and prints it, with no server, no browser
1562
- and no write but the `-o` file (src/graph-cli.ts). `--json`, the default, is
1563
- the `behold-graph/1` document; `--ir` is the unversioned `{ir, meta}` that
1564
- `/api/graph` answers, without its SVG. `--mermaid [--forge gitlab|github|forgejo]`
1565
- is a flowchart that fits that forge's character budget (below); `--svg` is
1566
- reserved for its painter (#1061) and exits 2 until it applies. Exit 1 is a
1567
- directory chant would not read (its refusal and remedy on stderr), exit 2 a
1568
- usage error. No output holds an absolute path: both go through
1569
- `documentOptions`' scrubber, and `attrs.source` is left out without
1570
- `--source`.
1571
-
1572
- The Mermaid writer (#1060) is `toMermaid(doc, { forge })` in
1573
- src/graph-mermaid.ts, over a `behold-graph/1` document, so a cut applies first.
1574
- Ids are `n<index>` and `g<index>` over the sorted ids, one label line per card,
1575
- boxes as subgraphs, inferred edges dotted, labels quoted and escaped with
1576
- Mermaid entity codes. A document with a plan's `change` or a cut's `seed` gets
1577
- four `classDef` lines: added (`create`), changed (`update`, `replace`), removed
1578
- (`delete`) and neighbour (a card in the cut that is neither a seed nor changed).
1579
- Over the budget it drops neighbours first, then whole boxes (those with the
1580
- fewest changed cards first), and ends with a `N cards not shown` card; it never
1581
- returns text over the budget. The budgets are one table, `FORGE_BUDGETS` in
1582
- src/mermaid-budgets.ts: gitlab 2,000 characters, github and forgejo 20,000 and
1583
- 250 edges, a whole comment under 60,000. Each row has `confirmed: false` until
1584
- the live check (e2e/forge-limits, #1065) records the forge's real figures; that
1585
- check's result is an edit to the row. `forgeComment` builds the comment body
1586
- (marker, count line, fenced diagram) and posts the per-root table from
1587
- `rootTable` instead when the diagram had to leave cards out or the comment
1588
- would reach its limit; the action (#1062) and the MCP text fallback (#1073)
1589
- use these.
1590
-
1591
- The read is `graphView(dir, opts)` (src/graph-view.ts): `readGraph`, then the
1592
- lenses `/api/graph` runs over an estate's source picture: the plan when
1593
- `terraformPlan` is passed (the server's setting, as an argument), collapse,
1594
- stacking alike cards (`--every-card` turns it off), and the note, joined by
1595
- `viewNote`. The route calls `shapeEstate` and `viewNote` from the same module,
1596
- and src/graph-view.test.ts holds the view equal to the route's answer. The
1597
- logical and components lenses, the traffic prediction (it reads per-user
1598
- settings) and the SVG stay in the route. An output format is one entry in
1599
- `GRAPH_FORMATS` (src/graph-formats.ts); a cut is a function over the document
1600
- that the CLI hands a format as `cut`.
1601
-
1602
- ### A bare cluster: `behold graph --context <name>` (#1083)
1603
-
1604
- `behold graph --context <name> [--kubeconfig <file>] [--namespace a,b]
1605
- [--types t,u] [--allow-exec-plugin]` draws the cluster a kubeconfig context
1606
- points at, with no chant project and no directory (src/read-cluster.ts).
1607
- `--kubeconfig` alone reads that file's current context; without it the file is
1608
- the first path in `KUBECONFIG`, then `~/.kube/config`. There is no reader of
1609
- behold's own. `readCluster` calls chant's `indexCloud` (the cloud lister
1610
- `behold index kubernetes` runs: API discovery, then a paged LIST per kind, read
1611
- allowlist only) with the `none` store, so no index version and no file is
1612
- written, and hands the result to `readComposed` (src/read-graph.ts), the passes
1613
- `readGraph` runs over a directory's estate. `readGraph` still reads no
1614
- kubeconfig. Cards are boxed by namespace (cluster-scoped objects in `cluster`)
1615
- and take the ids `<namespace>/<Kind>/<name>`; an edge to an object the read did
1616
- not list is dropped and counted in the note. What the objects name outside the
1617
- cluster (web/outside-refs.js, #1082) is added as cards in a box called Outside
1618
- the cluster. `behold serve` does not take a context yet.
1619
-
1620
- Credentials: a token, a token file or a client certificate. A user that
1621
- authenticates through an exec plugin (the GKE, EKS and AKS tools write these)
1622
- is refused with exit 2, naming the context, before chant is loaded and before
1623
- any request. `--allow-exec-plugin` runs the plugin once (src/kube-exec.ts, the
1624
- ExecCredential protocol, no terminal) and reads with the credential it prints.
1625
- An `auth-provider` user is always refused. Whether the switch should be on by
1626
- default is the maintainer's ruling and is open.
1627
-
1628
- The live read masks every key matching /secret/i, which chant's typing then
1629
- shows as `[REDACTED]`. On chant 0.124.58 an ExternalSecret's
1630
- `spec.secretStoreRef` is masked whole, so its store and provider draw no card
1631
- and the note says so (chant#5116 keeps such reference fields readable). An Argo
1632
- CD cluster Secret's name and server are masked too, and chant#5116 decides
1633
- whether they show. behold draws what the lister returns under either answer.
1634
- `BEHOLD_K3D_TESTS=1 npx vitest run src/read-cluster-live.test.ts` runs the
1635
- live test on a k3d cluster named `behold-read-cluster-<pid>`, deleted afterward
1636
- unless `BEHOLD_K3D_KEEP=1`; `BEHOLD_EXPECT_5116=1` makes its reference test
1637
- fail instead of skip.
1638
-
1639
- The same command is the `behold-graph` bin of `@intentius/behold-graph`,
1640
- built from this repo into packages/graph by `npm run build:graph` (part of
1641
- `npm run build`). Its entry is src/graph-package.ts, which exports `readGraph`,
1642
- `graphView`, the formats, `toDocument` and the document types. Its
1643
- dependencies are packages/graph/budget.json's allowlist, at behold's own
1644
- ranges and version (a test holds both). `npm run check:graph-package` (CI runs
1645
- it after the build) packs it, installs the tarball into an empty directory,
1646
- prints the installed size, and fails above the budget, on a dependency not on
1647
- the allowlist, or when `npm ls --all` names hono, `@hono/node-server`, the MCP
1648
- SDK or the Kubernetes client. The first measurement was 127 MB and 55
1649
- packages, against 238 MB and 162 for behold; the budget is 140 MB and 60.
1650
- Most of it is chant itself (73 MB) and the TypeScript compiler chant loads
1651
- configs with (23 MB). Publishing the package is the maintainer's step.
1652
-
1653
- ## The single-file viewer (#1070)
1654
-
1655
- `npm run build:viewer` (scripts/build-viewer.mts) writes
1656
- `dist/behold-viewer/`: `index.html` (no inline script), `viewer.js` (a
1657
- classic script), `viewer.mjs` (the same as an ES module), `viewer.css`, a
1658
- stand-in `graph.js`, and `viewer.html` with the script and the styles
1659
- inlined, for an MCP resource or an unzipped artifact. It draws a
1660
- `behold-graph/1` document with the painter `/api/graph` uses: the document is
1661
- turned back into the IR (src/viewer/document-ir.ts, a card's box walked up to
1662
- its stack, pipeline, wave and container) and painted by `paintDocument`
1663
- (src/viewer/paint.ts), with the same box badges. The source is src/viewer/.
1664
-
1665
- The document comes, in this order, from a `behold:graph {document, icons?}`
1666
- message, from `window.__BEHOLD_GRAPH__` (graph.js, the only form that works
1667
- from `file://`), or from `?src=<same-origin path>`. Options come from the
1668
- query string and from `window.__BEHOLD_VIEWER__`, the query winning:
1669
- `theme` (light, dark, blueprint, aws; absent, `prefers-color-scheme`),
1670
- `node`, `focus` (box keys or ids), `host` (the parent's origin), `transport`
1671
- (post, vscode, mcp, none) and `src`. In: `behold:theme {theme?, vars?}` (CSS
1672
- custom properties only) and `behold:view {node?, focus?}`. Out:
1673
- `behold:ready`, then `behold:select {id, kind, file}` per pick.
1674
- src/viewer/transport.ts has the three hosts: a parent page (`postMessage` to
1675
- `host` only, and only its messages read), a VS Code webview
1676
- (`acquireVsCodeApi`, called once), and an MCP Apps view (JSON-RPC:
1677
- `ui/initialize`, the document from `ui/notifications/tool-result`'s
1678
- `structuredContent`, the theme from the host context, a pick sent as
1679
- `ui/update-model-context`). With no `transport`, a page with
1680
- `acquireVsCodeApi` is VS Code, one with `host` is a parent page, and a
1681
- framed page with neither is MCP Apps.
1682
-
1683
- The layout runs in a Web Worker: the script starts itself as the worker,
1684
- from its own URL or, inlined, from its own text, and paints on the page when
1685
- no worker starts (index.html opened from `file://`). A document with no
1686
- boxes above `FLAT_LIMIT` cards is refused with the reason, since one flat
1687
- layout grows far faster than the card count. The page sets
1688
- `data-behold-viewer` on `<html>` (`waiting`, `drawing`, `drawn`, `refused`)
1689
- and `window.__BEHOLD_VIEWER_STATE__` (cards, where it laid out, time to first
1690
- paint).
1691
-
1692
- The vendored icon table is left out of the build: it is 544 KB of the 684 KB
1693
- painter. A host hands over the icons its document uses, as
1694
- `window.__BEHOLD_ICONS__` or the message's `icons`; `graphScript(doc)`
1695
- (src/viewer/graph-script.ts) writes a graph.js with both, and
1696
- `documentIcons(doc)` finds the icons by painting the document once with the
1697
- full table (`recordIcons` in src/icon-packs.ts). Once a host supplies icons,
1698
- an icon it did not supply falls through to pinhole's keyword glyph
1699
- (`supplyIcons`). The build fails above 300 KB minified or 100 KB gzipped for
1700
- `viewer.js` or `viewer.mjs`, above 1 MB for the directory, on any Node
1701
- built-in in the bundle, and when `viewer.js` names `EventSource` or
1702
- `WebSocket`. On pinhole 0.5.0 it fails on the four `node:` imports in
1703
- pinhole's root (#1069), which pinhole 0.6.0 removes.
1704
- src/viewer/viewer-browser.test.ts opens it in headless Chrome from `file://`
1705
- and under `default-src 'none'; script-src 'self'; style-src 'self'
1706
- 'unsafe-inline'`, and skips while pinhole is 0.5.0.
1707
-
1708
- ## Over MCP: `behold mcp` (#916)
1709
-
1710
- `behold mcp [project-dir] [--url <serve> | --port <n>]` is a stdio MCP server
1711
- with five tools for an agent (and a sixth for a view), most of them clients of a running serve's HTTP API; `graph` (#1073, below) reads the directory itself. An agent reads
1712
- `capabilities` first (#926): it calls `GET /api/capabilities` and returns
1713
- chant's capability catalog, the read contract's `capabilities` document
1714
- (`chant search --capabilities --json`, INTENTIUS/chant#4375), byte for byte.
1715
- It names each capability a `cap:` term asks, what it means, its parameters,
1716
- the search term, the questions it answers, what it does not evaluate, its
1717
- rule and which lexicons supply it, and it takes no arguments. `ask` calls
1718
- `GET /api/search` and returns chant's search document verbatim, with `link`
1719
- and `drawn: false` added after its own fields (a test holds it byte for byte
1720
- to what chant prints); it takes `query`, `env`, `snapshot` and `show`, and
1721
- never moves the tab. `show` calls
1722
- `POST /api/view` (its `by` is the MCP client's name plus "via behold mcp"),
1723
- and `shot` calls `GET /api/shot` and returns the PNG as MCP `image` content
1724
- followed by a text block `{link, state, serve}`. They take `query`, `env`,
1725
- `snapshot`, `member`, `zoom`, `focus` and `node`; `shot` also takes `width`
1726
- and `height`. The answers are chant's: behold passes chant's documents
1727
- through and computes none of its own.
1728
-
1729
- `graph` (#1073) draws the repository, or a cut of it, and takes `dir` (a folder
1730
- inside the project), `around` (comma-separated card or box ids, or a box title
1731
- or Terraform root as the roots table prints it), `changed` (`<base>..<head>`),
1732
- `depth` and `direction`. It reads in this process with the calls `behold graph`
1733
- makes (`src/mcp-graph.ts`) and answers in text for every host: the counts, the
1734
- cut, a Mermaid block when it fits (`MCP_MERMAID_BUDGET`, nine thousand
1735
- characters) or a table of roots when it does not, and a link to the running
1736
- serve at the card or box asked for, else the line that starts one. The whole
1737
- text stays under `TEXT_CHARS` (18,000), well under Claude Code's 10,000-token
1738
- warning, and holds no document JSON. `_meta.ui.resourceUri` names
1739
- `ui://behold/viewer` (MIME type `text/html;profile=mcp-app`, MCP Apps spec
1740
- 2026-01-26), which `resources/read` serves from `src/viewer-resource.ts`:
1741
- `dist/behold-viewer/viewer.html` (#1070's `npm run build:viewer`) when it is in
1742
- the package, else a page saying the view is not in this build. The view gets
1743
- its document from `graph_document`, a tool with `_meta.ui.visibility: ["app"]`
1744
- that takes `graph`'s arguments (`structuredContent.view` of a `graph` result
1745
- is exactly those), so the cards never enter the model's context.
1746
-
1747
- It finds the serve through `--url`/`--port`, then the per-user registry at
1748
- `<os.tmpdir()>/behold/serves/<pid>.json` (`{url, pid, projectDir, version,
1749
- startedAt}`, written by every serve at start, rewritten on a project switch,
1750
- removed at exit, a dead pid ignored; `BEHOLD_SERVES_DIR` moves it), then
1751
- `http://127.0.0.1:4600`. It confirms the serve through `GET /api/project`.
1752
- `show` refuses a serve of another project, naming both, and refuses with the
1753
- serve command when none runs. `capabilities`, `ask` and `shot` with no serve of the project
1754
- start behold in their own process for the call (`src/shot-cli.ts`), and the
1755
- answer comes from the same route.
1756
-
1757
- Arguments are checked against each tool's schema (`additionalProperties:
1758
- false`), a credential-named one is refused by name, and a refusal is an
1759
- `isError` result carrying the route's `{error, code, remedy}`. The server
1760
- refuses to start with a tool whose name holds a write word (deploy, apply,
1761
- approve, run, op, rollback, write and kin), and a call to an unlisted tool is
1762
- refused with the same words.
1763
-
1764
- ## The act loop (delegated, never direct)
1765
-
1766
- behold does not apply. To change the estate:
1767
-
1768
- 1. Edit the chant `.ts` source (the node's `sourceLoc`), or
1769
- 2. Trigger a committed Op via chant's MCP:
1770
- - `op-run <name>` — start the project's `ApplyOp` (code→cloud) or `ReconcileOp`
1771
- (cloud→code PR).
1772
- - `op-signal <name> <gate>` — approve a gate (e.g. a destructive apply).
1773
- - `op-status <name>` — watch phases; `op-report <name>`, the run report.
1774
-
1775
- Every mutation is a gated, durable Temporal workflow with a human-confirmable gate
1776
- and saga rollback. There is no behold endpoint that mutates the cloud.
1777
-
1778
- A run behold triggered is asked for chant's run events (#679, chant#4019:
1779
- `chant run <op> --events-json`, `chant run <target> --components --env <env>
1780
- --events-json`), so the ops lens and the dial show each step's start and settle,
1781
- a skip with chant's reason, a cache hit, and the gate or decision point a run
1782
- waits on, as they happen, and a pending gate renders as a card with an Approve
1783
- button. That button is `op-signal`, the same delegated write, and nothing else
1784
- about the run is behold's to decide: the verdict is the stream's own
1785
- `run-settle`, a stream that ends without one leaves the playhead at the last
1786
- settled step and says it was lost, and a gate paints as pending only when chant
1787
- named it (`gate-waiting`, or `chant run status`).
1788
-
1789
- `src/run-events.ts` is the one boundary every run line crosses. It validates
1790
- each line against chant's `run-event.schema.json` (vendored in
1791
- `src/run-event-schema/` from @intentius/chant 0.124.28, its source commit in
1792
- `RUN_EVENT_SCHEMA_SOURCE`), since the line comes from the project's chant,
1793
- not behold's, and refuses a line that fails it; it folds the stream into what
1794
- the dial and the ops lens render. The event types are chant's own `RunEvent`
1795
- and `RunEventBody`, imported as types only. `src/run-events-chant.test.ts`
1796
- runs the whole path against a real chant when `BEHOLD_TEST_CHANT_BIN` is set.
1797
-
1798
- A run behold did not start is followed when the status read names it: `chant
1799
- run events <run> --json --follow` replays what chant kept on this host and tails
1800
- it to `run-settle`. A run killed outright writes no settle, so a follow that is
1801
- silent for `BEHOLD_RUN_EVENTS_IDLE_MS` (60 s) asks `chant run status` whether it
1802
- still runs, and ends as lost when it does not or after
1803
- `BEHOLD_RUN_EVENTS_MAX_IDLE_MS` (30 min) of silence. A steward run keeps no
1804
- events here, and the playhead says so.
1805
-
1806
- The read has a floor, `RUN_EVENTS_CHANT_FLOOR` (0.124.28). Below it behold
1807
- starts runs with the older `--progress-json` (degraded mode: settled steps
1808
- only, no skip reasons, cache hits or gate events, and no follow), translates
1809
- those lines at the same boundary, and the dial and the playhead say they are
1810
- degraded. A local pipeline run (gitlab-ci-local, a forgejo runner) is the one
1811
- path that still reads a log, because chant does not run it; the dial labels it
1812
- best-effort, and only its exit code is certain (src/ci-run.ts).
1813
-
1814
- ### The executor contract (#165, #61)
1815
-
1816
- A member's `chant.config.ts` may designate which forge deploys an environment,
1817
- on the environment's entry (#470):
1818
-
1819
- ```ts
1820
- environments: [{ name: "prod", executor: { forge: "github", workflow: "deploy-prod.yml" } }]
1821
- ```
1822
-
1823
- behold reads it from `chant workspace graph --composites --json`
1824
- (`components[].environments[].executor`, floor `EXECUTOR_CHANT_FLOOR` 0.124.47,
1825
- src/executor.ts) through the workspace reader. It never reads `.behold.json`'s
1826
- `executor` (retired; `behold doctor` warns), and never derives it from a
1827
- `chant-components-<env>` workflow name (maintainer ruling, 2026-10-23). An older
1828
- chant prints no `executor`, and no row means none declared. `reason.code`
1829
- `executor-config-unreadable` stays designated and fails closed.
1830
-
1831
- It designates the committed WORKFLOW, not just the forge: two environments'
1832
- generated pipelines carry identical job ids, so a picker cannot tell them
1833
- apart, and a contract that names prod must not sit on a guess. For a
1834
- designated env, `POST /api/apply` and a committed ApplyOp's `/api/ops/:name/run`
1835
- answer `409 {code: "executor-forge"}`, auto-sync declines out loud, and the
1836
- only deploy is `POST /api/ci/dispatch?env=<env>`, which runs the designated
1837
- workflow through the operator's own `gh` and follows it on the dial. Any
1838
- approval the workflow's environment requires is granted on the forge by a
1839
- GitHub identity behold does not have; the dial links the run's page and offers
1840
- nothing else. Fail-closed: a designation behold cannot honour (a typo'd forge,
1841
- a missing or non-dispatchable workflow, a forge with no trigger here) disables
1842
- Deploy for that env with the reason on `/api/project`'s `executor` block, and
1843
- never falls back to running it here. `/api/project` reports `{forge, workflow,
1844
- ok, reason?}` per designated env.
1845
-
1846
- Without a designation, dispatch picks the committed workflow named for the env
1847
- (`chant-components-<env>`, chant ≥ 0.54.0); on the older job-overlap match it
1848
- refuses a tie rather than letting directory order choose, and a workflow named
1849
- for another env never stands in. `just e2e-ci-github` proves the contract
1850
- against the real forge (example-ci + `.github/workflows/behold-e2e-dispatch.yml`),
1851
- including the `lost` verdict, which `BEHOLD_CI_FOLLOW_TIMEOUT_MS` and
1852
- `BEHOLD_CI_POLL_FAIL_BUDGET` let a run force on purpose; a lost run is the one
1853
- `POST /api/ci/readopt` re-follows. The same e2e dispatches into an environment
1854
- with a required reviewer (`behold-e2e-gated`): the run holds at `waiting`, the
1855
- progress state carries `waiting: true` and the run's `url`, the now-line says
1856
- the approval is granted on the forge, and a cancellation lands as `failed`.
1857
-
1858
- A dispatched run is followed honestly (#165 §6, PR #350): only GitHub's own
1859
- `completed` + conclusion paints `ok`/`failed`; a poll-failure budget or the
1860
- follow deadline promotes the run to `lost` (chips frozen at last-observed,
1861
- the run possibly still live at its own page), never to a verdict. The adopted
1862
- run id is persisted as one JSON per project under `~/.behold/ci-runs/`, the
1863
- operator's machine-state, outside the project tree, so behold still writes
1864
- nothing in a served project (the Invariant below). `GET /api/ci/run` reads the
1865
- record; `POST /api/ci/readopt` (also attempted once at boot) re-follows an
1866
- unconcluded run by its saved id, so a restart mid-deploy leaves the run a
1867
- reader instead of nothing.
1868
-
1869
- ## The operating loop (a strip, a timeline, and a gate that is not the run gate)
1870
-
1871
- A project that declares a `ConvergeOp` gets an operator strip on the ops lens:
1872
- per loop, the last tick's own log line (verbatim, with its instant), the lease,
1873
- and how many gates are pending. **One** tick — `chant operator status` keeps only
1874
- `records.at(-1)`, so the strip is never a timeline, and it says so.
1875
-
1876
- The timeline is its own read: `GET /api/operator/log` → `chant operator log
1877
- --json` (chant#2029), the tick records and the gate resolutions against them
1878
- merged oldest-first. It lives in a panel that grows from the strip, and two rules
1879
- hold it there. It is **pulled**, on the click that opens it and never on a timer.
1880
- And it is **bounded** — `--limit` on every invocation, 50 by default and 200 at
1881
- most, `--since` when asked, because the ledger grows one line per tick forever;
1882
- the answer reports the window it used, so a full one can't read as the end of
1883
- history. The route checks the project's chant version *before* it spawns: below
1884
- 0.53.1, `chant operator log` resolves to `chant operator`, the tick daemon, and
1885
- behold reading a history must never become behold running an operator.
1886
-
1887
- Since chant 0.53.1 (chant#2027) a tick record carries an `id` and the
1888
- per-component verdicts it derived, and both ride through to
1889
- `[].lastTick.{id,components}`. The strip line names the tick (truncated), and
1890
- the verdicts join onto the component DAG by component name, the same key the
1891
- live `chant components status` read is joined by. They join **under** that read:
1892
- a tick only ever feeds the last tier of `componentStatusColor` (the
1893
- reconciliation verdict), only on a node the live read left unpainted, and only
1894
- while the tick is younger than fifteen of chant's own operator rounds. Past
1895
- that it is named on the node, dated, and painted nothing: a graph fill has
1896
- nowhere to put "as of an hour ago". A chant older than 0.53.1 sends neither
1897
- field and every one of these paths is a no-op.
1898
-
1899
- Two gate cards exist and they are **different acts**:
1900
-
1901
- - The **run gate** — `POST /api/ops/:name/signal/:gate` → `chant run approve
1902
- <op> <gate>` (chant#2121 renamed `chant run signal`, #459). Records the
1903
- resolution; a runtime that parks a run is woken, and the local one reads it
1904
- when the Op runs again (behold runs `chant run <op> --events-json`, which
1905
- says `gate-waiting`, settles `gated` and exits 3).
1906
- - The **converge gate** — `POST /api/operator/approve/:op/:gate` →
1907
- `chant approve <op> <gate>`. **Records a fact and unblocks nothing.** chant's
1908
- gate ledger says it outright: the local executor still refuses a gated op,
1909
- resolution or not. The next tick reads the fact. The card says this in its
1910
- body, and the toast after the click says "recorded; the next tick acts on it".
1911
-
1912
- A gate fact carries its address since chant#2028, on both halves, and the card
1913
- links it under chant's own words — `approve at: <url>`. The field is optional by
1914
- design (a local tick with no PR behind it has none) and never synthesized, so a
1915
- fact without one renders no link and no placeholder for one, and a url behold
1916
- would not put behind an `href` reads as no address at all.
1917
-
1918
- A gate someone already resolved simply leaves `pendingGates`, the status read
1919
- carries no `resolvedBy`/`when`, so the strip shows no resolved-by line rather
1920
- than attributing an approval to nobody. The timeline is where resolutions are
1921
- named, because there they are records rather than an inference.
1922
-
1923
- An `OperatorStack` (chant#1940) declares the loop as a k8s estate, so it already
1924
- appears in the entity graph. behold names it there, the Namespace as the loop's
1925
- home, each CronJob as a converge tick — off chant's own
1926
- `app.kubernetes.io/component: converge-tick` labels, never a naming convention.
1927
-
1928
- ## Who an approval is recorded as (#690)
1929
-
1930
- chant never signs a person in (ws-052); the surface that does passes the person
1931
- to chant as `--actor` (ws-080). behold has no login, so `src/approver.ts` names
1932
- the person for each request, in this order:
1933
-
1934
- - `--identity-header <name>` (BEHOLD_IDENTITY_HEADER, the per-user settings'
1935
- `approver.header`): behold sits behind a proxy that signed the person in
1936
- through the forge or OIDC, and the header names them. A bare login is an
1937
- account on `--identity-forge` (github unless set). A request without the
1938
- header approves nothing (`403 no-identity`). Refused at startup with a
1939
- `--host` other than loopback, since anyone reaching the port could send it.
1940
- - `--as <principal>` (BEHOLD_APPROVER, the per-user settings' `approver.as`): one
1941
- person runs behold and names themselves, `github:<login>` or a principal the
1942
- signers file lists.
1943
- - Neither: chant's own fallback (GITHUB_ACTOR, GITLAB_USER_LOGIN, USER), and
1944
- behold passes no `--actor`.
1945
-
1946
- Without a trusted header, a request carrying a usual proxy identity header
1947
- (`PROXY_IDENTITY_HEADERS`, such as `X-Forwarded-User`) is refused with `403
1948
- identity-header` on every approve route, rather than recorded as someone else.
1949
- Every approve route (`/api/workspace/gates/approve`, the converge gate's
1950
- `/api/operator/approve`, the run gate's `/api/ops/:name/signal`) adds
1951
- `--actor` (`--approver` on `chant run approve`) and `--note "approved in
1952
- behold"`. chant's ledger has no channel for a surface (its `origin` is `cli`,
1953
- `mcp` or `acp`), so the note is where behold is named. A workspace gate that
1954
- status marks `signed` is approved with `--sign <key>` when behold holds the
1955
- person's key (`--signing-key` beside `--as`, or the per-user settings'
1956
- `approver.keys` by principal) and refused `422 signed` with the line to run
1957
- otherwise. The key path never reaches a page: `GET /api/workspace/gates`
1958
- carries `approverIdentity: {principal, source, forge, signs}`, or `approver:
1959
- null` and `approverRefusal`. `src/approver-chant.test.ts` runs the whole path
1960
- against chant with a throwaway key and workspace.
1961
-
1962
- ## The trunk lane (#680)
1963
-
1964
- `GET /api/workspace/lane` (src/trunk-lane.ts) answers "what is in flight and
1965
- where is it?" for a served workspace, read through the reader on every request
1966
- and kept nowhere:
1967
-
1968
- - `chant ci list --json` at the root: the trunk's commits within ci.green's
1969
- window, each `green`, `revoked` or `undecided`, with its phases and runs
1970
- and its work items (`work`, chant#4029). It reads local tags only, so a
1971
- commit that failed without ever being green reads `undecided`.
1972
- - `chant workspace status <env> --json` once per environment, in the order the
1973
- members' `promotionOrder` gives (merged in member order): the gates with
1974
- `env` equal to that environment, with `gitSha`, `runId` and `changeSet`, and
1975
- the deploy records.
1976
- - `chant release list --json` in each member whose promotion order is not
1977
- empty: the releases, each with its commit and the environments that run it.
1978
-
1979
- The answer: `trunk` (or `trunkRefusal`), `commits[]` with `where` (`runs` or
1980
- `waits` per environment), `environments[]` with `releases`, `deploys` (records
1981
- no release covers) and `waiting` (each gate with `commitState`),
1982
- `order` (`promotion`, or `env` when no member declares one), `releaseRefusals`,
1983
- and the gate strip's approver fields. Gates with no environment stay in the
1984
- gate strip. The three reads are `ci list` and `release list` through
1985
- `readTrunk` on the reader (they are contract 1 documents outside `chant
1986
- workspace`) and `status` through `read`; each has its floor in
1987
- src/chant-floors.ts (0.124.28), and the route refuses a chant below any of them
1988
- before spawning. The panel's Trunk tab (web/trunk-lane.js) reads it when opened
1989
- and approves through `POST /api/workspace/gates/approve`.
1990
-
1991
- The release column (#692) sits between the commits and the environments:
1992
- `releases[]`, every release `release list` names, newest first, each with its
1993
- `commit`, `label` and digest, its newest `cut` (who, when, and chant's
1994
- `signatureCheck`), `runs` (environments in promotion order, with components),
1995
- `waits` (a release gate that binds it, or a gate of its member reached at its
1996
- commit; `pending`, or `superseded`), and `next`, the environment its member's
1997
- promotion order names after the last one that runs it (null in the last one,
1998
- and for a revoked release, which chant never promotes). Each commit carries
1999
- `cuts`, the releases cut from it.
2000
-
2001
- `configOnly` is true when a release carries artifact digests and they equal
2002
- its previous release's. The previous release is the one of the same member
2003
- cut from the nearest older commit: releases are ordered by their commit's
2004
- place in the trunk list (first-parent, newest first), a commit older than the
2005
- list after every listed one, and ties (one commit, or commits outside the
2006
- list) by `release list`'s order, newest cut first. That is how `release cut`
2007
- reuses an unchanged artifact's digest. It is null for the oldest release and
2008
- for a release with no artifact digests (a member with no components).
2009
-
2010
- The revoked fields ship in chant 0.124.29 (`RELEASE_COLUMN_CHANT_FLOOR`,
2011
- chant#4033, chant#4043): `revoked` on a `release list` release (the
2012
- ci/revoked tag, with `rollback`, the lines status gives for each component
2013
- running it), `superseded` on each environment (release gates chant reads as
2014
- superseded, never approvable), `rollback` on an environment's releases, and
2015
- `release` and `rollback` on a deploy record. `releaseColumn: {full, floor}`
2016
- says whether they were read. Below the floor nothing is refused: the column
2017
- comes from `release list` alone with no revoked mark, and the tab says which
2018
- chant would add it.
2019
-
2020
- A mixed environment (#731): from chant 0.124.29
2021
- (`MIXED_ENVIRONMENT_CHANT_FLOOR`, chant#4035, chant#4072) status gives an
2022
- environment `mixed` when its components run different releases, or a
2023
- promote, rollback or redeploy left one `failed` or `gated` (its
2024
- `outcomes.jsonl` on chant/lifecycle). Each environment carries `mixed[]`, one
2025
- per member: `components` (each with its recorded `release`, `state` and the
2026
- `attempt` that left it unsettled), `redeploy` lines and the `rollback` line,
2027
- as chant wrote them. The tab heads the environment `(mixed)` and shows the
2028
- lines to copy, run in the member's directory; behold runs none of them.
2029
- `mixedEnvironments: {read, floor}` says whether it was read; below the floor
2030
- `mixed` is empty and the lane is drawn as before.
2031
-
2032
- The fixtures in `src/__fixtures__/trunk-lane/` are recorded from chant main
2033
- in the workspace `src/trunk-lane-fixture.ts` makes (staging carries a deploy
2034
- outcome: v3's promote deployed api and failed on web), and
2035
- `src/trunk-lane-chant.test.ts` reads the same workspace through a real chant
2036
- when `BEHOLD_TEST_CHANT_BIN` names one.
2037
-
2038
- ## A gate's change set on the graph (#681)
2039
-
2040
- `GET /api/workspace/change-set?gate=<member>/<op>/<gate>&env=<env>`
2041
- (src/change-set-overlay.ts) reads the gate from `chant workspace status <env>
2042
- --json`, never from the page, and the change set it binds (`changeSet`,
2043
- chant#4022) from `chant change-set show <digest> --member <member> --json`
2044
- (`readChangeSet` on the reader, floor `CHANGE_SET_SHOW_CHANT_FLOOR`,
2045
- 0.124.28). The answer is that document keyed by graph node: `entries` (those
2046
- that change something, each with `bucket` create, change or delete and `node`,
2047
- or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
2048
- bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
2049
- failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
2050
- `planned` (a release gate's release and environment, chant#4045). An entry
2051
- with no node is kept and listed in the Change set tab, never dropped. An entry
2052
- for one instance of a counted block (#996) is put on the instance's node,
2053
- `<blockNode>[k]`, with `block` naming the block, whether chant mapped it to the
2054
- block node (before chant#4454) or the instance node; the block's node carries
2055
- the rollup (`instances`), so its card is outlined when the instance cards are
2056
- not drawn. The page
2057
- (web/change-set-overlay.js) outlines each card in the drift legend's tokens
2058
- (managed for create, foreign for update or replace, degraded for delete or
2059
- forget) with a tag above it, never a fill; it is opened from the "change set"
2060
- link on a Trunk tab gate card and turned off from its tab. A public view
2061
- refuses the route, as it refuses the lane.
2062
-
2063
- ## Feature flags on the graph (#683)
2064
-
2065
- `GET /api/workspace/flags` (src/feature-flags.ts) reads each member's
2066
- `featureFlags` from `chant workspace status <env> --json` (chant#4024, floor
2067
- `FEATURE_FLAGS_CHANT_FLOOR`, 0.124.29): per flag its `param`, `owner`, `work`
2068
- with its state, `values` per environment and `stale`, the stale-flag lint's
2069
- verdict (WSP118). It reads status in each environment of the promotion order
2070
- for the waiting gates, and for each gate of a flagged member with a stored
2071
- change set, `chant change-set show`, keeping the entries whose attribute
2072
- `param:<param>` moves the flag's parameter (`waiting`, with before, after and
2073
- the node chant mapped, which is null for a release's `chant:component`
2074
- entry). chant names no graph node that reads a build parameter, so a flag
2075
- marks every card of its member (`nodes: "member"`); behold infers no finer
2076
- mapping. behold writes no flag record and has no flag write route: a waiting
2077
- flip opens #681's change-set overlay for its gate, and otherwise `turnOn`
2078
- carries the lines a person runs (`chant workspace records amend <id> --kind
2079
- <kind> --set -` with the new values, then `git commit` of the record). The
2080
- page (web/feature-flags.js) is the Flags tab and a tag under each flagged
2081
- card in the environment the tab picks. Below the floor the route answers the
2082
- refusal and `degraded`, and the graph draws no marks. A public view refuses
2083
- the route. `src/feature-flags-chant.test.ts` reads the workspace
2084
- `src/feature-flags-fixture.ts` makes through a real chant when
2085
- `BEHOLD_TEST_CHANT_BIN` names one.
2086
- ## The why chain (#682)
2087
-
2088
- From chant 0.124.29 the intent document `GET /api/workspace/why` reads carries
2089
- `trace` (chant#4023): for each commit chant walked, the work items its
2090
- `Chant-Record` or `Chant-Lease` trailer names (judged linked, unlinked, wrong
2091
- or merge), the work items whose window it fell in (listed apart, never a
2092
- link), its ci tag, the release cut from it or containing it, that release's
2093
- gate resolutions (who, channel, when, the plan and the change set stored
2094
- under it) and its deploys per environment. Every link names its source
2095
- record (`source: {ref, field, value}`: a commit, a tag ref, a work record's
2096
- file, or `chant/lifecycle:<path>`), and the pane gives each as the `git show`
2097
- line that opens it, with a copy button. A link chant found nothing for is
2098
- drawn as missing, with chant's reason where it gives one, and `trace.reasons`
2099
- (`ledger-unreadable`, `declaration-invalid`) as partial-read notices. behold
2100
- adds each commit's subject and each work item's title from the same
2101
- document's `nodes` and joins nothing: a commit names its release and deploys
2102
- by id in the same trace. A release gate's change set is shown as `chant
2103
- change-set show <digest> --member <member>`, since the overlay (#681) opens
2104
- only a gate still waiting.
2105
-
2106
- The floor is `WHY_TRACE_CHANT_FLOOR` (0.124.29, read "why chain"). Below it
2107
- nothing is refused: the answer has `trace: null` and `chain: {full: false,
2108
- floor, note}`, and the pane shows the decisions, runs and commits it always
2109
- did with the note. `src/why-trace-schema/intent.schema.json` is chant's
2110
- intent schema at 5d33a48e7; `src/__fixtures__/why-trace/` was recorded from
2111
- chant main at that commit in the workspace `src/why-trace-fixture.ts` makes,
2112
- and `src/why-trace-chant.test.ts` reads the same workspace through a real
2113
- chant when `BEHOLD_TEST_CHANT_BIN` names one.
2114
-
2115
- ## Collision marks (#684)
2116
-
2117
- `GET /api/workspace/collisions` (src/collision-marks.ts) reads `overlap` from
2118
- `chant workspace status <env> --json` (chant#4025, floor `OVERLAP_CHANT_FLOOR`,
2119
- 0.124.29): the in-flight work items with a linked commit, and each pair of
2120
- them that changed one file or that a waiting gate's change set reaches at one
2121
- entry. An entry names its graph node (`<member>/<id>`), and that node is what
2122
- the graph marks (`nodes`, each with the items colliding there and the entries
2123
- behind it). Files two items both changed have no node, and neither does an
2124
- entry chant mapped to none: both go in a side list (`files`, `unplaced`).
2125
- `items` holds every in-flight item with `with`, the items it collides with
2126
- (empty for most). `overlap` absent is an older chant (`no-overlap`), and
2127
- `null` is no work kind declared or a failed read (`overlap-unavailable`); both
2128
- are refusals worded apart. One status read, through the read contract. behold
2129
- records, locks and refuses nothing. The page (web/collision-marks.js) is the
2130
- Collisions tab, a dashed ring and a tag under each marked card, and the
2131
- filter, "Show only colliding work": it hides every card that is not a marked
2132
- node and every edge with an unmarked end, and lists only the items that
2133
- collide. Below the floor the route answers the refusal and `degraded`, and
2134
- the graph draws no marks. A public view refuses the route.
2135
- `src/collision-marks-chant.test.ts` reads the workspace
2136
- `src/collision-fixture.ts` makes through a real chant when
2137
- `BEHOLD_TEST_CHANT_BIN` names one. `status.schema.json` in
2138
- src/trunk-lane-schemas/ is chant main at e9c996e93.
2139
-
2140
- ## Open decision points beside their gates (#472)
2141
-
2142
- The approvals inbox is arugula's rail (arugula-salad/arugula#621); behold
2143
- draws open decision points and answers none. `GET /api/workspace/points`
2144
- (src/decision-points.ts) reads `chant workspace points --open --json` through
2145
- the reader's `readPoints` (floor `DECISION_POINTS_CHANT_FLOOR`, 0.107.0, the
2146
- chant where a gate can ask a point, chant#3170). chant's conformance suite
2147
- does not list `points`, so the read is not in `BEHOLD_READS`; the reader test
2148
- holds every other module to not naming it. Each open question carries its
2149
- point's question, who may answer (the quorum's count and roles), a model's
2150
- proposal when there is one, and chant's `points answer` line. A gate that
2151
- asks a point carries `answer` in `workspace status` (the open question's id,
2152
- its point and path), and its `approve` is that same `points answer` line. The
2153
- gate strip (web/decision-points.js, web/workspace-gates.js) puts a question
2154
- on the card of the gate whose `answer.id` names it and gives a question no
2155
- waiting gate names a card of its own, naming the gate from its
2156
- `gate:<op>/<gate>@<env>` subject when a gate asked it. Such a gate gets no
2157
- approve button, framed or not, and `POST /api/workspace/gates/approve`
2158
- refuses it with `422 decision-point`. Standalone, a point card shows the line
2159
- as text to copy; framed, it says to answer in the host's rail. There is no
2160
- write route. Below the floor the route answers the refusal and `degraded`,
2161
- and the strip says which chant adds points. A public view refuses the route.
2162
- `src/decision-points-chant.test.ts` reads the workspace
2163
- `src/decision-points-fixture.ts` makes through a real chant when
2164
- `BEHOLD_TEST_CHANT_BIN` names one; src/__fixtures__/decision-points/ is
2165
- chant 0.124.31's output for it.
2166
-
2167
- ## Runtime health and rotation (#825)
2168
-
2169
- `GET /api/health?env=<env>` (src/health-overlay.ts) reads `chant lifecycle
2170
- health <env> --json` (chant#4177, floor `HEALTH_CHANT_FLOOR`, 0.124.33, read
2171
- "runtime health") once per chant project: the served project, or each chant
2172
- member of a workspace or an estate in its own directory with its own chant,
2173
- ids composed `<member>/<id>`. The read is the reader's `readHealth`
2174
- (src/workspace-reader.ts). Its document is `chant-health/v1`, not a contract 1
2175
- document, so it is checked against chant's schema, vendored unchanged in
2176
- src/health-schema/ (chant PR #4193 at d727944c4) and validated with ajv, with
2177
- a hole's `reason` loosened to any string; a document the schema refuses is
2178
- refused whole. A project with no lexicon that reads health is `none`, not a
2179
- failure. A member of another kind (#997) is listed as `none` without a
2180
- spawn: the read builds a chant project and it has none. A member below the
2181
- floor is refused before anything is spawned; when
2182
- every member is, the answer carries the refusal and `degraded`.
2183
-
2184
- The answer is `nodes` (per id: `healthy`, `unhealthy` or `unknown` with
2185
- chant's `detail`, `observedAt` and `checkedAt`; `unobserved` with chant's
2186
- `reason`; or `absent`), `rotation`, `members` and `counts`. Rotation is
2187
- behold's (src/runtime-health.ts, `rotationOf`): a Route 53 record whose
2188
- `HealthCheckId` edge (or `$ref` attribute) names a declared check is out of
2189
- rotation only when that check is unhealthy, in rotation when it is healthy,
2190
- and `inRotation: null` with the reason in words otherwise. The edges come
2191
- from each member's cached source graph (`memberIr` at detail 2). The answer
2192
- is cached per environment for 30 s, `?fresh=1` reads again, and `POST
2193
- /api/refresh` drops it. A public view refuses the route (it reads the live
2194
- estate with behold's credentials), and `behold export` captures it once per
2195
- environment. The page (web/health-marks.js) draws a tag under each card, a
2196
- solid ring on an unhealthy one and a dashed ring on a hole, dims a record out
2197
- of rotation with its edges, counts the states in the Model tab and shows the
2198
- detail in the inspect pane. It never changes a card's fill.
2199
- `src/__fixtures__/health/` was recorded from chant main at cd9a90716 against
2200
- a floci whose health checks probe (lex00/floci#259); src/runtime-health.test.ts
2201
- names each file's provenance. A multi-stack document (a project that declares
2202
- `stacks`) is keyed `<member>/<stack>::<name>` (#824), the ids chant's live
2203
- overlay gives that project's nodes.
2204
-
2205
- ## The three-cloud demo (#824)
2206
-
2207
- `example-three-cloud` is a chant workspace (`dns`, `aws`, `azure`, `gcp`) on
2208
- floci, floci-az and floci-gcp; docs/src/content/docs/using/three-cloud.mdx is
2209
- its page. `azure` is a choudoufu estate (`azure/*.tf`, choudoufu#2246), so the
2210
- demo requires choudoufu, `--local` boots no emulator for it (the setup starts
2211
- floci-az, with TLS), and the root's `chant.config.json` names it as the
2212
- terraform lexicon's `azure` root. `aws` is a Pulumi program on plunge
2213
- (behold#1000: `aws/index.ts`, kind `pulumi`, `Pulumi.yaml` naming the
2214
- `plunge+file://./.plunge` backend), so the demo requires plunge too
2215
- (PLUNGE_BIN counts, as CHOUDOUFU_BIN does). `scripts/front-door.ts plan --out <file>`
2216
- (`npm run change-set`) composes one change set, a part per engine: chant
2217
- parts for dns and gcp, azure's choudoufu part from `choudoufuPlanSet`, and
2218
- aws's pulumi part from `plunge preview` (`previewPulumiMember`);
2219
- e2e/three-cloud-change-set-e2e.sh asserts it. `apply --change-set <file>`
2220
- plans again and refuses the whole set, exit 3, when any part moved
2221
- (.front-door/apply-verdict.json names each), and `oob-edit <member>` makes
2222
- one out-of-band edit per member for the live run;
2223
- e2e/multi-engine-demo-e2e.sh asserts the composed graph, a colour change per
2224
- engine and the refusal, with a fake plunge and recorded drift streams. dns
2225
- reads azure's `azureEndpoint` and aws's `awsEndpoint` through chant
2226
- (chant#4455): dns/src/records.component.ts has `memberOutputsComponent("azure")`,
2227
- `memberOutputsComponent("aws")` and a records step whose cfn-deploy inputs
2228
- are `stackOutput("azure", "azureEndpoint")` and `stackOutput("aws",
2229
- "awsEndpoint")`, and dns lists `terraform` (with `terraform.roots.azure` at
2230
- `../azure`, which is the change signal) and `pulumi`. `member-outputs` and
2231
- the pulumi lexicon are in chant 0.124.54 and newer, and the example depends on 0.124.58, and
2232
- the workspace pins both lexicons by package at that version
2233
- (`CHANT_RELEASE`, src/chant-release.ts); behold's own code does not import
2234
- them, so there is no floor. scripts/front-door.ts loads the pulumi lexicon only for
2235
- the aws plan, so `npm ci` in the example runs every other subcommand. The e2e's second half runs
2236
- `chant components pr-plan --member dns` over a change to azure/ and asserts
2237
- dns's records step names azure under its unresolved inputs. `behold demo three-cloud` runs `scripts/emulators-up.sh` (the
2238
- emulators under chant's own container names, with the Docker socket, floci-az
2239
- running Container Apps unmocked), then serves with `--local --env local`.
2240
- `--local` on a workspace boots every chant member's emulators
2241
- (`emulatorDirs`/`emulatorsUp` in src/emulator.ts), not the first member's, and
2242
- tears down the same set. The `front-door` Op (`dns/ops/front-door.op.ts`)
2243
- runs `scripts/front-door.ts`: apply all four (aws with `plunge up`, then `plunge stack export` into aws/stack-export.json, the export chant draws the member from), deactivate the Azure revision,
2244
- wait for `azureCheck` to read unhealthy, then `behold export --open-env local
2245
- --open-zoom composites --note …`. `--note` (`settleNote` in src/export.ts) is
2246
- one line under 200 characters, written to the manifest as `note` and drawn at
2247
- the foot of a static page by web/export-note.js, backticked spans as code.
2248
-
2249
- ## Invariant
2250
-
2251
- If a request would have behold write to a cloud or to source directly, it's wrong.
2252
- behold shows truth and triggers Ops. Authority stays in the committed source and the
2253
- executor.
2254
-
2255
- behold writes nothing in a served project (#469, ruled 2026-10-23). What it
2256
- keeps for itself (the hand layout, the per-user settings, dispatched CI run
2257
- ids, recents, the serve registry) lives in the user's own home, cache or temp directory, keyed by the
2258
- project, never in the tree. The only files behold puts in a project are the
2259
- ones a person asks for by name: `behold doctor --fix` writing
2260
- `chant.workspace.json`, and the carve walkthrough writing into the demo copy
2261
- behold made itself (both below).
2262
-
2263
- The commands behold starts run with behold's own environment, so Deploy (`POST
2264
- /api/apply`, chant's local executor) applies with the credentials of whoever
2265
- started it. On a terragucci repo (a `terragucci.yml` in the served directory or
2266
- above it, up to the git root) behold deploys, approves and applies nothing,
2267
- and the only things it starts are terragucci's own request, rollout and
2268
- action workflows (below):
2269
- every other POST that deploys, approves or starts a run answers `409` with
2270
- `code: "terragucci"` and names the pipeline (`src/terragucci-repo.ts`, #489), `/api/project` carries `terragucci`
2271
- so the page offers no write, and auto-sync declines. The boundary is an
2272
- allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
2273
- any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
2274
- method and route, and that list holds only the exceptions below (the layout
2275
- cache, project open and reveal, demo open, refresh, and the four carve
2276
- steps), plus `POST /api/view`, which moves the open tabs and writes nothing
2277
- (#914), `POST /api/templates/request`, which dispatches terragucci's
2278
- request workflow (behold#1035), `POST /api/templates/upgrade`, which
2279
- dispatches its rollout workflow (behold#1036), and `POST
2280
- /api/templates/action`, which dispatches its action workflow (behold#1037). A new write route is refused on a terragucci repo until it is added
2281
- there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
2282
- app (`app.routes`, built plain, with a carve report and with `--terragucci`)
2283
- and asserts each one is allowlisted or answers 409, and that every allowlist
2284
- entry is a registered route. `TERRAGUCCI_REFUSED_WRITES` only words the
2285
- refusal for known routes. The remedy names `npx terragucci approve wave-<k>
2286
- --plan <digest>`, the digest from the wave's gate card.
2287
-
2288
- A SQL Yodeler repo (a `yodel.config.ts` in the served directory or above it,
2289
- up to the git root) is guarded the same way (#517): the same allowlist, the
2290
- same refused routes, auto-sync declined, and `/api/project` carries
2291
- `sqlYodeler` so the page offers no write. The refusal is `409` with `code:
2292
- "sql-yodeler"`, and its remedy names `npx yodel approve <env> --plan <digest>`
2293
- (with `--sign` when the environment's gate is sealed) and `yodel apply <env>`
2294
- in the project's pipeline. `productRepo()` in `src/terragucci-repo.ts` looks
2295
- for terragucci's config along the whole walk first, so a yodel project nested
2296
- inside a terragucci repo is refused as terragucci.
2297
-
2298
- Op discovery (`src/ops.ts`) reads a gate from `signalName: "<name>"` or from
2299
- `gate("<name>", ...)`, the form chant's op builder and SQL Yodeler write, so
2300
- a gated Op is never listed or run as ungated on any repo (#517).
2301
-
2302
- A policy denial is never approved from behold (#519, `src/policy-override.ts`).
2303
- `GET /api/workspace/gates` gives a gate of op `policy-override` an `override`
2304
- field `{subject, rules, plan, digest, state, spentAt, product, command,
2305
- source}`: the rules and denied plan come from `chant/lifecycle:_gates/
2306
- policy-override.jsonl` (read with `git show`, the local branch then
2307
- `origin/chant/lifecycle`), `state` is `waiting`, `overridden` (status says an
2308
- override counts) or `spent` (a line in `_gates/policy-override/applied.jsonl`
2309
- for its digest), and `command` is the product's (`npx terragucci override`,
2310
- `npx yodel override`) or chant's `chant approve policy-override <subject>
2311
- --rule <id> --reason "<why>" --plan <digest>`. The card shows that command and
2312
- no button, and `POST /api/workspace/gates/approve` answers such a gate `422`
2313
- with `code: "override"`. The ledger lines are parsed by chant's
2314
- `@intentius/chant/override-gate` (`recordedDenials`, `parseAppliedOverrides`,
2315
- `overrideCommand`) and `parseGateLedger`, and the product is `productRepo()`
2316
- from `src/terragucci-repo.ts` (#537).
2317
-
2318
- ### The exceptions, and their exact size
2319
-
2320
- These are also the only writes a guarded product repo answers: terragucci
2321
- (`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
2322
- listed in `TERRAGUCCI_ALLOWED_WRITES`.
2323
-
2324
- `POST /api/templates/request` (behold#1035, `src/templates.ts`),
2325
- `POST /api/templates/upgrade` (behold#1036) and `POST /api/templates/action`
2326
- (behold#1037) are the three starts on a terragucci repo, and they write
2327
- nothing anywhere. The request is described first. It is on the
2328
- allowlist, and because the list also guards SQL Yodeler repos the handler
2329
- refuses on its own (`409`, the product's refusal or `code: "no-templates"`)
2330
- unless the served repo is terragucci and its terragucci.yml sets
2331
- `templates`. It checks the request against what the repo's own
2332
- `terragucci templates list --json` printed (`GET /api/templates` answers that
2333
- output byte for byte) and against chant's template-request/v1 (`@intentius/chant/template-request`), then dispatches
2334
- the committed `terragucci-request.yml` with the inputs `template`, `version`,
2335
- `name` and `inputs`, plus `claimed_by` (the person behold says filled the
2336
- form) only when that workflow declares the input. On GitHub the dispatch and
2337
- every read go through the operator's `gh` (`dispatchWorkflow`,
2338
- `pullRequestOn` in src/gh-run.ts); on Forgejo through the HTTP API with the
2339
- operator's `FORGEJO_TOKEN` (src/forgejo-api.ts), sent only to the origin's
2340
- host and never stored or shown. GitLab has no request workflow and answers
2341
- `422 request-forge` with the `npx terragucci request` line to run. behold
2342
- never runs `terragucci request`, never shells out to plan or apply, and holds
2343
- no apply credential: the run in CI opens the pull request with the repo's own
2344
- token, its actor is the requester the forge vouches for, and the pull request
2345
- is planned and reviewed like any other (ruling A of INTENTIUS/chant#4642). The
2346
- follow runs in the runner's single slot, and `GET /api/templates/requests/:id`
2347
- answers the run's end and the pull request's number and URL. `--public`
2348
- refuses both reads (`403`) and the post (`405`).
2349
-
2350
- With `app` in the body (behold#1036) the request asks for an add-on in that
2351
- app's root. The template must be an add-on template (else `422 wrong-kind`),
2352
- the app must be one the repo's own `terragucci templates apps --json` lists
2353
- (`GET /api/templates/apps` answers that output byte for byte), else `422
2354
- not-an-app`, and the add-on's name must not be a module the app's root already
2355
- has (`422 addon-exists`). The dispatch adds the `app` input, and the branch is
2356
- `request/<template>/<app>/<addon>`.
2357
-
2358
- `POST /api/templates/upgrade` takes `{app, version?}`. It reads the apps again
2359
- and takes the module and version from terragucci, never from the caller: the
2360
- app's `template` and its `upgrade` (`422 not-an-app`, `422 no-upgrade` when
2361
- `upgrade` is null, `409 stale-upgrade` when `version` is not it). It refuses
2362
- on its own like the request, then dispatches the committed
2363
- `terragucci-rollout.yml` with `module` and `version` only (`409
2364
- no-rollout-workflow` when it is not committed, `409 terragucci-too-old` when
2365
- it takes neither input), through the same `gh` and Forgejo paths and the same
2366
- runner slot. A person starts it; terragucci's existing rollout opens one pull
2367
- request per wave, and each wave is planned, reviewed and applied by the
2368
- pipeline (ruling D). GitLab's rollout job takes no dispatch inputs, so GitLab
2369
- answers `422 request-forge` with the `npx terragucci rollout` line. `--public`
2370
- refuses the apps read (`403`) and the post (`405`).
2371
-
2372
- `POST /api/templates/action` takes `{root, address}`. It reads the apps again,
2373
- and the address must be one terragucci lists in that root's `actions` (`422
2374
- not-an-app` for a root no app has, `422 unknown-action` otherwise); nothing
2375
- starts before that. A root whose engine has no action invocation (terragucci.yml's
2376
- `binary`, the repo's `.opentofu-version`, or `.tofu` files in the root, as
2377
- terragucci detects it) answers `422 action-engine` naming OpenTofu or
2378
- choudoufu (ruling E), and `/api/project` carries `terragucciActionRefusal` so
2379
- the buttons say so. It refuses on its own like the request, then dispatches the
2380
- committed `terragucci-action.yml` with `root` and `address` only (`409
2381
- no-action-workflow` when it is not committed, which terragucci does only for
2382
- Terraform roots; `409 terragucci-too-old` when it takes neither input), through
2383
- the same `gh` and Forgejo paths and the same runner slot. The run asks chant's
2384
- gated request (op `tf-action`, gate `<root>:<address>`) and waits for a person
2385
- other than the requester to run `terragucci approve action <root> --plan
2386
- <digest>`; behold approves nothing and never runs the action. The lifecycle
2387
- lane reads `_gates/tf-action.jsonl` and `_gates/tf-action/applied.jsonl` into
2388
- `actions` (`src/terragucci-lifecycle.ts`), apart from the waves: a waiting
2389
- gate carries that approve line, the requester's own approval is listed as one
2390
- that does not count, and an applied one carries the run's `ok` or `failed`.
2391
- GitLab answers `422 request-forge` with the `npx terragucci action` line.
2392
- `--public` refuses the post (`405`).
2393
-
2394
- `POST /api/layout` (#228) writes **one** file, and not in the served project:
2395
- the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
2396
- with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
2397
- `$XDG_CACHE_HOME` or `~/.cache`), `<key>` the first 32 hex characters of the
2398
- sha256 of the project directory's realpath, and `BEHOLD_CACHE_DIR` replacing
2399
- `<user cache>/behold`. The file is `{version, projectDir, lenses: {<lens>:
2400
- {<node id>: {dx,dy,dw,dh}}}}`, mode 0600 in a 0700 directory (src/layout.ts):
2401
-
2402
- - It is **one operator's view**, not estate truth. Deltas describe how *you*
2403
- want the picture arranged on top of dagre's layout; the graph underneath
2404
- stays chant's, and a delta for a node that left the estate is dropped on read.
2405
- - It **never touches the cloud, your source or the project**. The path is a
2406
- hash of `cfg.projectDir` + constants; nothing from the request reaches the
2407
- filesystem.
2408
- - It refuses politely when it shouldn't write: preview mode, a static-export
2409
- capture, a cache directory that isn't writable, an oversized or malformed body.
2410
- - A project served before #469 may carry `.behold/layout.json`. When the cache
2411
- has no file for the project, that file is read once and copied into the
2412
- cache; it is never written, moved or deleted. Clearing the last lens keeps
2413
- an empty cache file, so the old one is not read back in.
2414
-
2415
- The per-user settings (#470, src/user-settings.ts) sit beside it at
2416
- `<user cache>/behold/settings/<key>.json`, same key, same modes: the operator's
2417
- `approver` block and `behaviour.traffic`, which are not facts about the estate.
2418
- No route writes them. When the cache has none for a project with a
2419
- `.behold.json`, that file's two blocks are read once and copied in (key paths
2420
- made absolute against the project), and a copy is kept even when neither
2421
- block is there, so `.behold.json` is not read for them again. It is never
2422
- written, moved or deleted. The tier axis is not a setting: it is the
2423
- project's `chant.config.ts` `buildParams` entry with a string `enum`
2424
- (src/project.ts `readTierParam`), read per request through `detectProject`
2425
- and passed to `chant graph` as `--param`.
2426
-
2427
- `GET /api/layout` reads it back; `GET /api/graph?layout=1` (and `/api/overlay`)
2428
- render with the deltas baked into the SVG, which is how `behold export` and
2429
- static snapshots honour a hand layout.
2430
-
2431
- A declared workspace (#464) keys the layout by the workspace root, the
2432
- directory holding `chant.workspace.json`, rather than by its first member.
2433
-
2434
- `behold doctor --fix` (#464, ws-015) is the third exception, and it runs only
2435
- when you type the flag: for an estate root whose members are listed in
2436
- `.behold.json`, it writes `chant.workspace.json` in that root (never over an
2437
- existing one) and copies the first member's saved layout to the root's cache
2438
- entry with its node ids rewritten. It then runs `chant workspace check`. The
2439
- first member's layout and `.behold.json` are left as they were.
2440
-
2441
- The fourth exception is the carve walkthrough's two steps above (#254), and it
2442
- is narrower still: they exist only when behold booted a `behold demo carve`
2443
- copy, they write only into `<copy>/app/carveout/`, and the directory they write
2444
- into is a scratch dir behold created inside a directory it copied for you a
2445
- minute earlier. `carve bridge` runs without `--apply-rewrites`, so the demo's
2446
- own Terraform is not edited either. The only request-derived value is `select`,
2447
- and it must be an address the served report already ranks, the value that
2448
- reaches the spawn's argv comes from a closed set read off disk. No cloud write,
2449
- no Terraform mutation, no edit to anyone's chant source.
2450
-
2451
- `behold export --publish s3://<bucket>/<prefix>/views/<name>` (#491) is the
2452
- one write to a cloud, and it is not a server route: an export, asked for it on
2453
- the command line, uploads the bundle it just wrote, signed with the AWS
2454
- credentials in the environment (src/s3-object.ts). `publishTarget` refuses
2455
- any destination that is not a `views/<name>` directory, terragucci's reserved
2456
- viewer prefix, so the bundle's `index.html` can never land on a page behold did
2457
- not make. `publishBundle` (src/export.ts, #500) uploads every other file
2458
- first, then `manifest.json`, then `index.html`. Snapshot names carry the first
2459
- 16 hex digits of their SHA-256 (`CONTENT_ADDRESSED`) and go up with
2460
- `Cache-Control: public, max-age=31536000, immutable`; everything else gets
2461
- `no-cache`. It GETs the previous `manifest.json` under the prefix before
2462
- uploading (no list call) and, after `index.html`, deletes the
2463
- `snapshots/<name>` files that manifest named and this export did not write.
2464
- Nothing outside the prefix is deleted. A refused delete stops the sweep with
2465
- a warning naming `s3:DeleteObject`, and the publish still succeeds.
2466
-
2467
- Since #510 the bundle goes to `<prefix>/<commit>/` (the checkout's HEAD, or
2468
- `--commit`), with publishBundle's order and sweep one level down, and
2469
- `src/publish-snapshots.ts` then writes, in order, `history.json` (newest
2470
- first, `{commit, at, project, generated}`, one GET of the old one),
2471
- `latest.json` (`{commit}`) and the root `index.html`, a no-cache page that
2472
- opens `<latest>/index.html`, so old links keep working. `--keep <n>` (30)
2473
- drops older commits from `history.json` and then deletes their files as each
2474
- commit's `manifest.json` lists them (`files`, which runExport now writes,
2475
- plus `keyToFile`), best effort with the same `s3:DeleteObject` warning. A
2476
- view from before the layout keeps its files; only its `index.html` is
2477
- replaced. With `--publish` the default `--reports-base` is `../../../`. The
2478
- view's history picker (`web/history-picker.js`) reads `../history.json` and
2479
- only navigates.
2480
-
2481
- A choudoufu estate member (#366) adds no exception. A move there is one tag
2482
- write through choudoufu's own `live-mv`, and behold never makes it: `GET
2483
- /api/choudoufu/split` (also answered as `/api/choudoufu/moves`, its name before
2484
- the split rename) reads a plan (`split.json`, or the workbench's `carve.json`)
2485
- from inside a served member,
2486
- previews each move with choudoufu's `live-mv -json -dry-run` (the only spelling
2487
- of `live-mv` in the tree, src/choudoufu-moves.ts `dryRunArgs`, asserted by
2488
- test), hands the lines back with copy buttons, and `?receipt=1` reads the
2489
- listing after a person ran them. **There is no `/api/choudoufu/mv`**, and
2490
- src/choudoufu-route.test.ts asserts it stays absent, for the same reason
2491
- `/api/carve/apply` does not exist.
2492
-
2493
- ## Changing behold (for agents working on this repo)
2494
-
2495
- The sections above are about driving a running behold. This one is about
2496
- changing it, the working rules that used to live in a handoff note and now
2497
- live here, with the enforceable ones enforced.
2498
-
2499
- - **Branches and merges.** Work on a branch off `main` (an isolated worktree
2500
- when more than one agent is active). `main` is protected by ruleset
2501
- 22042490, which requires a PR and a green `check` job in `ci.yml` of
2502
- everyone but the repository admin role. That role bypasses it
2503
- (`bypass_mode: always`, behold#1006, as chant and choudoufu have), so an
2504
- admin may push a tested integration branch's merge to `main` directly;
2505
- every other change arrives as a PR and merges once the check is green. A
2506
- check that has merely settled is not a pass — read the lines. The
2507
- ruleset's name still reads "every change is a PR with a green ci check";
2508
- renaming it is a settings change for the maintainer (behold#1018).
2509
- No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
2510
- next onto what landed.
2511
- - **Emulator e2e scripts** take their container names, ports and images
2512
- from the environment and run under `e2e/lib/safe-env.sh`, which keeps real
2513
- cloud credentials out of reach and fails on a real-cloud rejection in the
2514
- log; e2e/README.md has the variables (behold#1032).
2515
- - The painter bundles for a browser (#1069). `src/render.ts` and what it
2516
- imports take no Node built-in: `npm run check:browser-bundle` bundles it
2517
- with esbuild for `--platform=browser`, fails naming the import chain to any
2518
- `node:` import, and prints the minified and gzipped sizes; CI runs it. A
2519
- constant or card rule the painter needs from a module that reads disk or
2520
- spawns lives in a module of its own (src/card-marks.ts,
2521
- src/choudoufu-card.ts, src/carve-state.ts) and is re-exported from the old
2522
- one. The icons come from src/icons.generated.ts: after a vendor script
2523
- changes `web/icons`, run `npm run generate:icons` (`npm run check:icons`
2524
- and src/generate-icons.test.ts fail until you do).
2525
- - **The local gate** is `just check` (tsc, tests, build). The tests never read
2526
- the caller's environment (behold#1013): src/test-env.ts, vitest's setup
2527
- file, removes CHOUDOUFU_BIN, PLUNGE_BIN and the other variables behold
2528
- reads to pick a binary or a service, and vitest.config.ts points
2529
- PULUMI_BACKEND_URL at an empty `file://` directory made for the run, with
2530
- PULUMI_SKIP_UPDATE_CHECK=true, so no pulumi or plunge a test starts sees
2531
- the machine's login. A test that needs one of them sets it and puts back
2532
- what was there. Every vitest run
2533
- also writes `.vitest-last.json` (the json reporter, PR #351), and `just
2534
- test` keeps the reporter's full output in `vitest.log`, both gitignored —
2535
- because #334's one-shot first-run failures kept losing the failing file's
2536
- name. If the suite fails once and passes on rerun, those two files from the
2537
- first run are the evidence; attach them to #334 (`jq '.testResults[] |
2538
- select(.status != "passed") | .name' .vitest-last.json` names the file).
2539
- - **Releasing** is `just release`, after the version-bump PR merged: it tags
2540
- `behold-v<version>`, pushes the tag (which is what runs `release.yml`), and
2541
- waits for npm to show the version. It refuses in every state where a tag
2542
- push would be wrong. Never re-push a `behold-v*` tag by hand: a tag push
2543
- re-fires publish. Tags absent from origin (behold-v0.10.0, 0.10.1) stay
2544
- absent for that reason.
2545
- - **Scratch infrastructure** is governed by `src/scratch.ts`, asserted by
2546
- `scratch.test.ts` across every boot site: anything behold boots is named
2547
- `behold-*`, refuses if the name is taken, tears down only what it created,
2548
- and never binds the shared emulator ports. The protected names — `floci*`,
2549
- `chant-floci*`, the kubemicrovm and fountain k3d clusters, :4566 — are
2550
- listed there, not in prose. A new boot site calls `assertScratch` before
2551
- its spawn and gets a row in the test.
2552
- - **The write boundary** is the Invariant section above. Apply is never a
2553
- button; `/api/carve/apply` does not exist and the route test asserts it
2554
- stays that way.
2555
- - **chant's working rules** (its single-lane checkout, its release path) are
2556
- chant's and live in chant's repo, not here.
38
+ - Every chant read goes through src/workspace-reader.ts. chant's reader conformance suite runs against it in `npm test` (src/workspace-reader-conformance.test.ts). Do not shell chant from elsewhere or import chant's library for something a read-contract command answers.
39
+ - behold runs the project's own chant, which may be older. Each read gets one floor in src/chant-floors.ts: a `<READ>_CHANT_FLOOR` constant, an entry in `CHANT_FLOORS` (what doctor prints), and a `floorMet`/`floorRefusal` check before spawning.
40
+ - When the chant behold follows changes, edit `CHANT_RELEASE` in src/chant-release.ts and run `npx tsx scripts/chant-release.ts`; `--check` lists files out of step.
41
+ - behold computes nothing chant answers. It parses no HCL, invents no edges, and paints an unknown status or read as neutral with a label, never a guessed colour.
2557
42
 
2558
43
  ### Adding a member kind
2559
44
 
2560
- An estate member has a kind (#368): what a directory has to look like, what
2561
- tool answers reads for it, and how it becomes a `GraphIR`. `src/member-kind.ts`
2562
- is the one table; `chant` is the first row and every member was that row
2563
- until the table existed. A new kind is:
2564
-
2565
- 1. A `registerMemberKind({ kind, probe, expects, via, passes })` call in
2566
- `src/member-kind.ts`, the `probe` is sync, read-only and runs no code (a
2567
- file's presence, a regex over a root file, or either: the choudoufu probe
2568
- takes the `estate.chdf.hcl` sidecar, choudoufu's leading form, OR a `live {`
2569
- block in a root *.tf, #387); `via.tool` stamps the binary and
2570
- version that would answer, which is the version half of `memberIr`'s
2571
- cache key; `via.read` is the one uncached read, source or live per `opts`.
2572
- The module imports nothing from the read path at runtime (src/chant.ts
2573
- imports src/project.ts, which imports it); a kind's `via` closes over its
2574
- own tool module.
2575
- Add the word to `MEMBER_KINDS`. A word in the vocabulary that no row
2576
- registers is a doctor fail with the reason, never silently chant.
2577
- 2. Nothing in `src/estate.ts`: `composeEstate`, `composeEstateOverlay` and
2578
- `estateNamespaceScopes` already dispatch through `memberKindOf(dir)`.
2579
- The two routes that render an estate — `/api/graph`'s estate branch and
2580
- `/api/overlay`'s — run the same passes in the same order and must not
2581
- fork per kind; a kind's differences live inside its `read` or its `passes`.
2582
-
2583
- `passes` (#427) is the render-time half, and it exists because the read-time
2584
- one could not hold it: the Terraform kind's third pass takes the request's
2585
- zoom, so it cannot run where the reader runs. `applyMemberPasses(ir,
2586
- {detail})` is the one call the six render sites make, and `memberPassNote(run,
2587
- dirs)` the line they return, each kind handed only the served dirs that are
2588
- its own, so a route never names a kind. Three rules a `passes` holds. It
2589
- mutates IN PLACE, because the existing passes do and their callers depend on
2590
- it. It self-guards on the IR's own CONTENT and never on the served members'
2591
- kinds. A chant project may declare a kind's lexicon; a chant project
2592
- declaring `terraform` is what `src/terraform-route.test.ts`'s first block
2593
- serves, and `memberKindOf` says `chant` there, so membership dispatch would
2594
- silently stop rendering it. And a run is carried forward, never re-run: a
2595
- pass that already elided its cards returns an empty elision the second time,
2596
- which drops the note on every composed estate. A test that re-registers a
2597
- kind to stub its reader spreads the real spec (`{ ...terraformSpec, via: … }`)
2598
- or it drops the passes with it.
2599
- 3. A `registerPack({ lexicon, iconFor, fields })` in `src/render.ts`, or the
2600
- kind's cards lead with the alphabetically first two short attrs. A `fields`
2601
- function takes the box the card is drawn in as its second argument, so a
2602
- row the box already carries can be left off (#393 item 9,
2603
- `src/card-face.ts`).
2604
- 4. A row in `statusVocabulary` (`src/status-vocabulary.ts`) when the kind has
2605
- its own words for the four overlay colours — choudoufu's `bound` is not
2606
- chant's `managed`, and a legend that says `managed` over a card carrying no
2607
- marker is a claim behold has no right to make. The colours never move; only
2608
- the naming does, and an estate of several kinds keeps chant's words and says
2609
- so in the legend's tooltip.
2610
- 5. A `DoctorCheck` line when the kind needs a tool on PATH or a per-member
2611
- precondition (a version floor checked before the spawn, the way
2612
- `carveStatusReader` does; a PATH probe the way `src/demos.ts` does).
2613
- 6. Tests: the probe and the object form in `src/project.test.ts`; dispatch
2614
- in `src/estate.test.ts`'s "#368" block, which registers a fake kind and
2615
- asserts chant members still go through exactly the calls they did, and its
2616
- "#427" block for the render passes; the
2617
- kind's own reader off recorded documents in `src/__fixtures__/`, with
2618
- provenance in prose above the load.
2619
-
2620
- `.behold.json` names a kind as `{ "dir": "x", "kind": "<kind>" }`; a bare
2621
- string is `chant`. Anything behold boots for a kind goes through
2622
- `assertScratch` first.
2623
-
2624
- **What the first screen owes a non-chant member (#393).** Three chant-shaped
2625
- things used to be offered to every member whatever it was, and a new kind gets
2626
- all three answered for free:
2627
-
2628
- - `/api/project` publishes `memberKinds`, the served members' kinds, in
2629
- composition order. The SPA opens on the `resources` zoom when none of them is
2630
- `chant`, because `components` is a projection of a chant project's own
2631
- component DAG and a member without one opens on "the components lens doesn't
2632
- apply to a composed estate yet". #182's zero-node fallback still covers a
2633
- chant project that declares no components.
2634
- - `/api/project` publishes `runtimeCapable`, and the palette and the View tab
2635
- offer `zoom: runtime` only then. The tier below the declaration boundary is
2636
- the owner-referenced children chant stamps `runtimeOwner` on, and only a
2637
- Kubernetes read has an owner chain to resolve — `RUNTIME_LEXICONS` in
2638
- `src/server.ts` is the one word (`k8s`), read off the members' DECLARED
2639
- lexicons so the stop exists or not before anyone picks it.
2640
- - A chant-only facet answers emptily rather than 500ing for a non-chant
2641
- primary: `/api/resources` returns `{byComponent: {}}`, the shape carve mode
2642
- already returns and the SPA already reads as "no resource facet here".
2643
-
2644
- A kind that grows components, or a substrate with an owner chain, changes those
2645
- answers where they are decided rather than per kind in a route.
2646
-
2647
- ### The workbench catalog
2648
-
2649
- `demos.json` is the catalog that ships. `workbench.json`, read beside it and
2650
- deliberately absent from package.json's `files`, is the catalog of internal
2651
- estates this checkout is developed against (#386, #388). Four rules, and
2652
- src/demos.ts holds them:
2653
-
2654
- 1. A third source, `local`, and a second file. A local entry's `path` is
2655
- relative to the directory of the catalog file that named it, the intentius
2656
- checkouts are siblings, so the workbench writes `../choudoufu`,
2657
- `../waterpark`, `../chant`, and the file stays committed and reproducible.
2658
- An entry whose path is not checked out is unsatisfiable exactly as a
2659
- missing binary is: `--list` and `/api/demos` say so, CI stays clean.
2660
- `BEHOLD_WORKBENCH=<file>` names a catalog elsewhere; a workbench name that
2661
- collides with a bundled one is dropped with a stderr line.
2662
- 2. In place or copied, said explicitly. `inPlace: true` serves `path` where it
2663
- sits; the default copies to `behold-demos/<name>` with the bundled filter.
2664
- Anything whose setup writes into the tree — `init`, `apply`, a rendered
2665
- generator — is copied or generated into the target, never run in a
2666
- checkout, which is how #366's "behold never runs `choudoufu init` in a
2667
- served project" survives. An `inPlace` entry with a `setup` says so in its
2668
- description.
2669
- 3. A generator is a source. An entry with no `path` at all renders its estate
2670
- into an empty target through its own `setup`, which runs with cwd = the
2671
- target and two extra variables: `BEHOLD_WORKBENCH_DIR` (the catalog file's
2672
- directory, so a script can reach `../choudoufu`) and `BEHOLD_DEMO_NAME`.
2673
- The up script writes the matching down script into the target, the way the
2674
- bundled choudoufu demo ships `scripts/choudoufu-down.sh`.
2675
- 4. `CHOUDOUFU_BIN`. `choudoufuBinary()` (src/choudoufu-member.ts) names the
2676
- binary and every spawn, the doctor probe and the demo requirement check go
2677
- through it; the doctor line prints which binary answered. Workbench scripts
2678
- spell the same fallback, `${CHOUDOUFU_BIN:-choudoufu}`.
2679
-
2680
- `just example name="<entry>"` serves one. Scratch discipline is unchanged: an
2681
- emulator a workbench entry boots is `behold-wb-<entry>` on its own port, and
2682
- the up scripts (`workbench/<entry>/up.sh`, helpers in `workbench/lib/`) assert
2683
- the `behold-wb-` prefix and the not-4566 rule themselves, in bash, because they
2684
- are the boot site. Each writes the matching `scripts/down.sh` into its target.
2685
-
2686
- **The eleven entries**, in catalog order. The counts are measured, not
2687
- estimated — every entry the e2e below can reach on a developer machine prints
2688
- its own graph and overlay counts as it runs.
2689
-
2690
- | entry | what it serves | needs |
2691
- |---|---|---|
2692
- | `chant-getting-started` | chant's own getting-started example from `../chant`, in place: the source graph, 8 nodes, no substrate. The one-second answer to "did I break plain chant reading?" | that example's own `node_modules`, nothing is installed in your chant tree |
2693
- | `chant-local-cloud-trio` | chant's local-cloud-trio, in place: one project declaring across aws, azure and gcp, 8 nodes and 2 edges of source | the same |
2694
- | `fountain-ops` | `../fountain-ops` in place with `--env local`, the mature estate on your working checkout | docker, k3d, kubectl, jq, just. **The one entry whose setup runs in your working copy**: the checkout's own `just up`, a five-minute k3d cluster, and it switches your kubectl context. `just down` there removes it; behold never does |
2695
- | `choudoufu-workbench` | the live-mv workbench's four estates copied out of `../choudoufu`, composed with `--env live`: 42 cards — 24 bound, the 12 team cards reading `owned by tlmig-sample-monolith`, 6 neutral | docker, choudoufu |
2696
- | `choudoufu-cohort-s3` | `estate-gen`'s `s3` cohort rendered into the target, a sidecar-declared estate (#387): 6 cards, all neutral, because the apply stops where floci answers S3 Control tag reads on a hostname that does not resolve | docker, choudoufu, go, terraform |
2697
- | `choudoufu-cohort-iam-ecr` | the same for `iam-ecr`, the one cohort floci implements end to end: 6 cards, all 6 bound | the same |
2698
- | `choudoufu-cohort-ec2-networking` | the same for `ec2-networking`: 49 cards, the widest roster, all neutral (floci refuses a transit gateway call and the apply stops) | the same |
2699
- | `terralith-1` | `terralith-gen` at scale 1 plus the `estate.chdf.hcl` sidecar it omits, applied by choudoufu from nothing: 79 cards, all 79 bound | docker, choudoufu, go |
2700
- | `terralith-4` | the same at scale 4: 301 cards, all 301 bound. The estate behold is sized against | the same |
2701
- | `terralith-4-adopt` | scale 4 again, but STOCK terraform applies it first, so nothing wears a marker: 301 cards — 85 UNOWNED, 84 bound by derived identity alone, 132 neutral. One `choudoufu live-import` line, which the up script prints and you run, and all 301 read bound | docker, choudoufu, go, terraform |
2702
- | `waterpark` | `../waterpark/access` in place as a bare Terraform directory (#384): five roots as boxes, 58 cards, 49 edges, nothing written under the estate | `@intentius/chant-lexicon-terraform` + `@cdktn/hcl2json` beside behold, dependencies of behold since #909 |
2703
-
2704
- **The scratch, by name and port.** Each emulator is the entry's own, booted by
2705
- its up script and removed by the `scripts/down.sh` that script wrote into the
2706
- target rather than by pattern.
2707
-
2708
- | entry | container | host port |
2709
- |---|---|---|
2710
- | `choudoufu-workbench` | `behold-wb-choudoufu-workbench` | 4651 |
2711
- | `choudoufu-cohort-s3` | `behold-wb-choudoufu-cohort-s3` | 4652 |
2712
- | `choudoufu-cohort-iam-ecr` | `behold-wb-choudoufu-cohort-iam-ecr` | 4653 |
2713
- | `choudoufu-cohort-ec2-networking` | `behold-wb-choudoufu-cohort-ec2-networking` | 4654 |
2714
- | `terralith-1` | `behold-wb-terralith-1` | 4655 |
2715
- | `terralith-4` | `behold-wb-terralith-4` | 4656 |
2716
- | `terralith-4-adopt` | `behold-wb-terralith-4-adopt` | 4657 |
2717
- | `chant-*`, `waterpark` | none (source reads, no substrate |) |
2718
- | `fountain-ops` | the k3d cluster `fountain-local`, which is the checkout's, not behold's | — |
2719
-
2720
- The port is the floci's host binding and the entry's `serve.spawnEnv`
2721
- `AWS_ENDPOINT_URL` at once, so the estate's own applies and the choudoufu
2722
- behold spawns talk to the same emulator.
2723
-
2724
- **The e2e** is `just e2e-workbench` (`e2e/workbench-e2e.sh`, #391): every entry
2725
- loaded through `behold demo <entry> <tmp target> --port <p>` on its own port
2726
- from 4720 up, `/api/graph` asserted to carry nodes and a live entry's
2727
- `/api/overlay?env=live` to answer with its bound/unowned/neutral split, timings
2728
- per entry; eight entries and 553s on the machine this was written on.
2729
-
2730
- Time is asserted, not only printed (#423). Each entry carries a ceiling at
2731
- roughly twice its own measured value, and the run carries one too, because
2732
- #419's whole subject was a number nobody was watching: the ratio could not
2733
- regress silently and the duration could. The measured figures the ceilings come
2734
- from are in the script beside them; `BEHOLD_E2E_SECS_<entry>` and
2735
- `BEHOLD_E2E_RUN_SECS` override. A live entry also asserts #422's shape: the
2736
- progressive overlay answers with every member marked pending and does so before
2737
- the blocking read returns, so the estate cannot quietly regress to
2738
- all-or-nothing. Where the blocking read is already sub-second there is nothing
2739
- to beat, and the run reports the two numbers rather than claiming a pass.
2740
-
2741
- `terralith-4-adopt` is asserted twice — 85 UNOWNED, then the
2742
- `live-import` line the up script printed, run by the script itself in the
2743
- target the way a person would, then 301 bound, because that write is the
2744
- person's, never behold's (#372). `waterpark` is checked for an untouched
2745
- checkout afterwards. `missingRequirements` decides what runs: a missing binary,
2746
- an unchecked-out sibling, an uninstalled chant example or the absent Terraform
2747
- lexicon each print `skip: <entry>: needs …`, so in CI every entry skips and the
2748
- run exits 0. `fountain-ops` is skipped by name everywhere, for the reason in
2749
- the table. A `behold-wb-*` container left standing at the end fails the run.
2750
-
2751
- The seeded catalog (#389) found one thing missing in src/: a LONE choudoufu
2752
- estate (every generated entry is one) served the no-project card, because the
2753
- single-project read is `chant graph <dir>` and such a directory has no lexicon
2754
- for it to read. `servesAsEstate` (src/member-kind.ts) is the predicate that
2755
- routes one directory of a non-chant kind through the estate compose path, where
2756
- the member's own kind reads it. One member composes exactly as four do, ids
2757
- namespaced under the member's short name, so the graph, the pane and the morph
2758
- agree on what a node is called.
2759
-
2760
- ### Rendering a Terraform estate
2761
-
2762
- A Terraform estate reaches behold through chant.
2763
- `@intentius/chant-lexicon-terraform` reads the HCL an estate already has and
2764
- emits one entity per block, so **a Terraform estate is a chant project whose
2765
- only lexicon is a reader** and `chant graph --format ir` serves it like any
2766
- other. behold parses no HCL itself, the same posture `src/carve-lens.ts`
2767
- states for the carve report (#378). The parser chant uses is installed with
2768
- behold since #909, below.
2769
-
2770
- Three passes turn what arrives into a picture (`src/terraform-lens.ts`), in this
2771
- order, guarded on the IR carrying terraform entities so every other estate gets
2772
- the identical object back:
2773
-
2774
- 1. **`normalizeTerraformNodes`.** A node's `kind` arrives as the entity class
2775
- (`Terraform::Resource`), not the resource type, so every card would be titled
2776
- and iconed the same. The type moves out of `attrs.address` into `kind` and
2777
- the block class lands in `attrs.block`. That is the shape a carve node
2778
- already has, which is why one presentation pack serves both.
2779
- 2. **`groupTerraformByRoot`.** Roots are a Terraform project's only grouping.
2780
- It retires itself when chant#2266 groups upstream. A node sits in exactly one
2781
- box, so a box every node has left is dropped rather than drawn empty (#393):
2782
- a served directory arrives composed, `composeStacks` boxes the whole member,
2783
- and the root boxes then take those same nodes, which is what put an empty
2784
- box named `access` on water park's canvas. What the member box was there to
2785
- say moves into the root box's title, which is `<member>/<root>` whenever the
2786
- estate holds more than one member and the bare root name when it does not
2787
- (two members with a root apiece named `prod` would otherwise merge silently).
2788
- 3. **`filterTerraformCards`.** What is a card, below.
2789
-
2790
- **What is a card (#382).** Measured on a real estate: 247 nodes for 43
2791
- resources, four fifths of it not infrastructure.
2792
-
2793
- | tier | blocks | why |
2794
- |---|---|---|
2795
- | default (detail 0-2) | `resource`, `data`, `module` | the estate: what is declared, what it reads, what it composes |
2796
- | attributes (detail 3) | + `output`, `variable` | its interface — real, but a second question |
2797
- | never | `terraform`, `provider`, `locals` | settings, not estate |
2798
-
2799
- Nothing is dropped silently: `terraformElisionNote` says what is not drawn and
2800
- where to see it, the way `edgelessNote` says why a view has no edges.
2801
-
2802
- **The note, at every zoom and in a 260px strip (#393).** The roots note and the
2803
- elision note are built by one function in `/api/graph` and returned by all three
2804
- of its branches, the logical lens included — it was the lens that most needed
2805
- the line and the only one that dropped it. Both routes send `note` and, when
2806
- there is a shorter true form, `noteShort` (`5 roots · 2 skipped · 189 blocks not
2807
- drawn`). The strip shows the short one with the long one on its tooltip, and the
2808
- panel's Model tab prints it whole. The server writes both: the SPA does not
2809
- author notes, and truncating this one on a sentence boundary would keep the list
2810
- of root names and drop the counts.
2811
-
2812
- **Do not invent edges.** They arrive from chant or not at all: the fixtures here
2813
- were recorded when a Terraform IR carried none, and lexicon 0.61.0 (chant#2265,
2814
- which resolves a block's `"${…}"` references) draws 390 over water park's five
2815
- roots with no change on this side. The one relationship that looked derivable
2816
- without it (a cross-root read by name) was measured and refused (#381): both
2817
- ends carry the same unresolved interpolation, so a match would be a coincidence
2818
- of variable naming. A data source says what it reads as a row instead.
2819
-
2820
- **Serving a directory that declares nothing (#384).** Every estate this lane
2821
- exists to draw is a directory of `.tf` files and nothing else, and #378 chose
2822
- not to ask one for a `chant.config.ts` of its own — INTENTIUS/waterpark#88 was
2823
- withdrawn because the estate is more useful untouched. So `behold serve
2824
- <terraform-dir>` generates the reader config itself, outside the estate, and
2825
- points chant at it. behold writes nothing in a served project (the
2826
- Invariant), nothing is written under the served directory, and
2827
- `src/terraform-member.test.ts` asserts the estate's source stamp is unchanged
2828
- across a read. Three decisions, each a trade #384 left open and each measured on
2829
- water park's `access/` before it was taken:
2830
-
2831
- 1. **The reader ships with behold, and is still probed.** chant resolves the
2832
- lexicon from the config file's own location, so the generated project has to
2833
- see it, and chant core (not the lexicon) imports `@cdktn/hcl2json` from its
2834
- own real path; neither package declares the parser. #384 made both optional
2835
- peers to keep a ~1.8 MB wasm blob out of chant-only installs. #909 reversed
2836
- that so `npx @intentius/behold serve .` on a folder of `.tf` files is one
2837
- command: `@intentius/chant-lexicon-terraform` and `@cdktn/hcl2json` are
2838
- **dependencies** in package.json (the only place their versions are named;
2839
- the refusal reads them from there). The maintainer accepted the cost on #909:
2840
- +8.3 MB on a 195 MB install, six packages. The lexicon's range starts at
2841
- behold's chant floor so its chant peer dedupes against behold's chant, and
2842
- npm hoists both beside chant, which is where the scratch project's
2843
- `node_modules` symlink and chant's parser import look. They are still probed
2844
- at serve and doctor time and refused with the one install line and where
2845
- behold looked, because an install that pruned them reaches a chant that
2846
- warns, exits 0 and prints an empty graph. The lexicon's own chant peer is
2847
- what moved behold's `@intentius/chant` floor to `^0.61.0`: chant 0.54 loads
2848
- no published version of it (`applyLineage is not a function`).
2849
- 2. **Roots are discovered, and the skips are reported.** A root is a directory
2850
- with a `.tf` declaring a line-start `terraform {` or `provider "` block
2851
- beside a `resource`, `data` or `module` block, a regex probe at the depth
2852
- the choudoufu probe uses, no HCL parsed. #384 proposed the first half alone
2853
- ("what a root has and a called module does not") and the estate refuted it:
2854
- water park's `modules/persona` is a shared module called by three roots and
2855
- its `versions.tf` is `baseline`'s byte for byte. So two exclusions stand
2856
- beside the probe, a directory under a `modules/` segment (Terraform's own
2857
- standard module structure; the roots that call it draw its blocks already)
2858
- and one with nothing to draw (`access/backends` is two backend fragments) —
2859
- and both are named in the graph's note with their reason, the way
2860
- `terraformElisionNote` names what a zoom left out. Measured on `access/`:
2861
- five roots (`envs/prod`, `identity`, `github`, `baseline`,
2862
- `satellites/waterpark-runner`), two skipped, `envs/dev` neither drawn nor
2863
- reported because it holds only a README.
2864
- 3. **A `terraform` member kind, after chant and choudoufu.** #378 said there is
2865
- no such kind and meant it about *reading*: behold parses no HCL and the
2866
- render goes through chant. A kind whose `read` shells `chant graph` against a
2867
- generated config is a scaffold, not a second reader, and it inherits the
2868
- probe, the cache stamp, the doctor line and estate composition (#368) for
2869
- free, so a Terraform root composes in an estate beside a chant project and a
2870
- choudoufu estate at no extra cost. `src/terraform-member.ts` is the whole of
2871
- it; `detectProjectShape` answers a directory that is its own member with
2872
- `membersFrom: "probe"`, which is what retired #384's `no chant.config.ts
2873
- here` dead end.
2874
-
2875
- The scratch project is `<tmpdir>/behold-tf-<hash of the estate path>`:
2876
- `behold-*` and cleared through `assertScratch` (src/scratch.ts), one directory
2877
- per estate reused across runs, asserted to be outside the estate before a byte
2878
- is written. It holds the generated `chant.config.ts`, a `package.json` that
2879
- declares it an ES module (chant's compiled CLI, 0.124.14 on, otherwise reads a
2880
- config tsx compiled as CommonJS as `{default: config}` and finds no lexicon:
2881
- INTENTIUS/chant#3897), and two symlinks —
2882
- `node_modules` to behold's own, which is how the config resolves the lexicon,
2883
- and `estate` to the served directory, which is how each root's `dir` is spelled.
2884
- The second is not decoration: the lexicon sets a root's module boundary to the
2885
- root's own directory when its `dir` resolves outside the project root, so
2886
- absolute paths cost every `../modules/x` call the estate makes — 72 nodes and 6
2887
- resources on water park, against 247 and 43 through the symlink. Nothing in the
2888
- answer mentions the scratch path (a terraform entity carries `attrs.file`
2889
- relative to its root, and no `sourceLoc`).
2890
-
2891
- ### A choudoufu member's overlay is ownership; attribute drift is the plan (#404)
2892
-
2893
- **Read a green choudoufu card as "this is ours", never as "nothing changed".**
2894
- The overlay is composed from `live-ls -json` and `live-plan -json`, and those
2895
- two documents answer one question — bound, unowned, omitted, or invisible to
2896
- the listing. Neither of them ever compares an attribute VALUE. A resource whose
2897
- tag, path or mutability was changed out of band still carries its markers, so
2898
- it is still bound, and it is still green.
2899
-
2900
- The other half of the terminal's answer ("would a plan change anything?") is
2901
- a **separate, opt-in read**, and since #924 it goes through chant together with
2902
- the ownership it is about (src/choudoufu-chant-read.ts): one `chant graph
2903
- --live` over the member's `chdf` reader project at the plan depth
2904
- (`CHANT_TERRAFORM_OBSERVE=plan`, INTENTIUS/chant#4371). chant runs `choudoufu
2905
- live-plan -json` for ownership, then `choudoufu plan -input=false -lock=false
2906
- -out=<its tmp>` and `show -json` for the attributes, and puts `planChanges`
2907
- (live value `before`, declared value `after`) on each bound block. With
2908
- `CHANT_TERRAFORM_LIVE_PLAN_DIR` set to a directory behold made under the OS
2909
- temp directory (INTENTIUS/chant#4383), chant also hands back the `live-plan`
2910
- document its verdicts came from, and behold paints ownership from that, so a
2911
- re-check runs ONE `live-plan` per member and the plan sits on the same
2912
- verdicts as the card. Nothing is written in the served member (chant writes
2913
- its plan file and the handed document outside it, INTENTIUS/chant#4379).
2914
- (`choudoufu plan -json` is not this read: on 0.16.0 it prints choudoufu's own
2915
- ownership document with no attribute values in it at all, measured in #404.)
2916
- On a live root drift IS the planned `update`: choudoufu rebuilds prior state
2917
- from the account, so chant's `planDrift` is empty there and is not read. A
2918
- path chant finds flagged sensitive on either side is `(sensitive)` on both,
2919
- and so is every copy of a flagged string (`tags_all`): a choudoufu plan flags
2920
- a sensitive variable's value on `after` only, with the old secret unflagged in
2921
- `before`. Floor: `CHOUDOUFU_PLAN_CHANT_FLOOR` (0.124.46); below it, or with no
2922
- terraform lexicon, a re-check paints from behold's own `live-plan` and reads
2923
- no plan.
2924
-
2925
- It is opt-in because it costs differently: the ownership read is answered out
2926
- of the tagging index and is flat in the estate's size, while `plan` refreshes
2927
- every resource, one provider read per card, 301 of them on `terralith-4`. So:
2928
-
2929
- - **Never on an ordinary overlay read.** `GET /api/overlay?plan=1` and
2930
- `GET /api/diff?plan=1` are the only things that read one, and the palette's
2931
- **"Re-check live with plan (attribute drift)"** row is the only thing in the
2932
- SPA that sends the flag. The cheap **"Re-check live (refresh drift)"** row is
2933
- deliberately left alone — it is `POST /api/refresh`, a primary-only re-observe
2934
- that captures a lanes frame and never composes the estate.
2935
- - **Cached under the member's source stamp**, the same key half `memberIr`
2936
- uses. A read that did NOT ask is served that stored answer, so a reload after
2937
- a refresh keeps showing the drift without paying for a second pass; a read
2938
- that DID ask always re-reads both halves, because "re-check" means re-check.
2939
- - **The ownership verdict stays the card's colour.** A bound card that drifted
2940
- is still painted bound and still counted `bound`; it gains `attrs._planDrift`
2941
- and wears a dashed `--degraded` edge plus a `~ n attributes` corner glyph
2942
- (web/app.js `markDriftedCards`, the same post-render stamp as the carve and
2943
- operator marks). A card that is not bound is never marked: an unowned
2944
- object's planned `create` is an ownership fact the overlay already paints,
2945
- and `planDrift` drops creates for that reason.
2946
- - **`/api/overlay`'s meta carries `drift`**: `{read: false}` or `{read: true,
2947
- drifted: n}`. The two are different answers — "nobody looked" versus "looked,
2948
- nothing drifted", and the legend prints a count only for the second.
2949
-
2950
- ### A stock Terraform root's plan comes from chant (#910)
2951
-
2952
- `GET /api/graph?plan=1` (palette: **"Read the plan on the Terraform roots"**)
2953
- reads each stock Terraform member's roots at chant's plan depth
2954
- (INTENTIUS/chant#4358): behold's own chant over the member's scratch project,
2955
- `CHANT_TERRAFORM_OBSERVE=plan chant graph . --live --overlay --env behold-plan
2956
- --format ir --detail 3` (src/terraform-plan.ts). The plan runs with
2957
- `-lock=false`, its file under the OS temp directory. Each resource or data card
2958
- gains `attrs._plan` (`source`, `action`, `reason`, `replacePaths`,
2959
- `forcedFrom`, `afterUnknown`, `changes`, `drift`), and the card's rows lead with
2960
- `plan`, `forced by`, `from` and `read`. `GET /api/terraform/plan` answers the
2961
- same facts per card as JSON.
2962
-
2963
- - **Which read answered is per root**, parsed from chant's notes: `plan`,
2964
- `state` (the plan failed, for missing credentials or a provider error) or
2965
- `none` (declared only). A card in a root that fell back says `plan: not read`
2966
- and which read answered. Never "no changes" unless the plan said `no-op`.
2967
- - **Sensitive values arrive redacted** by chant, at any depth and every copy;
2968
- behold copies plan facts only, never a block's other attributes.
2969
- - **Floor**: `TERRAFORM_PLAN_CHANT_FLOOR` (0.124.46) for behold's chant and the
2970
- lexicon; below it the read is refused with the upgrade line.
2971
- - **A planned create has a card**: it reads absent at the plan depth, so it
2972
- stays pending with no physical id, and chant carries its plan attributes
2973
- onto the declared node anyway (chant#4372). Its rows read `plan: create`,
2974
- `unknown: N until apply`, `read: plan`.
2975
- - **A `count`/`for_each` block draws a card per instance** (#996,
2976
- src/instance-cards.ts). The id is the block's node id and the key as
2977
- Terraform prints it, `app/aws_s3_bucket.logs[0]`, `<member>/` in front on an
2978
- estate, the same rule chant's graph uses for its instance nodes
2979
- (INTENTIUS/chant#4454). Until chant emits them, behold derives them from the
2980
- plan's per-instance rows (`planActions` by instance address, each change and
2981
- drift row's `instance`), so each card has its own action, changes and drift.
2982
- An instance node chant draws is kept and only painted. The block card stays
2983
- as the rollup: chant's aggregate `_plan`, `attrs._instances` and an
2984
- `instances` row. A key under a module instance (`module.a[0]...[1]`) stays
2985
- in the rollup. A choudoufu member's roster is per instance already.
2986
- - **choudoufu members read ownership and the plan through chant together**
2987
- (src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
2988
- re-check's `live-plan` is chant's, handed back to behold. See the choudoufu
2989
- section above.
2990
-
2991
- ### A lexicon behold draws but cannot aim (#430)
2992
-
2993
- `behold doctor`'s **targets** line. `SUBSTRATE_TARGET_VARS` (src/targets.ts)
2994
- names four lexicons against the nine behold draws, deliberately — it withholds
2995
- one until chant can actually be pointed at an emulator for it. That module also
2996
- names the cost: a landed chant change leaves a stale omission "until someone
2997
- notices", which happened once (#125) and left behold showing a floci-gcp pill it
2998
- could not aim a read at. This is the line someone reads instead.
2999
-
3000
- `NO_AMBIENT_TARGET` (same module) is what stops it being noise: k8s and temporal
3001
- are not withheld, they are finished — they bind from `chant.config` rather than
3002
- an ambient variable, so there is nothing to override and nothing for a picker.
3003
- Those report as settled, not as a gap.
3004
-
3005
- What the line CANNOT say, stated because the gap is the point: the honest
3006
- question is "chant can route this and behold does not list it", and behold
3007
- cannot ask it. Since chant 0.61 the endpoint variable is declared by the LEXICON
3008
- PLUGIN (`endpointEnvVarsFor`), not by a table in core, and behold installs no
3009
- lexicon plugins; the served project does. No chant CLI reports them either
3010
- (`lifecycle whoami --json` answers identity and says nothing about endpoints).
3011
- So the check warns on the weaker question it can answer and says it may be
3012
- over-reporting. The real fix is upstream, and #430 records the ask.
3013
-
3014
- ### A card with no live half is not an unobserved one (#429)
3015
-
3016
- pinhole's painter takes a closed `_status` set and falls back to `neutral` for
3017
- anything else, `undefined` included. So on a mixed overlay a member with no live
3018
- half, a Terraform root, whose `live`/`overlay`/`env` are stripped in
3019
- src/terraform-member.ts — painted exactly like a card behold looked at and could
3020
- not see, while the legend counted only the latter. Measured on
3021
- `serve example-writes example-terraform-estate --env prod`: 37 Terraform cards
3022
- carrying no `_status`, 2 chant cards carrying `neutral`, one fill between them.
3023
-
3024
- Those cards now carry `data-no-live` and the legend gives them their own row.
3025
- Named rather than folded into `unobserved`, because "I looked and could not see"
3026
- and "there is nothing here to look at" are different claims, the same argument
3027
- #399 makes for an unpriced card, and the same answer: mark it, do not merely
3028
- colour it. The mark is overlay-only; on the source graph no card has a status
3029
- and marking every one of them would say nothing.
3030
-
3031
- This is presentation, not vocabulary. `statusVocabulary` gets no terraform row:
3032
- there is no status to name. See #429 for the measurement that established it.
3033
-
3034
- ### An adoptable row is painted like an unowned one, plus its evidence (#413)
3035
-
3036
- A `NEEDS_DISCOVERY` omission paired with an `adoptable[]` row at the same
3037
- address paints `warn` with `ownership: "foreign"`, the same verdict the UNOWNED
3038
- branch gives and for the same reason: the live object carries no marker for
3039
- this estate. On its own, `NEEDS_DISCOVERY` stays neutral — the declaration
3040
- names no identity, and with nothing found that is a "could not answer" rather
3041
- than an action.
3042
-
3043
- The card leads with `attrs.adopt`, which is choudoufu's own `adopt_command`
3044
- here rather than the marker pair an unowned row carries. `adoptLine`'s
3045
- composed-command branch had no real caller until this. behold composes no
3046
- command of its own: the API that writes a tag differs per resource type.
3047
-
3048
- `attrs.matchedOn` is the difference in kind. An unowned row needs no evidence
3049
- because the identity IS the match; here choudoufu asserts that a live object is
3050
- a declaration because their identity-bearing arguments agree, and a person
3051
- about to stamp two tags onto somebody's resource is owed the list.
3052
-
3053
- `web/app.js` renders both through the one copyable row, and its tooltip says
3054
- whether the line is a command or a pair of tags.
3055
-
3056
- ### The adoption sweep is off unless a serve asks (#412)
3057
-
3058
- `live-plan -json` carries `adoptable[]` (live resources the estate-wide sweep
3059
- matched to a declared instance by content) and `swept` (the types it listed in
3060
- full). Both are empty on a run that did not ask the account-inventory question,
3061
- and behold does not ask by default.
3062
-
3063
- The opt-in is `TOFU_LIVE_COLLECT_UNCLAIMED=1` (`ADOPTION_SWEEP_VAR`,
3064
- src/choudoufu-live.ts), carried through `serve.spawnEnv`, the seam
3065
- `setChoudoufuSpawnEnv` already feeds every choudoufu spawn. The env var rather
3066
- than `-adoption-only`, because that flag suppresses the resource diff the
3067
- overlay needs. Off by default because the sweep is bounded by the ACCOUNT rather
3068
- than the estate, and behold polls. `0` means no, which is choudoufu's own
3069
- spelling, not a truthiness test.
3070
-
3071
- **Content matching is a closed per-type table**, and that is what decides
3072
- whether a declaration can ever produce an `adoptable[]` row. `matchTable`
3073
- (choudoufu's internal/live/foreign/classify.go) lists eleven types against the
3074
- identity-bearing arguments a match may use — `aws_vpc` on `cidr_block`,
3075
- `aws_security_group`/`aws_lb`/`aws_sns_topic` and friends on `name`,
3076
- `aws_subnet` on `cidr_block` + `availability_zone`, `aws_acm_certificate` on
3077
- `domain_name`. A type absent from it, in the table's own words, "can never
3078
- produce a bind candidate". `aws_iam_role` is absent, which is why #412's first
3079
- attempt measured a shape that cannot match rather than a gap. A resource with a
3080
- `count`/`for_each` key is skipped too, so a fixture wants a scalar.
45
+ src/member-kind.ts is the one table (`registerMemberKind`, `MEMBER_KINDS`).
46
+ A probe is sync, read-only and runs no code. Routes never branch on kind:
47
+ differences live in the kind's `via.read` or `passes`. A `passes` function
48
+ mutates in place, guards on the IR's content rather than the served kinds,
49
+ and must not re-run. A test that stubs a kind's reader spreads the real spec
50
+ or it loses the passes. Add a pack in src/render.ts, a row in
51
+ src/status-vocabulary.ts if the kind has its own words, a doctor check if it
52
+ needs a binary, and tests in src/project.test.ts and src/estate.test.ts.
3081
53
 
3082
- `src/__fixtures__/choudoufu-live-plan-adoptable.json` is the real thing,
3083
- recorded off floci: one scalar `aws_vpc` declaring a static `cidr_block`, its
3084
- unmarked live twin created out of band, and the run asked with the opt-in. It
3085
- carries the pairing M2 is about, a `NEEDS_DISCOVERY` omission and an
3086
- `adoptable[]` row at the same address — plus `matched[]` naming what was
3087
- compared and choudoufu's own `adopt_command`.
54
+ ### Scratch infrastructure
3088
55
 
3089
- ### A choudoufu estate's own references (#393)
56
+ Anything behold boots goes through `assertScratch` (src/scratch.ts): named
57
+ `behold-*`, refuses a taken name, tears down only what it created, never
58
+ binds :4566. Protected names are listed in `PROTECTED_INFRA`. A new boot site
59
+ gets a row in src/scratch.test.ts.
3090
60
 
3091
- `choudoufu live-check -json` states the roster and `references[]`, and that
3092
- second list is *cross-estate by construction* — data sources filtered on
3093
- another estate's marker tags. So a 301-resource terralith of roles, policies
3094
- and attachments drew no edge at all and the graph asserted "nothing in this
3095
- estate references anything else", which is false about every one of them.
61
+ ### Tests and checks
3096
62
 
3097
- The references were never missing; nothing was reading them. **A choudoufu
3098
- member's read now also runs the terraform kind's reader over its own
3099
- directory**, one root, the estate directory itself, through the same scratch
3100
- project machinery above (nothing written under the estate), and joins the two
3101
- documents by address. behold still parses no HCL: `src/choudoufu-refs.ts` is
3102
- two lists of strings and the rules that match them, and its header is the
3103
- argument for each. In short: the lexicon names *blocks* in a path of module
3104
- *calls* (`estate/module.team_pod/aws_iam_role.pod_role`) and choudoufu names
3105
- *instances* in a path of module *instances*
3106
- (`module.team_pod["pod-a"].aws_iam_role.pod_role[0]`), so one lexicon edge is a
3107
- product — kept inside one module instance (Terraform's scoping, not a guess),
3108
- joined key to key when both ends expand over the same keys (266 true edges on
3109
- `terralith-4` against 666 of which ~400 would be false), landing on a module
3110
- call's whole interior, and dropped whole when either end is a `var`, a
3111
- `locals` or anything else the roster declares no card for.
63
+ - The local gate is `just check` (tsc, tests, build). The docs site has its own: `npm run build` in docs/ lints the agent prompts and checks every link.
64
+ - src/test-env.ts strips CHOUDOUFU_BIN, PLUNGE_BIN and similar from the test environment. A test that needs one sets it and restores it.
65
+ - Tests against a real chant run only when `BEHOLD_TEST_CHANT_BIN` is set; k3d tests only with `BEHOLD_K3D_TESTS=1`.
66
+ - src/render.ts and its imports must bundle for the browser, so no `node:` imports (`npm run check:browser-bundle` names the chain). After `web/icons` changes, run `npm run generate:icons`.
67
+ - src/graph-package.ts (built to dist/index.js, used by the action and the VS Code extension) stays free of hono, the MCP SDK and the Kubernetes client; src/read-graph-imports.test.ts holds it. The Kubernetes client is an optional peer, loaded by dynamic import.
68
+ - e2e scripts run under e2e/lib/safe-env.sh, which keeps real cloud credentials out; e2e/README.md lists the variables.
3112
69
 
3113
- Every edge is `inferred` and carries the lexicon's own attribute name (`role`,
3114
- `policy_arn`), so the card says what made the reference. **Without the
3115
- lexicon there are no edges and the note says so** — carrying the terraform
3116
- kind's own install line rather than the sentence behold has no reader to
3117
- assert, and the lexicon's version is in the member's cache stamp, so
3118
- installing it invalidates the edgeless IR rather than serving it forever.
70
+ ### Merging
3119
71
 
3120
- The layout half is `packBoxComponents` (src/render.ts). src/edgeless.ts wraps a
3121
- box whose cards reference *nothing*; a box that has edges is never wrapped, so
3122
- `terralith-4` came back as a 110996 x 628 strip the day the join landed —
3123
- dagre lays 42 connected components side by side on three ranks. The pass packs
3124
- a box's components into shelves and resizes the box around them, re-laying each
3125
- component on its own first (inside a cluster dagre interleaves them: a six-card
3126
- cluster's bounding box spanned 46598 units) and wrapping a component that is a
3127
- strip either way: the DNS fan is 19564 x 400 upright and 900 x 10046 on its
3128
- side. A box under 4:1 is left exactly as it laid out. Measured: `terralith-4`
3129
- 7660 x 5162 with 266 edges, waterpark 3536 x 3138 at detail 2 and 7142 x 6974
3130
- at detail 3 (from 4.2:1 and 15.1:1, the case #393's wrap did not answer).
72
+ No merge queue yet: open the pull request with the local gate passing and
73
+ stop; the orchestrator merges. Pull requests merge one at a time, in order,
74
+ each rebased onto what landed; no `gh pr merge --auto`. A repository admin
75
+ may push a tested integration branch's merge to `main` directly.
3131
76
 
3132
- ## What live objects name outside the cluster (behold#1082)
77
+ ### Workbench and release
3133
78
 
3134
- `outsideRefs(objects, { graph })` in web/outside-refs.js is a pure function
3135
- with no imports, so a browser bundle takes it whole. It turns Kubernetes
3136
- objects as the API serves them into `{ cards, edges, notes }`: a cloud identity
3137
- card for a ServiceAccount's `iam.gke.io/gcp-service-account`,
3138
- `eks.amazonaws.com/role-arn` or `azure.workload.identity/client-id`
3139
- annotation, a store card and a provider card (GCP Secret Manager, AWS Secrets
3140
- Manager or Parameter Store, Vault, with the `remoteRef.key` values) for an
3141
- ExternalSecret, and a source card for an Argo CD Application's `spec.source`
3142
- and `spec.sources[]` or a Flux Kustomization's `sourceRef` and `path`. It reads
3143
- the field paths chant#5098 and chant#5099 read, so a placeholder and a derived
3144
- edge agree. A card's id is made from what it names, so two objects naming one
3145
- thing share it, and a target the `graph` already holds gets no card and no
3146
- edge. A field it cannot read goes in `notes`, never dropped.
79
+ workbench.json lists internal estates used for development; `just example
80
+ <entry>` serves one. Paths are siblings (`../chant`, `../choudoufu`); a
81
+ missing sibling just marks the entry unsatisfiable. `fountain-ops` runs its
82
+ setup in your working checkout and switches your kubectl context, so avoid it
83
+ unless asked.
3147
84
 
3148
- Chant's live Kubernetes read masks every key matching /secret/i. An
3149
- ExternalSecret's whole `spec.secretStoreRef` comes back as `<masked>`, so on a
3150
- live read that ExternalSecret has no store card and its keys stay off the
3151
- provider card; its note carries `waitsOn: "INTENTIUS/chant#5116"`. The
3152
- ServiceAccount, provider and source cards work on a live read today.
3153
- src/outside-refs-live.test.ts reads a scratch k3d cluster through chant's
3154
- lister to show it (BEHOLD_K3D_TESTS=1; the cluster is `behold-outside-refs-<pid>`,
3155
- created and deleted by the test). Fixtures are in web/outside-refs.test.js.
85
+ `just release` tags `behold-v<version>` after the version-bump PR is in.
86
+ A tag push publishes, so never push a `behold-v*` tag by hand.