@intentius/chant 0.56.0 → 0.58.0

package/src/components/index.ts

@@ -95,7 +95,7 @@ export {
   accumulateComponentOutputs,
   runComponentDeploy,
   runInterpretDriver,
-  DriverGateUnsupportedError,
+  type GateContext,
   DependencyCycleError,
   UnknownDependencyError,
   DriverRunFailure,
@@ -108,8 +108,3 @@ export {
   SingleHostComposeComponent,
   type SingleHostComposeComponentConfig,
 } from "./presets/index";
-export {
-  type ComponentTemporalCodegen,
-  type ComponentTemporalCodegenOptions,
-  loadComponentTemporalCodegen,
-} from "./temporal-codegen-loader";

package/src/components/manifest-persistence.test.ts

@@ -16,7 +16,6 @@ vi.mock("../lifecycle/git", () => ({
 const {
   maybePersistBuildManifest,
   extractRunManifest,
-  extractRunManifestFromPhaseOutputs,
 } = await import("./manifest-persistence");
 
 function makeManifest(component: string, digest: string): BuildArchiveManifest {
@@ -67,23 +66,6 @@ describe("extractRunManifest", () => {
   });
 });
 
-describe("extractRunManifestFromPhaseOutputs", () => {
-  test("finds the manifest across phase outputs (Temporal workflow result shape)", () => {
-    const manifest = makeManifest("svc", "sha256:abc");
-    expect(
-      extractRunManifestFromPhaseOutputs({
-        Build: { archivePath: "image.tar", digest: "sha256:abc", manifest },
-        Apply: { ok: true },
-      }),
-    ).toEqual(manifest);
-  });
-
-  test("returns undefined for undefined/empty phaseOutputs", () => {
-    expect(extractRunManifestFromPhaseOutputs(undefined)).toBeUndefined();
-    expect(extractRunManifestFromPhaseOutputs({})).toBeUndefined();
-  });
-});
-
 describe("maybePersistBuildManifest", () => {
   beforeEach(() => {
     persistBuildManifestMock.mockReset();
@@ -102,8 +84,8 @@ describe("maybePersistBuildManifest", () => {
     expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
   });
 
-  test("a pre-resolved manifest (Temporal path) takes precedence over records", async () => {
-    const preResolved = makeManifest("svc", "sha256:temporal");
+  test("a pre-resolved manifest takes precedence over records", async () => {
+    const preResolved = makeManifest("svc", "sha256:preresolved");
     persistBuildManifestMock.mockResolvedValue({ commit: "b".repeat(40) });
 
     const outcome = await maybePersistBuildManifest({

package/src/components/manifest-persistence.ts

@@ -13,10 +13,9 @@
  * doc: a manifest write is a git commit + push, a non-idempotent side effect
  * with real-world I/O — exactly what `driver.ts` resists taking on (it is
  * exercised in tests against a bare `CapabilityRegistry` with no lifecycle
- * dependency at all) and what Temporal workflow code must never do directly
- * (replay-safety). The CLI calls this after `runComponents`/`handle.result()`
- * reports success, the same place `maybeRecordAutoRelease` is already
- * called from (../cli/handlers/run.ts).
+ * dependency at all). The CLI calls this after `runComponents` reports
+ * success, the same place `maybeRecordAutoRelease` is already called from
+ * (../cli/handlers/run.ts).
  *
  * **Extraction is duck-typed, not capability-specific.** `docker-build`,
  * `generate-sbom`, `extract-config-bom`, and `addArchiveTemplate` (the
@@ -68,25 +67,6 @@ export function extractRunManifest(records: DriverStepRecord[]): BuildArchiveMan
   return found;
 }
 
-/**
- * Same manifest extraction as `extractRunManifest`, but over a component
- * Temporal workflow's returned `phaseOutputs` (`{ [phase]: output }`) —
- * mirroring ./auto-release.ts's `extractRunDigestFromPhaseOutputs`, the
- * `--temporal` CLI path's counterpart, since that path never sees individual
- * step records either.
- */
-export function extractRunManifestFromPhaseOutputs(
-  phaseOutputs: Record<string, Record<string, unknown>> | undefined,
-): BuildArchiveManifest | undefined {
-  let found: BuildArchiveManifest | undefined;
-  for (const output of Object.values(phaseOutputs ?? {})) {
-    if (isManifestShaped(output)) {
-      found = output.manifest;
-    }
-  }
-  return found;
-}
-
 /** Explicit reasons `maybePersistBuildManifest` declined to write — never a thrown error, mirroring ./auto-release.ts's `AutoReleaseSkipReason`. */
 export type ManifestPersistSkipReason = "opted-out" | "run-not-successful" | "no-manifest";
 
@@ -101,7 +81,7 @@ export interface ManifestPersistRunInfo {
   success: boolean;
   /** The component's step records (local executor), used to locate the accumulated manifest via `extractRunManifest`. Mutually exclusive with `manifest`. */
   records?: DriverStepRecord[];
-  /** A manifest already resolved by the caller (e.g. a future durable/Temporal path that has its own phaseOutputs-shaped extraction). Takes precedence over `records` when both are given. */
+  /** A manifest the caller already resolved by its own means. Takes precedence over `records` when both are given. */
   manifest?: BuildArchiveManifest;
 }
 

package/src/components/pilots/pilots-lint-clean.test.ts

@@ -52,17 +52,18 @@ describe("Real pilots lint clean under COMP* (#562 acceptance criteria)", () =>
     expect(runAll(ctx)).toEqual([]);
   });
 
-  it("the Neo4j fan-out pilot produces zero COMP* diagnostics other than the expected COMP004 (gate requires Temporal)", () => {
+  it("the Neo4j fan-out pilot produces zero COMP* diagnostics other than the expected COMP004 (a gate ends the run pending approval)", () => {
     // The Neo4j pilot's Node-1 approval gate is a deliberate design choice
-    // (see neo4j-fanout.pilot.ts's own docstring and
-    // ../driver.ts's DriverGateUnsupportedError / docs/components/
-    // orchestration.mdx's "Temporal is optional" aside) — it is the one real
-    // pilot that genuinely needs the durable backend, so COMP004 firing here
-    // is the *correct*, expected signal, not a defect. A real project would
-    // acknowledge it with `// chant-disable-next-line COMP004 -- <reason>`
-    // once authored as an actual `*.component.ts` file (see
-    // ../../lint/rules/comp/comp004-gate-needs-temporal.ts and the
-    // comp004/pass fixture demonstrating that opt-out end to end).
+    // (see neo4j-fanout.pilot.ts's own docstring, and ../driver.ts on
+    // gate-as-fact, #2119) — a run reaching it stops there pending `chant
+    // approve`, which is exactly the standing human wait COMP004 exists to
+    // surface, so COMP004 firing here is the *correct*, expected signal, not
+    // a defect. A real project would acknowledge it with a file-level
+    // `// chant-disable COMP004 -- <reason>` once authored as an actual
+    // `*.component.ts` file — a COMP* diagnostic is reported for the whole
+    // component and carries no line, so `-line`/`-next-line` do not suppress
+    // one (see ../../lint/rules/comp/comp004-gate-needs-durable-runtime.ts
+    // and the comp004/pass fixture demonstrating that opt-out end to end).
     const ctx = contextFor([neo4jCluster]);
     const diagnostics = runAll(ctx);
     expect(diagnostics.every((d) => d.checkId === "COMP004")).toBe(true);

package/src/components/run-progress.ts

@@ -10,17 +10,17 @@
  * single-component path, ./cli-support.ts's `runComponents`), that never
  * changes run ordering, gating, `onFailure`, rollback, or exit codes — it
  * only reports what already happened, as it happens. See ./driver.ts's
- * module doc for what actually executes; streaming progress on the *durable*
- * (Temporal) path is a separate, later concern (Temporal already exposes
- * durable run state via `chant run status`/`log`).
+ * module doc for what actually executes; streaming progress from a hosted
+ * runtime is a separate, later concern (`chant run status`/`log` already ask
+ * one for the run state it keeps).
  *
  * `RunProgressEvent` is a discriminated union on `type`, one JSON object per
  * NDJSON line (see `ndjsonProgressSink` below and
  * ../cli/handlers/run.ts's `--progress-json` wiring).
  */
 
-/** Terminal status for a wave/component/phase/run — mirrors DriverStepRecord's ok/fail split, collapsed to the two outcomes a consumer renders progress against. */
-export type RunProgressStatus = "ok" | "failed";
+/** Terminal status for a wave/component/phase/run — mirrors `DriverRunResult.status`'s three outcomes (#2119): `gated` is neither, and reporting it as `failed` would have a progress consumer page someone for a decision nobody has made yet. */
+export type RunProgressStatus = "ok" | "failed" | "gated";
 
 /** The run is about to start. `waves` are the parallel-safe waves the run will attempt, in order (see resolveComponentGraph) — 1-based wave numbers in every other event index into this array. */
 export interface RunStartEvent {
@@ -108,7 +108,7 @@ export type RunProgressSink = (event: RunProgressEvent) => void;
  * Build a sink that writes `JSON.stringify(event) + "\n"` to `write` (default:
  * `process.stdout.write`), one line per event, as they happen — the
  * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts, for both the
- * `--components` driver's `RunProgressEvent`s and the Temporal Op path's
+ * `--components` driver's `RunProgressEvent`s and the Op path's
  * `StepRecord`s, chant #1676). Kept separate from `driver-output.ts`'s
  * end-of-run renderers: this emits *during* the run, one line at a time;
  * `renderDriverJson`/`renderDriverHuman` render the completed

package/src/components/verbs/run-agent.ts

@@ -86,9 +86,8 @@
  *    `run(ctx, input)` was called with, plus (since #1944) the exact `output`
  *    `run()` returned — `../capability.ts`'s `Capability.rollback` grew an
  *    optional third parameter for precisely this, and ../driver.ts's saga
- *    unwind (both the local in-process path and, via
- *    `lexicons/temporal/src/component-op/{activities,serializer}.ts`, the
- *    durable Temporal path) always threads it through. `run()` records the
+ *    unwind (and any hosting runtime that splits `run`/`rollback` across
+ *    process boundaries) always threads it through. `run()` records the
  *    sprite id and exact pre-run checkpoint id two ways: in a private
  *    `WeakMap` keyed by the exact `input` object (works only when `rollback`
  *    is called with that same object — true in-process, e.g. this module's
@@ -115,18 +114,13 @@
  *    commented no-op return — the same pattern
  *    `../../lexicons/aws/src/components/host-delivery.ts`'s `code-deploy`
  *    rollback uses (`if (!deploymentId) return;`) — rather than throwing.
- *    **Before #1944**, the Temporal durable path (`run` and `rollback`
- *    executing as separate Activities, each rebuilding `input` fresh via
- *    `resolveStepInput`) never gave the `WeakMap` a hit, so a fresh sprite's
- *    rollback there silently degraded to that no-op; passing `output` through
- *    (this revision) closes that gap directly, without redesigning the
- *    component-op wire format — see #1944's PR description for why this was
- *    chosen over the "make the degrade loud" alternative. The generated
- *    workflow's saga-unwind loop (`lexicons/temporal/src/component-op/
- *    serializer.ts`) also no longer swallows a rollback failure silently
- *    (any capability's, not just this one) — it now logs it and surfaces it
- *    via a `RollbackFailed` search attribute, defense in depth for a rollback
- *    failure unrelated to identity (e.g. the sprite backend itself erroring).
+ *    **Before #1944**, a hosted path running `run` and `rollback` as separate
+ *    units of work — each rebuilding `input` fresh via `resolveStepInput` —
+ *    never gave the `WeakMap` a hit, so a fresh sprite's rollback there
+ *    silently degraded to that no-op; passing `output` through (this revision)
+ *    closes that gap directly, without redesigning the component-op wire
+ *    format — see #1944's PR description for why this was chosen over the
+ *    "make the degrade loud" alternative.
  *  - **Destroy vs. leave-alive.** `run()` destroys a freshly created (not
  *    `workspace.spriteName`-reused) sprite only when `turn.status ===
  *    "completed"`. An ordinary failed turn leaves the sprite alive — it
@@ -526,8 +520,8 @@ export function createRunAgentCapability(
     async rollback(_ctx, input, output): Promise<void> {
       // The durable-safe channel first (#1944): `output` is the exact value
       // this step's own `run()` returned, threaded through by every current
-      // caller (../driver.ts locally, lexicons/temporal/src/component-op/
-      // {activities,serializer}.ts across the Activity boundary) — it
+      // caller (../driver.ts locally, and a hosting runtime across whatever
+      // process boundary it puts between the two) — it
       // survives even when `rollback()` is called with a freshly-rebuilt
       // `input` object the in-process WeakMap below has never seen. Falls
       // back to the WeakMap for a caller that predates/never threads

package/src/components/verbs/verify.ts

@@ -6,8 +6,8 @@
  * configured identity policy and **throws** on any failure, so composing it
  * before an apply phase fails the deploy the same way a thrown capability
  * error already halts `driver.ts`'s step execution — no new failure
- * mechanism, no gate-signal/human-approval semantics (that is `Gate`,
- * ../component.ts, a different, durable-runtime-only concept). `verify` is a
+ * mechanism, no human-approval semantics (that is `Gate`, ../component.ts, a
+ * different concept: a fact on the gate ledger). `verify` is a
  * synchronous, local-executor-safe capability, exactly like `health-gate`
  * (./wait-verify.ts).
  *

package/src/deep-observation.test.ts

@@ -12,6 +12,7 @@ import {
   normalizeDeepProperties,
   type DeepNormalizationHooks,
 } from "./deep-observation";
+import { HELD_ELSEWHERE_TAG, heldElsewhere, isNormalizedHeldElsewhere } from "./held-elsewhere";
 
 describe("the deep observation envelope", () => {
   test("is discriminated by its version literal", () => {
@@ -319,6 +320,80 @@ describe("deepValueEqual", () => {
   });
 });
 
+// #2162 — a `heldElsewhere()` marker is declared on purpose, not authored
+// data to walk into and not an unresolved intrinsic. It must survive
+// normalization as one recognizable leaf, all the way through
+// `flattenDeepProperties` and `deepPathSet`, or `deep-diff.ts` has nothing
+// to key its held classification on.
+describe("normalizeDeepProperties — heldElsewhere() markers (#2162)", () => {
+  test("normalizes to a JSON-safe tagged leaf rather than being walked as a two-key object", () => {
+    const out = normalizeDeepProperties(
+      { replicas: heldElsewhere<number>({ by: "hpa", reason: "the autoscaler owns replicas after the first apply" }) },
+      { entityType: "Deployment", side: "declared" },
+    );
+    expect(out).toEqual({
+      replicas: { heldElsewhere: HELD_ELSEWHERE_TAG, by: "hpa", reason: "the autoscaler owns replicas after the first apply" },
+    });
+    expect(isNormalizedHeldElsewhere(out.replicas)).toBe(true);
+  });
+
+  test("is not masked, unresolved, or subjected to a lexicon's own hooks", () => {
+    const out = normalizeDeepProperties(
+      { password: heldElsewhere<string>({ by: "operator", reason: "rotated out of band" }) },
+      {
+        entityType: "T",
+        side: "declared",
+        // Scoped to the one path under test — a hook that fires on every
+        // node (including the root) would mask/unresolve the whole tree,
+        // which is a hazard of the hook, not something this test is after.
+        hooks: { unresolved: (n) => n.path === "password", mask: (n) => n.path === "password" },
+      },
+    );
+    // If either hook had run ahead of the held check, this would be
+    // UNRESOLVED or MASKED instead — the key name looks secret-bearing
+    // (`isSensitiveKey`) and both hooks say yes too, and the held check
+    // still has to win.
+    expect(isNormalizedHeldElsewhere(out.password)).toBe(true);
+  });
+
+  test("nested inside a property-kind declarable, still normalizes to the tagged leaf", () => {
+    const propertyDeclarable = (entityType: string, props: Record<string, unknown>) => ({
+      entityType,
+      kind: "property",
+      props,
+    });
+    const out = normalizeDeepProperties(
+      {
+        Behavior: propertyDeclarable("HorizontalPodAutoscaler.Behavior", {
+          scaleUp: heldElsewhere<Record<string, unknown>>({ by: "hpa", reason: "the controller tunes its own policy" }),
+        }),
+      },
+      { entityType: "HorizontalPodAutoscaler", side: "declared" },
+    );
+    expect(isNormalizedHeldElsewhere((out.Behavior as Record<string, unknown>).scaleUp)).toBe(true);
+  });
+});
+
+describe("flattenDeepProperties — heldElsewhere() markers (#2162)", () => {
+  test("addresses the marker as one leaf path, not two", () => {
+    const normalized = normalizeDeepProperties(
+      { replicas: heldElsewhere<number>({ by: "hpa", reason: "x" }) },
+      { entityType: "Deployment", side: "declared" },
+    );
+    const flat = flattenDeepProperties(normalized);
+    expect([...flat.keys()]).toEqual(["replicas"]);
+    expect(isNormalizedHeldElsewhere(flat.get("replicas"))).toBe(true);
+  });
+});
+
+describe("deepPathSet — heldElsewhere() markers (#2162)", () => {
+  test("records the held property's own path, not synthetic sub-paths into by/reason", () => {
+    const marker = heldElsewhere<number>({ by: "hpa", reason: "x" });
+    const set = deepPathSet({ replicas: marker });
+    expect([...set].sort()).toEqual(["replicas"]);
+  });
+});
+
 // #1314 — a nested property authored through a lexicon's generated constructor
 // is authored data, not an opaque class instance. Collapsing it to UNRESOLVED
 // left the declared side empty while the live side held the real value, so

package/src/deep-observation.ts

@@ -44,6 +44,7 @@
  */
 
 import type { UnobservedEntity } from "./observation";
+import { isHeldElsewhere, isNormalizedHeldElsewhere, normalizeHeldElsewhere } from "./held-elsewhere";
 
 /**
  * A live property tree for one declared entity, already normalized by the
@@ -67,6 +68,23 @@ export interface DeepResourceObservation {
    * very different answers to an operator.
    */
   fieldOwners?: Record<string, string>;
+  /**
+   * The paths this entity's declaration claims (#2160) — every property chant
+   * set, flattened into the diff's own grammar and sorted. Built by core in
+   * `lifecycle/deep-observe.ts` from the declaration's `props`, never by a
+   * reader: a lexicon has no more to say about it than the props it was handed.
+   *
+   * It rides here, on the live row, because this is the envelope a consumer
+   * holds. With it, a live value classifies three ways instead of two — chant
+   * set this and it matches, chant set this and it moved, chant never set it —
+   * and only the middle one is drift. Absent for a live entity nobody declared,
+   * which has no claim to carry.
+   *
+   * Complementary to {@link fieldOwners} rather than a replacement: the manager
+   * name says *who* holds a field, which is strictly more than "not chant". See
+   * `../claimed-fields.ts`.
+   */
+  claimedFields?: readonly string[];
 }
 
 /**
@@ -340,6 +358,11 @@ export function deepPathSet(tree: Record<string, unknown>): Set<string> {
       out.add(path);
       out.add(pattern);
     }
+    // A held marker (#2162) is one declared value, not a `{ by, reason }`
+    // object to walk into — same leaf treatment `normalizeDeepProperties`
+    // gives it, so this path set agrees with what the normalized tree
+    // actually looks like a path down.
+    if (isHeldElsewhere(value)) return;
     if (Array.isArray(value)) {
       value.forEach((el, i) => walk(el, joinIndex(path, i), joinPattern(pattern)));
       return;
@@ -418,6 +441,24 @@ export function normalizeDeepProperties(
   };
 
   const normalizeValue = (value: unknown, path: string, pattern: string, key: string): unknown => {
+    // A `heldElsewhere()` marker (#2162) — declared on purpose, not
+    // unresolved and not a plain object to walk into. Checked ahead of even
+    // the secret-masking rules below: the marker carries no value at all,
+    // only who holds the field and why, so there is nothing for masking to
+    // protect and masking it would destroy the one thing worth reporting —
+    // a `heldElsewhere()` on a `password`-shaped key ("an operator rotates
+    // this out of band") must still say so, not collapse to `[REDACTED]`.
+    // Normalized to a JSON-safe tagged leaf so its identity survives this
+    // pass and a `--json` round-trip; `deep-diff.ts` reads the tag to
+    // report a live difference here as held rather than as drift, on
+    // either side (a lexicon's own reader never produces this shape, so
+    // the check is safe on the live tree too, though only the declared
+    // side ever carries one in practice). Checked ahead of the
+    // array/object branches too, same reason a property-Declarable is: it
+    // would otherwise be walked as a two-key plain object and lose the
+    // very identity that makes it a marker rather than authored data.
+    if (isHeldElsewhere(value)) return normalizeHeldElsewhere(value);
+
     if (isSensitiveKey(key)) return MASKED;
     // The lexicon's structural mask — same collapse, path-shaped rather than
     // key-named (a k8s Secret's `data.*` no matter what the key is called).
@@ -426,6 +467,7 @@ export function normalizeDeepProperties(
     // expression-string reference — collapses exactly like a class-instance
     // intrinsic does below.
     if (hooks?.unresolved?.(nodeOf(path, pattern, key, value))) return UNRESOLVED;
+
     if (isJsonPrimitive(value)) return value;
 
     // A PROPERTY-kind Declarable is authored data wearing a class, not an
@@ -567,6 +609,12 @@ export function flattenDeepProperties(
   };
 
   const walk = (value: unknown, path: string, pattern: string): void => {
+    // A normalized held marker (#2162) is one value, not a two-key object to
+    // descend into — same reason UNRESOLVED and a JSON primitive are leaves.
+    if (isNormalizedHeldElsewhere(value)) {
+      out.set(path, value);
+      return;
+    }
     if (Array.isArray(value)) {
       if (value.length === 0) {
         out.set(path, []);

package/src/discovery/collect.test.ts

@@ -395,8 +395,8 @@ describe("collectEntities with composites", () => {
 
 describe("collectEntities — default exports (op files)", () => {
   test("two files with `export default` do not collide (keyed per file)", () => {
-    const apply = createMockEntity("Temporal::Op");
-    const reconcile = createMockEntity("Temporal::Op");
+    const apply = createMockEntity("Chant::Op");
+    const reconcile = createMockEntity("Chant::Op");
     const result = collectEntities([
       { file: "ops/apply.op.ts", exports: { default: apply } },
       { file: "ops/reconcile.op.ts", exports: { default: reconcile } },
@@ -409,7 +409,7 @@ describe("collectEntities — default exports (op files)", () => {
   });
 
   test("a single default export is collected (not dropped)", () => {
-    const op = createMockEntity("Temporal::Op");
+    const op = createMockEntity("Chant::Op");
     const result = collectEntities([{ file: "ops/deploy.op.ts", exports: { default: op } }]);
     expect(result.get("deploy")).toBe(op);
   });

package/src/discovery/files.ts

@@ -3,10 +3,10 @@ import { existsSync } from "node:fs";
 import { join, relative } from "node:path";
 
 /**
- * Marker chant writes at the top of files it generates (worker/workflow/activities
- * bootstrap for Temporal Ops, etc.). Discovery must not treat these as authored
- * infra source: they hold no Declarables, they self-execute on import (the worker
- * bootstrap calls `run()`), and they use runtime patterns the authored-source lint
+ * Marker chant writes at the top of files it generates (a hosting lexicon's
+ * worker/bootstrap output, and the like). Discovery must not treat these as
+ * authored infra source: they hold no Declarables, they self-execute on import,
+ * and they use runtime patterns the authored-source lint
  * rules forbid (dynamic `process.env[...]` access, spreads). Skipping them keeps
  * `chant lint`/`build` from importing or linting the tool's own output.
  */

package/src/discovery/fold-import.ts

@@ -38,7 +38,11 @@ import {
   SUPPORTED_UNARY_OPERATORS,
 } from "../fold/subset";
 import { importModule } from "./import";
-import { collectParamDependencies } from "./param-deps";
+import {
+  collectCompositeOrigins,
+  collectParamDependencies,
+  type CompositeParamScope,
+} from "./param-deps";
 import { setPathProvenance } from "../provenance";
 import { intrinsicCallFoldsEagerly, type IntrinsicDef } from "../lexicon";
 import type { BuildParamValue } from "../build-params";
@@ -1273,6 +1277,29 @@ interface ResolveCtx {
    * terminates it — see {@link MAX_INTERPRETATION_DEPTH}.
    */
   interpretDepth: number;
+  /**
+   * chant #2161 — the composite whose factory body this context is evaluating,
+   * and how its props are bound there. Present ONLY inside
+   * {@link interpretCompositeFactory}'s body context, so a `new Type(...)` at a
+   * file's own top level records nothing and a nested composite records its own
+   * innermost factory rather than the enclosing one.
+   */
+  compositeParams?: CompositeParamRecorder;
+}
+
+/** chant #2161 — what {@link stampCompositeOrigins} needs at one `new Type(...)` inside a factory body. */
+interface CompositeParamRecorder {
+  /** The composite's declared name, as `Composite(fn, "<name>")` gave it. */
+  composite: string;
+  /** How the factory's single parameter is bound in this body. */
+  scope: CompositeParamScope;
+  /**
+   * The body's own `const` initializers, so a value hoisted out of a member's
+   * props (`const roleName = \`${props.name}-role\``) is still attributed. The
+   * defining module's top-level consts are layered underneath, exactly as
+   * `fold()` sees them.
+   */
+  consts: Map<string, ts.Expression>;
 }
 
 /** `{ value }` when `node`'s shape was recognized and resolved (value may itself be `undefined`/`null` — e.g. an optional composite member that wasn't created); `undefined` when the shape isn't one the live resolver understands (a plain literal, etc.) — callers fall back to the original, unchanged handling for that shape. */
@@ -2149,6 +2176,77 @@ function isLiteralPropertyNameNode(node: ts.PropertyName): boolean {
   return ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node);
 }
 
+/**
+ * chant #2161 — how one admissible factory's parameter is bound in its body,
+ * plus the consts an attribution walk has to follow.
+ *
+ * Built from the SOURCE, not from the argument value: the question is which
+ * expression a member's property was written as, not what it evaluated to. A
+ * factory with no parameter at all still gets a recorder, so every path in its
+ * members records as a literal the composite fixes, which is exactly what a
+ * parameterless composite does.
+ */
+function compositeParamRecorder(
+  factory: InterpretableFactory,
+  moduleConsts: ReadonlyMap<string, ts.Expression>,
+): CompositeParamRecorder {
+  const whole = new Set<string>();
+  const destructured = new Map<string, string>();
+  const param = factory.fn.parameters[0];
+  if (param) {
+    if (ts.isIdentifier(param.name)) {
+      whole.add(param.name.text);
+    } else if (ts.isObjectBindingPattern(param.name)) {
+      for (const el of param.name.elements) {
+        const key = bindingElementPropKey(el);
+        if (key !== undefined && ts.isIdentifier(el.name)) destructured.set(el.name.text, key);
+      }
+    }
+  }
+
+  // Body `const`s layered over the defining module's, so a hoisted value is
+  // followed. `interpretCompositeFactory` deletes shadowed names from the
+  // context's own const map as it binds values; this map is separate precisely
+  // so the INITIALIZER stays available to the attribution walk.
+  const consts = new Map(moduleConsts);
+  const body = factory.fn.body;
+  if (ts.isBlock(body)) {
+    for (const statement of body.statements) {
+      if (!ts.isVariableStatement(statement)) continue;
+      for (const decl of statement.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.initializer) consts.set(decl.name.text, decl.initializer);
+      }
+    }
+  }
+
+  return { composite: factory.compositeName, scope: { whole, destructured }, consts };
+}
+
+/**
+ * chant #2161 — record, for one `new Type({...})` written inside an interpreted
+ * factory body, which factory parameter produced each of its property paths and
+ * which paths the composite fixes.
+ *
+ * Best-effort and additive, exactly like {@link stampParamDependencies}: a
+ * constructor called with no object literal records nothing, and
+ * `setPathProvenance` keeps the first (innermost) writer.
+ */
+function stampCompositeOrigins(entity: unknown, node: ts.NewExpression, ctx: ResolveCtx): void {
+  const recorder = ctx.compositeParams;
+  if (!recorder) return;
+  if (typeof entity !== "object" || entity === null) return;
+  let propsArg: ts.ObjectLiteralExpression | undefined;
+  for (const argument of node.arguments ?? []) {
+    if (ts.isObjectLiteralExpression(argument)) {
+      propsArg = argument;
+      break;
+    }
+  }
+  if (!propsArg) return;
+  const origins = collectCompositeOrigins(propsArg, recorder.consts, recorder.scope, recorder.composite);
+  for (const [path, origin] of Object.entries(origins)) setPathProvenance(entity, path, origin);
+}
+
 /**
  * Interpret an admissible factory's body against `args`, and assemble the
  * result through chant's own {@link Composite}.
@@ -2196,6 +2294,9 @@ async function interpretCompositeFactory(
     sandbox: ctx.sandbox,
     session: ctx.session,
     interpretDepth: ctx.interpretDepth + 1,
+    // chant #2161 — set unconditionally, and NOT inherited from `ctx`: a nested
+    // composite records its own parameters, never the enclosing one's.
+    compositeParams: compositeParamRecorder(factory, scope.consts),
   };
 
   const bind = (name: string, value: unknown): void => {
@@ -2392,7 +2493,9 @@ async function interpretNewExpression(node: ts.NewExpression, ctx: ResolveCtx):
 
   const ctorArgs: unknown[] = [];
   for (const arg of node.arguments ?? []) ctorArgs.push(await interpretExpression(arg, ctx));
-  return new (Ctor as new (...ctorArguments: unknown[]) => unknown)(...ctorArgs);
+  const instance = new (Ctor as new (...ctorArguments: unknown[]) => unknown)(...ctorArgs);
+  stampCompositeOrigins(instance, node, ctx);
+  return instance;
 }
 
 /**