@intentius/behold 0.30.2 → 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 (92) hide show
  1. package/AGENTS.md +444 -15
  2. package/README.md +14 -13
  3. package/demos.json +14 -9
  4. package/dist/cli.js +53928 -26475
  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-three-cloud/README.md +111 -18
  19. package/example-three-cloud/aws/Pulumi.yaml +15 -0
  20. package/example-three-cloud/aws/index.ts +174 -0
  21. package/example-three-cloud/aws/package-lock.json +2725 -0
  22. package/example-three-cloud/aws/package.json +14 -0
  23. package/example-three-cloud/aws/tsconfig.json +17 -0
  24. package/example-three-cloud/azure/main.tf +48 -0
  25. package/example-three-cloud/azure/site.tf +104 -0
  26. package/example-three-cloud/chant.config.json +9 -0
  27. package/example-three-cloud/chant.workspace.json +30 -4
  28. package/example-three-cloud/dns/chant.config.ts +26 -1
  29. package/example-three-cloud/dns/src/records.component.ts +32 -6
  30. package/example-three-cloud/package-lock.json +48 -27
  31. package/example-three-cloud/package.json +8 -6
  32. package/example-three-cloud/scripts/emulators-up.sh +28 -1
  33. package/example-three-cloud/scripts/front-door.ts +679 -86
  34. package/package.json +13 -6
  35. package/web/adopt-pulumi.js +114 -0
  36. package/web/adopt-pulumi.test.js +28 -0
  37. package/web/adopt.js +203 -0
  38. package/web/adopt.test.js +27 -0
  39. package/web/app.js +358 -10
  40. package/web/carve-steps.js +1 -1
  41. package/web/carve-steps.test.js +2 -2
  42. package/web/change-set-overlay.js +12 -5
  43. package/web/change-set-overlay.test.js +22 -0
  44. package/web/drift-stream.js +241 -0
  45. package/web/drift-stream.test.js +146 -0
  46. package/web/edge-weight.d.ts +1 -1
  47. package/web/edge-weight.js +5 -1
  48. package/web/edge-weight.test.js +19 -0
  49. package/web/graph-query.js +180 -0
  50. package/web/graph-query.test.js +49 -0
  51. package/web/graph.html +107 -0
  52. package/web/index-diff.js +109 -0
  53. package/web/index-diff.test.js +39 -0
  54. package/web/index.html +37 -0
  55. package/web/kiosk-ask-tips.js +15 -5
  56. package/web/kiosk-ask-tips.test.js +14 -1
  57. package/web/kiosk-estate-scene.js +72 -8
  58. package/web/kiosk-light-frame.js +1 -0
  59. package/web/kiosk-light.js +41 -3
  60. package/web/kiosk-member-kind.test.js +140 -0
  61. package/web/kiosk-popover.js +4 -1
  62. package/web/kiosk-side.js +296 -0
  63. package/web/kiosk-side.test.js +249 -0
  64. package/web/kiosk-watch.js +12 -0
  65. package/web/kiosk-watch.test.js +15 -1
  66. package/web/kiosk.html +47 -1
  67. package/web/kiosk.js +106 -7
  68. package/web/member-kind.js +31 -0
  69. package/web/template-apps.js +245 -0
  70. package/web/template-apps.test.js +252 -0
  71. package/web/templates.js +285 -0
  72. package/web/templates.test.js +155 -0
  73. package/web/terragucci-lifecycle.js +112 -62
  74. package/web/terragucci-lifecycle.test.js +29 -1
  75. package/web/terragucci-timeline.js +39 -2
  76. package/web/terragucci-timeline.test.js +42 -1
  77. package/example-three-cloud/aws/chant.config.ts +0 -8
  78. package/example-three-cloud/aws/site.component.ts +0 -13
  79. package/example-three-cloud/aws/src/site.ts +0 -27
  80. package/example-three-cloud/azure/chant.config.ts +0 -1
  81. package/example-three-cloud/azure/src/site.component.ts +0 -13
  82. package/example-three-cloud/azure/src/site.ts +0 -18
  83. /package/example-carve/{legacy-tf → tf-root}/cdn.tf +0 -0
  84. /package/example-carve/{legacy-tf → tf-root}/compute.tf +0 -0
  85. /package/example-carve/{legacy-tf → tf-root}/floci-override.tf.disabled +0 -0
  86. /package/example-carve/{legacy-tf → tf-root}/modules/cdn/main.tf +0 -0
  87. /package/example-carve/{legacy-tf → tf-root}/naming.tf +0 -0
  88. /package/example-carve/{legacy-tf → tf-root}/network.tf +0 -0
  89. /package/example-carve/{legacy-tf → tf-root}/observability.tf +0 -0
  90. /package/example-carve/{legacy-tf → tf-root}/outputs.tf +0 -0
  91. /package/example-carve/{legacy-tf → tf-root}/storage.tf +0 -0
  92. /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://…>`
@@ -657,6 +826,101 @@ pending member becomes a real one only when its own read completes, and the
657
826
  live pass a progressive request starts is the same one per member under the
658
827
  same budget: a progressive load costs the estate no extra spawn.
659
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
+
660
924
  ### What a read cost (#420, #421)
661
925
 
662
926
  `GET /api/doctor` serves `diagnose()`, the same report `behold doctor` prints,
@@ -888,7 +1152,7 @@ would go.
888
1152
 
889
1153
  ### The walkthrough (`behold demo carve`, #254)
890
1154
 
891
- `behold demo carve` copies a bundled half-migrated estate (a chant project
1155
+ `behold demo carve` copies a bundled mixed estate (a chant project
892
1156
  beside a Terraform one), runs the advisor over the copy, and serves the same
893
1157
  carve view plus a six-step stepper on the panel's Carve tab: advise → pick →
894
1158
  emit → bridge → handoff → done.
@@ -1029,6 +1293,33 @@ GET /api/capabilities
1029
1293
  "helpers":[...]}
1030
1294
  ```
1031
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
+
1032
1323
  ## Moving the person's open tab (#914)
1033
1324
 
1034
1325
  `POST /api/view` changes what every open tab of this serve draws. It is a
@@ -1446,7 +1737,12 @@ or null where chant mapped none), `nodes` (`<member>/<id>` to the strongest
1446
1737
  bucket and the actions on it), `counts`, `unchanged`, `gaps` (members that
1447
1738
  failed to plan or have holes), `gate` (commit, run, `releaseDigest`) and
1448
1739
  `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
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
1450
1746
  (web/change-set-overlay.js) outlines each card in the drift legend's tokens
1451
1747
  (managed for create, foreign for update or replace, degraded for delete or
1452
1748
  forget) with a tag above it, never a fill; it is opened from the "change set"
@@ -1569,7 +1865,9 @@ document, so it is checked against chant's schema, vendored unchanged in
1569
1865
  src/health-schema/ (chant PR #4193 at d727944c4) and validated with ajv, with
1570
1866
  a hole's `reason` loosened to any string; a document the schema refuses is
1571
1867
  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
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
1573
1871
  every member is, the answer carries the refusal and `degraded`.
1574
1872
 
1575
1873
  The answer is `nodes` (per id: `healthy`, `unhealthy` or `unknown` with
@@ -1597,13 +1895,41 @@ overlay gives that project's nodes.
1597
1895
 
1598
1896
  `example-three-cloud` is a chant workspace (`dns`, `aws`, `azure`, `gcp`) on
1599
1897
  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
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
1601
1927
  emulators under chant's own container names, with the Docker socket, floci-az
1602
1928
  running Container Apps unmocked), then serves with `--local --env local`.
1603
1929
  `--local` on a workspace boots every chant member's emulators
1604
1930
  (`emulatorDirs`/`emulatorsUp` in src/emulator.ts), not the first member's, and
1605
1931
  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,
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,
1607
1933
  wait for `azureCheck` to read unhealthy, then `behold export --open-env local
1608
1934
  --open-zoom composites --note …`. `--note` (`settleNote` in src/export.ts) is
1609
1935
  one line under 200 characters, written to the manifest as `note` and drawn at
@@ -1626,16 +1952,21 @@ behold made itself (both below).
1626
1952
  The commands behold starts run with behold's own environment, so Deploy (`POST
1627
1953
  /api/apply`, chant's local executor) applies with the credentials of whoever
1628
1954
  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`
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`
1632
1960
  so the page offers no write, and auto-sync declines. The boundary is an
1633
1961
  allowlist (#500): every request whose method is not GET, HEAD or OPTIONS, on
1634
1962
  any path, answers that `409` unless `TERRAGUCCI_ALLOWED_WRITES` names its
1635
1963
  method and route, and that list holds only the exceptions below (the layout
1636
1964
  cache, project open and reveal, demo open, refresh, and the four carve
1637
1965
  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
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
1639
1970
  there. `src/terragucci-repo.test.ts` walks every non-GET route of the real
1640
1971
  app (`app.routes`, built plain, with a carve report and with `--terragucci`)
1641
1972
  and asserts each one is allowlisted or answers 409, and that every allowlist
@@ -1679,6 +2010,76 @@ These are also the only writes a guarded product repo answers: terragucci
1679
2010
  (`terragucci.yml` and its siblings) and SQL Yodeler (`yodel.config.ts`), both
1680
2011
  listed in `TERRAGUCCI_ALLOWED_WRITES`.
1681
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
+
1682
2083
  `POST /api/layout` (#228) writes **one** file, and not in the served project:
1683
2084
  the hand layout is a per-user cache (#469), `<user cache>/behold/layouts/<key>.json`
1684
2085
  with `<user cache>` the OS's (`~/Library/Caches`, `%LOCALAPPDATA%`,
@@ -1785,12 +2186,29 @@ changing it, the working rules that used to live in a handoff note and now
1785
2186
  live here, with the enforceable ones enforced.
1786
2187
 
1787
2188
  - **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.
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).
1791
2198
  No `gh pr merge --auto`; merge one PR at a time, in order, and rebase the
1792
2199
  next onto what landed.
1793
- - **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
1794
2212
  also writes `.vitest-last.json` (the json reporter, PR #351), and `just
1795
2213
  test` keeps the reporter's full output in `vitest.log`, both gitignored —
1796
2214
  because #334's one-shot first-run failures kept losing the failing file's
@@ -2233,6 +2651,17 @@ same facts per card as JSON.
2233
2651
  stays pending with no physical id, and chant carries its plan attributes
2234
2652
  onto the declared node anyway (chant#4372). Its rows read `plan: create`,
2235
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.
2236
2665
  - **choudoufu members read ownership and the plan through chant together**
2237
2666
  (src/choudoufu-chant-read.ts, #924): src/choudoufu-plan.ts is gone, and a
2238
2667
  re-check's `live-plan` is chant's, handed back to behold. See the choudoufu
package/README.md CHANGED
@@ -27,9 +27,9 @@ https://intentius.io/behold/using/agents/.
27
27
  Never deploy with the Deploy button, `POST /api/apply` or `POST /api/ci/dispatch`. Gate approvals stay mine as well (`/api/ops/:name/signal/:gate`, `/api/workspace/gates/approve`, `/api/operator/approve/:op/:gate`). Op runs (`/api/ops/:name/run`) and rollbacks (`/api/rollback`) are mine too. Leave `--auto-sync` off, and keep a `behold preview` or `--public` serve read-only.
28
28
  ```
29
29
 
30
- Where Argo CD shows one cluster's tree, behold shows the mixed-substrate estate:
31
- cloud drift on AWS, supply-chain drift on GitHub Actions, artifact presence on
32
- Helm. Each substrate's own kind of truth, in one picture.
30
+ behold shows the mixed-substrate estate: cloud drift on AWS, supply-chain drift
31
+ on GitHub Actions, artifact presence on Helm. An Argo CD cluster draws in the
32
+ same graph, with each substrate's own kind of truth in one picture.
33
33
 
34
34
  ```
35
35
  chant source ──build/lint──▶ graph IR ──behold──▶ live graph + drift + (delegated) actions
@@ -51,12 +51,13 @@ There's a whole catalog, and `behold demo --list` names the rest (`behold demo
51
51
  k8s` stands the same loop up on a throwaway k3d cluster: runtime Pods, field
52
52
  ownership; `behold demo argo-estate` needs nothing at all, being a three-project
53
53
  Argo CD estate, declared only, so it runs where Docker doesn't; `behold demo
54
- choudoufu-estate` is four tag-owned OpenTofu estates served composed, where a
54
+ choudoufu-estate` is four tag-owned OpenTofu estates served as one declared
55
+ workspace, where a
55
56
  card's colour is **ownership** (bound, unowned, pending) rather than "nothing
56
57
  changed": a resource whose attributes drifted out of band still carries its
57
58
  markers and is still green, so attribute drift is a separate read you ask for
58
- with ⌘K → "Re-check live with plan"; `behold demo carve` is the Terraform peel
59
- walkthrough, below). Two more need no Docker either: `behold demo
59
+ with ⌘K → "Re-check live with plan"; `behold demo carve` shows chant and
60
+ Terraform managing one account together, below). Two more need no Docker either: `behold demo
60
61
  terraform-estate` draws a multi-root Terraform estate boxed by root, and shows
61
62
  what behold refuses to infer, since one root reads a key the other declares and
62
63
  no edge is drawn between them; `behold demo flux-estate` is a GitOps estate on
@@ -504,11 +505,11 @@ Documents are checked against terragucci's JSON Schemas when
504
505
  docs `using/terragucci`. `example-terragucci-reports/` is a bucket for
505
506
  terragucci's own example, written by terragucci's code.
506
507
 
507
- ## Terraform carve-out: `behold carve <report.json>`
508
+ ## Terraform and chant: `behold carve <report.json>`
508
509
 
509
- `chant carve advise` ranks a Terraform estate by **peelability**: how cleanly
510
- each resource could be carved into native chant source. `behold carve` draws
511
- that ranking: one card per resource, three panels (carve now / boundary work /
510
+ `chant carve advise` reads a Terraform estate and shows which resources chant
511
+ can also manage, and the work each handoff takes. `behold carve` draws that
512
+ report: one card per resource, three panels (carve now / boundary work /
512
513
  leave in Terraform) on the same `attrs._status` drift palette every other view
513
514
  uses, and the score arithmetic behind each rank in the inspect pane.
514
515
 
@@ -534,8 +535,8 @@ own `<address>.carve.json` manifests.
534
535
  npx @intentius/behold demo carve # no Docker, no cloud, no terraform binary
535
536
  ```
536
537
 
537
- Copies a half-migrated estate (a small chant project beside a Terraform one,
538
- both describing the same AWS account), installs the chant it will shell, runs
538
+ Copies a mixed estate (a small chant project beside a Terraform one, both on
539
+ the same AWS account), installs the chant it will shell, runs
539
540
  `chant carve advise` over the copy, and opens the banded graph with a six-step
540
541
  stepper on the panel's **Carve** tab:
541
542
 
@@ -555,7 +556,7 @@ stepper on the panel's **Carve** tab:
555
556
 
556
557
  The Emit step reports `chant lint`, not `chant build`: `build` fails on the
557
558
  emitted bucket (scored 84 by the advisor) on one rule: WAW042, a TLS-deny
558
- bucket policy the source Terraform never declared. The panel links the
559
+ bucket policy. Adding one in Terraform fixes it too. The panel links the
559
560
  reason. [example-carve/README.md](example-carve/README.md) has the estate's full story, the band table,
560
561
  and the offline/`--live` split.
561
562