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