Non-AWS substrate parity for live/drift/logical/reconcile layers (tracking)

[lex00]

Background

behold renders a chant infra project as a live graph. chant supports many substrates via lexicons — aws, azure, gcp, k8s, helm, gitlab, github, forgejo, docker, fly, temporal (../chant/lexicons/). behold's marketing promise is a mixed-substrate estate in one graph.

Today, the base source graph and component DAG are substrate-neutral — behold paints whatever chant graph --format ir returns, so a non-AWS project's source graph renders fine. But the richer live layers are AWS/CloudFormation-shaped and were only ever exercised against the AWS-based Loom demo. This is a tracking issue for reaching non-AWS parity on those layers. It is a larger, separate track from the "open your own project" MVP (which delivers the source graph for any substrate).

Where the AWS coupling lives

• Logical zoom — src/logical.ts. Header states "AWS-lexicon only, by design"; HEADLINE_KINDS are literal AWS::* CloudFormation types (VPC/subnet/ELB/etc.). Non-AWS projects get no logical architecture view.
• Component status — src/component-status.ts, via chant components status <env> --live --json. Single-substrate AWS, resolved from each component's CloudFormation stack. No CFN → no live status.
• Live overlay edges — reconstructed per-substrate and "never cross providers" (per ../chant/docs/.../cli/graph.mdx). Cross-substrate topology exists only in the source graph. --live is also managed-only: it needs each resource to carry chant's ownership marker (ownership.stack set in chant.config.ts).
• Deploy targets / axes — src/server.ts deployTargets() derives a single target from AWS_ENDPOINT_URL; AWS-centric.
• Substrate mapping — src/substrates.ts detectSubstrates() only surfaces aws→Floci and k8s→k3d (plus .gitlab/.forgejo dir markers), all gated on Docker. Other lexicons aren't surfaced as substrates at all.

Scope of this track (break into follow-up issues as sized)

This issue is a placeholder to plan and decompose. Candidate sub-work:

1. Logical zoom beyond AWS — decide whether a logical/architecture view is meaningful for k8s/GCP/Azure/Fly and, if so, define per-lexicon HEADLINE_KINDS and grouping. Otherwise, make the logical zoom gracefully unavailable (not broken) for non-AWS projects.
2. Live status per substrate — generalize chant components status --live consumption beyond CloudFormation, or clearly gate the status overlay to substrates chant can report on.
3. Cross-substrate topology — the source graph already has cross-provider edges; decide how much of that to preserve in live/overlay views (chant reconstructs per-substrate and won't cross providers live).
4. Substrate strip coverage — surface the other lexicons (azure/gcp/fly/helm/temporal/github) in src/substrates.ts where a bring-up/emulator concept exists, or show them read-only.
5. Deploy target genericization — replace the AWS_ENDPOINT_URL-derived single target with per-substrate targets.

Not blocking "open your own project"

The MVP goal only requires the substrate-neutral source graph to render for an arbitrary chant project — which it already does. This track is the follow-on to make drift/status/logical/reconcile first-class for non-AWS substrates. Prioritize per real demand (which substrates users actually open).

Acceptance criteria (for the track, not a single PR)

• A concrete decomposition into sized follow-up issues exists.
• Each AWS-shaped layer above is either generalized or gracefully degraded (never a broken/blank view) for non-AWS projects.

[lex00]

The k8s slice of this track is now decomposed under #84 (epic: Kubernetes runtime surface), matching the epic name on the chant side (INTENTIUS/chant#1073).

Four children: #85 overlay parity, #86 runtime tier below the declaration boundary, #87 field-level ownership colouring, #88 k3d turnkey demo. Each names the chant-side issue it depends on.

Two notes relevant to this track's framing. The k8s overlay gap is upstream, not a behold limitation — chant's describeResources() is 20 hardcoded kinds with every CRD warn-skipped, fixed by INTENTIUS/chant#1074. And the substrate-mapping item here is already half-done: src/substrates.ts probes k3d cluster list today, which is what makes #88 cheap.

[lex00]

A concrete mixed-substrate consumer for this, measured rather than inferred — kubemicrovm-ops, an AWS + Kubernetes estate where the Kubernetes half is the point.

Standing prod-ha estate, 11 nodes: 7 AWS (S3 bucket + bucket policy, 2 IAM roles, 3 managed policies) and 4 Kubernetes (MicroVMImage, MicroVM, 2 Namespaces). Behind them a real operator reconciling against an emulated MicroVMs API.

logical: 1 node

GET /api/overlay?logical=1&env=dev&tier=prod-ha
  nodes=1 | AWS::S3::Bucket

projectTopology dispatches on which cloud lexicon is present, and hasAws is true, so it takes projectLogical — which filters to n.lexicon === "aws" and drops the Kubernetes half before rendering. What survives is the AWS half, and for this estate that is IAM plumbing plus a bucket, so one headline card comes out.

Worth noting a k8s lens on its own would not fix this. The dispatch would still pick AWS, because AWS nodes are present. A mixed estate needs the lenses composed rather than chosen between — which is the design question, and why I'm leaving it here rather than sending a PR.

This is the view kubemicrovm-ops' own docs call "the view to put in front of a platform review".

component status: 2 of 4 grey, by construction

aws-plane     good     live and chant-owned, but no release record exists
golden-image  accent   no release record and nothing observed live
operator      neutral  no release record and nothing observed live
workload      neutral  no release record and nothing observed live

Status resolves per CloudFormation stack, so aws-plane answers and the other two cannot ever: operator is a Helm release, workload is Kubernetes custom resources. Neither has a stack, so neither has evidence — permanently neutral however healthy the estate is.

Both greys are the Kubernetes half. For an estate whose whole pitch is that it spans two planes, the two views that should show that best are the two that show it least.

What does work, for calibration

Not a complaint about the whole surface — the rest reads well on this estate:

• resources / entity graph: 11 nodes, cross-lexicon edges drawn, 9 good under the live overlay
• component DAG: 4 components, 3 waves, correct edges
• /api/resources: 7 under aws-plane, 4 under workload, uncorrelated: 0 (since fix: correlate resources to components against the paths chant emits #136)
• behold export: 66 clean snapshots, deploy-ready Cloudflare bundle (since fix: ask for the forge a project declares, not gitlab regardless #137)

So the gap is specifically the two layers this issue names, and it is the difference between "this works" and "this is worth showing to someone".

Happy to test against this estate — it stands up free in about four minutes with ./go prod-ha, no AWS account.

[lex00]

Another k8s project hitting this, with a measurement that may be useful for scoping.

fountain-ops (pure k8s, 11 resources, live --env local) renders logical as 0 nodes / 1426 bytes, byte-identical to components — so the two are indistinguishable from each other as well as empty.

Confirming this is the AWS-only-by-design behaviour described here rather than something new: src/logical.ts's headline kinds are literal AWS::*, so a k8s estate matches nothing and the projection is correctly empty.

What a k8s equivalent would have to project, from what this estate actually contains:

AWS analogue	k8s
region / VPC / subnet containment	cluster → namespace containment
headline card per composite	Deployment (or the workload kind) with its Service and PVC folded in
security-group edges	Service → selector → workload

fountain-ops is a reasonable small test case if one is wanted: 11 resources, one namespace, four Deployments each with a Service, one PVC, one CronJob. Enough containment to be non-trivial, small enough to eyeball.

Not asking for it here — #131 is the one that makes the empty result legible, and that fixes the reported symptom without any of this. Recording the data point since a second lexicon now wants the lens.

[lex00]

Item 1 is done — #141 merged. Recording where that leaves the track, since the acceptance criterion here is a decomposition rather than a single PR.

Done

Logical zoom beyond AWS (item 1). A Kubernetes lens (cluster → namespace ⊃ resource), plus the fix that mattered more: projectTopology composed instead of dispatched.

The dispatch was the real bug. azure && !aws, gcp && !aws, else AWS reads as "pick the substrate this estate is", which is wrong for an estate that is genuinely two — kubemicrovm-ops has both planes, hasAws won, and the Kubernetes half was filtered out before rendering. Composing is safe because every lens already filters to its own lexicon and returns nothing otherwise, so single-substrate projects are byte-identical.

Logical went 1 node → 5 on a standing prod-ha estate. The k8s lens is a denylist where the other three are allowlists, because CRDs make an allowlist structurally unable to work — reasoning in the module header.

Graceful degradation is already covered by #131/#139/#140, so the "never a broken/blank view" half of the acceptance criteria is met independently.

Next, and where the boundary is

Item 2, live status per substrate, is the remaining visible gap and is not fixable here. On kubemicrovm-ops:

aws-plane     good     live and chant-owned
golden-image  accent   no release record and nothing observed live
operator      neutral  no release record and nothing observed live
workload      neutral  no release record and nothing observed live

Worth being precise about why, because behold is closer than it looks. componentStatusColor already prefers row.resources — the {total, present, absent, unobserved} rollup from behold#98/chant#1300 — over the coarse live boolean, and only falls back to CloudFormation-shaped evidence when the rollup is absent. It is absent here: chant components status dev --live --json returns no resources key at all for operator or workload, because status resolves per CFN stack and neither has one.

So the palette is ready and the data is not. Two ways forward, and the choice is a real one:

1. chant populates resources for non-CFN components. The clean fix — behold needs no change, and every consumer benefits. Needs the k8s lexicon to report per-resource presence the way the AWS one does.
2. behold synthesizes the rollup from what it already has. /api/resources gives per-component resources with ownership from the live overlay (7 under aws-plane, 4 under workload, since fix: correlate resources to components against the paths chant emits #136), which is enough to compute {total, present, unobserved} without chant changing.

(2) is tempting and I have not done it, because it changes the evidence source: component status would come from the entity overlay rather than the release ledger, and those can legitimately disagree. That is your call rather than mine.

operator is a third case and probably wants saying explicitly: it is a Helm release with no chant-declared resources at all, so no rollup will ever be non-empty for it. It should likely read as "not something chant observes" rather than as neutral/not-deployed — otherwise a correct estate shows a grey node forever.

Still untouched

Items 3 (cross-substrate live edges), 4 (substrate strip coverage) and 5 (deploy-target genericization) are as filed. Happy to keep going on any of them; item 2 is the one a mixed-substrate demo notices next.

[lex00]

Item 2 is done for k8s, and it turned out not to need behold changes or the contract change I proposed earlier. Correcting that, since I argued for the wrong thing above.

It was not a substrate gap

The tell was in the measurement I posted and I read past it: resources was null for aws-plane too. A CloudFormation component with no rollup rules out "k8s cannot be observed" as the explanation.

Two causes, both now fixed upstream:

1. The consumer never declared what its components own. chant joins live evidence to a component by entity name, falling back to component-name == entity-name unless Component.liveNames says otherwise. Nothing in that estate is called workload or aws-plane, so the join matched nothing and every component reported no rollup. Consumer-side fix, no chant change (kubemicrovm-ops#57).

2. chant built the declared side of every live comparison on parameter defaults. lifecycle diff, snapshot, plan and components status --live all had chant#1483's defect — the same one fixed in graph — so the rollup was computed against a different tier's declarations than the estate deployed. chant#1498.

Result

before   workload  resources: null                     -> neutral
after    workload  {total: 6, present: 6, absent: 0}   -> good

behold needed nothing: componentStatusColor already prefers the rollup over stack evidence and only falls back to the CFN-shaped path when there is no rollup. It was correct the whole time and simply never received one.

So my earlier "two routes, (1) chant populates resources, (2) behold synthesizes it" was a false choice — chant already populates it for every substrate that implements describeResources, which k8s, gcp and azure all do. Do not build (2); it would have papered over two bugs with a second evidence source.

What is genuinely left

operator — a Helm release owning no chant-declared entities, so no rollup will ever exist for it and it stays neutral however healthy the chart is. That is the one case that really does need the deploy-unit path: a helm-upgrade capability plus describeStackStatus over helm status, which maps onto StackStatusObservation almost field-for-field. Tracked on chant#1495, now retitled in scope to Helm rather than "non-CFN" generally.

Also worth noting for behold specifically: stackObserver is plugins.find((p) => p.describeStackStatus) — singular. If Helm and AWS both gain the hook, a mixed estate gets one observer for all components. Not biting today because only one lexicon implements it.

With #141 (logical) and this, items 1 and 2 are done for k8s. Items 3–5 untouched.

[lex00]

Decomposition, per the tracking issue's own acceptance bar. Filed today after a full read of chant's docs + lexicon internals and this repo's render path:

k8s family (first)

• topology lens: nest the k8s half inside the managed-cluster card (EKS/AKS/GKE) #142 — topology lens nests the k8s half inside the managed-cluster card (EKS/AKS/GKE): the one-graph claim at the logical zoom
• k8s logical lens: edges from declared attributes (selector, ingress backend, scaleTargetRef) #143 — k8s lens edges from declared attributes (selector / ingress backend / scaleTargetRef)
• runtime tier: the owning workload renders outside its own box, and /api/refresh ignores the zoom #144 — runtime tier: owner card inside its own box, /api/refresh honors the zoom, a real runtime status colour at the pinhole seam
• adopt gates on _status === "foreign", but the IR carries "warn" #145 — Adopt gates on the translated status vocabulary and can never fire
• e2e: a mixed-substrate (CC) logical acceptance run — assert the cluster join, one root, runtime tier #148 — a CC logical acceptance run asserting the join (the assertion the aws/azure/gcp scripts all skip)

helm

• helm: the substrate renders nowhere — no logical presence, no live artifact join, no substrate entry #146 — artifact-presence join + logical release boxes + substrate entry (chant#1495 piece 4 covers the component-status half)

azure/gcp

• value-match: typeSegment cannot see Azure kinds, so azure estates lose name-match edges #147 — value-match cannot see `Microsoft.*/x` kinds
• the remaining substrate work is chant-side and already tracked there: chant#1495 (component status is CFN-shaped end to end), chant#1213/#1214 (D/E azure), chant#1210/#1211 (D/E gcp), chant#1491 (liveNames on the component IR → the composites tier only works for projects that use chant Composites, and a component DAG is substrate-neutral #138 here), chant#1488/#1489 (k8s binding + detail tiers)

Status-strip coverage for fly/helm and the deploy-target genericization rows of this issue are covered by #146 and were largely landed by #99/#106; what remains after the list above is fly parity, which has no lane yet.

[lex00]

Closing as decomposed — this umbrella's list no longer matches the code. Where each bullet landed:

1. Logical zoom beyond AWS — lenses exist for k8s (src/logical-k8s.ts), helm (src/logical-helm.ts, helm: the substrate renders nowhere — no logical presence, no live artifact join, no substrate entry #146/feat: the helm substrate renders — artifact presence, release boxes, substrate entry (#146) #157), azure, and gcp (feat(azure): live overlay + logical zoom (RG-nested topology) #102), composed in projectTopology; the k8s lens draws k3d clusters and helm releases since feat: the k3d/floci estates render whole — cluster root, helm releases, honest component status #159. Remaining: fly only → logical lens for fly — or a graceful absence #167.
2. Live status per substrate — componentStatusColor paints from the substrate-neutral resource rollup first (feat: resource-rollup component status (substrate-neutral) #98/feat(aws): live overlay + logical zoom on resource-rollup status #100), the deploy-unit registry covers cfn-deploy/kubectl-apply/helm-upgrade (chant#1495), and the absent-stack accent bug died in feat: the k3d/floci estates render whole — cluster root, helm releases, honest component status #159. Done.
3. Cross-substrate topology live — value-match, k8s declared-attribute joins (k8s logical lens: edges from declared attributes (selector, ingress backend, scaleTargetRef) #143), and cluster anchoring (feat: cross-substrate live overlay -- preserve the IR's cross-provider edges in --live #103/topology lens: nest the k8s half inside the managed-cluster card (EKS/AKS/GKE) #142, k3d-aware) run on both paths; what's still lost live is now an empirical question → cross-provider edges in live overlays — measure what's still lost vs the source graph #166.
4. Substrate strip coverage — helm/k3d/floci-az/floci-gcp landed along the way; fly, GitHub Actions, and temporal pills landed in feat: composites joins by declared ownership; the target lens and substrate strip stop being AWS-only #162. Done.
5. Deploy target genericization — the feat: per-substrate target lens for live/diff/reconcile #99 override table existed but nothing populated it, so a picked target only ever reached AWS_ENDPOINT_URL; fixed in feat: composites joins by declared ownership; the target lens and substrate strip stop being AWS-only #162 (optsFromQuery resolves substrateTargets, chosen endpoint reaches every declared substrate's var).

Follow-ups: #166, #167. The forge-executor track is #61 (now decomposed into #163/#164/#165).