@intentius/behold 0.17.0 → 0.18.0

package/AGENTS.md

@@ -25,6 +25,12 @@ it against a local emulator (Docker). A directory that is not a chant project
 gets a structured `{code: "no-project"}` error from `/api/graph`, not a blank
 graph.
 
+In a checkout, `behold demo --list` prints a second block under the bundled
+one: the eleven workbench entries from `workbench.json`, this repo's own
+catalog of the internal estates behold is developed against — the same
+`behold demo <entry>` load, `just example name="<entry>"` to serve one, and
+"The workbench catalog" below for what each is and what it boots.
+
 A running server offers the same catalog over HTTP (#268): `GET /api/demos`
 lists every bundled demo with `{name, description, requires, satisfiable,
 reason?, fetches, repo?, target, loaded}` — `satisfiable` is doctor's PATH probe
@@ -76,9 +82,126 @@ preview-locked, and one load runs at a time (409 otherwise).
    `chant operator status --json`.
 2. **focus** — narrow with chant graph options as query params: `?detail=0..3`,
    `?components=1`, `?logical=1`, `?lens=blast:<id>&down=1`, `?lens=lexicon:aws`,
-   `?env=`, `?stack=`, `?tier=`, `?target=`.
+   `?env=`, `?stack=`, `?tier=`, `?target=`, `?collapse=1`.
+   `?collapse=1` (#393) shuts every member box holding more than 40 cards: the
+   box is drawn as ONE card carrying the count it was badged with (`301
+   resources · 84 bound · 85 unowned · 132 neutral`, in the estate's own
+   words), ids namespaced `box:<member>`, and the returned IR is the collapsed
+   one so every count and note speaks about the picture on screen. ⌘K →
+   "Collapse large boxes" / "Expand all". Below the limit it changes nothing.
 3. **inspect** — a node's `sourceLoc.file` is the typed source that declared it;
    edit there to change the estate (chant is the source of truth, not behold).
+4. **find** — ⌘K also takes an ADDRESS (#393). Two characters in, the palette
+   matches the ids and addresses of the graph the page is currently showing and
+   offers up to twelve `node: <address>` rows, prefix matches first, each with
+   its member and kind on a second line (two members of one estate can declare
+   the same address). Enter takes the same path a click on the card does — the
+   inspect pane and the highlight — and pans the graph onto it: `revealNode` in
+   web/app.js drives the same viewBox the wheel, the drag and "⤢ fit" drive.
+   Nothing here fetches, so it works in a static export too.
+
+### The behaviour overlay (#398, M1 of #397)
+
+What the estate costs and where it runs out of headroom, on `/api/overlay`
+only. **behold never calls a behavioural engine**, never holds its key, and
+produces no figure of its own — it renders what a chant lexicon handed it, the
+way it already renders drift and the carve score. The one arithmetic it does is
+addition, and the result is named `sum` so nobody can read it as a bill.
+
+The contract's source of truth is the comment titled "The behaviour block,
+proposed" on INTENTIUS/behold#398 (chant#2356 is the writing half). Field names
+here match it exactly; `src/behaviour.ts` is the implementation and the
+validator.
+
+Per entity, `attrs._behaviour` on the overlay IR node — the channel `_status`,
+`_release` and `_carve` already ride: `{at: {traffic}, cost: {perHour,
+currency}, headroom: {cpu?, latency?}, errorRate, resilience: {failure, verdict:
+survives|degrades|fails, note?}, rightSize?: {suggestion, reason?}, provenance:
+{engine, version, tolerance, basis: modeled|validated}}`. An entity nothing
+priced carries **no `_behaviour` key at all**, never a zeroed block, and a
+missing headroom axis is absent rather than 0. The block stays on the node and
+there is deliberately no top-level `behaviour: {}` map: the SPA already walks
+`ir.nodes` reading `attrs._status`, and a colour-by-cost mode is that same walk,
+with no join.
+
+Two sources, in this order:
+
+1. `attrs._behaviour` on the nodes, as `chant graph --live --overlay` painted
+   them, with `meta._behaviour` beside them for the graph-level half.
+2. `behaviour.<env>.json` at a member's root — `{meta, entities: {<address>:
+   block}}` — read **only** when no node of that member carries the attr, and
+   **only on the overlay** (`/api/graph` is the source graph; a prediction
+   about a live account has no business on it). The file's keys are the
+   member's own addresses; behold prefixes them to reach the composed id
+   `<member>/<address>`.
+
+`meta.behaviour` carries the graph-level half: `engine`, `version`, `at`, the
+engine's own `total` when it stated one, else behold's `sum` and the same per
+box under `boxes[<boxKey>]` (`{perHour, currency, priced, unpriced}`). Mixed
+currencies produce no sum and a diagnostic — behold converts no currency. A
+malformed block is dropped whole with its reason in `diagnostics`, never
+half-rendered. A member with neither source gets `{absent: "…"}` naming both
+places behold looked; that is an absence, not a refusal, because nothing was
+configured.
+
+`meta.behaviour.refusal` is `{reason, remedy}` in the lexicon's own words,
+printed as it came, and it is present **instead of** everything above: a
+refusal emits no entity block at all and strips any that had arrived. The drift
+overlay is untouched either way — nothing in this pass reads or writes
+`_status`. `?logical=1` projects a different picture and carries no behaviour
+block in M1.
+
+### Colour by drift, cost or headroom (#399, M2)
+
+The SPA colours the graph by one of three modes. The mode is **client-side
+state** — `web/app.js`'s `colourMode`, persisted under `behold.colourBy` the way
+the theme is. It is deliberately NOT in `LENS_PARAMS`/`canonicalKey`: a lens
+param means "a different snapshot comes back", and a mode change changes no
+fetch at all. The block is already on every priced card, so a switch is a
+repaint of the SVG on screen.
+
+`drift` keeps the categorical fill and #393's vocabulary legend, unchanged. The
+two behaviour modes replace the card's FILL only, so the drift bar underneath
+keeps saying what chant observed. `cost` is a sequential scale over
+`cost.perHour` between the estate's own min and max; `headroom` is absolute over
+0..1 and reads **the lower of the axes present**. An entity with no block draws
+the drift overlay's neutral (`pinTokensFor().neutralFill`) and is marked
+`data-unpriced`, never the zero end of the scale — "nothing priced this" and
+"this is free" are opposite claims.
+
+Both ramps are derived from the active palette (`rampFor` in
+`web/behaviour-scale.js`), the way #229 derives the chrome: cost is a single hue
+off the accent walked in lightness away from the background — expensive is not a
+verdict behold gets to paint — and headroom rides the three status hues the
+drift overlay already anchors, degraded → foreign → managed.
+
+One legend per mode, in the Model tab. The Scope tab carries a totals row per
+box and per estate for the active mode: `cost` quotes `meta.behaviour.boxes[key]`
+and `.sum`, or `meta.behaviour.total` when the ENGINE stated one (labelled
+"engine total"); `headroom` has no server-side aggregate — no engine states one —
+so the SPA takes the scope's min and median itself and the row says "computed".
+Every row carries `n priced · m unpriced`. In drift mode there is no row.
+
+Everything either mode decides is pure in `web/behaviour-scale.js`, with
+`web/behaviour-scale.test.js` beside it; the SPA owns the fetches and the SVG.
+
+### Provenance on every figure, and the refusal (#401, M4)
+
+Every figure the SPA shows — the totals rows, the legend, and the inspect pane's
+`behaviour` section — carries `{engine} {version} · {tolerance} · {basis}`
+beside it, never once per page. `modeled` is spelled out on hover as "modeled,
+not billed": #397's one prohibition is a prediction presented as a bill, and the
+badge is where that is prevented. Provenance is per ENTITY in #398's contract, so
+a badge over a set (a box, the estate) says `mixed` on any field the set
+disagrees on rather than picking one.
+
+`meta.behaviour.refusal` disables both behaviour modes in the View tab and in
+⌘K — visibly, with the lexicon's reason and remedy as their tooltip — and prints
+those words verbatim where the legend would be. The drift overlay keeps
+rendering; it never depended on an engine. `meta.behaviour.absent` disables the
+same two modes with the absent line as their tooltip and prints **nothing**:
+nothing was configured, so nothing refused. `meta.behaviour.diagnostics` render
+in the Model tab under the legend.
 
 ## The carve loop (Terraform → chant, #230)
 
@@ -201,7 +324,10 @@ for another env never stands in. `just e2e-ci-github` proves the contract
 against the real forge (example-ci + `.github/workflows/behold-e2e-dispatch.yml`),
 including the `lost` verdict, which `BEHOLD_CI_FOLLOW_TIMEOUT_MS` and
 `BEHOLD_CI_POLL_FAIL_BUDGET` let a run force on purpose; a lost run is the one
-`POST /api/ci/readopt` re-follows.
+`POST /api/ci/readopt` re-follows. The same e2e dispatches into an environment
+with a required reviewer (`behold-e2e-gated`): the run holds at `waiting`, the
+progress state carries `waiting: true` and the run's `url`, the now-line says
+the approval is granted on the forge, and a cancellation lands as `failed`.
 
 A dispatched run is followed honestly (#165 §6, PR #350): only GitHub's own
 `completed` + conclusion paints `ok`/`failed`; a poll-failure budget or the
@@ -308,6 +434,16 @@ and it must be an address the served report already ranks — the value that
 reaches the spawn's argv comes from a closed set read off disk. No cloud write,
 no Terraform mutation, no edit to anyone's chant source.
 
+A choudoufu estate member (#366) adds no exception. A move there is one tag
+write through choudoufu's own `live-mv`, and behold never makes it: `GET
+/api/choudoufu/moves` reads a plan (`carve.json`) from inside a served member,
+previews each move with choudoufu's `live-mv -json -dry-run` (the only spelling
+of `live-mv` in the tree, src/choudoufu-moves.ts `dryRunArgs`, asserted by
+test), hands the lines back with copy buttons, and `?receipt=1` reads the
+listing after a person ran them. **There is no `/api/choudoufu/mv`**, and
+src/choudoufu-route.test.ts asserts it stays absent, for the same reason
+`/api/carve/apply` does not exist.
+
 ## Changing behold (for agents working on this repo)
 
 The sections above are about driving a running behold. This one is about
@@ -345,3 +481,382 @@ live here, with the enforceable ones enforced.
   stays that way.
 - **chant's working rules** (its single-lane checkout, its release path) are
   chant's and live in chant's repo, not here.
+
+### Adding a member kind
+
+An estate member has a kind (#368): what a directory has to look like, what
+tool answers reads for it, and how it becomes a `GraphIR`. `src/member-kind.ts`
+is the one table; `chant` is the first row and every member was that row
+until the table existed. A new kind is:
+
+1. A `registerMemberKind({ kind, probe, expects, via })` call in
+   `src/member-kind.ts` — the `probe` is sync, read-only and runs no code (a
+   file's presence, a regex over a root file, or either: the choudoufu probe
+   takes the `estate.chdf.hcl` sidecar, choudoufu's leading form, OR a `live {`
+   block in a root *.tf, #387); `via.tool` stamps the binary and
+   version that would answer, which is the version half of `memberIr`'s
+   cache key; `via.read` is the one uncached read, source or live per `opts`.
+   The module imports nothing from the read path at runtime (src/chant.ts
+   imports src/project.ts, which imports it); a kind's `via` closes over its
+   own tool module.
+   Add the word to `MEMBER_KINDS`. A word in the vocabulary that no row
+   registers is a doctor fail with the reason, never silently chant.
+2. Nothing in `src/estate.ts`: `composeEstate`, `composeEstateOverlay` and
+   `estateNamespaceScopes` already dispatch through `memberKindOf(dir)`.
+   The two routes that render an estate — `/api/graph`'s estate branch and
+   `/api/overlay`'s — run the same passes in the same order and must not
+   fork per kind; a kind's differences live inside its `read`.
+3. A `registerPack({ lexicon, iconFor, fields })` in `src/render.ts`, or the
+   kind's cards lead with the alphabetically first two short attrs. A `fields`
+   function takes the box the card is drawn in as its second argument, so a
+   row the box already carries can be left off (#393 item 9,
+   `src/card-face.ts`).
+4. A row in `statusVocabulary` (`src/status-vocabulary.ts`) when the kind has
+   its own words for the four overlay colours — choudoufu's `bound` is not
+   chant's `managed`, and a legend that says `managed` over a card carrying no
+   marker is a claim behold has no right to make. The colours never move; only
+   the naming does, and an estate of several kinds keeps chant's words and says
+   so in the legend's tooltip.
+5. A `DoctorCheck` line when the kind needs a tool on PATH or a per-member
+   precondition (a version floor checked before the spawn, the way
+   `carveStatusReader` does; a PATH probe the way `src/demos.ts` does).
+6. Tests: the probe and the object form in `src/project.test.ts`; dispatch
+   in `src/estate.test.ts`'s "#368" block, which registers a fake kind and
+   asserts chant members still go through exactly the calls they did; the
+   kind's own reader off recorded documents in `src/__fixtures__/`, with
+   provenance in prose above the load.
+
+`.behold.json` names a kind as `{ "dir": "x", "kind": "<kind>" }`; a bare
+string is `chant`. Anything behold boots for a kind goes through
+`assertScratch` first.
+
+**What the first screen owes a non-chant member (#393).** Three chant-shaped
+things used to be offered to every member whatever it was, and a new kind gets
+all three answered for free:
+
+- `/api/project` publishes `memberKinds` — the served members' kinds, in
+  composition order. The SPA opens on the `resources` zoom when none of them is
+  `chant`, because `components` is a projection of a chant project's own
+  component DAG and a member without one opens on "the components lens doesn't
+  apply to a composed estate yet". #182's zero-node fallback still covers a
+  chant project that declares no components.
+- `/api/project` publishes `runtimeCapable`, and the palette and the View tab
+  offer `zoom: runtime` only then. The tier below the declaration boundary is
+  the owner-referenced children chant stamps `runtimeOwner` on, and only a
+  Kubernetes read has an owner chain to resolve — `RUNTIME_LEXICONS` in
+  `src/server.ts` is the one word (`k8s`), read off the members' DECLARED
+  lexicons so the stop exists or not before anyone picks it.
+- A chant-only facet answers emptily rather than 500ing for a non-chant
+  primary: `/api/resources` returns `{byComponent: {}}`, the shape carve mode
+  already returns and the SPA already reads as "no resource facet here".
+
+A kind that grows components, or a substrate with an owner chain, changes those
+answers where they are decided — never per kind in a route.
+
+### The workbench catalog
+
+`demos.json` is the catalog that ships. `workbench.json`, read beside it and
+deliberately absent from package.json's `files`, is the catalog of internal
+estates this checkout is developed against (#386, #388). Four rules, and
+src/demos.ts holds them:
+
+1. A third source, `local`, and a second file. A local entry's `path` is
+   relative to the directory of the catalog file that named it — the intentius
+   checkouts are siblings, so the workbench writes `../choudoufu`,
+   `../waterpark`, `../chant`, and the file stays committed and reproducible.
+   An entry whose path is not checked out is unsatisfiable exactly as a
+   missing binary is: `--list` and `/api/demos` say so, CI stays clean.
+   `BEHOLD_WORKBENCH=<file>` names a catalog elsewhere; a workbench name that
+   collides with a bundled one is dropped with a stderr line.
+2. In place or copied, said explicitly. `inPlace: true` serves `path` where it
+   sits; the default copies to `behold-demos/<name>` with the bundled filter.
+   Anything whose setup writes into the tree — `init`, `apply`, a rendered
+   generator — is copied or generated into the target, never run in a
+   checkout, which is how #366's "behold never runs `choudoufu init` in a
+   served project" survives. An `inPlace` entry with a `setup` says so in its
+   description.
+3. A generator is a source. An entry with no `path` at all renders its estate
+   into an empty target through its own `setup`, which runs with cwd = the
+   target and two extra variables: `BEHOLD_WORKBENCH_DIR` (the catalog file's
+   directory, so a script can reach `../choudoufu`) and `BEHOLD_DEMO_NAME`.
+   The up script writes the matching down script into the target, the way the
+   bundled choudoufu demo ships `scripts/choudoufu-down.sh`.
+4. `CHOUDOUFU_BIN`. `choudoufuBinary()` (src/choudoufu-member.ts) names the
+   binary and every spawn, the doctor probe and the demo requirement check go
+   through it; the doctor line prints which binary answered. Workbench scripts
+   spell the same fallback, `${CHOUDOUFU_BIN:-choudoufu}`.
+
+`just example name="<entry>"` serves one. Scratch discipline is unchanged: an
+emulator a workbench entry boots is `behold-wb-<entry>` on its own port, and
+the up scripts (`workbench/<entry>/up.sh`, helpers in `workbench/lib/`) assert
+the `behold-wb-` prefix and the not-4566 rule themselves, in bash, because they
+are the boot site. Each writes the matching `scripts/down.sh` into its target.
+
+**The eleven entries**, in catalog order. The counts are measured, not
+estimated — every entry the e2e below can reach on a developer machine prints
+its own graph and overlay counts as it runs.
+
+| entry | what it serves | needs |
+|---|---|---|
+| `chant-getting-started` | chant's own getting-started example from `../chant`, in place: the source graph, 8 nodes, no substrate. The one-second answer to "did I break plain chant reading?" | that example's own `node_modules` — nothing is installed in your chant tree |
+| `chant-local-cloud-trio` | chant's local-cloud-trio, in place: one project declaring across aws, azure and gcp, 8 nodes and 2 edges of source | the same |
+| `fountain-ops` | `../fountain-ops` in place with `--env local` — the mature estate on your working checkout | docker, k3d, kubectl, jq, just. **The one entry whose setup runs in your working copy**: the checkout's own `just up`, a five-minute k3d cluster, and it switches your kubectl context. `just down` there removes it; behold never does |
+| `choudoufu-workbench` | the live-mv workbench's four estates copied out of `../choudoufu`, composed with `--env live`: 42 cards — 24 bound, the 12 team cards reading `owned by tlmig-sample-monolith`, 6 neutral | docker, choudoufu |
+| `choudoufu-cohort-s3` | `estate-gen`'s `s3` cohort rendered into the target — a sidecar-declared estate (#387): 6 cards, all neutral, because the apply stops where floci answers S3 Control tag reads on a hostname that does not resolve | docker, choudoufu, go, terraform |
+| `choudoufu-cohort-iam-ecr` | the same for `iam-ecr`, the one cohort floci implements end to end: 6 cards, all 6 bound | the same |
+| `choudoufu-cohort-ec2-networking` | the same for `ec2-networking`: 49 cards, the widest roster, all neutral (floci refuses a transit gateway call and the apply stops) | the same |
+| `terralith-1` | `terralith-gen` at scale 1 plus the `estate.chdf.hcl` sidecar it omits, applied by choudoufu from nothing: 79 cards, all 79 bound | docker, choudoufu, go |
+| `terralith-4` | the same at scale 4: 301 cards, all 301 bound. The estate behold is sized against | the same |
+| `terralith-4-adopt` | scale 4 again, but STOCK terraform applies it first, so nothing wears a marker: 301 cards — 85 UNOWNED, 84 bound by derived identity alone, 132 neutral. One `choudoufu live-import` line, which the up script prints and you run, and all 301 read bound | docker, choudoufu, go, terraform |
+| `waterpark` | `../waterpark/access` in place as a bare Terraform directory (#384): five roots as boxes, 58 cards, 49 edges, nothing written under the estate | `@intentius/chant-lexicon-terraform` + `@cdktf/hcl2json` beside behold — optional peers behold declares and does not install |
+
+**The scratch, by name and port.** Each emulator is the entry's own, booted by
+its up script and removed by the `scripts/down.sh` that script wrote into the
+target — never by pattern.
+
+| entry | container | host port |
+|---|---|---|
+| `choudoufu-workbench` | `behold-wb-choudoufu-workbench` | 4651 |
+| `choudoufu-cohort-s3` | `behold-wb-choudoufu-cohort-s3` | 4652 |
+| `choudoufu-cohort-iam-ecr` | `behold-wb-choudoufu-cohort-iam-ecr` | 4653 |
+| `choudoufu-cohort-ec2-networking` | `behold-wb-choudoufu-cohort-ec2-networking` | 4654 |
+| `terralith-1` | `behold-wb-terralith-1` | 4655 |
+| `terralith-4` | `behold-wb-terralith-4` | 4656 |
+| `terralith-4-adopt` | `behold-wb-terralith-4-adopt` | 4657 |
+| `chant-*`, `waterpark` | none — source reads, no substrate | — |
+| `fountain-ops` | the k3d cluster `fountain-local`, which is the checkout's, not behold's | — |
+
+The port is the floci's host binding and the entry's `serve.spawnEnv`
+`AWS_ENDPOINT_URL` at once, so the estate's own applies and the choudoufu
+behold spawns talk to the same emulator.
+
+**The e2e** is `just e2e-workbench` (`e2e/workbench-e2e.sh`, #391): every entry
+loaded through `behold demo <entry> <tmp target> --port <p>` on its own port
+from 4720 up, `/api/graph` asserted to carry nodes and a live entry's
+`/api/overlay?env=live` to answer with its bound/unowned/neutral split, timings
+per entry; eight entries and 475s on the machine this was written on.
+`terralith-4-adopt` is asserted twice — 85 UNOWNED, then the
+`live-import` line the up script printed, run by the script itself in the
+target the way a person would, then 301 bound — because that write is the
+person's, never behold's (#372). `waterpark` is checked for an untouched
+checkout afterwards. `missingRequirements` decides what runs: a missing binary,
+an unchecked-out sibling, an uninstalled chant example or the absent Terraform
+lexicon each print `skip: <entry>: needs …`, so in CI every entry skips and the
+run exits 0. `fountain-ops` is skipped by name everywhere, for the reason in
+the table. A `behold-wb-*` container left standing at the end fails the run.
+
+The seeded catalog (#389) found one thing missing in src/: a LONE choudoufu
+estate — every generated entry is one — served the no-project card, because the
+single-project read is `chant graph <dir>` and such a directory has no lexicon
+for it to read. `servesAsEstate` (src/member-kind.ts) is the predicate that
+routes one directory of a non-chant kind through the estate compose path, where
+the member's own kind reads it. One member composes exactly as four do, ids
+namespaced under the member's short name, so the graph, the pane and the morph
+agree on what a node is called.
+
+### Rendering a Terraform estate
+
+A Terraform estate reaches behold through chant.
+`@intentius/chant-lexicon-terraform` reads the HCL an estate already has and
+emits one entity per block, so **a Terraform estate is a chant project whose
+only lexicon is a reader** and `chant graph --format ir` serves it like any
+other. behold parses no HCL and ships no HCL parser — the same posture
+`src/carve-lens.ts` states for the carve report (#378).
+
+Three passes turn what arrives into a picture (`src/terraform-lens.ts`), in this
+order, guarded on the IR carrying terraform entities so every other estate gets
+the identical object back:
+
+1. **`normalizeTerraformNodes`** — a node's `kind` arrives as the entity class
+   (`Terraform::Resource`), not the resource type, so every card would be titled
+   and iconed the same. The type moves out of `attrs.address` into `kind` and
+   the block class lands in `attrs.block`. That is the shape a carve node
+   already has, which is why one presentation pack serves both.
+2. **`groupTerraformByRoot`** — roots are a Terraform project's only grouping.
+   It retires itself when chant#2266 groups upstream. A node sits in exactly one
+   box, so a box every node has left is dropped rather than drawn empty (#393):
+   a served directory arrives composed, `composeStacks` boxes the whole member,
+   and the root boxes then take those same nodes — which is what put an empty
+   box named `access` on water park's canvas. What the member box was there to
+   say moves into the root box's title, which is `<member>/<root>` whenever the
+   estate holds more than one member and the bare root name when it does not
+   (two members with a root apiece named `prod` would otherwise merge silently).
+3. **`filterTerraformCards`** — what is a card, below.
+
+**What is a card (#382).** Measured on a real estate: 247 nodes for 43
+resources, four fifths of it not infrastructure.
+
+| tier | blocks | why |
+|---|---|---|
+| default (detail 0-2) | `resource`, `data`, `module` | the estate: what is declared, what it reads, what it composes |
+| attributes (detail 3) | + `output`, `variable` | its interface — real, but a second question |
+| never | `terraform`, `provider`, `locals` | settings, not estate |
+
+Nothing is dropped silently: `terraformElisionNote` says what is not drawn and
+where to see it, the way `edgelessNote` says why a view has no edges.
+
+**The note, at every zoom and in a 260px strip (#393).** The roots note and the
+elision note are built by one function in `/api/graph` and returned by all three
+of its branches, the logical lens included — it was the lens that most needed
+the line and the only one that dropped it. Both routes send `note` and, when
+there is a shorter true form, `noteShort` (`5 roots · 2 skipped · 189 blocks not
+drawn`). The strip shows the short one with the long one on its tooltip, and the
+panel's Model tab prints it whole. The server writes both: the SPA does not
+author notes, and truncating this one on a sentence boundary would keep the list
+of root names and drop the counts.
+
+**Do not invent edges.** They arrive from chant or not at all: the fixtures here
+were recorded when a Terraform IR carried none, and lexicon 0.61.0 (chant#2265,
+which resolves a block's `"${…}"` references) draws 390 over water park's five
+roots with no change on this side. The one relationship that looked derivable
+without it — a cross-root read by name — was measured and refused (#381): both
+ends carry the same unresolved interpolation, so a match would be a coincidence
+of variable naming. A data source says what it reads as a row instead.
+
+**Serving a directory that declares nothing (#384).** Every estate this lane
+exists to draw is a directory of `.tf` files and nothing else, and #378 chose
+not to ask one for a `chant.config.ts` of its own — INTENTIUS/waterpark#88 was
+withdrawn because the estate is more useful untouched. So `behold serve
+<terraform-dir>` generates the reader config itself, outside the estate, and
+points chant at it. The Invariant's one in-project write stays
+`.behold/layout.json`; nothing is written under the served directory, and
+`src/terraform-member.test.ts` asserts the estate's source stamp is unchanged
+across a read. Three decisions, each a trade #384 left open and each measured on
+water park's `access/` before it was taken:
+
+1. **The lexicon is opt-in.** chant resolves the lexicon from the config file's
+   own location, so the generated project has to see it — and making it a
+   dependency would put `@cdktf/hcl2json`, a ~1.8 MB wasm blob, in the install
+   of every user who serves a chant project. `@intentius/chant-lexicon-terraform`
+   and `@cdktf/hcl2json` are therefore **optional peers**: declared in
+   package.json (the only place their versions are named — the refusal reads
+   them from there), never installed by behold, probed at serve and doctor time,
+   and refused with the one install line and where behold looked. The same gate
+   `behold demo` puts on a binary it does not ship. The lexicon's own chant peer
+   is what moved behold's `@intentius/chant` floor to `^0.61.0`: chant 0.54
+   loads no published version of it (`applyLineage is not a function`).
+2. **Roots are discovered, and the skips are reported.** A root is a directory
+   with a `.tf` declaring a line-start `terraform {` or `provider "` block
+   beside a `resource`, `data` or `module` block — a regex probe at the depth
+   the choudoufu probe uses, no HCL parsed. #384 proposed the first half alone
+   ("what a root has and a called module does not") and the estate refuted it:
+   water park's `modules/persona` is a shared module called by three roots and
+   its `versions.tf` is `baseline`'s byte for byte. So two exclusions stand
+   beside the probe — a directory under a `modules/` segment (Terraform's own
+   standard module structure; the roots that call it draw its blocks already)
+   and one with nothing to draw (`access/backends` is two backend fragments) —
+   and both are named in the graph's note with their reason, the way
+   `terraformElisionNote` names what a zoom left out. Measured on `access/`:
+   five roots (`envs/prod`, `identity`, `github`, `baseline`,
+   `satellites/waterpark-runner`), two skipped, `envs/dev` neither drawn nor
+   reported because it holds only a README.
+3. **A `terraform` member kind, after chant and choudoufu.** #378 said there is
+   no such kind and meant it about *reading*: behold parses no HCL and the
+   render goes through chant. A kind whose `read` shells `chant graph` against a
+   generated config is a scaffold, not a second reader, and it inherits the
+   probe, the cache stamp, the doctor line and estate composition (#368) for
+   free — so a Terraform root composes in an estate beside a chant project and a
+   choudoufu estate at no extra cost. `src/terraform-member.ts` is the whole of
+   it; `detectProjectShape` answers a directory that is its own member with
+   `membersFrom: "probe"`, which is what retired #384's `no chant.config.ts
+   here` dead end.
+
+The scratch project is `<tmpdir>/behold-tf-<hash of the estate path>`:
+`behold-*` and cleared through `assertScratch` (src/scratch.ts), one directory
+per estate reused across runs, asserted to be outside the estate before a byte
+is written. It holds the generated `chant.config.ts` and two symlinks —
+`node_modules` to behold's own, which is how the config resolves the lexicon,
+and `estate` to the served directory, which is how each root's `dir` is spelled.
+The second is not decoration: the lexicon sets a root's module boundary to the
+root's own directory when its `dir` resolves outside the project root, so
+absolute paths cost every `../modules/x` call the estate makes — 72 nodes and 6
+resources on water park, against 247 and 43 through the symlink. Nothing in the
+answer mentions the scratch path (a terraform entity carries `attrs.file`
+relative to its root, and no `sourceLoc`).
+
+### A choudoufu member's overlay is ownership; attribute drift is the plan (#404)
+
+**Read a green choudoufu card as "this is ours", never as "nothing changed".**
+The overlay is composed from `live-ls -json` and `live-plan -json`, and those
+two documents answer one question — bound, unowned, omitted, or invisible to
+the listing. Neither of them ever compares an attribute VALUE. A resource whose
+tag, path or mutability was changed out of band still carries its markers, so
+it is still bound, and it is still green.
+
+The other half of the terminal's answer — "would a plan change anything?" — is
+a **separate, opt-in read**: `choudoufu plan -input=false -out=<tmp>` then
+`choudoufu show -json <tmp>`, whose `resource_changes[].change.{actions,before,
+after}` name the attributes and both their values. (`choudoufu plan -json` is
+NOT this: on 0.16.0 it prints choudoufu's own ownership document, the same
+shape as `live-plan -json`, with no attribute values in it at all. The
+measurement is in src/choudoufu-plan.ts's header.) The plan file is written to
+a scratch directory of behold's own and removed after — never inside the served
+member, which would be a write into someone's source.
+
+It is opt-in because it costs differently: the ownership read is answered out
+of the tagging index and is flat in the estate's size, while `plan` refreshes
+every resource — one provider read per card, 301 of them on `terralith-4`. So:
+
+- **Never on an ordinary overlay read.** `GET /api/overlay?plan=1` and
+  `GET /api/diff?plan=1` are the only things that spawn one, and the palette's
+  **"Re-check live with plan (attribute drift)"** row is the only thing in the
+  SPA that sends the flag. The cheap **"Re-check live (refresh drift)"** row is
+  deliberately left alone — it is `POST /api/refresh`, a primary-only re-observe
+  that captures a lanes frame and never composes the estate.
+- **Cached under the member's source stamp**, the same key half `memberIr`
+  uses. A read that did NOT ask is served that stored answer, so a reload after
+  a refresh keeps showing the drift without paying for a second pass; a read
+  that DID ask always re-plans, because "re-check" means re-check.
+- **The ownership verdict stays the card's colour.** A bound card that drifted
+  is still painted bound and still counted `bound`; it gains `attrs._planDrift`
+  and wears a dashed `--degraded` edge plus a `~ n attributes` corner glyph
+  (web/app.js `markDriftedCards`, the same post-render stamp as the carve and
+  operator marks). A card that is not bound is never marked — an unowned
+  object's planned `create` is an ownership fact the overlay already paints,
+  and `planDrift` drops creates for that reason.
+- **`/api/overlay`'s meta carries `drift`**: `{read: false}` or `{read: true,
+  drifted: n}`. The two are different answers — "nobody looked" versus "looked,
+  nothing drifted" — and the legend prints a count only for the second.
+
+### A choudoufu estate's own references (#393)
+
+`choudoufu live-check -json` states the roster and `references[]`, and that
+second list is *cross-estate by construction* — data sources filtered on
+another estate's marker tags. So a 301-resource terralith of roles, policies
+and attachments drew no edge at all and the graph asserted "nothing in this
+estate references anything else", which is false about every one of them.
+
+The references were never missing; nothing was reading them. **A choudoufu
+member's read now also runs the terraform kind's reader over its own
+directory** — one root, the estate directory itself, through the same scratch
+project machinery above (nothing written under the estate) — and joins the two
+documents by address. behold still parses no HCL: `src/choudoufu-refs.ts` is
+two lists of strings and the rules that match them, and its header is the
+argument for each. In short: the lexicon names *blocks* in a path of module
+*calls* (`estate/module.team_pod/aws_iam_role.pod_role`) and choudoufu names
+*instances* in a path of module *instances*
+(`module.team_pod["pod-a"].aws_iam_role.pod_role[0]`), so one lexicon edge is a
+product — kept inside one module instance (Terraform's scoping, not a guess),
+joined key to key when both ends expand over the same keys (266 true edges on
+`terralith-4` against 666 of which ~400 would be false), landing on a module
+call's whole interior, and dropped whole when either end is a `var`, a
+`locals` or anything else the roster declares no card for.
+
+Every edge is `inferred` and carries the lexicon's own attribute name (`role`,
+`policy_arn`), so the card says what made the reference. **Without the
+lexicon there are no edges and the note says so** — carrying the terraform
+kind's own install line rather than the sentence behold has no reader to
+assert — and the lexicon's version is in the member's cache stamp, so
+installing it invalidates the edgeless IR rather than serving it forever.
+
+The layout half is `packBoxComponents` (src/render.ts). src/edgeless.ts wraps a
+box whose cards reference *nothing*; a box that has edges is never wrapped, so
+`terralith-4` came back as a 110996 x 628 strip the day the join landed —
+dagre lays 42 connected components side by side on three ranks. The pass packs
+a box's components into shelves and resizes the box around them, re-laying each
+component on its own first (inside a cluster dagre interleaves them: a six-card
+cluster's bounding box spanned 46598 units) and wrapping a component that is a
+strip either way — the DNS fan is 19564 x 400 upright and 900 x 10046 on its
+side. A box under 4:1 is left exactly as it laid out. Measured: `terralith-4`
+7660 x 5162 with 266 edges, waterpark 3536 x 3138 at detail 2 and 7142 x 6974
+at detail 3 (from 4.2:1 and 15.1:1, the case #393's wrap did not answer).