@intentius/behold 0.30.1 → 0.31.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 (129) hide show
  1. package/AGENTS.md +475 -16
  2. package/README.md +25 -19
  3. package/demos.json +14 -9
  4. package/dist/cli.js +54900 -26771
  5. package/example-carve/README.md +19 -23
  6. package/example-carve/app/package.json +1 -1
  7. package/example-carve/app/src/carved.ts +3 -3
  8. package/example-carve/carve-report.json +1 -1
  9. package/example-carve/{legacy-tf → tf-root}/terraform.tfstate +1 -1
  10. package/example-choudoufu-estate/README.md +7 -0
  11. package/example-choudoufu-estate/chant.workspace.json +1 -1
  12. package/example-choudoufu-estate/scripts/choudoufu-down.sh +2 -1
  13. package/example-choudoufu-estate/scripts/choudoufu-up.sh +10 -3
  14. package/example-terraform-estate/README.md +32 -5
  15. package/example-terraform-estate/chant.workspace.json +1 -1
  16. package/example-terraform-estate/recorded/adoption/platform.json +72 -0
  17. package/example-terraform-estate/recorded/adoption/prod.json +224 -0
  18. package/example-terralith/README.md +1 -1
  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 +13 -6
  36. package/web/adopt-pulumi.js +114 -0
  37. package/web/adopt-pulumi.test.js +28 -0
  38. package/web/adopt.js +203 -0
  39. package/web/adopt.test.js +27 -0
  40. package/web/app.js +614 -19
  41. package/web/carve-steps.js +1 -1
  42. package/web/carve-steps.test.js +2 -2
  43. package/web/change-set-overlay.js +12 -5
  44. package/web/change-set-overlay.test.js +22 -0
  45. package/web/drift-stream.js +241 -0
  46. package/web/drift-stream.test.js +146 -0
  47. package/web/edge-weight.d.ts +1 -1
  48. package/web/edge-weight.js +5 -1
  49. package/web/edge-weight.test.js +19 -0
  50. package/web/embed.js +2 -2
  51. package/web/event-help-modal.js +18 -12
  52. package/web/event-help-modal.test.js +28 -1
  53. package/web/graph-query.js +180 -0
  54. package/web/graph-query.test.js +49 -0
  55. package/web/graph.html +107 -0
  56. package/web/index-diff.js +109 -0
  57. package/web/index-diff.test.js +39 -0
  58. package/web/index.html +55 -0
  59. package/web/kiosk-ask-layout.js +85 -0
  60. package/web/kiosk-ask-layout.test.js +83 -0
  61. package/web/kiosk-ask-tips.js +477 -0
  62. package/web/kiosk-ask-tips.test.js +372 -0
  63. package/web/kiosk-ask.js +774 -0
  64. package/web/kiosk-ask.test.js +593 -0
  65. package/web/kiosk-banner.js +108 -0
  66. package/web/kiosk-banner.test.js +72 -0
  67. package/web/kiosk-center-cards.test.js +110 -0
  68. package/web/kiosk-estate-scene.js +267 -0
  69. package/web/kiosk-estate-scene.test.js +21 -0
  70. package/web/kiosk-event-help.js +4 -1
  71. package/web/kiosk-graph-pane.js +63 -0
  72. package/web/kiosk-graph-pane.test.js +105 -0
  73. package/web/kiosk-light-frame.js +197 -0
  74. package/web/kiosk-light.js +547 -0
  75. package/web/kiosk-light.test.js +297 -0
  76. package/web/kiosk-member-kind.test.js +140 -0
  77. package/web/kiosk-metrics.js +7 -4
  78. package/web/kiosk-modal-sticky.test.js +2 -1
  79. package/web/kiosk-popover.js +4 -1
  80. package/web/kiosk-refit.test.js +81 -0
  81. package/web/kiosk-reset.js +49 -0
  82. package/web/kiosk-reset.test.js +11 -0
  83. package/web/kiosk-shot.js +40 -2
  84. package/web/kiosk-shot.test.js +23 -1
  85. package/web/kiosk-side.js +296 -0
  86. package/web/kiosk-side.test.js +249 -0
  87. package/web/kiosk-vendor.js +85 -7
  88. package/web/kiosk-vendor.test.js +9 -9
  89. package/web/kiosk-watch.js +20 -4
  90. package/web/kiosk-watch.test.js +15 -1
  91. package/web/kiosk.html +153 -1
  92. package/web/kiosk.js +252 -27
  93. package/web/kiosk.test.js +25 -1
  94. package/web/member-kind.js +31 -0
  95. package/web/small-stage.test.js +4 -0
  96. package/web/template-apps.js +245 -0
  97. package/web/template-apps.test.js +252 -0
  98. package/web/templates.js +285 -0
  99. package/web/templates.test.js +155 -0
  100. package/web/terragucci-change.js +30 -13
  101. package/web/terragucci-lifecycle.js +112 -62
  102. package/web/terragucci-lifecycle.test.js +29 -1
  103. package/web/terragucci-timeline.js +39 -2
  104. package/web/terragucci-timeline.test.js +42 -1
  105. package/web/tool-mark.js +4 -4
  106. package/web/tool-mark.test.js +1 -1
  107. package/web/vendors/atmos.svg +1 -0
  108. package/web/vendors/chant.svg +1 -0
  109. package/web/vendors/choudoufu.svg +1 -0
  110. package/web/vendors/terragrunt.svg +9 -0
  111. package/web/vendors/terragucci.svg +1 -0
  112. package/example-three-cloud/aws/chant.config.ts +0 -8
  113. package/example-three-cloud/aws/site.component.ts +0 -13
  114. package/example-three-cloud/aws/src/site.ts +0 -27
  115. package/example-three-cloud/azure/chant.config.ts +0 -1
  116. package/example-three-cloud/azure/src/site.component.ts +0 -13
  117. package/example-three-cloud/azure/src/site.ts +0 -18
  118. package/web/vendors/choudoufu-128.png +0 -0
  119. package/web/vendors/choudoufu-64.png +0 -0
  120. /package/example-carve/{legacy-tf → tf-root}/cdn.tf +0 -0
  121. /package/example-carve/{legacy-tf → tf-root}/compute.tf +0 -0
  122. /package/example-carve/{legacy-tf → tf-root}/floci-override.tf.disabled +0 -0
  123. /package/example-carve/{legacy-tf → tf-root}/modules/cdn/main.tf +0 -0
  124. /package/example-carve/{legacy-tf → tf-root}/naming.tf +0 -0
  125. /package/example-carve/{legacy-tf → tf-root}/network.tf +0 -0
  126. /package/example-carve/{legacy-tf → tf-root}/observability.tf +0 -0
  127. /package/example-carve/{legacy-tf → tf-root}/outputs.tf +0 -0
  128. /package/example-carve/{legacy-tf → tf-root}/storage.tf +0 -0
  129. /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
@@ -80,6 +88,37 @@ spawning the read. A new read adds its constant and entry in the issue that
80
88
  adds the read, once the chant release is known, and reads through the read
81
89
  contract (`src/workspace-reader.ts`), never chant's library.
82
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
+
83
122
  ## A pipeline's numbers, from Prometheus (behold#571)
84
123
 
85
124
  `behold serve --prometheus <url>` (or `BEHOLD_PROMETHEUS_URL`) adds `GET
@@ -127,6 +166,78 @@ makes, `declaredReportUrl` in src/workspace.ts, floor
127
166
  declaration included; the flag overrides it, and each answer's `urlFrom` says
128
167
  `flag` or `declaration`. With neither, nothing changes.
129
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
+
130
241
  ## A plan job run locally (behold#685)
131
242
 
132
243
  `POST /api/chant/ci/local` `{job: "plan", commit, pr, env?, base?, member?,
@@ -154,6 +265,64 @@ that holds for it: `ci run` gives the job a clean environment that keeps HOME,
154
265
  so `serve --local`'s emulator env does not reach the job and the operator's
155
266
  own credentials would. Cached-step marks wait on chant#4015.
156
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
+
157
326
  ## A terragucci estate, from its reports (#490)
158
327
 
159
328
  `behold serve <repo> --terragucci <dir|s3://bucket/prefix|https://…>`
@@ -369,6 +538,34 @@ checkout declares no Terraform root (`controlRepo` in
369
538
  structural check otherwise. The page (`web/terragucci-estate.js`) draws it
370
539
  in a layer over the graph area.
371
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
+
372
569
  ## Releases per environment, from the release ledger (#525)
373
570
 
374
571
  `GET /api/lifecycle/releases[?fresh=1]` (src/lifecycle-releases.ts) reads
@@ -629,6 +826,101 @@ pending member becomes a real one only when its own read completes, and the
629
826
  live pass a progressive request starts is the same one per member under the
630
827
  same budget: a progressive load costs the estate no extra spawn.
631
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
+
632
924
  ### What a read cost (#420, #421)
633
925
 
634
926
  `GET /api/doctor` serves `diagnose()`, the same report `behold doctor` prints,
@@ -860,7 +1152,7 @@ would go.
860
1152
 
861
1153
  ### The walkthrough (`behold demo carve`, #254)
862
1154
 
863
- `behold demo carve` copies a bundled half-migrated estate (a chant project
1155
+ `behold demo carve` copies a bundled mixed estate (a chant project
864
1156
  beside a Terraform one), runs the advisor over the copy, and serves the same
865
1157
  carve view plus a six-step stepper on the panel's Carve tab: advise → pick →
866
1158
  emit → bridge → handoff → done.
@@ -990,7 +1282,9 @@ folder's scratch project. Each capability has its `name`, `meaning`,
990
1282
  it leaves `notEvaluated`, its `rule`, and per lexicon whether it is
991
1283
  supplied. A chant below 0.124.46 answers 422 `code: "chant-too-old"`
992
1284
  (`CAPABILITIES_CHANT_FLOOR`). behold mcp's `capabilities` tool returns the
993
- same text.
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).
994
1288
 
995
1289
  ```
996
1290
  GET /api/capabilities
@@ -999,6 +1293,33 @@ GET /api/capabilities
999
1293
  "helpers":[...]}
1000
1294
  ```
1001
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
+
1002
1323
  ## Moving the person's open tab (#914)
1003
1324
 
1004
1325
  `POST /api/view` changes what every open tab of this serve draws. It is a
@@ -1416,7 +1737,12 @@ or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
1416
1737
  bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
1417
1738
  failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
1418
1739
  `planned` (a release gate's release and environment, chant#4045). An entry
1419
- with no node is kept and listed in the Change set tab, never dropped. The page
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
1420
1746
  (web/change-set-overlay.js) outlines each card in the drift legend's tokens
1421
1747
  (managed for create, foreign for update or replace, degraded for delete or
1422
1748
  forget) with a tag above it, never a fill; it is opened from the "change set"
@@ -1539,7 +1865,9 @@ document, so it is checked against chant's schema, vendored unchanged in
1539
1865
  src/health-schema/ (chant PR #4193 at d727944c4) and validated with ajv, with
1540
1866
  a hole's `reason` loosened to any string; a document the schema refuses is
1541
1867
  refused whole. A project with no lexicon that reads health is `none`, not a
1542
- failure. A member below the floor is refused before anything is spawned; when
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
1543
1871
  every member is, the answer carries the refusal and `degraded`.
1544
1872
 
1545
1873
  The answer is `nodes` (per id: `healthy`, `unhealthy` or `unknown` with
@@ -1567,13 +1895,41 @@ overlay gives that project's nodes.
1567
1895
 
1568
1896
  `example-three-cloud` is a chant workspace (`dns`, `aws`, `azure`, `gcp`) on
1569
1897
  floci, floci-az and floci-gcp; docs/src/content/docs/using/three-cloud.mdx is
1570
- its page. `behold demo three-cloud` runs `scripts/emulators-up.sh` (the
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
1571
1927
  emulators under chant's own container names, with the Docker socket, floci-az
1572
1928
  running Container Apps unmocked), then serves with `--local --env local`.
1573
1929
  `--local` on a workspace boots every chant member's emulators
1574
1930
  (`emulatorDirs`/`emulatorsUp` in src/emulator.ts), not the first member's, and
1575
1931
  tears down the same set. The `front-door` Op (`dns/ops/front-door.op.ts`)
1576
- runs `scripts/front-door.ts`: apply all four, deactivate the Azure revision,
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,
1577
1933
  wait for `azureCheck` to read unhealthy, then `behold export --open-env local
1578
1934
  --open-zoom composites --note …`. `--note` (`settleNote` in src/export.ts) is
1579
1935
  one line under 200 characters, written to the manifest as `note` and drawn at
@@ -1596,16 +1952,21 @@ behold made itself (both below).
1596
1952
  The commands behold starts run with behold's own environment, so Deploy (`POST
1597
1953
  /api/apply`, chant's local executor) applies with the credentials of whoever
1598
1954
  started it. On a terragucci repo (a `terragucci.yml` in the served directory or
1599
- above it, up to the git root) behold starts nothing: every POST that deploys,
1600
- approves or starts a run answers `409` with `code: "terragucci"` and names the
1601
- pipeline (`src/terragucci-repo.ts`, #489), `/api/project` carries `terragucci`
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`
1602
1960
  so the page offers no write, and auto-sync declines. The boundary is an
1603
1961
  allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
1604
1962
  any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
1605
1963
  method and route, and that list holds only the exceptions below (the layout
1606
1964
  cache, project open and reveal, demo open, refresh, and the four carve
1607
1965
  steps), plus `POST /api/view`, which moves the open tabs and writes nothing
1608
- (#914). A new write route is refused on a terragucci repo until it is added
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
1609
1970
  there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
1610
1971
  app (`app.routes`, built plain, with a carve report and with `--terragucci`)
1611
1972
  and asserts each one is allowlisted or answers 409, and that every allowlist
@@ -1649,6 +2010,76 @@ These are also the only writes a guarded product repo answers: terragucci
1649
2010
  (`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
1650
2011
  listed in `TERRAGUCCI_ALLOWED_WRITES`.
1651
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
+
1652
2083
  `POST /api/layout` (#228) writes **one** file, and not in the served project:
1653
2084
  the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
1654
2085
  with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
@@ -1755,12 +2186,29 @@ changing it, the working rules that used to live in a handoff note and now
1755
2186
  live here, with the enforceable ones enforced.
1756
2187
 
1757
2188
  - **Branches and merges.** Work on a branch off `main` (an isolated worktree
1758
- when more than one agent is active). `main` is protected by a ruleset: every
1759
- change arrives as a PR, and the `check` job in `ci.yml` must be green before
1760
- it merges. A check that has merely settled is not a pass — read the lines.
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).
1761
2198
  No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
1762
2199
  next onto what landed.
1763
- - **The local gate** is `just check` (tsc, tests, build). Every vitest run
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
1764
2212
  also writes `.vitest-last.json` (the json reporter, PR #351), and `just
1765
2213
  test` keeps the reporter's full output in `vitest.log`, both gitignored —
1766
2214
  because #334's one-shot first-run failures kept losing the failing file's
@@ -2203,6 +2651,17 @@ same facts per card as JSON.
2203
2651
  stays pending with no physical id, and chant carries its plan attributes
2204
2652
  onto the declared node anyway (chant#4372). Its rows read `plan: create`,
2205
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.
2206
2665
  - **choudoufu members read ownership and the plan through chant together**
2207
2666
  (src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
2208
2667
  re-check's `live-plan` is chant's, handed back to behold. See the choudoufu