feat(core): ambient build context (experiment, for evaluation)

[laazyj]

What & why

Refs #386. This is a demonstration for evaluation, not a merge candidate — opened as a draft deliberately. It exists so the trade-off can be read as code rather than argued in the abstract. The recommendation at the bottom of this description is still to ship the lint rule (#398) and hold this.

Stacked on the five fixes (#390, #393, #394, #395, #396), because the demonstration works by removing the threading those PRs add and showing their regression tests still pass.

The mechanism

compose and taggedBuilder push the context they are building with onto a stack for the duration of that build() call. resolve falls back to the top of that stack when handed no context of its own. A sub-builder built inside an enclosing build() inherits the enclosing context whether or not anyone remembered to pass it down. An explicit context argument always wins — the ambient value is a fallback for the undefined case, never an override.

What it buys that neither listed option does

Refs work through a sub-builder with no action from the builder's author:

• The lint rule catches the mistake at author time, but only inside this repo — @composurecdk/eslint-plugin is private: true, so it never reaches a consumer writing their own builder.
• The uniform three-parameter signature would not have prevented two of the four live bugs; s3 and cloudfront already had the parameter and still dropped the context.

This is the only one of the three that fixes the failure for code this repo does not lint.

The demonstration (subset, as requested)

ec2 and s3 have had their explicit threading removed, and their regression tests from #393/#394 pass unchanged. To confirm the tests exercise the new mechanism rather than leftover plumbing, drop ?? currentAmbientContext() from resolve and re-run — both fail with the original Ref to "…" cannot be resolved: component not found in context. I ran exactly that check; it fails as expected.

The other three fixed packages keep their explicit threading, so the branch also shows the two styles coexisting — what any real migration would look like.

What it costs — please read this part

Documented in full in docs/proposals/ambient-build-context.md:

• Data flow becomes implicit. Thirty builders thread context by hand today, and that explicitness is a deliberate property of the codebase. Reading a builder no longer tells you where its sub-builder's refs resolve from. This is the real objection.
• The parameter does not actually go away. build(scope, id, context?) is the public Lifecycle contract and callers pass it, so a conduit builder keeps an unused parameter (see the no-unused-vars disable on VpcBuilder.build). I tried removing it outright first — it narrows the public signature and broke ec2's own test. The ceremony is reduced, not eliminated.
• It weakens a real error. A ref that should fail loudly because a dependency was never declared can instead find a same-named component in an enclosing context and resolve to the wrong thing. Narrow, but it trades a loud failure for a silent mis-wire.
• A dual-package trap. The stack must live on globalThis under a Symbol.for key — module scope would give the ESM and CommonJS copies separate stacks, so an ESM push would be invisible to a CommonJS resolve, failing exactly the way this mechanism exists to prevent and only in a dual-loaded process. Same hazard REF_BRAND and ADR-0007 address. A test pins it.
• Synchrony is load-bearing. A plain stack is safe only because Lifecycle.build returns T and never a promise. If build ever became async this needs AsyncLocalStorage, which is Node-only.

Scope if adopted

ADR-scale — it changes resolve's contract for every package. It would need an ADR, a migration removing the now-redundant threading from the other 28 builders, and a module-compat test proving cross-realm behaviour against genuinely dual-loaded copies rather than the single-process proxy used here.

Checklist

• Linked to an issue (or it's a small, obvious fix)
• npm run verify passes locally — with one exception, see below
• Tests added/updated for the change — 12 cases covering nesting, throw-safety, explicit-wins precedence, the no-push-on-undefined case, and the global-registry invariant
• If it adds an example stack: registered, listed in the examples README, and covered by a smoke test that exercises its runtime behaviour — n/a, no example stack

On npm run verify: every gate passes (format:check, build, catalogue:check, check:exports, lint, cdk-floors:check, validate, test — the full suite across 24 projects) except actionlint, which could not run: its shellcheck binary download returns 403 through this environment's proxy. No file under .github/workflows/ is touched.

---

Generated by Claude Code