@intentius/chant 0.38.0 → 0.41.0

package/src/codegen/naming.ts

@@ -1,12 +1,32 @@
 /**
  * Collision-free naming strategy for TypeScript class names.
  *
- * 5-phase algorithm:
+ * 6-phase algorithm:
  * 1. Priority names (backward compatibility)
+ * 1a. Reserved names — names this lexicon has already published (chant #1459)
  * 2. Priority aliases (additional short names)
  * 3. Short names (last segment of type)
  * 4. Collision resolution (service-prefixed)
  * 5. Property type aliases (globally unique defs)
+ *
+ * ## Why phase 1a exists
+ *
+ * Phases 3 and 4 assign a short name to whoever asks first and service-qualify
+ * everyone after. Membership of that contest is the whole input set, so a
+ * resource's name was a function of its NEIGHBOURS: removing
+ * `AWS::Athena::Session` upstream freed `Session`, and `AWS::Macie::Session`
+ * silently changed from `MacieSession` to `Session` — a breaking rename for a
+ * resource whose schema had not moved. Adding a resource does the same in
+ * reverse: `AWS::QuickSight::Space` appearing renamed `AWS::SageMaker::Space`
+ * from `Space` to `SageMakerSpace`.
+ *
+ * Worse, it is reversible. These are read-only registry types that come and go,
+ * so a name could flip back on the next upgrade and break consumers again.
+ *
+ * Reserved names invert the bias: a name that has already shipped belongs to
+ * the type that shipped it, and a newcomer colliding with it gets qualified
+ * instead. A published name then changes only when its own type disappears,
+ * which is a genuine breaking change rather than an incidental one.
  */
 
 /**
@@ -35,6 +55,40 @@ export interface NamingConfig {
   shortName: (typeName: string) => string;
   /** Extract the service name from a type name (e.g. "Vendor::Service::Resource" → "Service"). */
   serviceName: (typeName: string) => string;
+  /**
+   * chant #1459 — spec type name → the TypeScript name this lexicon has
+   * already published for it, normally read from the committed
+   * `surface.snapshot.json` via {@link reservedNamesFromSnapshot}.
+   *
+   * Claimed before short names are contested, so a shipped name is not taken
+   * away from its owner by an unrelated upstream change. Omit for a lexicon
+   * with no published surface yet; an entry for a type that is no longer in
+   * the input is ignored, so a removed type frees its name for reuse.
+   */
+  reservedNames?: Record<string, string>;
+}
+
+/**
+ * The names a lexicon has already published, read from a committed surface
+ * snapshot (chant #1459).
+ *
+ * The snapshot is keyed by TypeScript name with the spec type inside, which is
+ * exactly the mapping phase 1a needs, inverted. Only `resource` entries are
+ * reserved: property-type names are derived from their owning resource's name
+ * (phase 5), so pinning the resource pins them, and reserving them separately
+ * would freeze aliases that are meant to follow their parent.
+ */
+export function reservedNamesFromSnapshot(
+  snapshot: { entries?: Record<string, { kind?: string; resourceType?: string }> } | undefined,
+): Record<string, string> {
+  const reserved: Record<string, string> = {};
+  for (const [tsName, entry] of Object.entries(snapshot?.entries ?? {})) {
+    if (entry.kind !== "resource" || !entry.resourceType) continue;
+    // First writer wins: a snapshot that somehow lists one spec type under two
+    // names keeps the earlier, rather than silently preferring iteration order.
+    reserved[entry.resourceType] ??= tsName;
+  }
+  return reserved;
 }
 
 export class NamingStrategy {
@@ -58,6 +112,23 @@ export class NamingStrategy {
       }
     }
 
+    // Phase 1a: claim previously-published names (chant #1459).
+    //
+    // After priority names, which are explicit hand-pinned decisions and still
+    // win, and before any short name is contested. A reserved name whose type
+    // is gone from the input is simply never reached, so its name is released
+    // for whoever legitimately claims it next.
+    for (const t of typeNames) {
+      if (this.assigned.has(t)) continue;
+      const published = config.reservedNames?.[t];
+      // `usedNames` guards the case where a priority name already took it —
+      // an explicit pin outranks history.
+      if (published && !this.usedNames.has(published)) {
+        this.assigned.set(t, published);
+        this.usedNames.add(published);
+      }
+    }
+
     // Phase 1b: assign priority aliases
     for (const t of typeNames) {
       const extras = config.priorityAliases[t];

package/src/codegen/registry.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadLexiconRegistry, LexiconRegistryMissingError } from "./registry";
+
+const REGISTRY = { Bucket: { resourceType: "AWS::S3::Bucket", kind: "resource" } };
+
+function pkg(): string {
+  return mkdtempSync(join(tmpdir(), "chant-registry-"));
+}
+
+describe("loadLexiconRegistry (#1367)", () => {
+  test("reads the dev copy — src/generated, which is what a working checkout has", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "src", "generated"), { recursive: true });
+    writeFileSync(join(dir, "src", "generated", "lexicon-aws.json"), JSON.stringify(REGISTRY));
+    expect(loadLexiconRegistry(dir, "aws")).toEqual(REGISTRY);
+  });
+
+  test("falls back to dist/meta.json — what an installed package ships", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "dist"), { recursive: true });
+    writeFileSync(join(dir, "dist", "meta.json"), JSON.stringify(REGISTRY));
+    expect(loadLexiconRegistry(dir, "aws")).toEqual(REGISTRY);
+  });
+
+  test("prefers the dev copy when both exist", () => {
+    const dir = pkg();
+    mkdirSync(join(dir, "src", "generated"), { recursive: true });
+    mkdirSync(join(dir, "dist"), { recursive: true });
+    writeFileSync(join(dir, "src", "generated", "lexicon-aws.json"), JSON.stringify({ Dev: REGISTRY.Bucket }));
+    writeFileSync(join(dir, "dist", "meta.json"), JSON.stringify({ Dist: REGISTRY.Bucket }));
+    expect(Object.keys(loadLexiconRegistry(dir, "aws"))).toEqual(["Dev"]);
+  });
+
+  test("throws with the command to run, rather than a module-not-found or an empty map", () => {
+    // The whole point. An empty map reads downstream as a lexicon with no
+    // resource types, which is how azure's import came to emit
+    // `// Unknown resource type: Microsoft.…` and look like a coverage gap.
+    const dir = pkg();
+    expect(() => loadLexiconRegistry(dir, "azure")).toThrow(LexiconRegistryMissingError);
+    expect(() => loadLexiconRegistry(dir, "azure")).toThrow(/npm run --prefix lexicons\/azure prepack/);
+  });
+
+  test("names the lexicon that is missing, not a generic one", () => {
+    const dir = pkg();
+    try {
+      loadLexiconRegistry(dir, "gcp");
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect((err as LexiconRegistryMissingError).lexicon).toBe("gcp");
+      expect((err as Error).message).toContain("lexicons/gcp");
+    }
+  });
+});

package/src/codegen/registry.ts

@@ -0,0 +1,69 @@
+/**
+ * Locating a lexicon's generated registry (#1367).
+ *
+ * The registry — every resource type the lexicon knows, keyed by class name —
+ * is written to two places by `npm run --prefix lexicons/<name> prepack`:
+ * `src/generated/lexicon-<name>.json` by the generate step, and `dist/meta.json`
+ * by the bundle step, byte-identical. Both are gitignored, so a fresh clone has
+ * neither until that command runs; CI runs it explicitly before anything else.
+ *
+ * That is a legitimate state. Being silent about it is not, and the two readers
+ * that needed the registry were silent in opposite directions:
+ *
+ * - AWS's import generator `require`d `dist/meta.json` with no catch, so a
+ *   fresh clone got `Cannot find module …/lexicons/aws/dist/meta.json` — from
+ *   `chant import`, and from twelve tests that mention neither modules nor
+ *   registries.
+ * - Azure's caught the failure and continued with an empty map, so the import
+ *   emitted `// Unknown resource type: Microsoft.Network/virtualNetworks` and
+ *   its round-trip tests failed as though the registry were incomplete. That is
+ *   the worse of the two: it looks like a coverage gap in the lexicon.
+ *
+ * Both now go through here, which tries the dev path first (matching what the
+ * azure serializer already did) and, failing both, says what to run.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Thrown when neither copy of the registry exists — carries the fix. */
+export class LexiconRegistryMissingError extends Error {
+  constructor(readonly lexicon: string) {
+    super(
+      `${lexicon} lexicon registry not found — it is a build artifact and this checkout has not built it.\n` +
+        `Run: npm run --prefix lexicons/${lexicon} prepack\n` +
+        `(generate writes src/generated/lexicon-${lexicon}.json; bundle writes dist/meta.json)`,
+    );
+    this.name = "LexiconRegistryMissingError";
+  }
+}
+
+/** One entry in a lexicon's generated registry. */
+export interface LexiconRegistryEntry {
+  resourceType: string;
+  kind: string;
+  apiVersion?: string;
+}
+
+/**
+ * Read a lexicon's generated registry, dev copy first.
+ *
+ * `pkgDir` is the lexicon PACKAGE directory (the one holding `src/` and
+ * `dist/`) — callers pass an `import.meta.dirname`-derived path, so this stays
+ * free of assumptions about where it is imported from. Throws
+ * {@link LexiconRegistryMissingError} when neither copy exists, rather than
+ * returning an empty map that reads downstream as a lexicon with no resource
+ * types at all.
+ */
+export function loadLexiconRegistry(pkgDir: string, lexicon: string): Record<string, LexiconRegistryEntry> {
+  for (const candidate of [
+    join(pkgDir, "src", "generated", `lexicon-${lexicon}.json`),
+    join(pkgDir, "dist", "meta.json"),
+  ]) {
+    try {
+      return JSON.parse(readFileSync(candidate, "utf-8")) as Record<string, LexiconRegistryEntry>;
+    } catch {
+      // Try the next candidate; only both failing is an error.
+    }
+  }
+  throw new LexiconRegistryMissingError(lexicon);
+}

package/src/codegen/validate.test.ts

@@ -84,3 +84,89 @@ describe("validateLexiconArtifacts", () => {
     rmSync(dir, { recursive: true, force: true });
   });
 });
+
+/**
+ * chant #1473 — the release gate. `prepack` regenerates from an upstream that
+ * moves, so what must match the reviewed baseline is the API that comes out,
+ * not the archive that went in.
+ */
+describe("surface snapshot gate (#1473)", () => {
+  const LEXICON = JSON.stringify({
+    Bucket: { resourceType: "AWS::S3::Bucket", kind: "resource", lexicon: "aws" },
+  });
+  const DTS = "export declare class Bucket {}\n";
+
+  function fixture(opts: { snapshot?: string } = {}): string {
+    const dir = makeTempDir();
+    const genDir = join(dir, "src", "generated");
+    mkdirSync(genDir, { recursive: true });
+    writeFileSync(join(genDir, "lexicon-test.json"), LEXICON);
+    writeFileSync(join(genDir, "index.d.ts"), DTS);
+    if (opts.snapshot !== undefined) writeFileSync(join(dir, "surface.snapshot.json"), opts.snapshot);
+    return dir;
+  }
+
+  const run = (basePath: string, checkSurfaceSnapshot: boolean, armed = true) =>
+    validateLexiconArtifacts({
+      lexiconJsonFilename: "lexicon-test.json",
+      requiredNames: [],
+      basePath,
+      checkSurfaceSnapshot,
+      env: armed ? { CHANT_RELEASE_GATE: "1" } : {},
+    });
+
+  /** The snapshot a matching build would have produced. */
+  async function matchingSnapshot(): Promise<string> {
+    const { extractSurface, serializeSnapshot } = await import("./surface-snapshot");
+    return serializeSnapshot(extractSurface(LEXICON, DTS));
+  }
+
+  test("passes when the generated API matches the snapshot", async () => {
+    const result = await run(fixture({ snapshot: await matchingSnapshot() }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(true);
+  });
+
+  test("fails when the generated API differs, and says how to accept it", async () => {
+    const stale = JSON.stringify({
+      schemaVersion: 1,
+      generatedAt: "2026-01-01T00:00:00.000Z",
+      entries: { Queue: { kind: "resource", resourceType: "AWS::SQS::Queue", attrs: [], props: [] } },
+    });
+    const result = await run(fixture({ snapshot: stale }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(false);
+    expect(check?.error).toContain("--update-snapshot");
+    expect(result.success).toBe(false);
+  });
+
+  test("is off unless the lexicon opts in", async () => {
+    // k8s and azure are adrift from their own baselines (#1475); switching
+    // this on globally would block their releases.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await run(fixture({ snapshot: stale }), false);
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+  });
+
+  test("does not run outside a release, even for a lexicon that opted in", async () => {
+    // `validate` runs on every PR. Upstream can move the surface at any time,
+    // so a hard check here would turn unrelated PRs red — the same trap the
+    // spec pin fell into. Drift between releases is the upgrade job's business.
+    const stale = JSON.stringify({ schemaVersion: 1, generatedAt: "2026-01-01T00:00:00.000Z", entries: {} });
+    const result = await run(fixture({ snapshot: stale }), true, false);
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+    expect(result.success).toBe(true);
+  });
+
+  test("is skipped for a lexicon with no committed snapshot", async () => {
+    // A new lexicon before its first baseline must still be able to build.
+    const result = await run(fixture(), true);
+    expect(result.checks.find((c) => c.name === "surface-matches-snapshot")).toBeUndefined();
+  });
+
+  test("an unreadable snapshot fails rather than passing silently", async () => {
+    const result = await run(fixture({ snapshot: "{ not json" }), true);
+    const check = result.checks.find((c) => c.name === "surface-matches-snapshot");
+    expect(check?.ok).toBe(false);
+  });
+});

package/src/codegen/validate.ts

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { computeCoverage, checkThresholds, type CoverageThresholds } from "./coverage";
+import { extractSurface, diffSurface, parseSnapshot, formatDelta } from "./surface-snapshot";
 
 export interface ValidateCheck {
   name: string;
@@ -20,6 +21,12 @@ export interface ValidateResult {
   checks: ValidateCheck[];
 }
 
+/**
+ * Set by the publish workflow to arm the release-time surface gate
+ * (chant #1473). Absent in ordinary CI, where upstream drift is expected.
+ */
+export const RELEASE_GATE_ENV = "CHANT_RELEASE_GATE";
+
 export interface LexiconValidationConfig {
   /** Filename of the lexicon JSON (e.g. "lexicon-mydom.json") */
   lexiconJsonFilename: string;
@@ -35,6 +42,32 @@ export interface LexiconValidationConfig {
   requiredNamesMatchSubstring?: boolean;
   /** Base path of the lexicon package */
   basePath: string;
+  /**
+   * chant #1473 — this lexicon's release is gated on the generated API
+   * matching the committed `surface.snapshot.json`.
+   *
+   * Two conditions, both required. The lexicon opts in here, AND
+   * {@link RELEASE_GATE_ENV} is set — which the publish workflow does and
+   * ordinary CI does not.
+   *
+   * The env half is not caution, it is correctness. `validate` runs on every
+   * PR, and the upstream a lexicon generates from can move at any time: the
+   * CloudFormation archive republishes schemas several times a day, and some
+   * of those edits do change the surface. A hard surface check on every PR
+   * would turn any unrelated change red the moment upstream moved, which is
+   * the same trap the spec pin fell into one level down. Drift between
+   * releases is expected and is what the scheduled lexicon-upgrade job exists
+   * to report (#1423).
+   *
+   * What must never happen is *publishing* a surface nobody reviewed. That is
+   * a release-time property, so it is checked at release time.
+   *
+   * Opt-in per lexicon because k8s and azure are currently adrift from their
+   * own baselines (393 and 483 entries, #1475).
+   */
+  checkSurfaceSnapshot?: boolean;
+  /** Environment to read {@link RELEASE_GATE_ENV} from. Defaults to `process.env`; overridden in tests. */
+  env?: NodeJS.ProcessEnv;
   /** Path to the generated directory (defaults to basePath/src/generated) */
   generatedDir?: string;
   /** Coverage thresholds (optional) */
@@ -148,6 +181,47 @@ export async function validateLexiconArtifacts(config: LexiconValidationConfig):
     }
   }
 
+  // Check: the generated API matches the reviewed one (chant #1473).
+  //
+  // This is the gate that makes a release trustworthy. `prepack` regenerates
+  // from upstream, and for aws that upstream republishes schemas several times
+  // a day, so the input can differ from the one whose delta a human accepted.
+  // What must not differ is the API that ships. Comparing the just-generated
+  // artifacts against the committed `surface.snapshot.json` says exactly that,
+  // and says nothing about byte churn that changed no declaration.
+  //
+  // Runs on the artifacts already on disk — no second generation — and is
+  // skipped for a lexicon with no committed snapshot, which is the case for a
+  // new lexicon before its first baseline.
+  const snapshotPath = join(config.basePath, "surface.snapshot.json");
+  const releaseGate = config.checkSurfaceSnapshot && (config.env ?? process.env)[RELEASE_GATE_ENV] === "1";
+  if (releaseGate && lexiconData && existsSync(snapshotPath) && existsSync(dtsPath)) {
+    try {
+      const fresh = extractSurface(readFileSync(lexiconPath, "utf-8"), readFileSync(dtsPath, "utf-8"));
+      const delta = diffSurface(parseSnapshot(readFileSync(snapshotPath, "utf-8")), fresh);
+      const moved = delta.added.length + delta.removed.length + delta.changed.length;
+      checks.push(
+        moved === 0
+          ? { name: "surface-matches-snapshot", ok: true }
+          : {
+              name: "surface-matches-snapshot",
+              ok: false,
+              error:
+                `The generated API differs from the reviewed surface.snapshot.json ` +
+                `(${delta.added.length} added, ${delta.removed.length} removed, ${delta.changed.length} changed). ` +
+                `Accept it deliberately with \`chant dev surface-diff <lexicon> --update-snapshot --bump\`, ` +
+                `never as a side effect of a release.\n${formatDelta(delta)}`,
+            },
+      );
+    } catch (err) {
+      checks.push({
+        name: "surface-matches-snapshot",
+        ok: false,
+        error: `Failed to compare against surface.snapshot.json: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  }
+
   return {
     success: checks.every((c) => c.ok),
     checks,

package/src/components/SPRAWL-VALIDATION.md

@@ -16,7 +16,7 @@ generic `runInterpretDriver` (#556, [`../driver.ts`](./driver.ts)), unchanged.
 ## Before / after: the ALB/ECS pipeline glue this replaces
 
 The component model's whole reason for existing is visible in one concrete
-diff. [`examples/gitlab-aws-alb-api/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-api/src/pipeline.ts)
+diff. [`examples/gitlab-aws-alb-api/src/pipeline.ts`](../../../../examples/gitlab-aws-alb-api/src/pipeline.ts)
 hand-rolls a `deployService` job that shells out to CloudFormation and greps
 its own infra stack's outputs before it can deploy:
 
@@ -49,7 +49,7 @@ No `describe-stacks`, no `jq`, no shell string-building. `dependsOn:
 ["shared-alb"]` plus three `stackOutput()` references replace the whole glue
 block; `docker build`/`docker push` become the `docker-build`/`publish-image`
 capabilities the driver dispatches to. [`driver.test.ts`](./driver.test.ts)
-and [`pilots/pilots-e2e.test.ts`](./pilots/pilots-e2e.test.ts) exercise this
+and [`pilots/pilots.test.ts`](./pilots/pilots.test.ts) exercise this
 exact wiring end to end against a mock `CloudExecutor` — `cfn-deploy`
 resolves the `stackOutput` reference itself; no orchestrator code parses a
 CloudFormation output.
@@ -59,7 +59,7 @@ CloudFormation output.
 [`driver.test.ts`](./driver.test.ts)'s `"runs the three pilots through one
 driver instance with zero per-component driver code (sprawl metric)"` test
 (pre-existing from #556/#557, still green) and
-[`pilots-e2e.test.ts`](./pilots/pilots-e2e.test.ts)'s first `describe` block
+[`pilots.test.ts`](./pilots/pilots.test.ts)'s first `describe` block
 run Neo4j fan-out, DynamoDB (sticky apply), and ALB/ECS (cross-stack, build)
 through the same `runInterpretDriver` call, dispatching to the real,
 `MockCloudExecutor`-backed capability implementations from #557
@@ -103,7 +103,7 @@ uses carries the image reference into the apply step.
 
 ### The one new capability: `lambda-deploy`
 
-[`verbs/apply.ts`](./verbs/apply.ts)'s `createLambdaDeployCapability` is the
+[`lexicons/aws/src/components/apply.ts`](../../../../lexicons/aws/src/components/apply.ts)'s `createLambdaDeployCapability` is the
 only new leaf this component required, built the same way #557 built the
 other real leaves: typed input/output, an injectable `CloudExecutor`
 (extended with a `lambda` client — [`verbs/cloud-executor.ts`](./verbs/cloud-executor.ts)),
@@ -121,7 +121,7 @@ No other verb was touched or added. `driver.ts` was not edited.
 
 [`driver.test.ts`](./driver.test.ts)'s `"runs all four components ... through
 one driver instance with zero per-component driver code (sprawl metric,
-extended)"` test and [`pilots-e2e.test.ts`](./pilots/pilots-e2e.test.ts)'s
+extended)"` test and [`pilots.test.ts`](./pilots/pilots.test.ts)'s
 second `describe`-block test run all five components (`shared-alb`,
 `orders-table`, `neo4j-cluster`, `search-service`, `image-processor-lambda`)
 through one `runInterpretDriver` call, dispatching `image-processor-lambda`'s

package/src/components/sandbox/driver.test.ts

@@ -0,0 +1,27 @@
+import { describe, test, expect, afterEach } from "vitest";
+import { resolve } from "node:path";
+import { generateComponentDriverSource } from "./driver";
+import { setBuildParams } from "../../params";
+
+/**
+ * chant #1108 — same re-binding the entity driver does (../../discovery/
+ * sandbox/driver.test.ts): a `*.component.ts` file imported in the sandboxed
+ * child must see the parent's resolved build-time parameters, not `{}`.
+ */
+describe("generateComponentDriverSource — build-time parameters (#1108)", () => {
+  afterEach(() => {
+    setBuildParams({});
+  });
+
+  test("embeds a snapshot of the parent's current params, bound before any component import", () => {
+    setBuildParams({ stage: "prod" });
+    const source = generateComponentDriverSource({ files: ["proj/svc.component.ts"] });
+
+    expect(source).toContain("import { setBuildParams } from ");
+    const bindAt = source.indexOf(`setBuildParams(${JSON.stringify({ stage: "prod" })});`);
+    const firstImportAt = source.indexOf(`await import(${JSON.stringify(resolve("proj/svc.component.ts"))})`);
+    expect(bindAt).toBeGreaterThan(-1);
+    expect(firstImportAt).toBeGreaterThan(-1);
+    expect(bindAt).toBeLessThan(firstImportAt);
+  });
+});

package/src/components/sandbox/driver.ts

@@ -1,4 +1,5 @@
 import { join, resolve } from "node:path";
+import { params as currentBuildParams } from "../../params";
 
 /**
  * chant #1051 — generates the source of the "driver" module that runs INSIDE
@@ -29,6 +30,12 @@ const COMPONENTS_DIR = join(HERE, "..");
 /** Absolute paths to chant's OWN trusted modules the generated driver imports — resolved relative to THIS file's own location on disk, exactly like `../../discovery/sandbox/driver.ts` does for the entity path (works whether chant runs from the monorepo or a consumer's `node_modules`). */
 const DISCOVER_MODULE = join(COMPONENTS_DIR, "discover.ts");
 const CHILD_ERRORS_MODULE = join(COMPONENTS_DIR, "..", "discovery", "sandbox", "child-errors.ts");
+// chant #1108 — same re-binding the entity driver does (see ../../discovery/
+// sandbox/driver.ts's PARAMS_MODULE doc): the child's copy of the shared
+// `params` object starts empty, so a `*.component.ts` file importing
+// `@intentius/chant/params` would otherwise see `{}` under sandboxed
+// discovery no matter what the parent resolved.
+const PARAMS_MODULE = join(COMPONENTS_DIR, "..", "params.ts");
 
 export interface GenerateComponentDriverOptions {
   /** Absolute paths to every discovered `*.component.ts` file for this build. */
@@ -52,6 +59,11 @@ export function generateComponentDriverSource(options: GenerateComponentDriverOp
   const lines: string[] = [
     `import { collectComponents } from ${lit(DISCOVER_MODULE)};`,
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+    `import { setBuildParams } from ${lit(PARAMS_MODULE)};`,
+    ``,
+    // chant #1108 — snapshot of the parent's resolved build-time parameter
+    // values (scalars only), bound before any component file is imported.
+    `setBuildParams(${lit({ ...currentBuildParams })});`,
     ``,
     `function send(payload) {`,
     `  if (typeof process.send === "function") process.send(payload);`,

package/src/composite.ts

@@ -7,14 +7,43 @@ import { setProvenance } from "./provenance";
 export const COMPOSITE_MARKER = Symbol.for("chant.composite");
 
 /**
- * A record of named Declarable members produced by a composite factory.
+ * A record of named members produced by a composite factory.
+ *
+ * What a consumer reads off `instance.members`. Deliberately narrow: every
+ * value here is a real Declarable, so `.entityType` and friends resolve without
+ * narrowing. What a factory may RETURN is wider — see
+ * {@link CompositeFactoryMembers}.
  */
 export type CompositeMembers = Record<string, Declarable>;
 
+/**
+ * What a factory is allowed to RETURN — {@link CompositeMembers} plus
+ * `undefined`, used only as the generic constraint.
+ *
+ * A member produced by a conditional spread (`...(cond ? { policy } : {})`) is
+ * typed optional, and an optional property is not assignable to a
+ * required-value record. Widening the constraint lets such a factory typecheck;
+ * widening `CompositeMembers` itself would make every member possibly-undefined
+ * for everyone reading `instance.members`, which is a worse trade.
+ *
+ * The key is absent at runtime rather than present-and-undefined, so nothing
+ * reaches the validation in `Composite` below.
+ */
+export type CompositeFactoryMembers =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  | Record<string, Declarable | CompositeInstance<any> | undefined>
+  // A pass-through composite returns another composite's INSTANCE rather than
+  // building a record (`return FargateService({...})`). That works at runtime
+  // because `members` and `_definition` are defined non-enumerable below
+  // precisely so an instance exposes only its member resources — but a type
+  // cannot say "non-enumerable", so the instance has to be admitted directly.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  | CompositeInstance<any>;
+
 /**
  * The result of instantiating a composite — contains the marker and expanded members.
  */
-export interface CompositeInstance<M extends CompositeMembers = CompositeMembers> {
+export interface CompositeInstance<M extends CompositeFactoryMembers = CompositeMembers> {
   readonly [COMPOSITE_MARKER]: true;
   readonly members: M;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -24,7 +53,7 @@ export interface CompositeInstance<M extends CompositeMembers = CompositeMembers
 /**
  * A composite definition: a callable that produces a CompositeInstance.
  */
-export interface CompositeDefinition<P, M extends CompositeMembers = CompositeMembers> {
+export interface CompositeDefinition<P, M extends CompositeFactoryMembers = CompositeMembers> {
   (props: P): CompositeInstance<M> & M;
   readonly compositeName: string;
   readonly _id: symbol;
@@ -78,7 +107,7 @@ export class CompositeRegistry {
  * export const storage = SecureStorage({ name: "data" });
  * ```
  */
-export function Composite<P, M extends CompositeMembers = CompositeMembers>(
+export function Composite<P, M extends CompositeFactoryMembers = CompositeMembers>(
   factory: (props: P) => M,
   name?: string,
 ): CompositeDefinition<P, M> {

package/src/deep-observation.ts

@@ -56,6 +56,17 @@ export interface DeepResourceObservation {
   physicalId?: string;
   /** The normalized live property tree. JSON-safe. */
   properties: Record<string, unknown>;
+  /**
+   * Path → the field manager that owns it, where the substrate records one
+   * (#1189). Additive to the v1 envelope: a lexicon with no per-field ownership
+   * omits it, and every consumer behaves exactly as before.
+   *
+   * Only Kubernetes has this — the API server maintains `managedFields`
+   * server-side. It is the difference between "this field is foreign" and
+   * "`hpa-controller` owns `spec.replicas`", which are the same category and
+   * very different answers to an operator.
+   */
+  fieldOwners?: Record<string, string>;
 }
 
 /**