@intentius/behold 0.30.2 → 0.32.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 (102) hide show
  1. package/AGENTS.md +791 -16
  2. package/README.md +78 -23
  3. package/THIRD_PARTY.md +6 -5
  4. package/demos.json +14 -9
  5. package/dist/cli.js +51926 -20221
  6. package/example-carve/README.md +19 -23
  7. package/example-carve/app/package.json +1 -1
  8. package/example-carve/app/src/carved.ts +3 -3
  9. package/example-carve/carve-report.json +1 -1
  10. package/example-carve/{legacy-tf → tf-root}/terraform.tfstate +1 -1
  11. package/example-choudoufu-estate/README.md +7 -0
  12. package/example-choudoufu-estate/chant.workspace.json +1 -1
  13. package/example-choudoufu-estate/scripts/choudoufu-down.sh +2 -1
  14. package/example-choudoufu-estate/scripts/choudoufu-up.sh +10 -3
  15. package/example-terraform-estate/README.md +32 -5
  16. package/example-terraform-estate/chant.workspace.json +1 -1
  17. package/example-terraform-estate/recorded/adoption/platform.json +72 -0
  18. package/example-terraform-estate/recorded/adoption/prod.json +224 -0
  19. package/example-three-cloud/README.md +111 -18
  20. package/example-three-cloud/aws/Pulumi.yaml +15 -0
  21. package/example-three-cloud/aws/index.ts +174 -0
  22. package/example-three-cloud/aws/package-lock.json +2725 -0
  23. package/example-three-cloud/aws/package.json +14 -0
  24. package/example-three-cloud/aws/tsconfig.json +17 -0
  25. package/example-three-cloud/azure/main.tf +48 -0
  26. package/example-three-cloud/azure/site.tf +104 -0
  27. package/example-three-cloud/chant.config.json +9 -0
  28. package/example-three-cloud/chant.workspace.json +30 -4
  29. package/example-three-cloud/dns/chant.config.ts +26 -1
  30. package/example-three-cloud/dns/src/records.component.ts +32 -6
  31. package/example-three-cloud/package-lock.json +48 -27
  32. package/example-three-cloud/package.json +8 -6
  33. package/example-three-cloud/scripts/emulators-up.sh +28 -1
  34. package/example-three-cloud/scripts/front-door.ts +679 -86
  35. package/package.json +26 -8
  36. package/schemas/graph/v1/graph.schema.json +140 -0
  37. package/web/adopt-pulumi.js +114 -0
  38. package/web/adopt-pulumi.test.js +28 -0
  39. package/web/adopt.js +203 -0
  40. package/web/adopt.test.js +27 -0
  41. package/web/app.js +367 -14
  42. package/web/boot-motion.js +6 -0
  43. package/web/carve-steps.js +1 -1
  44. package/web/carve-steps.test.js +2 -2
  45. package/web/change-set-overlay.js +12 -5
  46. package/web/change-set-overlay.test.js +22 -0
  47. package/web/cut-around.d.ts +30 -0
  48. package/web/cut-around.js +138 -0
  49. package/web/drift-stream.js +241 -0
  50. package/web/drift-stream.test.js +146 -0
  51. package/web/edge-weight.d.ts +8 -2
  52. package/web/edge-weight.js +38 -4
  53. package/web/edge-weight.test.js +55 -1
  54. package/web/graph-query.js +180 -0
  55. package/web/graph-query.test.js +49 -0
  56. package/web/graph.html +107 -0
  57. package/web/index-diff.js +109 -0
  58. package/web/index-diff.test.js +39 -0
  59. package/web/index.html +45 -20
  60. package/web/kiosk-ask-tips.js +15 -5
  61. package/web/kiosk-ask-tips.test.js +14 -1
  62. package/web/kiosk-estate-scene.js +72 -8
  63. package/web/kiosk-light-frame.js +1 -0
  64. package/web/kiosk-light.js +41 -3
  65. package/web/kiosk-member-kind.test.js +140 -0
  66. package/web/kiosk-popover.js +4 -1
  67. package/web/kiosk-side.js +296 -0
  68. package/web/kiosk-side.test.js +249 -0
  69. package/web/kiosk-watch.js +12 -0
  70. package/web/kiosk-watch.test.js +15 -1
  71. package/web/kiosk.html +47 -1
  72. package/web/kiosk.js +106 -7
  73. package/web/member-kind.js +31 -0
  74. package/web/neighbourhood.js +105 -0
  75. package/web/neighbourhood.test.js +131 -0
  76. package/web/outside-refs.js +515 -0
  77. package/web/outside-refs.test.js +249 -0
  78. package/web/template-apps.js +245 -0
  79. package/web/template-apps.test.js +252 -0
  80. package/web/templates.js +285 -0
  81. package/web/templates.test.js +155 -0
  82. package/web/terragucci-lifecycle.js +112 -62
  83. package/web/terragucci-lifecycle.test.js +29 -1
  84. package/web/terragucci-timeline.js +39 -2
  85. package/web/terragucci-timeline.test.js +42 -1
  86. package/web/theme-paint.js +14 -0
  87. package/example-three-cloud/aws/chant.config.ts +0 -8
  88. package/example-three-cloud/aws/site.component.ts +0 -13
  89. package/example-three-cloud/aws/src/site.ts +0 -27
  90. package/example-three-cloud/azure/chant.config.ts +0 -1
  91. package/example-three-cloud/azure/src/site.component.ts +0 -13
  92. package/example-three-cloud/azure/src/site.ts +0 -18
  93. /package/example-carve/{legacy-tf → tf-root}/cdn.tf +0 -0
  94. /package/example-carve/{legacy-tf → tf-root}/compute.tf +0 -0
  95. /package/example-carve/{legacy-tf → tf-root}/floci-override.tf.disabled +0 -0
  96. /package/example-carve/{legacy-tf → tf-root}/modules/cdn/main.tf +0 -0
  97. /package/example-carve/{legacy-tf → tf-root}/naming.tf +0 -0
  98. /package/example-carve/{legacy-tf → tf-root}/network.tf +0 -0
  99. /package/example-carve/{legacy-tf → tf-root}/observability.tf +0 -0
  100. /package/example-carve/{legacy-tf → tf-root}/outputs.tf +0 -0
  101. /package/example-carve/{legacy-tf → tf-root}/storage.tf +0 -0
  102. /package/example-carve/{legacy-tf → tf-root}/versions.tf +0 -0
package/AGENTS.md CHANGED
@@ -21,7 +21,7 @@ apply creds.
21
21
  A directory with a `chant.workspace.json` is a chant workspace (chant ≥ 0.81.0,
22
22
  INTENTIUS/chant#2524). `behold serve <root>` serves it from chant's own member
23
23
  list (`chant workspace ls --json`, read contract 1; any other contract is
24
- refused), and reads each `chant`, `terraform` and `choudoufu` member through
24
+ refused), and reads each `chant`, `terraform`, `choudoufu` and `pulumi` member through
25
25
  `chant workspace graph --member <name>`. A `choudoufu` member takes its block
26
26
  graph from it (the estate's own edges, each block's `file` and `line`) and
27
27
  joins it onto choudoufu's `live-check` roster, which still names the cards,
@@ -29,7 +29,15 @@ the rungs and the cross-estate references: chant's graph is one node per
29
29
  block, ownership is per instance, and chant carries no rung or reference
30
30
  (src/choudoufu-workspace.ts, #465). The ids are the roster's, as before, so a
31
31
  saved layout keeps matching. behold's own lexicon read of a choudoufu
32
- directory stays for a loose view only. Node ids are `<member>/<id>` with the declared member name, the same
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
33
41
  form chant composes. A member chant cannot read is drawn as one
34
42
  `UnreadableMember` node carrying `attrs._unreadable: {code, message}` with
35
43
  chant's reason code. An `other` member is listed on startup and in doctor and
@@ -37,6 +45,16 @@ draws nothing. A declaration with `members: []` (terragucci writes one for its
37
45
  gates) declares nothing to draw, so serve, export and doctor read the
38
46
  directory as they would without one, and say so (#489). `.behold.json`'s `members` are ignored beside a declaration;
39
47
  `behold doctor --fix` writes the declaration for an estate that has only them.
48
+ A `kustomize`, `argo-app`, `flux-kustomization`, `helm-chart` or `cloudformation`
49
+ member is read the same way (#1056), and the detail tier of a read is passed on
50
+ as `--detail` (chant 0.124.35, `WORKSPACE_DETAIL_CHANT_FLOOR`). The kinds come
51
+ from the k8s, helm and aws lexicons the workspace pins (chant 0.124.49,
52
+ `WORKSPACE_KINDS_CHANT_FLOOR`). At chant's default detail a k8s node carries only
53
+ `apiVersion` and `kind`; the Argo and Flux path edges of src/estate-edges.ts need
54
+ `spec`, which comes at detail 3. A lens, `up`, `down` and a namespace stay on the
55
+ member's own `chant graph`. A kustomize member needs `kustomize` or `kubectl` on
56
+ PATH and a helm-chart member needs `helm`. The fixture is
57
+ e2e/fixtures/k8s-workspace and the test src/k8s-member.test.ts.
40
58
  Several directories on the command line (`behold serve a b c`) stay the loose
41
59
  view behold composes itself.
42
60
 
@@ -59,6 +77,52 @@ a scheduled read: it holds a slot in the read budget, has the read deadline,
59
77
  and stops when the request does. `serve --hud <url>` (or `BEHOLD_HUD_URL`)
60
78
  links a proposed decision to its review in hud.
61
79
 
80
+ ## A folder with no declaration, read by its kinds' probes (behold#1079)
81
+
82
+ `chant workspace graph <dir> --discover` (INTENTIUS/chant#5095) finds the members
83
+ of a directory that has no `chant.workspace.json`: the kinds' probes claim
84
+ directories, a directory a local `module` source calls or that sits inside
85
+ another member is not a member of its own, and two kinds claiming one directory
86
+ at the same precedence is a tie that is not read. The document is a contract 1
87
+ graph with one more field, `discovered[]`, one entry per claimed directory
88
+ (`dir`, `member`, `kind`, `source`, `probe`, `outcome`, `claims`, `note`).
89
+ Member names are the lowercased path with runs of characters a name cannot
90
+ hold turned to `-`, and `.` is `root`, so node ids and `member=` links in a
91
+ discovered folder carry those names, not the folder's name.
92
+
93
+ src/discover-read.ts reads it through `src/workspace-reader.ts`, one chant call
94
+ per folder, and `readGraph` (src/read-graph.ts, signature unchanged) turns the
95
+ document into the `Workspace` a declaration would give. Each member then takes
96
+ its part of that one document (`discoveredVia`), so the estate code composes a
97
+ discovered folder exactly as it composes a declared workspace, including an
98
+ unreadable member drawn as a box with chant's reason. The note names each tied
99
+ directory and counts the directories left out as modules or inside a member.
100
+ A list of one path is read as that folder, which is how the server hands it
101
+ over; `behold serve`, `behold shot` and the server treat a folder this applies
102
+ to as an estate (`discoverAppliesToList`). The overlay, search and the other
103
+ per-member reads still go to the folder as they did.
104
+
105
+ The floor is `WORKSPACE_DISCOVER_CHANT_FLOOR`, 0.124.98 (src/chant-floors.ts):
106
+ chant#5095 is on chant's main after the 0.124.97 freeze. Below it, or when the
107
+ chant's version is unknown, nothing here runs and a folder is read as before.
108
+ `CHANT_RELEASE` (src/chant-release.ts) is not moved by this: that is a
109
+ maintainer step once 0.124.98 is on npm.
110
+
111
+ Which folders go through it is a measured choice, not "all of them". On the
112
+ `infra/` tree of a Kubernetes project checkout (52 Terraform roots, 2
113
+ CloudFormation templates, 1 manifests directory), behold's own Terraform reader
114
+ takes 3.5 s cold and 72 ms on a reread, because one chant reads one generated
115
+ project naming every root. `--discover` runs a reader per member: 44 s cold,
116
+ 6.8 s on chant's member cache, 55 members. So the default (`auto`) discovers a
117
+ folder behold cannot draw (no member kind claims it: Kubernetes, Helm) or draws
118
+ only half of (a Terraform or choudoufu folder that also holds Kubernetes or
119
+ Helm files), and leaves a Terraform or choudoufu folder with none on its own
120
+ reader. A chant project is never discovered. `BEHOLD_DISCOVER=always|never|auto`
121
+ overrides it. Because the Terraform scratch project (`behold-tf-*`) stays the
122
+ reader for those folders, and the plan read, choudoufu, behaviour and search
123
+ (`behold-tfws-*`) write it too, `writeTerraformScratchProject` and its tests
124
+ stay.
125
+
62
126
  ## Chant version floors (behold#691)
63
127
 
64
128
  behold shells each project's own chant, so a read can reach a chant that
@@ -80,6 +144,75 @@ spawning the read. A new read adds its constant and entry in the issue that
80
144
  adds the read, once the chant release is known, and reads through the read
81
145
  contract (`src/workspace-reader.ts`), never chant's library.
82
146
 
147
+ ### The chant release behold follows (behold#1005)
148
+
149
+ `CHANT_RELEASE` in src/chant-release.ts, `{ version, released }`, names the
150
+ chant release behold's newest reads need. It says `{ version: "0.124.58",
151
+ released: true }`: chant 0.124.58 is on npm (0.124.54 was the first release with the
152
+ drift record and its stream, the adoption report, `member-outputs` and
153
+ `@intentius/chant-lexicon-pulumi`; 0.124.58 adds the self-service modules). `ADOPTION_REPORT_CHANT_FLOOR`,
154
+ `DRIFT_RECORD_CHANT_FLOOR`, `DRIFT_STREAM_CHANT_FLOOR` and
155
+ `LEDGER_ROOT_MEMBER_CHANT_FLOOR` are its `version`, which is chant's
156
+ `NEXT_RELEASE` (INTENTIUS/chant#4480) at the cut. scripts/chant-release.ts
157
+ writes the files the switch decides (src/chant-release-sync.ts lists them):
158
+ the exact terraform and pulumi lexicon pins of example-terraform-estate,
159
+ example-choudoufu-estate and e2e/fixtures/pulumi-workspace (the published
160
+ chant, `PUBLISHED_CHANT`, while unreleased, so a plain `npm ci` meets them,
161
+ and `version` once released, moving with the floors; behold#1015), the
162
+ three-cloud workspace's pins (by path while unreleased, by package and
163
+ version once released) and its package.json, and behold's own chant ranges,
164
+ the pulumi lexicon devDependency among them. src/chant-release.test.ts holds
165
+ them to the switch, and `npx tsx scripts/chant-release.ts --check` lists any
166
+ file out of step.
167
+
168
+ With the release out, behold imports what it once copied from chant:
169
+ src/drift-line.ts decodes with `@intentius/chant/drift-record` (keeping
170
+ behold#995's unknown-status rule on top), src/graph-db/types.ts, listing.ts
171
+ and mask.ts re-export chant's engine-facts, index-document, cloud-lister and
172
+ mask modules, the investigation templates come from
173
+ `@intentius/chant/capabilities/templates` with no stub, the index diff is
174
+ `@intentius/chant/lifecycle/index-diff`, and `behold index` calls chant's
175
+ `runCloudIndex` statically. src/value-match.ts stays until the pulumi
176
+ lexicon has a `referenceCatalog` (chant#4535's note on behold#1005).
177
+
178
+ ## chant's reference catalog (behold#1080)
179
+
180
+ A declared workspace read by a chant at `REFERENCE_CATALOG_CHANT_FLOOR`
181
+ (0.124.98, the release that carries INTENTIUS/chant#5097; 0.124.97 is on npm
182
+ today) gets one more read: `chant workspace graph <root>` for the whole
183
+ workspace, at the tier the members are read at (src/reference-catalog.ts,
184
+ cached under the workspace's source stamp). A read of one member cannot see a
185
+ reference into another, so the per-member reads' `dangling` entries that carry
186
+ a `rule` are replaced by this read's, and its derived edges, `dangling[]`,
187
+ `ambiguous[]` and `catalog.rules` go on the composed IR (`ir.catalog`). The
188
+ floor is checked first; below it nothing is sent and the estate is composed as
189
+ before. `readGraph` does this, after behold's own edge passes and before the
190
+ cluster anchor.
191
+
192
+ src/catalog-draw.ts draws it, after the stacking (`graphView` and the estate
193
+ branch of `/api/graph` call `drawCatalog`). A catalog edge is weighed "joined"
194
+ (web/edge-weight.js, `isCatalogEdge`), apart from "inferred", and the weight
195
+ and the rule are stamped on the SVG's edge (`data-edge-weight`,
196
+ `data-edge-rule`) with inline strokes, so a static export keeps them. A
197
+ dangling reference whose rule is not containment is a dashed placeholder card
198
+ (kind of the `targetKind`, lexicon `behold`, `attrs._placeholder` the value, one
199
+ per member, kind and value), and an ambiguous one is a dotted edge to each
200
+ candidate with `viaAttr` "one of N". The picture ends with the key; the answer's
201
+ `meta.catalogLegend` has the same rows for the page, which hides the in-SVG one
202
+ and draws its own. The graph document keeps `rule`, the one field: chant's rule
203
+ id on a joined edge, and the reference's rule on the placeholder and ambiguous
204
+ edges.
205
+
206
+ The cluster anchor (src/cluster-anchor.ts) reads the join: a member whose
207
+ Applications name a cluster Secret that chant joins to one cluster resource
208
+ anchors its objects to that cluster only; a Secret with no match, two matches,
209
+ or a member that reaches several clusters anchors nothing and puts the reason
210
+ in the note (`ir.anchorNotes`). A member without a cluster Secret keeps the
211
+ guess. The fixtures are `chant workspace graph --discover --json` recorded
212
+ from a chant checkout at the catalog and its rules (e2e/fixtures/
213
+ reference-catalog), the tests src/catalog-draw.test.ts and
214
+ src/catalog-route.test.ts.
215
+
83
216
  ## A pipeline's numbers, from Prometheus (behold#571)
84
217
 
85
218
  `behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
@@ -127,6 +260,78 @@ makes, `declaredReportUrl` in src/workspace.ts, floor
127
260
  declaration included; the flag overrides it, and each answer's `urlFrom` says
128
261
  `flag` or `declaration`. With neither, nothing changes.
129
262
 
263
+ A member of another kind in an estate's components picture (#997): chant
264
+ writes its release ledger per component and a TerraformApplyOp writes no
265
+ release, so a `choudoufu` or `terraform` member is one card,
266
+ `<member>/<kind>` (lexicon `member-runs`, src/component-releases.ts), with
267
+ every resource of the member under it. Its `apply` and `_lastApply` are the
268
+ run index's newest `apply` entry for that member that passed (an entry with
269
+ no `member` is a run of the whole workspace and is not taken as one), and
270
+ its `since` and `_runSince` the newest entry after it, the member's or the
271
+ workspace's, when that did not pass. A card the index names nothing of says
272
+ `no runs recorded`, or `no run index read` when behold has no report URL;
273
+ behold never makes one up. The members are read through the same
274
+ `ciRunIndexOf` as the runs pane.
275
+
276
+ The same card lists the member's local applies (behold#1010,
277
+ src/member-local-applies.ts): the TerraformApplyOp runs that applied a root
278
+ in the member's directory, from `chant ledger runs --where
279
+ root_member=<member> --json` at the served workspace's root (chant#4482,
280
+ chant#4500), as `_localApplies` (newest first, at most five) and `local`, the
281
+ newest that passed. The read is sent only to a chant at
282
+ `LEDGER_ROOT_MEMBER_CHANT_FLOOR`, and a `runs` table whose `columns` lack
283
+ `root_member` reads as "this chant does not say", so the card keeps the run
284
+ index alone. A null `root_member` is unknown (chant#4508): such a run is on
285
+ no card, the declaring member's included, and the picture's note counts it
286
+ as an apply of an unknown root with its `labels.TerraformRoot`, read with
287
+ `--where labels.Apply=true`.
288
+
289
+ ## Adopting a Pulumi stack into plunge (behold#999)
290
+
291
+ A `pulumi` member of a declared workspace is offered adoption into plunge,
292
+ the engine tier, through plunge's own `plunge stack adopt` (INTENTIUS/plunge#7,
293
+ P-L4). The Adopt tab and `GET /api/adopt` say what it gains (a record per
294
+ resource, marker tags, no stack lock, the checkpoint's IDs kept, a recorded
295
+ adoption that a re-run leaves alone, a back-out through `plunge stack export`
296
+ and `pulumi stack import`) and what it does not (plunge's refusals, bridged
297
+ types classed at the first run, record-only ownership for untaggable types).
298
+
299
+ - `GET /api/adopt/report?member=<name>[&stack=<name>]` runs `plunge stack
300
+ adopt --stack <s> --json --non-interactive` in the member's directory, with
301
+ `PULUMI_BACKEND_URL=plunge+<backend.url from Pulumi.yaml>`, no stdin and no
302
+ `--yes`. That is plunge's read-only stage, as one v1 JSON document
303
+ (INTENTIUS/plunge#17, plunge docs/plunge/ADOPT.md): every resource with its
304
+ fate (marker, record, pending, already-adopted), having written nothing.
305
+ Each resource gets its fate and why. When plunge refuses the adoption
306
+ (pending operations, a provider hiding the markers, an aws-native
307
+ create-only-tag type, foreign records), each refusal is listed with its
308
+ code and the URN it names. behold reads the JSON view only (behold#1007).
309
+ - `POST /api/adopt/start` `{member, stack?}` runs the same classification
310
+ through the runner's `track` and answers the confirm command, `cd <dir> &&
311
+ PULUMI_BACKEND_URL=<url> plunge stack adopt --stack <s> --yes`. A person
312
+ runs it. behold never passes `--yes` or `-y`, drops
313
+ `PULUMI_SKIP_CONFIRMATIONS` from the environment it hands plunge, and
314
+ refuses any other plunge argv before spawning (`assertClassificationOnly`,
315
+ src/pulumi-adoption.ts). After the confirm, point Pulumi.yaml's
316
+ `backend.url` at `plunge+<url>` so chant runs the member through plunge.
317
+ - The backend comes from the member's Pulumi.yaml only, never login state. A
318
+ `file://`, `s3://`, `gs://` or `azblob://` URL is a DIY backend; a
319
+ `plunge+` one is already plunge's. No URL, or a Pulumi Cloud URL, gets no
320
+ start, and the offer says why. The stack is read off the checked-in
321
+ `stack-export.json` URNs unless the request names one.
322
+ - A plunge without the `stack adopt --json` view is detected from its answer
323
+ (outcome `no-view`), not from a version, and refused with words naming
324
+ plunge 968b54748d, the commit that adds the view.
325
+ - The table is keyed on member kind (`ADOPTERS`, src/adoption.ts), the same
326
+ names the Terraform half uses on integration/choudoufu-engine.
327
+ `/api/adopt*` is refused in a public view, and the start goes through the
328
+ terragucci and SQL Yodeler write allowlist.
329
+ - Tests: src/pulumi-adoption.test.ts, web/adopt-pulumi.test.js, and the e2e
330
+ `just e2e-adopt-pulumi` (e2e/adopt-pulumi-e2e.sh with the stand-in
331
+ e2e/fixtures/adopt-pulumi/plunge), which asserts nothing is written before
332
+ a person runs the confirm line, even with `PULUMI_SKIP_CONFIRMATIONS=true`
333
+ in behold's environment.
334
+
130
335
  ## A plan job run locally (behold#685)
131
336
 
132
337
  `POST /api/chant/ci/local` `{job: "plan", commit, pr, env?, base?, member?,
@@ -154,6 +359,64 @@ that holds for it: `ci run` gives the job a clean environment that keeps HOME,
154
359
  so `serve --local`'s emulator env does not reach the job and the operator's
155
360
  own credentials would. Cached-step marks wait on chant#4015.
156
361
 
362
+ ## Adopting a Terraform root into choudoufu (behold#999)
363
+
364
+ A `terraform` member of a declared workspace is offered adoption into
365
+ choudoufu, the engine tier, through chant's `chant workspace promote <member>
366
+ --state <file>` (src/adoption.ts, floor `ADOPTION_REPORT_CHANT_FLOOR`, which
367
+ is `CHANT_RELEASE.version` in src/chant-release.ts until the chant release
368
+ carrying the report is cut; see "The coming chant release" below). The panel's
369
+ **Adopt** tab (web/adopt.js) shows, per member, what the engine tier gives
370
+ and what it does not, the command, and promote's report.
371
+
372
+ - `GET /api/adopt`: each adoptable member's offer `{member, kind, dir,
373
+ offered, engine, gains, limits, stateHint, state: {file, present},
374
+ command, approve, recorded, start: {offered, why?}}`. A `pulumi` member is
375
+ listed `offered: false` with `waits` (plunge P-L4, INTENTIUS/plunge#7):
376
+ `ADOPTERS` and `ADOPTION_WAITS` are keyed on member kind, and the Pulumi
377
+ half adds its adopter there.
378
+ - `GET /api/adopt/report?member=<name>[&state=<file>]`: promote's read-only
379
+ stage, `workspace promote <member> --state <abs> --dry-run --json`, through
380
+ the reader (`readPromoteReport`, `PROMOTE_REPORT_READ`). chant stages in a
381
+ throwaway worktree, runs `choudoufu live-check` and `live-import` without
382
+ `-approve`, records no gate and leaves the tree as it was. Its `adoption`
383
+ field (chant's `adoption-report.ts`, parsed from choudoufu's text) lists
384
+ every resource instance; behold gives each a `fate`: `claimed` (VERIFIED,
385
+ DRIFTED) or `left-out` (MISSING, UNTAGGABLE, UNADMITTED_TYPE), with a
386
+ `why` and choudoufu's `detail`. An unknown status is listed as `unknown`,
387
+ never dropped.
388
+ - `POST /api/adopt/start` `{member, state?}`: the delegated write. It starts
389
+ `workspace promote <member> --state <abs> --json` (never `--dry-run`,
390
+ never `-approve`) at the workspace root through the runner's `track`.
391
+ chant's gate decides: without an approval of the patch's digest promote
392
+ records a pending gate on `chant/lifecycle` and exits 3 (`gated`), and
393
+ nothing in the tree or the cloud is written; after `chant approve
394
+ workspace-promote <member> --plan <digest>`, the same start applies the
395
+ patch and runs `live-import -approve`. behold never approves here; the
396
+ approve line is shown to copy. `GET /api/adopt/runs/:id` answers one start
397
+ (`outcome`, `digest`, `words`, `approve`, `report`), the last 20 in memory;
398
+ the SSE `adopt-run` event names one that moved.
399
+ - The state file is a file name in the member's declared directory
400
+ (`terraform.tfstate` by default), never a path. A root on a remote backend
401
+ pulls one there under a name git ignores first, since promote refuses a
402
+ member with uncommitted changes.
403
+
404
+ Refusals: no declared workspace `404`, below the floor `409 chant-too-old`,
405
+ preview `403` for the start, a kind behold does not adopt `422 adopt-kind`,
406
+ no state file `422 adopt-state`, a second command while one runs `409 busy`.
407
+ A terragucci or SQL Yodeler repo refuses the start through the write
408
+ allowlist (`409`), and `--public` refuses every `/api/adopt` read (`403`)
409
+ and the start (`405`). The tab is not drawn in a public view, an embed, a
410
+ static export or a guarded repo.
411
+
412
+ `behold demo terraform-estate` serves `serve --adopt-recorded
413
+ recorded/adoption` (DemoServe `adoptRecorded`): one recorded `<member>.json`
414
+ per root in promote's shape, labelled recorded (`RECORDED_NOTE`), and no
415
+ start. `just e2e-adopt` (e2e/adopt-terraform-e2e.sh) runs the whole path over
416
+ a real chant and serve with choudoufu replaced by
417
+ e2e/fixtures/adopt/choudoufu, and asserts the report lists every resource
418
+ with its fate and that nothing is written before approval.
419
+
157
420
  ## A terragucci estate, from its reports (#490)
158
421
 
159
422
  `behold serve <repo> --terragucci <dir|s3://bucket/prefix|https://…>`
@@ -657,6 +920,101 @@ pending member becomes a real one only when its own read completes, and the
657
920
  live pass a progressive request starts is the same one per member under the
658
921
  same budget: a progressive load costs the estate no extra spawn.
659
922
 
923
+ ### Drift, streamed card by card (#998)
924
+
925
+ `POST /api/workspace/drift/stream {member, addresses?}` (palette: **"Stream
926
+ drift card by card: <member>"**) runs `chant workspace drift --member <name>
927
+ --stream` at the workspace root and narrates it as `drift` frames on
928
+ `/api/events` (src/drift-stream.ts). The stream is chant's drift record in
929
+ NDJSON (chant#4451): one `drift-start` with the addresses it expects, one
930
+ `drift-record` per instance as its read finishes, one `drift-settle`. Each
931
+ line is decoded in `streamDrift` (src/workspace-reader.ts) by
932
+ src/drift-line.ts, which uses chant's own `decodeDriftLine` from
933
+ `@intentius/chant/drift-record` (behold#1005) and narrows its line to what a
934
+ card reads, and each record frame repaints only its own card. The
935
+ start is refused below `DRIFT_STREAM_CHANT_FLOOR` (409, the floor's refusal,
936
+ nothing spawned), unless `BEHOLD_DRIFT_CHANT` names the chant to run.
937
+
938
+ - **Per resource on a choudoufu member.** choudoufu's single-resource path
939
+ (`live-plan -resource`, choudoufu#2245) plans one resource and writes its
940
+ records when that plan ends, and there is no whole-estate stream. So behold
941
+ asks once per resource block (`--resource <addr>`, instance keys dropped,
942
+ data sources left out), one after another, from the card addresses the page
943
+ sends; the cards change colour resource by resource. Any other member is
944
+ asked once without `--resource`.
945
+ - **Reading is not a status.** Between a start and its settle, an expected
946
+ card that has not reported is `data-drift-reading`: dimmed and dashed, its
947
+ fill and `_status` unchanged. Only a record sets `_status`.
948
+ - **Not reached.** At settle, every expected address no record answered
949
+ becomes `not-observed` with reason `not-reached` (chant's fold rule), sent
950
+ as a record frame before the settle frame. A read that fails or prints a
951
+ line that does not decode is a `failed` frame: its cards stop reading and
952
+ keep the colour they had. A read that never started stops the run.
953
+ - **Colour** is `toneFor(record)`, #995's `(status, read)` table
954
+ (src/drift-tone.ts, below). A status or read outside it is neutral, and the
955
+ card carries `data-drift-unknown` and says so in its tooltip.
956
+ - One run at a time (`409 drift-streaming`); `{stop: true}` stops it.
957
+ `BEHOLD_DRIFT_CHANT` names the chant the read runs, for a chant built
958
+ ahead of the release that adds `workspace drift --stream`, and for
959
+ `just e2e-streamed-drift`'s fake (e2e/fixtures/fake-chant-drift); the
960
+ floor, `DRIFT_STREAM_CHANT_FLOOR`, is checked only against the root's own
961
+ chant, so it does not apply then.
962
+
963
+ ### Colour from the drift record (#995)
964
+
965
+ Every card's live colour is one fixed table over chant's drift record
966
+ (chant#4451), keyed on the record's `status` and the `read` that answered,
967
+ and on nothing else: `DRIFT_TONE_TABLE` and `toneFor` in src/drift-tone.ts.
968
+ No engine is named there, so a Pulumi member (path 2, chant#4453) colours
969
+ through the same cells as the rest. The read limits the claim: an
970
+ `ownership` read's `in-sync` is green and labelled "bound (ownership only)"
971
+ (#404), a `state` read's `recorded` is neutral, and a state read that says
972
+ `in-sync` or `drifted` (a record chant refuses) is neutral and labelled. An
973
+ unknown status or read is neutral and labelled unknown, never a guessed
974
+ colour.
975
+
976
+ - **The drift document.** `chant workspace drift --member <name> [--read
977
+ <read>] [--resource <addr>] [--env <env>]` prints one member's drift
978
+ document (contract 1, `drift: "v1"`), read by the member's own engine. It is
979
+ `read("drift", driftArgs(ask))` on the workspace reader, the sixth
980
+ `BEHOLD_READS` entry, held by chant's conformance suite when that suite
981
+ lists `drift`. `paintWorkspaceDrift` (src/drift-overlay.ts) reads it per
982
+ member and paints `_status`, `_drift: {status, read, label, reason?,
983
+ engineCode?, fellBackFrom?, unknown?}` and `_unobserved` on each card.
984
+ `/api/overlay` on a declared workspace whose chant meets
985
+ `DRIFT_RECORD_CHANT_FLOOR` (`CHANT_RELEASE.version`, the release not cut yet) does this on
986
+ every read for the members with no live half of their own (`terraform`,
987
+ `pulumi`), and with `?drift=1` for `chant` and `choudoufu` members too, at
988
+ the cost of a second live read. `meta.driftRecord` lists each member's
989
+ painted and unplaced records and chant's error. With `?plan=1` a terraform
990
+ or choudoufu member is asked `--read plan`.
991
+ - **The reads behold still makes itself colour through the same table.** A
992
+ choudoufu member's `live-plan`/`live-ls` paint (src/choudoufu-live.ts
993
+ `verdictFor`) gives each address the status chant's adapter gives it
994
+ (`bound` in-sync, `unowned`/`adoptable` unclaimed, `ABSENT` pending, every
995
+ other omission not-observed, a listed item nothing declares undeclared) and
996
+ takes the table's tone, read `ownership`. A component status row's
997
+ reconciliation fallback (src/component-status.ts `reconciliationStatus`) is
998
+ chant's `componentStatusDriftRecords` mapping, read `live-read`.
999
+ - **UNOWNED, settled with chant.** An `UNOWNED` omission with no `unowned[]`
1000
+ row is `not-observed` (`read-failed`, `engineCode: "UNOWNED"`), as chant C1
1001
+ decided: neutral, not `warn`. With its `unowned[]` row it is `unclaimed`
1002
+ and `warn`, as before.
1003
+ - **Which read answered a root** is the IR's `rootReads` (chant#4452):
1004
+ `terraform.roots.<root>` with `depth`, `fellBackTo` and `reason`
1005
+ (src/terraform-plan.ts `planRootAnswers`, src/choudoufu-chant-read.ts
1006
+ `rootAnswerOf`). chant's note text is not parsed. A chant that puts no
1007
+ `rootReads` on the IR reports no root: a stock root's cards carry no plan
1008
+ answer, and a choudoufu re-check reads as live-plan alone.
1009
+ - **choudoufu card ids and chant node ids (the B3 follow-up).** behold keeps
1010
+ a choudoufu member's card ids, the roster's `<member>/<address>`, because
1011
+ saved layouts are keyed on them, while chant names the same blocks
1012
+ `<member>/<root>/<block path>`. One alias table, built from chant's graph
1013
+ of the member (`choudoufuCardAliases`, src/drift-overlay.ts), maps a chant
1014
+ node and an instance address onto the card (`cardIdFor`), and both the
1015
+ change-set overlay (src/change-set-overlay.ts) and drift records use it. A
1016
+ node the table does not know lands on no card and is listed.
1017
+
660
1018
  ### What a read cost (#420, #421)
661
1019
 
662
1020
  `GET /api/doctor` serves `diagnose()`, the same report `behold doctor` prints,
@@ -888,7 +1246,7 @@ would go.
888
1246
 
889
1247
  ### The walkthrough (`behold demo carve`, #254)
890
1248
 
891
- `behold demo carve` copies a bundled half-migrated estate (a chant project
1249
+ `behold demo carve` copies a bundled mixed estate (a chant project
892
1250
  beside a Terraform one), runs the advisor over the copy, and serves the same
893
1251
  carve view plus a six-step stepper on the panel's Carve tab: advise → pick →
894
1252
  emit → bridge → handoff → done.
@@ -1029,6 +1387,33 @@ GET /api/capabilities
1029
1387
  "helpers":[...]}
1030
1388
  ```
1031
1389
 
1390
+ ### The graph pane: Cypher and resolve-from-resource (behold#1027)
1391
+
1392
+ Every member's chant IR, every engine graph document (`choudoufu live-graph
1393
+ -json`, `plunge graph --json`, read from `engine-graph.json` beside a member
1394
+ or `.behold/graph/*.json`), every index version (the latest per scope in
1395
+ `.chant/store/index/`, `_index/` on `refs/chant/snapshots`, and behold's
1396
+ per-user index directory) and every cloud listing in one LadybugDB per
1397
+ session. Tables: `Resource` keyed `<member>/<id>` (or the source's scope
1398
+ key), `CloudId` with `KNOWN_AS` from each Resource, and `REF` with `grain`,
1399
+ `origin` (`derived` for an identity match, with its `rule`) and `ambiguous`.
1400
+ The database is behold's own file under `$XDG_DATA_HOME/behold/graph` and
1401
+ read-only once built; a query that writes is refused. Cypher needs the
1402
+ optional peer `@ladybugdb/core` and answers 503 `graph-peer-missing` with the
1403
+ install line without it; resolve, the template catalog and the path-pattern
1404
+ templates work without it. Every answer carries `sources`, each with
1405
+ `observedAt` (null for a declared source) and `readAt`. A `--public` serve
1406
+ refuses the pane. behold mcp's `ask` takes `cypher` or `resource` (with
1407
+ `template` and `inputs`) beside `query`. All GET.
1408
+
1409
+ ```
1410
+ GET /api/graphdb sources, counts, notes, peer
1411
+ GET /api/graphdb/query?cypher=&params= {"columns","rows","keys","draw":{nodes,edges},"link","sources"}
1412
+ GET /api/graphdb/resolve?ref= {"candidates":[{key,matchedBy,...}],"templates":[...],"sources"}
1413
+ GET /api/graphdb/template?name=&node=&in.<input>=
1414
+ GET /graph the pane
1415
+ ```
1416
+
1032
1417
  ## Moving the person's open tab (#914)
1033
1418
 
1034
1419
  `POST /api/view` changes what every open tab of this serve draws. It is a
@@ -1121,10 +1506,209 @@ remote does not take the LFS object, it refuses with the setup line and exits
1121
1506
  1 before the branch moves; the local PNG is kept. `behold mcp`, `GET
1122
1507
  /api/shot` and a `--public` serve never publish.
1123
1508
 
1509
+ ## The graph document: `behold-graph/1` (#1066)
1510
+
1511
+ A graph snapshot (`{ir, meta}`, what `/api/graph` answers and what every
1512
+ export snapshot holds) becomes a versioned document through
1513
+ `toDocument(snapshot, opts)` (`src/to-document.ts`). The types, the version
1514
+ string and `checkGraphDocument` are in `src/graph-document.ts`, which imports
1515
+ nothing, so a browser host can load it. The JSON Schema ships in the package
1516
+ at `schemas/graph/v1/graph.schema.json` and is published at
1517
+ https://intentius.io/behold/schemas/graph/v1/graph.schema.json (its `$id`,
1518
+ the same bytes from `docs/public/`; a test holds the two together).
1519
+
1520
+ ```
1521
+ {schema: "behold-graph/1", generator: {behold, chant?}, origin: {dir, rev?},
1522
+ cut: {kind: "whole" | "around" | "changed", ...}, nodes[], edges[], groups[],
1523
+ notes[], layout?}
1524
+ node: {id, title, subtitle, kind, lexicon, box?, file?, line?, change?,
1525
+ status?, color?, mainstat?, secondarystat?, stackOf?, detail__member?,
1526
+ detail__root?, detail__namespace?, detail__release?, attrs}
1527
+ edge: {id, source, target, kind, inferred, rule?, via?}
1528
+ group: {id: "<kind>:<key>", title, kind: stack | wave | pipeline | container, parent?}
1529
+ note: {kind, text, short?, box?, count?}
1530
+ ```
1531
+
1532
+ The node and edge field names are the ones Grafana's node graph panel takes,
1533
+ so the panel reads `nodes` and `edges` with no transform. `subtitle` is the
1534
+ tool (`k8s` reads `kubernetes`), `status` is `attrs._status`, `color` its
1535
+ pinhole bar colour, `mainstat` the drift record's words or the plan's action,
1536
+ `change` the plan's action unless it is `no-op` or `read`. `file` is relative
1537
+ to the repository root, and absent when behold cannot place it there; an
1538
+ absolute `sourceLoc` is dropped. An edge whose end the view does not draw is
1539
+ left out and counted in `notes` (`edges-left-out`), so every `source` and
1540
+ `target` names a node. Edge ids are `<source>-><target>:<kind>[:<via>]`, with
1541
+ `#2`, `#3` on repeats. `rule` names the join behind an inferred edge: chant's
1542
+ catalog rule (`origin: "derived"`), or `behold:<join>` from the `join` field
1543
+ each behold pass now sets beside `inferred: true` (`value-match`,
1544
+ `k8s-declared`, `estate-member`, `cluster-anchor`, `composite-deps`,
1545
+ `choudoufu-lexicon`, `choudoufu-estate`). `attrs.source` is left out unless
1546
+ `opts.source` asks for it.
1547
+
1548
+ `documentOptions({projectDir, projectDirs?, workspace?, behold, rev?})`
1549
+ (`src/graph-document-context.ts`) works out what the IR does not carry: the
1550
+ served directory relative to its repository (the nearest `.git` above it),
1551
+ each member's directory and Terraform roots, and a scrubber that rewrites this
1552
+ machine's paths to repository-relative ones, the home directory to `~` and
1553
+ the temporary directory to `$TMPDIR`. The same snapshot and options give
1554
+ byte-identical JSON. Within `behold-graph/1` fields are only added and a
1555
+ reader ignores what it does not know; `checkGraphDocument` refuses any other
1556
+ `behold-graph/<n>` by name.
1557
+
1558
+ ## The graph from the command line: `behold graph` (#1058)
1559
+
1560
+ `behold graph [dir] [--json | --ir] [-o <file>] [--detail 0..3] [--source]
1561
+ [--every-card]` reads a directory and prints it, with no server, no browser
1562
+ and no write but the `-o` file (src/graph-cli.ts). `--json`, the default, is
1563
+ the `behold-graph/1` document; `--ir` is the unversioned `{ir, meta}` that
1564
+ `/api/graph` answers, without its SVG. `--mermaid [--forge gitlab|github|forgejo]`
1565
+ is a flowchart that fits that forge's character budget (below); `--svg` is
1566
+ reserved for its painter (#1061) and exits 2 until it applies. Exit 1 is a
1567
+ directory chant would not read (its refusal and remedy on stderr), exit 2 a
1568
+ usage error. No output holds an absolute path: both go through
1569
+ `documentOptions`' scrubber, and `attrs.source` is left out without
1570
+ `--source`.
1571
+
1572
+ The Mermaid writer (#1060) is `toMermaid(doc, { forge })` in
1573
+ src/graph-mermaid.ts, over a `behold-graph/1` document, so a cut applies first.
1574
+ Ids are `n<index>` and `g<index>` over the sorted ids, one label line per card,
1575
+ boxes as subgraphs, inferred edges dotted, labels quoted and escaped with
1576
+ Mermaid entity codes. A document with a plan's `change` or a cut's `seed` gets
1577
+ four `classDef` lines: added (`create`), changed (`update`, `replace`), removed
1578
+ (`delete`) and neighbour (a card in the cut that is neither a seed nor changed).
1579
+ Over the budget it drops neighbours first, then whole boxes (those with the
1580
+ fewest changed cards first), and ends with a `N cards not shown` card; it never
1581
+ returns text over the budget. The budgets are one table, `FORGE_BUDGETS` in
1582
+ src/mermaid-budgets.ts: gitlab 2,000 characters, github and forgejo 20,000 and
1583
+ 250 edges, a whole comment under 60,000. Each row has `confirmed: false` until
1584
+ the live check (e2e/forge-limits, #1065) records the forge's real figures; that
1585
+ check's result is an edit to the row. `forgeComment` builds the comment body
1586
+ (marker, count line, fenced diagram) and posts the per-root table from
1587
+ `rootTable` instead when the diagram had to leave cards out or the comment
1588
+ would reach its limit; the action (#1062) and the MCP text fallback (#1073)
1589
+ use these.
1590
+
1591
+ The read is `graphView(dir, opts)` (src/graph-view.ts): `readGraph`, then the
1592
+ lenses `/api/graph` runs over an estate's source picture: the plan when
1593
+ `terraformPlan` is passed (the server's setting, as an argument), collapse,
1594
+ stacking alike cards (`--every-card` turns it off), and the note, joined by
1595
+ `viewNote`. The route calls `shapeEstate` and `viewNote` from the same module,
1596
+ and src/graph-view.test.ts holds the view equal to the route's answer. The
1597
+ logical and components lenses, the traffic prediction (it reads per-user
1598
+ settings) and the SVG stay in the route. An output format is one entry in
1599
+ `GRAPH_FORMATS` (src/graph-formats.ts); a cut is a function over the document
1600
+ that the CLI hands a format as `cut`.
1601
+
1602
+ ### A bare cluster: `behold graph --context <name>` (#1083)
1603
+
1604
+ `behold graph --context <name> [--kubeconfig <file>] [--namespace a,b]
1605
+ [--types t,u] [--allow-exec-plugin]` draws the cluster a kubeconfig context
1606
+ points at, with no chant project and no directory (src/read-cluster.ts).
1607
+ `--kubeconfig` alone reads that file's current context; without it the file is
1608
+ the first path in `KUBECONFIG`, then `~/.kube/config`. There is no reader of
1609
+ behold's own. `readCluster` calls chant's `indexCloud` (the cloud lister
1610
+ `behold index kubernetes` runs: API discovery, then a paged LIST per kind, read
1611
+ allowlist only) with the `none` store, so no index version and no file is
1612
+ written, and hands the result to `readComposed` (src/read-graph.ts), the passes
1613
+ `readGraph` runs over a directory's estate. `readGraph` still reads no
1614
+ kubeconfig. Cards are boxed by namespace (cluster-scoped objects in `cluster`)
1615
+ and take the ids `<namespace>/<Kind>/<name>`; an edge to an object the read did
1616
+ not list is dropped and counted in the note. What the objects name outside the
1617
+ cluster (web/outside-refs.js, #1082) is added as cards in a box called Outside
1618
+ the cluster. `behold serve` does not take a context yet.
1619
+
1620
+ Credentials: a token, a token file or a client certificate. A user that
1621
+ authenticates through an exec plugin (the GKE, EKS and AKS tools write these)
1622
+ is refused with exit 2, naming the context, before chant is loaded and before
1623
+ any request. `--allow-exec-plugin` runs the plugin once (src/kube-exec.ts, the
1624
+ ExecCredential protocol, no terminal) and reads with the credential it prints.
1625
+ An `auth-provider` user is always refused. Whether the switch should be on by
1626
+ default is the maintainer's ruling and is open.
1627
+
1628
+ The live read masks every key matching /secret/i, which chant's typing then
1629
+ shows as `[REDACTED]`. On chant 0.124.58 an ExternalSecret's
1630
+ `spec.secretStoreRef` is masked whole, so its store and provider draw no card
1631
+ and the note says so (chant#5116 keeps such reference fields readable). An Argo
1632
+ CD cluster Secret's name and server are masked too, and chant#5116 decides
1633
+ whether they show. behold draws what the lister returns under either answer.
1634
+ `BEHOLD_K3D_TESTS=1 npx vitest run src/read-cluster-live.test.ts` runs the
1635
+ live test on a k3d cluster named `behold-read-cluster-<pid>`, deleted afterward
1636
+ unless `BEHOLD_K3D_KEEP=1`; `BEHOLD_EXPECT_5116=1` makes its reference test
1637
+ fail instead of skip.
1638
+
1639
+ The same command is the `behold-graph` bin of `@intentius/behold-graph`,
1640
+ built from this repo into packages/graph by `npm run build:graph` (part of
1641
+ `npm run build`). Its entry is src/graph-package.ts, which exports `readGraph`,
1642
+ `graphView`, the formats, `toDocument` and the document types. Its
1643
+ dependencies are packages/graph/budget.json's allowlist, at behold's own
1644
+ ranges and version (a test holds both). `npm run check:graph-package` (CI runs
1645
+ it after the build) packs it, installs the tarball into an empty directory,
1646
+ prints the installed size, and fails above the budget, on a dependency not on
1647
+ the allowlist, or when `npm ls --all` names hono, `@hono/node-server`, the MCP
1648
+ SDK or the Kubernetes client. The first measurement was 127 MB and 55
1649
+ packages, against 238 MB and 162 for behold; the budget is 140 MB and 60.
1650
+ Most of it is chant itself (73 MB) and the TypeScript compiler chant loads
1651
+ configs with (23 MB). Publishing the package is the maintainer's step.
1652
+
1653
+ ## The single-file viewer (#1070)
1654
+
1655
+ `npm run build:viewer` (scripts/build-viewer.mts) writes
1656
+ `dist/behold-viewer/`: `index.html` (no inline script), `viewer.js` (a
1657
+ classic script), `viewer.mjs` (the same as an ES module), `viewer.css`, a
1658
+ stand-in `graph.js`, and `viewer.html` with the script and the styles
1659
+ inlined, for an MCP resource or an unzipped artifact. It draws a
1660
+ `behold-graph/1` document with the painter `/api/graph` uses: the document is
1661
+ turned back into the IR (src/viewer/document-ir.ts, a card's box walked up to
1662
+ its stack, pipeline, wave and container) and painted by `paintDocument`
1663
+ (src/viewer/paint.ts), with the same box badges. The source is src/viewer/.
1664
+
1665
+ The document comes, in this order, from a `behold:graph {document, icons?}`
1666
+ message, from `window.__BEHOLD_GRAPH__` (graph.js, the only form that works
1667
+ from `file://`), or from `?src=<same-origin path>`. Options come from the
1668
+ query string and from `window.__BEHOLD_VIEWER__`, the query winning:
1669
+ `theme` (light, dark, blueprint, aws; absent, `prefers-color-scheme`),
1670
+ `node`, `focus` (box keys or ids), `host` (the parent's origin), `transport`
1671
+ (post, vscode, mcp, none) and `src`. In: `behold:theme {theme?, vars?}` (CSS
1672
+ custom properties only) and `behold:view {node?, focus?}`. Out:
1673
+ `behold:ready`, then `behold:select {id, kind, file}` per pick.
1674
+ src/viewer/transport.ts has the three hosts: a parent page (`postMessage` to
1675
+ `host` only, and only its messages read), a VS Code webview
1676
+ (`acquireVsCodeApi`, called once), and an MCP Apps view (JSON-RPC:
1677
+ `ui/initialize`, the document from `ui/notifications/tool-result`'s
1678
+ `structuredContent`, the theme from the host context, a pick sent as
1679
+ `ui/update-model-context`). With no `transport`, a page with
1680
+ `acquireVsCodeApi` is VS Code, one with `host` is a parent page, and a
1681
+ framed page with neither is MCP Apps.
1682
+
1683
+ The layout runs in a Web Worker: the script starts itself as the worker,
1684
+ from its own URL or, inlined, from its own text, and paints on the page when
1685
+ no worker starts (index.html opened from `file://`). A document with no
1686
+ boxes above `FLAT_LIMIT` cards is refused with the reason, since one flat
1687
+ layout grows far faster than the card count. The page sets
1688
+ `data-behold-viewer` on `<html>` (`waiting`, `drawing`, `drawn`, `refused`)
1689
+ and `window.__BEHOLD_VIEWER_STATE__` (cards, where it laid out, time to first
1690
+ paint).
1691
+
1692
+ The vendored icon table is left out of the build: it is 544 KB of the 684 KB
1693
+ painter. A host hands over the icons its document uses, as
1694
+ `window.__BEHOLD_ICONS__` or the message's `icons`; `graphScript(doc)`
1695
+ (src/viewer/graph-script.ts) writes a graph.js with both, and
1696
+ `documentIcons(doc)` finds the icons by painting the document once with the
1697
+ full table (`recordIcons` in src/icon-packs.ts). Once a host supplies icons,
1698
+ an icon it did not supply falls through to pinhole's keyword glyph
1699
+ (`supplyIcons`). The build fails above 300 KB minified or 100 KB gzipped for
1700
+ `viewer.js` or `viewer.mjs`, above 1 MB for the directory, on any Node
1701
+ built-in in the bundle, and when `viewer.js` names `EventSource` or
1702
+ `WebSocket`. On pinhole 0.5.0 it fails on the four `node:` imports in
1703
+ pinhole's root (#1069), which pinhole 0.6.0 removes.
1704
+ src/viewer/viewer-browser.test.ts opens it in headless Chrome from `file://`
1705
+ and under `default-src 'none'; script-src 'self'; style-src 'self'
1706
+ 'unsafe-inline'`, and skips while pinhole is 0.5.0.
1707
+
1124
1708
  ## Over MCP: `behold mcp` (#916)
1125
1709
 
1126
1710
  `behold mcp [project-dir] [--url <serve> | --port <n>]` is a stdio MCP server
1127
- with four tools, all clients of a running serve's HTTP API. An agent reads
1711
+ with five tools for an agent (and a sixth for a view), most of them clients of a running serve's HTTP API; `graph` (#1073, below) reads the directory itself. An agent reads
1128
1712
  `capabilities` first (#926): it calls `GET /api/capabilities` and returns
1129
1713
  chant's capability catalog, the read contract's `capabilities` document
1130
1714
  (`chant search --capabilities --json`, INTENTIUS/chant#4375), byte for byte.
@@ -1142,6 +1726,24 @@ followed by a text block `{link, state, serve}`. They take `query`, `env`,
1142
1726
  and `height`. The answers are chant's: behold passes chant's documents
1143
1727
  through and computes none of its own.
1144
1728
 
1729
+ `graph` (#1073) draws the repository, or a cut of it, and takes `dir` (a folder
1730
+ inside the project), `around` (comma-separated card or box ids, or a box title
1731
+ or Terraform root as the roots table prints it), `changed` (`<base>..<head>`),
1732
+ `depth` and `direction`. It reads in this process with the calls `behold graph`
1733
+ makes (`src/mcp-graph.ts`) and answers in text for every host: the counts, the
1734
+ cut, a Mermaid block when it fits (`MCP_MERMAID_BUDGET`, nine thousand
1735
+ characters) or a table of roots when it does not, and a link to the running
1736
+ serve at the card or box asked for, else the line that starts one. The whole
1737
+ text stays under `TEXT_CHARS` (18,000), well under Claude Code's 10,000-token
1738
+ warning, and holds no document JSON. `_meta.ui.resourceUri` names
1739
+ `ui://behold/viewer` (MIME type `text/html;profile=mcp-app`, MCP Apps spec
1740
+ 2026-01-26), which `resources/read` serves from `src/viewer-resource.ts`:
1741
+ `dist/behold-viewer/viewer.html` (#1070's `npm run build:viewer`) when it is in
1742
+ the package, else a page saying the view is not in this build. The view gets
1743
+ its document from `graph_document`, a tool with `_meta.ui.visibility: ["app"]`
1744
+ that takes `graph`'s arguments (`structuredContent.view` of a `graph` result
1745
+ is exactly those), so the cards never enter the model's context.
1746
+
1145
1747
  It finds the serve through `--url`/`--port`, then the per-user registry at
1146
1748
  `<os.tmpdir()>/behold/serves/<pid>.json` (`{url, pid, projectDir, version,
1147
1749
  startedAt}`, written by every serve at start, rewritten on a project switch,
@@ -1446,7 +2048,12 @@ or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
1446
2048
  bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
1447
2049
  failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
1448
2050
  `planned` (a release gate's release and environment, chant#4045). An entry
1449
- with no node is kept and listed in the Change set tab, never dropped. The page
2051
+ with no node is kept and listed in the Change set tab, never dropped. An entry
2052
+ for one instance of a counted block (#996) is put on the instance's node,
2053
+ `<blockNode>[k]`, with `block` naming the block, whether chant mapped it to the
2054
+ block node (before chant#4454) or the instance node; the block's node carries
2055
+ the rollup (`instances`), so its card is outlined when the instance cards are
2056
+ not drawn. The page
1450
2057
  (web/change-set-overlay.js) outlines each card in the drift legend's tokens
1451
2058
  (managed for create, foreign for update or replace, degraded for delete or
1452
2059
  forget) with a tag above it, never a fill; it is opened from the "change set"
@@ -1569,7 +2176,9 @@ document, so it is checked against chant's schema, vendored unchanged in
1569
2176
  src/health-schema/ (chant PR #4193 at d727944c4) and validated with ajv, with
1570
2177
  a hole's `reason` loosened to any string; a document the schema refuses is
1571
2178
  refused whole. A project with no lexicon that reads health is `none`, not a
1572
- failure. A member below the floor is refused before anything is spawned; when
2179
+ failure. A member of another kind (#997) is listed as `none` without a
2180
+ spawn: the read builds a chant project and it has none. A member below the
2181
+ floor is refused before anything is spawned; when
1573
2182
  every member is, the answer carries the refusal and `degraded`.
1574
2183
 
1575
2184
  The answer is `nodes` (per id: `healthy`, `unhealthy` or `unknown` with
@@ -1597,13 +2206,41 @@ overlay gives that project's nodes.
1597
2206
 
1598
2207
  `example-three-cloud` is a chant workspace (`dns`, `aws`, `azure`, `gcp`) on
1599
2208
  floci, floci-az and floci-gcp; docs/src/content/docs/using/three-cloud.mdx is
1600
- its page. `behold demo three-cloud` runs `scripts/emulators-up.sh` (the
2209
+ its page. `azure` is a choudoufu estate (`azure/*.tf`, choudoufu#2246), so the
2210
+ demo requires choudoufu, `--local` boots no emulator for it (the setup starts
2211
+ floci-az, with TLS), and the root's `chant.config.json` names it as the
2212
+ terraform lexicon's `azure` root. `aws` is a Pulumi program on plunge
2213
+ (behold#1000: `aws/index.ts`, kind `pulumi`, `Pulumi.yaml` naming the
2214
+ `plunge+file://./.plunge` backend), so the demo requires plunge too
2215
+ (PLUNGE_BIN counts, as CHOUDOUFU_BIN does). `scripts/front-door.ts plan --out <file>`
2216
+ (`npm run change-set`) composes one change set, a part per engine: chant
2217
+ parts for dns and gcp, azure's choudoufu part from `choudoufuPlanSet`, and
2218
+ aws's pulumi part from `plunge preview` (`previewPulumiMember`);
2219
+ e2e/three-cloud-change-set-e2e.sh asserts it. `apply --change-set <file>`
2220
+ plans again and refuses the whole set, exit 3, when any part moved
2221
+ (.front-door/apply-verdict.json names each), and `oob-edit <member>` makes
2222
+ one out-of-band edit per member for the live run;
2223
+ e2e/multi-engine-demo-e2e.sh asserts the composed graph, a colour change per
2224
+ engine and the refusal, with a fake plunge and recorded drift streams. dns
2225
+ reads azure's `azureEndpoint` and aws's `awsEndpoint` through chant
2226
+ (chant#4455): dns/src/records.component.ts has `memberOutputsComponent("azure")`,
2227
+ `memberOutputsComponent("aws")` and a records step whose cfn-deploy inputs
2228
+ are `stackOutput("azure", "azureEndpoint")` and `stackOutput("aws",
2229
+ "awsEndpoint")`, and dns lists `terraform` (with `terraform.roots.azure` at
2230
+ `../azure`, which is the change signal) and `pulumi`. `member-outputs` and
2231
+ the pulumi lexicon are in chant 0.124.54 and newer, and the example depends on 0.124.58, and
2232
+ the workspace pins both lexicons by package at that version
2233
+ (`CHANT_RELEASE`, src/chant-release.ts); behold's own code does not import
2234
+ them, so there is no floor. scripts/front-door.ts loads the pulumi lexicon only for
2235
+ the aws plan, so `npm ci` in the example runs every other subcommand. The e2e's second half runs
2236
+ `chant components pr-plan --member dns` over a change to azure/ and asserts
2237
+ dns's records step names azure under its unresolved inputs. `behold demo three-cloud` runs `scripts/emulators-up.sh` (the
1601
2238
  emulators under chant's own container names, with the Docker socket, floci-az
1602
2239
  running Container Apps unmocked), then serves with `--local --env local`.
1603
2240
  `--local` on a workspace boots every chant member's emulators
1604
2241
  (`emulatorDirs`/`emulatorsUp` in src/emulator.ts), not the first member's, and
1605
2242
  tears down the same set. The `front-door` Op (`dns/ops/front-door.op.ts`)
1606
- runs `scripts/front-door.ts`: apply all four, deactivate the Azure revision,
2243
+ runs `scripts/front-door.ts`: apply all four (aws with `plunge up`, then `plunge stack export` into aws/stack-export.json, the export chant draws the member from), deactivate the Azure revision,
1607
2244
  wait for `azureCheck` to read unhealthy, then `behold export --open-env local
1608
2245
  --open-zoom composites --note …`. `--note` (`settleNote` in src/export.ts) is
1609
2246
  one line under 200 characters, written to the manifest as `note` and drawn at
@@ -1626,16 +2263,21 @@ behold made itself (both below).
1626
2263
  The commands behold starts run with behold's own environment, so Deploy (`POST
1627
2264
  /api/apply`, chant's local executor) applies with the credentials of whoever
1628
2265
  started it. On a terragucci repo (a `terragucci.yml` in the served directory or
1629
- above it, up to the git root) behold starts nothing: every POST that deploys,
1630
- approves or starts a run answers `409` with `code: "terragucci"` and names the
1631
- pipeline (`src/terragucci-repo.ts`, #489), `/api/project` carries `terragucci`
2266
+ above it, up to the git root) behold deploys, approves and applies nothing,
2267
+ and the only things it starts are terragucci's own request, rollout and
2268
+ action workflows (below):
2269
+ every other POST that deploys, approves or starts a run answers `409` with
2270
+ `code: "terragucci"` and names the pipeline (`src/terragucci-repo.ts`, #489), `/api/project` carries `terragucci`
1632
2271
  so the page offers no write, and auto-sync declines. The boundary is an
1633
2272
  allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
1634
2273
  any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
1635
2274
  method and route, and that list holds only the exceptions below (the layout
1636
2275
  cache, project open and reveal, demo open, refresh, and the four carve
1637
2276
  steps), plus `POST /api/view`, which moves the open tabs and writes nothing
1638
- (#914). A new write route is refused on a terragucci repo until it is added
2277
+ (#914), `POST /api/templates/request`, which dispatches terragucci's
2278
+ request workflow (behold#1035), `POST /api/templates/upgrade`, which
2279
+ dispatches its rollout workflow (behold#1036), and `POST
2280
+ /api/templates/action`, which dispatches its action workflow (behold#1037). A new write route is refused on a terragucci repo until it is added
1639
2281
  there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
1640
2282
  app (`app.routes`, built plain, with a carve report and with `--terragucci`)
1641
2283
  and asserts each one is allowlisted or answers 409, and that every allowlist
@@ -1679,6 +2321,76 @@ These are also the only writes a guarded product repo answers: terragucci
1679
2321
  (`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
1680
2322
  listed in `TERRAGUCCI_ALLOWED_WRITES`.
1681
2323
 
2324
+ `POST /api/templates/request` (behold#1035, `src/templates.ts`),
2325
+ `POST /api/templates/upgrade` (behold#1036) and `POST /api/templates/action`
2326
+ (behold#1037) are the three starts on a terragucci repo, and they write
2327
+ nothing anywhere. The request is described first. It is on the
2328
+ allowlist, and because the list also guards SQL Yodeler repos the handler
2329
+ refuses on its own (`409`, the product's refusal or `code: "no-templates"`)
2330
+ unless the served repo is terragucci and its terragucci.yml sets
2331
+ `templates`. It checks the request against what the repo's own
2332
+ `terragucci templates list --json` printed (`GET /api/templates` answers that
2333
+ output byte for byte) and against chant's template-request/v1 (`@intentius/chant/template-request`), then dispatches
2334
+ the committed `terragucci-request.yml` with the inputs `template`, `version`,
2335
+ `name` and `inputs`, plus `claimed_by` (the person behold says filled the
2336
+ form) only when that workflow declares the input. On GitHub the dispatch and
2337
+ every read go through the operator's `gh` (`dispatchWorkflow`,
2338
+ `pullRequestOn` in src/gh-run.ts); on Forgejo through the HTTP API with the
2339
+ operator's `FORGEJO_TOKEN` (src/forgejo-api.ts), sent only to the origin's
2340
+ host and never stored or shown. GitLab has no request workflow and answers
2341
+ `422 request-forge` with the `npx terragucci request` line to run. behold
2342
+ never runs `terragucci request`, never shells out to plan or apply, and holds
2343
+ no apply credential: the run in CI opens the pull request with the repo's own
2344
+ token, its actor is the requester the forge vouches for, and the pull request
2345
+ is planned and reviewed like any other (ruling A of INTENTIUS/chant#4642). The
2346
+ follow runs in the runner's single slot, and `GET /api/templates/requests/:id`
2347
+ answers the run's end and the pull request's number and URL. `--public`
2348
+ refuses both reads (`403`) and the post (`405`).
2349
+
2350
+ With `app` in the body (behold#1036) the request asks for an add-on in that
2351
+ app's root. The template must be an add-on template (else `422 wrong-kind`),
2352
+ the app must be one the repo's own `terragucci templates apps --json` lists
2353
+ (`GET /api/templates/apps` answers that output byte for byte), else `422
2354
+ not-an-app`, and the add-on's name must not be a module the app's root already
2355
+ has (`422 addon-exists`). The dispatch adds the `app` input, and the branch is
2356
+ `request/<template>/<app>/<addon>`.
2357
+
2358
+ `POST /api/templates/upgrade` takes `{app, version?}`. It reads the apps again
2359
+ and takes the module and version from terragucci, never from the caller: the
2360
+ app's `template` and its `upgrade` (`422 not-an-app`, `422 no-upgrade` when
2361
+ `upgrade` is null, `409 stale-upgrade` when `version` is not it). It refuses
2362
+ on its own like the request, then dispatches the committed
2363
+ `terragucci-rollout.yml` with `module` and `version` only (`409
2364
+ no-rollout-workflow` when it is not committed, `409 terragucci-too-old` when
2365
+ it takes neither input), through the same `gh` and Forgejo paths and the same
2366
+ runner slot. A person starts it; terragucci's existing rollout opens one pull
2367
+ request per wave, and each wave is planned, reviewed and applied by the
2368
+ pipeline (ruling D). GitLab's rollout job takes no dispatch inputs, so GitLab
2369
+ answers `422 request-forge` with the `npx terragucci rollout` line. `--public`
2370
+ refuses the apps read (`403`) and the post (`405`).
2371
+
2372
+ `POST /api/templates/action` takes `{root, address}`. It reads the apps again,
2373
+ and the address must be one terragucci lists in that root's `actions` (`422
2374
+ not-an-app` for a root no app has, `422 unknown-action` otherwise); nothing
2375
+ starts before that. A root whose engine has no action invocation (terragucci.yml's
2376
+ `binary`, the repo's `.opentofu-version`, or `.tofu` files in the root, as
2377
+ terragucci detects it) answers `422 action-engine` naming OpenTofu or
2378
+ choudoufu (ruling E), and `/api/project` carries `terragucciActionRefusal` so
2379
+ the buttons say so. It refuses on its own like the request, then dispatches the
2380
+ committed `terragucci-action.yml` with `root` and `address` only (`409
2381
+ no-action-workflow` when it is not committed, which terragucci does only for
2382
+ Terraform roots; `409 terragucci-too-old` when it takes neither input), through
2383
+ the same `gh` and Forgejo paths and the same runner slot. The run asks chant's
2384
+ gated request (op `tf-action`, gate `<root>:<address>`) and waits for a person
2385
+ other than the requester to run `terragucci approve action <root> --plan
2386
+ <digest>`; behold approves nothing and never runs the action. The lifecycle
2387
+ lane reads `_gates/tf-action.jsonl` and `_gates/tf-action/applied.jsonl` into
2388
+ `actions` (`src/terragucci-lifecycle.ts`), apart from the waves: a waiting
2389
+ gate carries that approve line, the requester's own approval is listed as one
2390
+ that does not count, and an applied one carries the run's `ok` or `failed`.
2391
+ GitLab answers `422 request-forge` with the `npx terragucci action` line.
2392
+ `--public` refuses the post (`405`).
2393
+
1682
2394
  `POST /api/layout` (#228) writes **one** file, and not in the served project:
1683
2395
  the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
1684
2396
  with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
@@ -1785,12 +2497,39 @@ changing it, the working rules that used to live in a handoff note and now
1785
2497
  live here, with the enforceable ones enforced.
1786
2498
 
1787
2499
  - **Branches and merges.** Work on a branch off `main` (an isolated worktree
1788
- when more than one agent is active). `main` is protected by a ruleset: every
1789
- change arrives as a PR, and the `check` job in `ci.yml` must be green before
1790
- it merges. A check that has merely settled is not a pass — read the lines.
2500
+ when more than one agent is active). `main` is protected by ruleset
2501
+ 22042490, which requires a PR and a green `check` job in `ci.yml` of
2502
+ everyone but the repository admin role. That role bypasses it
2503
+ (`bypass_mode: always`, behold#1006, as chant and choudoufu have), so an
2504
+ admin may push a tested integration branch's merge to `main` directly;
2505
+ every other change arrives as a PR and merges once the check is green. A
2506
+ check that has merely settled is not a pass — read the lines. The
2507
+ ruleset's name still reads "every change is a PR with a green ci check";
2508
+ renaming it is a settings change for the maintainer (behold#1018).
1791
2509
  No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
1792
2510
  next onto what landed.
1793
- - **The local gate** is `just check` (tsc, tests, build). Every vitest run
2511
+ - **Emulator e2e scripts** take their container names, ports and images
2512
+ from the environment and run under `e2e/lib/safe-env.sh`, which keeps real
2513
+ cloud credentials out of reach and fails on a real-cloud rejection in the
2514
+ log; e2e/README.md has the variables (behold#1032).
2515
+ - The painter bundles for a browser (#1069). `src/render.ts` and what it
2516
+ imports take no Node built-in: `npm run check:browser-bundle` bundles it
2517
+ with esbuild for `--platform=browser`, fails naming the import chain to any
2518
+ `node:` import, and prints the minified and gzipped sizes; CI runs it. A
2519
+ constant or card rule the painter needs from a module that reads disk or
2520
+ spawns lives in a module of its own (src/card-marks.ts,
2521
+ src/choudoufu-card.ts, src/carve-state.ts) and is re-exported from the old
2522
+ one. The icons come from src/icons.generated.ts: after a vendor script
2523
+ changes `web/icons`, run `npm run generate:icons` (`npm run check:icons`
2524
+ and src/generate-icons.test.ts fail until you do).
2525
+ - **The local gate** is `just check` (tsc, tests, build). The tests never read
2526
+ the caller's environment (behold#1013): src/test-env.ts, vitest's setup
2527
+ file, removes CHOUDOUFU_BIN, PLUNGE_BIN and the other variables behold
2528
+ reads to pick a binary or a service, and vitest.config.ts points
2529
+ PULUMI_BACKEND_URL at an empty `file://` directory made for the run, with
2530
+ PULUMI_SKIP_UPDATE_CHECK=true, so no pulumi or plunge a test starts sees
2531
+ the machine's login. A test that needs one of them sets it and puts back
2532
+ what was there. Every vitest run
1794
2533
  also writes `.vitest-last.json` (the json reporter, PR #351), and `just
1795
2534
  test` keeps the reporter's full output in `vitest.log`, both gitignored —
1796
2535
  because #334's one-shot first-run failures kept losing the failing file's
@@ -2233,6 +2972,17 @@ same facts per card as JSON.
2233
2972
  stays pending with no physical id, and chant carries its plan attributes
2234
2973
  onto the declared node anyway (chant#4372). Its rows read `plan: create`,
2235
2974
  `unknown: N until apply`, `read: plan`.
2975
+ - **A `count`/`for_each` block draws a card per instance** (#996,
2976
+ src/instance-cards.ts). The id is the block's node id and the key as
2977
+ Terraform prints it, `app/aws_s3_bucket.logs[0]`, `<member>/` in front on an
2978
+ estate, the same rule chant's graph uses for its instance nodes
2979
+ (INTENTIUS/chant#4454). Until chant emits them, behold derives them from the
2980
+ plan's per-instance rows (`planActions` by instance address, each change and
2981
+ drift row's `instance`), so each card has its own action, changes and drift.
2982
+ An instance node chant draws is kept and only painted. The block card stays
2983
+ as the rollup: chant's aggregate `_plan`, `attrs._instances` and an
2984
+ `instances` row. A key under a module instance (`module.a[0]...[1]`) stays
2985
+ in the rollup. A choudoufu member's roster is per instance already.
2236
2986
  - **choudoufu members read ownership and the plan through chant together**
2237
2987
  (src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
2238
2988
  re-check's `live-plan` is chant's, handed back to behold. See the choudoufu
@@ -2378,3 +3128,28 @@ strip either way: the DNS fan is 19564 x 400 upright and 900 x 10046 on its
2378
3128
  side. A box under 4:1 is left exactly as it laid out. Measured: `terralith-4`
2379
3129
  7660 x 5162 with 266 edges, waterpark 3536 x 3138 at detail 2 and 7142 x 6974
2380
3130
  at detail 3 (from 4.2:1 and 15.1:1, the case #393's wrap did not answer).
3131
+
3132
+ ## What live objects name outside the cluster (behold#1082)
3133
+
3134
+ `outsideRefs(objects, { graph })` in web/outside-refs.js is a pure function
3135
+ with no imports, so a browser bundle takes it whole. It turns Kubernetes
3136
+ objects as the API serves them into `{ cards, edges, notes }`: a cloud identity
3137
+ card for a ServiceAccount's `iam.gke.io/gcp-service-account`,
3138
+ `eks.amazonaws.com/role-arn` or `azure.workload.identity/client-id`
3139
+ annotation, a store card and a provider card (GCP Secret Manager, AWS Secrets
3140
+ Manager or Parameter Store, Vault, with the `remoteRef.key` values) for an
3141
+ ExternalSecret, and a source card for an Argo CD Application's `spec.source`
3142
+ and `spec.sources[]` or a Flux Kustomization's `sourceRef` and `path`. It reads
3143
+ the field paths chant#5098 and chant#5099 read, so a placeholder and a derived
3144
+ edge agree. A card's id is made from what it names, so two objects naming one
3145
+ thing share it, and a target the `graph` already holds gets no card and no
3146
+ edge. A field it cannot read goes in `notes`, never dropped.
3147
+
3148
+ Chant's live Kubernetes read masks every key matching /secret/i. An
3149
+ ExternalSecret's whole `spec.secretStoreRef` comes back as `<masked>`, so on a
3150
+ live read that ExternalSecret has no store card and its keys stay off the
3151
+ provider card; its note carries `waitsOn: "INTENTIUS/chant#5116"`. The
3152
+ ServiceAccount, provider and source cards work on a live read today.
3153
+ src/outside-refs-live.test.ts reads a scratch k3d cluster through chant's
3154
+ lister to show it (BEHOLD_K3D_TESTS=1; the cluster is `behold-outside-refs-<pid>`,
3155
+ created and deleted by the test). Fixtures are in web/outside-refs.test.js.