@intentius/chant 0.57.0 → 0.59.0

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.test.ts

@@ -287,6 +287,25 @@ describe("run() — failed turn: non-zero exit surfaces as status \"failed\", ne
   });
 });
 
+describe("RunAgentTurn[\"status\"] is exactly the two states run() produces (#2072)", () => {
+  it("has no third member: a switch handling only \"completed\" and \"failed\" compiles with no default needed", () => {
+    // Compile-time exhaustiveness check, not a runtime assertion: if a third
+    // member were ever added back to the union (e.g. "interrupted"), this
+    // switch would stop being exhaustive and `tsc` would reject the missing
+    // case, since `identity`'s return type has no branch left to satisfy it.
+    const identity = (status: RunAgentOutput["turn"]["status"]): "completed" | "failed" => {
+      switch (status) {
+        case "completed":
+          return "completed";
+        case "failed":
+          return "failed";
+      }
+    };
+    expect(identity("completed")).toBe("completed");
+    expect(identity("failed")).toBe("failed");
+  });
+});
+
 describe("collectArtifacts — only a \"not found\" read means \"no artifact\"; a genuine infra failure propagates (#1942 review finding 2)", () => {
   it("branch A: readFile rejecting with the sprite-fs \"not found\" shape resolves to empty artifacts.files, not a run() rejection", async () => {
     const { sprites } = makeFakeSprites(succeed); // never writes /work/output — readFile hits the fake's "not found" branch

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
@@ -155,12 +149,6 @@
  *    snapshot folded into a `BuildArchiveManifest` entry (./build-archive.ts)
  *    remains an open question, as does `artifacts.diff`, which `run()` never
  *    populates (the real Sprites API has no built-in diff endpoint).
- *  - Interrupted turns — `turn.status: "interrupted"` stays in the type but
- *    is unreachable from this implementation: any `sprites.exec` rejection
- *    (including one caused by an aborted signal) propagates as a genuine
- *    `run()` failure rather than being classified as an interrupted turn.
- *    Distinguishing "deadline hit mid-run" from "the sprite backend errored"
- *    well enough to surface `"interrupted"` safely is left for #1944.
  *
  * **#1943 (this revision) resolved the transcript-hash basis and
  * sign/verify-gate interop, closing #1941's open "transcript hash basis"
@@ -291,7 +279,7 @@ export interface RunAgentInput {
 
 /** Mirrors fountain's `Turn` shape (`status`/`exit_code`/`started_at`/`ended_at`), even though the turn itself runs on a chant-owned sprite rather than a fountain-managed `Sandbox`. */
 export interface RunAgentTurn {
-  status: "completed" | "failed" | "interrupted";
+  status: "completed" | "failed";
   exitCode: number | null;
   startedAt: string;
   endedAt: string | null;
@@ -526,8 +514,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/detectLexicon.ts

@@ -1,5 +1,22 @@
 import { readFile } from "node:fs/promises";
 
+/**
+ * The message {@link detectLexicons} throws when a scan of the project's
+ * source files turns up no `@intentius/chant-lexicon-*` import at all.
+ *
+ * Named (chant #2222) because one caller has to tell this failure apart from
+ * every other one: `chant lint` reports a lexicon it cannot resolve as an
+ * error diagnostic, but "this directory declares no lexicon and imports none"
+ * is not that. It is a project that lints under the core rules alone, and it
+ * has always been allowed to. See {@link isNoLexiconDetected}.
+ */
+export const NO_LEXICON_DETECTED_MESSAGE = "No lexicon detected in infrastructure files";
+
+/** Whether `error` is the {@link NO_LEXICON_DETECTED_MESSAGE} failure. */
+export function isNoLexiconDetected(error: unknown): boolean {
+  return error instanceof Error && error.message === NO_LEXICON_DETECTED_MESSAGE;
+}
+
 /**
  * Detects which lexicons are being used by analyzing import statements
  * in the provided infrastructure files. Matches any `@intentius/chant-lexicon-*` package.
@@ -32,7 +49,7 @@ export async function detectLexicons(files: string[]): Promise<string[]> {
 
   // Validate results
   if (detectedLexicons.size === 0) {
-    throw new Error("No lexicon detected in infrastructure files");
+    throw new Error(NO_LEXICON_DETECTED_MESSAGE);
   }
 
   return Array.from(detectedLexicons);

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.test.ts

@@ -1276,7 +1276,7 @@ describe("tryFoldFile — registered authoring helpers (#1082)", () => {
               stack: "web",
               inputs: { pVpcId: { stackOutput: { stack: "shared-foundation", name: "oVpcId" } } },
             },
-            { kind: "gate", signalName: "approve", timeout: "24h" },
+            { kind: "gate", gate: "approve", timeout: "24h" },
           ],
         },
       ],

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;
 }
 
 /**