design: a Terraform carve lens — chant carve advise as a scored overlay, TF as an estate member

[lex00]

Design issue — thinking this through now, while behold is aws/k8s only, so the UI shape is agreed before anyone needs it.

chant ships a full Terraform carve surface: carve advise (read-only peelability scoring over .tf/.tfstate: inbound/outbound boundary edges, tier map, 0-100 bands), carve emit (adopt into typed chant source at observe), carve bridge (patch the surviving TF), carve apply (graduate ownership). The advisor's whole output is a graph with scores — which is behold's native medium, and today it only exists as CLI text.

What a carve lens could be:

1. The advisor as an overlay. Point behold at a Terraform dir (a new project flavor next to chant projects: .behold.json gains a terraform member or behold serve --tf <dir>), render the TF resource graph, color by band (carve-now green / boundary-work yellow / leave grey — deliberately rhyming with the drift palette), and draw the inbound/outbound boundary edges the score is made of. Clicking a resource shows the score arithmetic — the CLI already emits per-resource JSON (--json), so the server shells chant carve advise --json exactly like it shells chant graph.
2. The strangler-fig picture over time. A mixed estate (part chant, part TF) is behold's sweet spot: the estate view gains a TF member whose carved-out pieces literally move from the TF boundary box into the chant project's box as they graduate. The estate compose already handles multi-project IRs; a TF member is one more IR producer.
3. Delegated carve actions, later. carve emit/bridge as gated Ops (the same delegated-write contract as ApplyOp) — behold never writes TF itself. This half stays deferred until the advisor lens earns use; chant#197's own gate ("everything past the advisor is design exploration until a real user pulls it") applies to the UI too.

Why now: the advisor JSON is stable and read-only, the estate machinery (#188/#189) is fresh, and deciding "TF renders as an estate member with a band overlay" costs a design decision today versus a refactor later. Why not yet: no user has pulled it, chant#998's hardening epic is still open, and behold has no TF fixture. Recommendation: build nothing until the icons/render-coverage lanes land; revisit when a real mixed estate shows up.

[lex00]

Plan update (session 2026-08-10, with Alex)

The peelability report is already a graph — per-resource address, score, band, tier, and the boundary edges the score is made of. So behold never parses TF; the carve advise --json report is the contract.

M1 — point behold at a report. behold carve <report.json> (or --carve-report on serve): a ~100-line carveReportToIr(), pinhole paints it. Bands on the drift palette (carve-now green / boundary yellow / leave grey). Boundary edges drawn, labeled inbound/outbound. Inspect pane shows the score arithmetic the report itemizes. Selecting a candidate highlights the edges it would cut + the survivors needing data-source patches — the predicted diff, before any emit. GET /api/carve serves the same to agents.

M2 — the real diff after emit+bridge. (a) the bridge output (proposed data sources, rewritten survivors, runbook) as a reconcile-style pending change-set view; (b) before/after frames — the resource moves from the TF boundary box into the chant project box with rewired edges — pinhole's morph frame-sequence is exactly this.

M3 — TF as an estate member. An estate names a terraform member; behold shells carve advise --json for it as it shells chant graph for chant members. The estate view becomes the strangler-fig progress bar: TF box empties, chant box fills. Wants chant#1005 (carve-state manifest) as the no-database progression source.

M4 — the agent workflow (docs, not code). User → agent: "carve the assets bucket". Agent reads /api/carve, confirms band, runs carve emit --state + lint, runs carve bridge; behold is the shared screen. terraform state rm + applying rewrites stay a human gate — op-signal discipline, no new behold write endpoints. Lands as an AGENTS.md recipe.

Asks into chant: a version field + stability promise on carve advise --json; chant#1005 when M3 approaches.

M1 is small and dispatch-ready; M2+ gated on someone actually carving.

[lex00]

Research pass on the half of this issue that item 1 named in passing and never specified: "render the TF resource graph." #252 shipped the advisory; the estate itself is still unrendered, and it turns out to be much closer than the rest of the plan here assumes.

The finding, up front: chant already builds the complete Terraform dependency graph and then throws it away at the JSON boundary. Grading the depths below against that changes which one to do first.

What we render today

behold carve <report.json> (#252) turns chant carve advise --json into a GraphIR — one card per ranked resource, kind = the Terraform type, lexicon: "terraform", the band on attrs._status so the drift palette colours it, one boundary box per band, boundary edges deduped across both endpoints. 441 lines in src/carve-lens.ts, zero Terraform tooling in behold's dependency tree.

But that picture is an advisory, and it is honest about being one. It carries only ranked resources — folded sub-resources (aws_s3_bucket_versioning inlined into its bucket) are dropped upstream by the scorer, because they carve with their parent. It carries only boundary edges: edges internal to a carve set are not boundary work and chant does not list them. Any edge whose other endpoint isn't itself a ranked resource is skipped on our side (src/carve-lens.ts:396). Grouping is by band. No data sources, no providers, no variables, no module nesting, no live state.

Someone looking at that graph is looking at a ranking with cut lines on it. They are not looking at their Terraform.

What chant already has

packages/core/src/terraform/graph.ts — buildGraph, 272 lines, pure, unit-tested on hand-written fixtures with no wasm and no filesystem. It produces the whole TfGraph:

• a TfNode per resource and module: address, kind, type, name, instances (state-expanded when --state is passed, via state.ts), hasDynamic, and identity when the physical name is a plain HCL literal
• a TfEdge per dependency: from, to, the referenced attrs, and via — the referring block's own attribute, e.g. ["vpc_id"] for a subnet reading its VPC
• output blocks as fromKind: "output" pseudo-edges from output.<name>

References are classified off the hcl2json expression AST, not a regex — a quoted address inside var.m["aws_s3_bucket.assets.arn"] or an escaped $${...} is correctly not a reference (chant#998).

And then: CarveAdviseResult.graph carries it in memory with the comment "Not part of the JSON payload — carveJson derives from it." The published report is resources[] plus a per-resource boundary. The graph is dropped.

CARVE_REPORT_VERSION is 1 and its contract is explicitly additive — new top-level fields may appear in any release, and a reader must ignore what it does not know. Publishing the graph does not bump the version.

Tier 1 — the Terraform estate graph, structure only

Render the actual .tf estate: every resource and module, every dependency edge, module nesting as containment, count/for_each fan-out as instance counts. No scores, no live state. The carve lens stays exactly as it is; this is a sibling lens off the same report.

Work. On the chant side, publish the graph it already holds — an additive graph: {nodes, edges} on the report, or a chant carve graph --from <dir> --json. On the behold side, a second IR builder beside carveReportToIr: node per TfNode, edge per TfEdge with toAttr/viaAttr from fields that already exist, groups.byStack keyed by module instead of band. Roughly 150-250 lines. examples/terraform-carve-out/ is a ready fixture.

Expected outcome. Point behold at a Terraform directory and get the graph, in the same pane, with the same painter, the same inspect pane, the same hand layout, the same ↓ SVG, and the same static export — behold export is lens-driven, so a new lens flows into a bundle for free. Overlay the carve bands on top of that graph and the advisory becomes a reading of a real estate rather than a free-floating ranking.

Pros. The expensive half is already written, tested, and running in production behind carve advise. It holds the line the carve lens set: behold parses no HCL, chant's JSON is the contract, and the ~1.8MB @cdktf/hcl2json wasm blob stays an optional chant dependency that only carve users install. It gives #230's strangler-fig picture something to actually move pieces out of. And it is the first thing here a person with a Terraform estate and no chant could open.

Cons. A second lens to keep honest as chant's report evolves, and a second place the band vocabulary has to agree with itself. A large .tf estate is a wide flat DAG and will need the same layout attention the composed estate needed at 11 members (#296). Nobody has asked for it yet — chant#197's own gate, that everything past the advisor is exploration until a real user pulls it, applies here too.

Tier 2 — Terraform as an estate member

#230's item 2. A mixed estate where a Terraform member sits beside chant projects and carved pieces migrate from the TF box into the chant box as they graduate.

Work. Needs an id scheme where a tf node and a chant entity for the same physical resource can coexist or dedupe — TfNode.identity is the only handle we have and it's only populated for literal names. Needs chant to treat terraform as a lexicon/substrate so the substrate pills and estate composition have something to key on. The zoom dial is the awkward part: composites → resources → attributes has no natural Terraform meaning past module nesting.

Expected outcome. The graduation picture #230 wants, and the one demo that makes the carve campaign land: watch a resource leave Terraform and arrive in chant without being destroyed.

Pros. Behold's actual sweet spot — one graph over mixed substrates is the product claim. The estate compose machinery already handles multi-project IRs; a TF member is one more IR producer.

Cons. The dedupe question is genuinely unsolved and getting it wrong means claiming two things are one resource, or one resource is two. Depends on Tier 1 for anything to compose. Real chant surface area, not just a behold change.

Tier 3 — live state and drift for Terraform-managed resources

Colour tf nodes by observed reality the way the overlay colours chant nodes.

This is currently a trap, and our own code says so. src/carve-live.ts:8: the observe beat stays deferred on chant#1647 — AWS live observe is CFN-stack-scoped by logical id, so a Terraform-owned resource reads confirmed-missing today. Rendering that is worse than rendering nothing: it is a false claim in the one place behold is careful never to make them. state.ts reads tfstate, but only for instance counts; promoting it to a drift baseline is a chant design question, not a behold feature.

Expected outcome if attempted now. A graph that says a live bucket does not exist.

Recommendation. Blocked on chant#1647 or on tfstate-as-baseline. Do not start.

What the investigation should produce

1. Confirmation from the chant side that publishing TfGraph on the carve report is additive and wanted — the ~20-line change is theirs, and it gates everything above.
2. One mock of the Tier 1 lens against examples/terraform-carve-out/, specifically answering whether module containment reads at the estate's real width or needs the Estate layout degenerates into a 45,000px-wide strip at 11 members #296 row-packing treatment.
3. A decision on whether the Tier 1 lens is its own verb (behold tf <dir>) or a mode of behold carve, given the report would then carry both the ranking and the graph.
4. The dedupe question for Tier 2 written down as a chant ask, before anything is built against identity.

What this changes about the plan above

The original recommendation here was to build nothing until a real mixed estate shows up, and for Tier 2 and Tier 3 that still holds — Tier 2 has an unsolved dedupe question and Tier 3 is blocked outright. But item 1's "render the TF resource graph" was priced as if behold would have to learn Terraform, and it doesn't: the graph exists upstream and is discarded rather than absent. That moves Tier 1 out of "revisit later" and into "a small chant patch away", which is a different decision than the one this issue was parked on.

🤖 Filed by Claude Code from the 2026-08-13 session

https://claude.ai/code/session_01J5NmMnBYU64RtVGN6CuPkk

[lex00]

Follow-up to the tier grading above, after reading choudoufu. It changes the Tier 3 picture — narrowly, and in a way worth writing down before anyone re-reads that section as a flat "don't."

What choudoufu is, for this issue's purposes

An OpenTofu fork (fork point 03743ce6e8) that deletes the state file. Every managed resource carries its own ownership record as plain AWS tags, and each plan rebuilds prior state by reading those markers off the live system. No backend, no lock, no state surgery. AWS only, experimental, narrow on purpose.

live/MARKERS.md is spec version 1 and says it is the entire contract — "Nothing else about the mode's internals is a contract. This document is." Three tag keys: tofu-estate (the ownership domain), tofu-address (the canonical config address, AWS-escaped, with tofu-address-2..4 continuations past 256 characters), and tofu-slot (an opaque cardinality slot for count instances).

Two things in that spec are aimed squarely at a tool like behold. The interop section: "Any tool, in any language, can read and write these three tags without linking against this fork or knowing it exists," followed by the honest note that "no known implementation of this spec exists outside this fork today." And internal/live/coupling_test.go, which enforces the separation from the other side — nothing under internal/live may import an external reader, with the comment naming who it expects: "chant is the reader that exists today, so it is the name these tests sweep for."

Both projects have written down that an external marker reader is expected. Neither has built one.

What it changes here

Tier 3 was graded a trap because chant's AWS live observe is CFN-stack-scoped by logical id (chant#1647), so a Terraform-owned resource reads confirmed-missing and rendering it would be a false claim. That reasoning is about plain Terraform, where nothing on the live resource says who owns it.

A choudoufu estate is the opposite case by construction. tofu-estate + tofu-address on the live resource is an ownership handle, readable with a tag call by anything, which is exactly the contract chant#1647 is missing. For that estate shape, live colouring is not blocked on #1647 at all.

The marker vocabulary also lands close to the palette behold already paints. MARKERS.md's ownership semantics are three-valued and refuse to guess: tofu-estate present is owned, full stop; neither tag present is foreign, reported and never auto-deleted; tofu-estate present with a missing or unparseable tofu-address is malformed — a named error, never silently read as "belongs to no one" or "belongs to whichever address looks close enough." Owned and foreign map onto good/warn directly. Malformed does not map onto anything we have — it is not neutral/unobserved, which means "did not look," and calling it that would be the same class of lie #1168 exists to prevent. A fourth token, or an explicit refusal to paint it, is a real design question rather than a detail.

What it does not change

• Not plain Terraform or plain OpenTofu. Those carry no marker, so Tier 3's original blocker stands unchanged for them. This is a fourth path beside Tier 3, narrower than it, not a replacement for it.
• AWS only, and experimental, per the fork's own framing.
• Tier 1 is unaffected either way. A choudoufu estate is still .tf files, so carve advise --from <dir> parses it exactly as it parses anything else. The --state path is moot against an estate with no state file, but that only ever fed instance counts.

The architectural question this raises

Where does a marker reader live? The coupling test assumes chant, and that matches how behold already works: behold's live resource state always arrives through chant (chant graph --live --overlay, lifecycle diff --live) — the one thing it reads directly is kubeconfig, via @intentius/chant-k8s-client, for target resolution, not cluster state. A behold that made its own tagging API calls would be the first crack in that, and would put cloud credentials in a process whose whole invariant is that it holds none.

So the shape that keeps the invariant is: chant learns to read markers (a lexicon or an observe path keyed on tofu-estate), and behold gets it for free through the overlay it already renders. That is chant surface area, not ours — but it is worth naming here, because it means the Tier 3 exception is not something behold can pick up unilaterally even though it looks like the cheapest live path on the board.

Also worth recording: the two trees already share lineage. tools/row-gen/carveseed.go transcribes chant's AWS_CARVE_TYPES — the same table behind tier-map.ts in the carve advisor this issue is built on — and tools/registry-gen/pin.go ports chant's pin.ts pinning semantics including the #1473 softening. The AWS type table this lens ranks against and the one choudoufu admits against have a common ancestor.

🤖 Filed by Claude Code from the 2026-08-13 session

https://claude.ai/code/session_01J5NmMnBYU64RtVGN6CuPkk