@intentius/chant 0.46.0 → 0.50.0

package/src/provenance.test.ts

@@ -1,11 +1,19 @@
 import { describe, expect, test } from "vitest";
-import { setProvenance, getProvenance } from "./provenance";
-import { Composite, expandComposite } from "./composite";
+import {
+  describePathOrigin,
+  getPathProvenance,
+  getProvenance,
+  originOfPath,
+  setPathProvenance,
+  setProvenance,
+  type PathOrigin,
+} from "./provenance";
+import { Composite, expandComposite, propagate } from "./composite";
 import { collectEntities } from "./discovery/collect";
 import { DECLARABLE_MARKER, type Declarable } from "./declarable";
 
-const decl = (entityType: string): Declarable =>
-  ({ [DECLARABLE_MARKER]: true, lexicon: "test", entityType, kind: "resource", props: {} }) as unknown as Declarable;
+const decl = (entityType: string, props: Record<string, unknown> = {}): Declarable =>
+  ({ [DECLARABLE_MARKER]: true, lexicon: "test", entityType, kind: "resource", props }) as unknown as Declarable;
 
 const Pair = Composite<{ n: string }>((props) => ({
   first: decl(`Test::First:${props.n}`),
@@ -77,3 +85,142 @@ describe("collectEntities stamps the source file", () => {
     expect(prov?.composite).toBe("Pair");
   });
 });
+
+describe("path provenance storage (#1443)", () => {
+  test("first writer wins per path, independently of other paths", () => {
+    const e = decl("Test::Thing");
+    setPathProvenance(e, "spec.replicas", { kind: "build-param", params: ["tier"] });
+    setPathProvenance(e, "spec.replicas", { kind: "authored" });
+    setPathProvenance(e, "", { kind: "authored" });
+    expect(getPathProvenance(e)).toEqual({
+      "": { kind: "authored" },
+      "spec.replicas": { kind: "build-param", params: ["tier"] },
+    });
+  });
+
+  test("keys come back sorted, whatever order they were written in", () => {
+    const e = decl("Test::Thing");
+    setPathProvenance(e, "spec.z", { kind: "authored" });
+    setPathProvenance(e, "metadata.a", { kind: "authored" });
+    setPathProvenance(e, "", { kind: "authored" });
+    expect(Object.keys(getPathProvenance(e)!)).toEqual(["", "metadata.a", "spec.z"]);
+  });
+
+  test("path origins stay off the serialized entity", () => {
+    const e = decl("Test::Thing");
+    setPathProvenance(e, "spec.replicas", { kind: "authored" });
+    expect(JSON.stringify(e)).not.toContain("replicas");
+  });
+
+  test("nothing recorded reads as undefined, not an empty record", () => {
+    expect(getPathProvenance(decl("Test::Thing"))).toBeUndefined();
+    expect(originOfPath(undefined, "spec.replicas")).toBeUndefined();
+  });
+});
+
+describe("originOfPath resolution", () => {
+  const paths: Record<string, PathOrigin> = {
+    "": { kind: "authored" },
+    spec: { kind: "composite", composite: "WebService", instance: "web" },
+    "spec.template.spec.containers": { kind: "build-param", params: ["image", "tier"] },
+  };
+
+  test("the longest matching prefix wins", () => {
+    expect(originOfPath(paths, "spec.template.spec.containers")).toEqual(paths["spec.template.spec.containers"]);
+    expect(originOfPath(paths, "spec.replicas")).toEqual(paths.spec);
+    expect(originOfPath(paths, "metadata.name")).toEqual(paths[""]);
+  });
+
+  test("a keyed list element inherits the origin recorded for the list (#1441 grammar)", () => {
+    expect(originOfPath(paths, "spec.template.spec.containers[#app].image")).toEqual(
+      paths["spec.template.spec.containers"],
+    );
+    expect(originOfPath(paths, "spec.template.spec.containers[0].image")).toEqual(
+      paths["spec.template.spec.containers"],
+    );
+  });
+
+  test("prefixes only match on a segment boundary", () => {
+    // `spec` must not claim `specialCase`, and a deeper recorded key must not
+    // claim a shallower query.
+    expect(originOfPath(paths, "specialCase")).toEqual(paths[""]);
+    expect(originOfPath({ "spec.containers.image": { kind: "authored" } }, "spec.containers")).toBeUndefined();
+  });
+});
+
+describe("describePathOrigin", () => {
+  test("renders each kind", () => {
+    expect(describePathOrigin({ kind: "authored" })).toBe("authored");
+    expect(describePathOrigin({ kind: "composite", composite: "WebService", instance: "web" })).toBe(
+      "composite WebService (web)",
+    );
+    expect(describePathOrigin({ kind: "build-param", params: ["region", "tier"] })).toBe("param region, tier");
+  });
+});
+
+describe("composite expansion records path origins (#1443)", () => {
+  test("each member's whole-entity origin names the composite and the instance", () => {
+    const expanded = expandComposite("web", Pair({ n: "x" }));
+    for (const [, entity] of expanded) {
+      expect(originOfPath(getPathProvenance(entity), "anything.at.all")).toEqual({
+        kind: "composite",
+        composite: "Pair",
+        instance: "web",
+      });
+    }
+  });
+
+  test("a nested member keeps the innermost composite but the outer instance", () => {
+    const Wrapper = Composite<{ n: string }>((props) => ({
+      inner: Pair({ n: props.n }) as unknown as Declarable,
+    }), "Wrapper");
+    const expanded = expandComposite("stack", Wrapper({ n: "y" }));
+    for (const [, entity] of expanded) {
+      expect(getPathProvenance(entity)?.[""]).toEqual({
+        kind: "composite",
+        composite: "Pair",
+        instance: "stack",
+      });
+    }
+  });
+
+  test("a propagated key the member never set is attributed to the instance", () => {
+    const Tagged = Composite<{ n: string }>(() => ({
+      only: decl("Test::Only", { name: "fixed" }),
+    }), "Tagged");
+    const expanded = expandComposite("env", propagate(Tagged({ n: "x" }), { tags: [{ key: "env", value: "prod" }] }));
+    const entity = expanded.get("envOnly")!;
+    expect(getPathProvenance(entity)?.tags).toEqual({
+      kind: "composite",
+      composite: "Tagged",
+      instance: "env",
+    });
+  });
+
+  test("a key both the member and the propagation wrote is left to the whole-entity origin", () => {
+    const Tagged = Composite<{ n: string }>(() => ({
+      only: decl("Test::Only", { tags: [{ key: "own", value: "1" }] }),
+    }), "Tagged");
+    const expanded = expandComposite("env", propagate(Tagged({ n: "x" }), { tags: [{ key: "env", value: "prod" }] }));
+    const paths = getPathProvenance(expanded.get("envOnly")!);
+    expect(paths?.tags).toBeUndefined();
+    expect(paths?.[""]).toBeDefined();
+  });
+});
+
+describe("collectEntities records the authored origin", () => {
+  test("a directly exported declarable is authored at the root", () => {
+    const a = decl("Test::A");
+    const entities = collectEntities([{ file: "/proj/src/infra.ts", exports: { a } }]);
+    expect(getPathProvenance(entities.get("a")!)?.[""]).toEqual({ kind: "authored" });
+  });
+
+  test("a composite member is not relabelled authored", () => {
+    const entities = collectEntities([{ file: "/proj/src/pipe.ts", exports: { p: Pair({ n: "z" }) } }]);
+    expect(getPathProvenance(entities.get("pFirst")!)?.[""]).toEqual({
+      kind: "composite",
+      composite: "Pair",
+      instance: "p",
+    });
+  });
+});

package/src/provenance.ts

@@ -5,9 +5,11 @@
  * entity object, so it never serializes into the emitted YAML/JSON — it is build
  * metadata, not declared configuration. Read it back with {@link getProvenance}.
  *
- * This is entity-level provenance (which file declared it, and which composite
- * expanded it), not a YAML-line source map. It answers "where did this resource
- * come from?", which is the question an agent asks before changing it.
+ * Entity-level provenance (which file declared it, and which composite expanded
+ * it) answers "where did this resource come from?", which is the question an
+ * agent asks before changing it. {@link PathOrigin} (chant #1443) answers the
+ * follow-up — "what set THIS field" — for the paths a build can attribute
+ * without guessing. Neither is a YAML-line source map.
  *
  * {@link BuildParamProvenance} (chant #1064) is the other half: not "where did
  * this ENTITY come from" but "what INPUTS was this whole BUILD invoked with" —
@@ -30,6 +32,58 @@ export interface EntityProvenance {
    * collapse a composite to a single node at coarse diagram detail levels (#494).
    */
   compositeInstance?: string;
+  /**
+   * Per-path origins within the entity's `props` (chant #1443). Read with
+   * {@link originOfPath}, which does the prefix resolution these keys are
+   * written for.
+   *
+   * Keys are dotted property paths only — `spec.template.spec.containers` —
+   * with `""` for the whole entity. They never carry an array segment, because
+   * a producing mechanism attributes a whole array at once: the coarsest path
+   * it actually determines is the honest one to record, and a positional key
+   * would go stale the moment an element moved.
+   *
+   * Query paths come from #1441's diff addressing and may carry `[#key]` for an
+   * element of an associative list or `[n]` for a positional one. Resolution is
+   * longest segment-boundary prefix, so `spec.containers[#app].image` finds a
+   * key recorded at `spec.containers`, and a key recorded at
+   * `spec.containers.image` never matches it. The two grammars agree without
+   * the recorder needing the lexicon's ordering hook, which it has no access to.
+   *
+   * Absent means this build could not record path origins, not that nothing
+   * governs the entity's fields — the run path executes modules and has no
+   * expression to inspect, and a sandboxed child's provenance does not survive
+   * the wire (`discovery/entity-wire-codec.ts` drops build metadata).
+   */
+  paths?: Record<string, PathOrigin>;
+}
+
+/**
+ * What produced one path inside an entity's props.
+ *
+ * - `authored` — written in the source file that declared the entity.
+ * - `composite` — the entity was expanded by a composite, or the path was
+ *   supplied by `propagate()`'s shared props at the instance.
+ * - `build-param` — the build parameters the authored expression for this path
+ *   *reads*, which is a syntactic dependency, not a value taint. For
+ *   `replicas: params.tier === "prod" ? 5 : 1` a taint says the value came from
+ *   the literal `5`, which is true and useless; the dependency says the field
+ *   is governed by `tier`, which is what an editor needs to know. Under-reports
+ *   (a shape the collector does not follow drops a dependency) and never
+ *   over-reports a parameter the expression does not mention.
+ */
+export type PathOrigin =
+  | { kind: "authored" }
+  | { kind: "composite"; composite: string; instance: string }
+  | { kind: "build-param"; params: string[] };
+
+/** True when `prefix` addresses `path` or an ancestor of it, on a segment boundary. */
+function isPathPrefix(prefix: string, path: string): boolean {
+  if (prefix === "") return true;
+  if (!path.startsWith(prefix)) return false;
+  if (path.length === prefix.length) return true;
+  const next = path[prefix.length];
+  return next === "." || next === "[";
 }
 
 /**
@@ -44,10 +98,16 @@ export function setProvenance(entity: object, prov: EntityProvenance): void {
     existing.sourceFile ??= prov.sourceFile;
     existing.composite ??= prov.composite;
     existing.compositeInstance ??= prov.compositeInstance;
+    if (prov.paths) {
+      existing.paths ??= {};
+      for (const [path, origin] of Object.entries(prov.paths)) {
+        existing.paths[path] ??= origin;
+      }
+    }
     return;
   }
   Object.defineProperty(entity, PROVENANCE, {
-    value: { ...prov },
+    value: { ...prov, ...(prov.paths ? { paths: { ...prov.paths } } : {}) },
     enumerable: false,
     writable: true,
     configurable: true,
@@ -59,6 +119,60 @@ export function getProvenance(entity: object): EntityProvenance | undefined {
   return (entity as Record<symbol, unknown>)[PROVENANCE] as EntityProvenance | undefined;
 }
 
+/**
+ * Record one path's origin, first writer wins — the same rule
+ * {@link setProvenance} applies to entity-level fields, and for the same
+ * reason: expansion runs innermost-composite-first, so the earliest writer is
+ * the most specific one.
+ */
+export function setPathProvenance(entity: object, path: string, origin: PathOrigin): void {
+  setProvenance(entity, { paths: { [path]: origin } });
+}
+
+/**
+ * An entity's recorded path origins in sorted key order, or `undefined` when
+ * none were recorded. Sorted because a build's outputs are compared byte for
+ * byte and object key order is not something insertion should decide.
+ */
+export function getPathProvenance(entity: object): Record<string, PathOrigin> | undefined {
+  const paths = getProvenance(entity)?.paths;
+  if (!paths) return undefined;
+  const keys = Object.keys(paths).sort();
+  if (keys.length === 0) return undefined;
+  const out: Record<string, PathOrigin> = {};
+  for (const key of keys) out[key] = paths[key];
+  return out;
+}
+
+/**
+ * The origin governing `path` — the longest recorded key that addresses it or
+ * one of its ancestors. See {@link PROVENANCE_PATH_GRAMMAR}.
+ */
+export function originOfPath(
+  paths: Readonly<Record<string, PathOrigin>> | undefined,
+  path: string,
+): PathOrigin | undefined {
+  if (!paths) return undefined;
+  let best: string | undefined;
+  for (const key of Object.keys(paths)) {
+    if (!isPathPrefix(key, path)) continue;
+    if (best === undefined || key.length > best.length) best = key;
+  }
+  return best === undefined ? undefined : paths[best];
+}
+
+/** One-line rendering of an origin, for diff output. */
+export function describePathOrigin(origin: PathOrigin): string {
+  switch (origin.kind) {
+    case "authored":
+      return "authored";
+    case "composite":
+      return `composite ${origin.composite} (${origin.instance})`;
+    case "build-param":
+      return `param ${origin.params.join(", ")}`;
+  }
+}
+
 /**
  * One resolved build-time parameter (chant #1064, see ../build-params.ts): its
  * final value and which source won it, so a build's parameter inputs are

package/src/runtime-adapter.ts

@@ -34,8 +34,13 @@ export interface RuntimeAdapter {
   readonly hashAlgorithm: string;
   /** Test whether filePath matches a glob pattern */
   globMatch(pattern: string, filePath: string): boolean;
-  /** Spawn a child process and collect output */
-  spawn(cmd: string[], opts?: { cwd?: string }): Promise<SpawnResult>;
+  /**
+   * Spawn a child process and collect output. When `opts.stdin` is set, it is
+   * written to the child's stdin and the stream is closed — the caller never
+   * needs to round-trip content through a shell (`sh -c "echo … | cmd"`) just
+   * to feed a command that reads from stdin (e.g. `git hash-object --stdin`).
+   */
+  spawn(cmd: string[], opts?: { cwd?: string; stdin?: string }): Promise<SpawnResult>;
   /** Commands to use when spawning package manager / executor */
   readonly commands: RuntimeCommands;
 }
@@ -59,16 +64,32 @@ class NodeRuntimeAdapter implements RuntimeAdapter {
     return picomatch(pattern)(filePath);
   }
 
-  async spawn(cmd: string[], opts?: { cwd?: string }): Promise<SpawnResult> {
+  async spawn(cmd: string[], opts?: { cwd?: string; stdin?: string }): Promise<SpawnResult> {
     return new Promise((resolve) => {
-      execFile(cmd[0], cmd.slice(1), { cwd: opts?.cwd, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
-        resolve({
-          stdout: stdout ?? "",
-          stderr: stderr ?? "",
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          exitCode: err ? (err as any).code ?? 1 : 0,
+      const child = execFile(
+        cmd[0],
+        cmd.slice(1),
+        { cwd: opts?.cwd, maxBuffer: 10 * 1024 * 1024 },
+        (err, stdout, stderr) => {
+          resolve({
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            exitCode: err ? (err as any).code ?? 1 : 0,
+          });
+        },
+      );
+      // Content is written verbatim (utf-8) — no shell involved, so nothing
+      // reinterprets backslash-escape sequences or needs quote-escaping.
+      // The error handler is load-bearing: a child that exits without reading
+      // stdin (any command that ignores it) makes this write race the pipe
+      // teardown, and an unhandled EPIPE 'error' event crashes the process.
+      if (child.stdin) {
+        child.stdin.on("error", () => {
+          /* EPIPE: child exited without consuming stdin — harmless */
         });
-      });
+        child.stdin.end(opts?.stdin ?? "");
+      }
     });
   }
 }

package/src/secret-materialization.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Generated-once materialization engine tests (#1829, epic #1365 decisions 3
+ * and 6): read-then-write, present means done, mismatch fails loudly naming
+ * key names and metadata keys — and no code path returns, logs, or retains
+ * the generated material.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { inspect } from "node:util";
+import {
+  SecretMaterial,
+  SecretContractMismatchError,
+  consumeSecretMaterial,
+  defaultSecretMaterialGenerator,
+  ensureSecretMaterialization,
+  type SecretMaterialGenerator,
+  type SecretStoreAdapter,
+  type SecretStoreDescription,
+} from "./secret-materialization";
+
+/** A recognizable plaintext no output may ever contain. */
+const CANARY = "canary-s3kr3t-material";
+
+/** Generator minting a per-key canary value, so leak assertions can grep for it. */
+const canaryGenerator: SecretMaterialGenerator = (key) => SecretMaterial.mint(`${CANARY}:${key}`);
+
+interface StoredSecret {
+  data: Record<string, string>;
+  metadata?: Record<string, string>;
+}
+
+/**
+ * In-memory fake store. `create` consumes each key's material exactly the way
+ * a real adapter writes it, so the tests can check the stored bytes without
+ * any material ever traveling back through the engine.
+ */
+function fakeStore(seed?: Record<string, StoredSecret>) {
+  const secrets = new Map<string, StoredSecret>(Object.entries(seed ?? {}));
+  const adapter: SecretStoreAdapter = {
+    exists: vi.fn(async (name: string) => secrets.has(name)),
+    describe: vi.fn(async (name: string): Promise<SecretStoreDescription> => {
+      const secret = secrets.get(name);
+      if (!secret) throw new Error(`fake store: no secret "${name}"`);
+      return { keys: Object.keys(secret.data), metadata: secret.metadata };
+    }),
+    create: vi.fn(async (name: string, keys: readonly string[], generate: SecretMaterialGenerator) => {
+      const data: Record<string, string> = {};
+      for (const key of keys) {
+        data[key] = consumeSecretMaterial(await generate(key));
+      }
+      secrets.set(name, { data });
+    }),
+  };
+  return { adapter, secrets };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("ensureSecretMaterialization", () => {
+  it("absent: mints once through the adapter and reports created", async () => {
+    const { adapter, secrets } = fakeStore();
+    const outcome = await ensureSecretMaterialization(
+      adapter,
+      { name: "master-key", keys: ["MASTER_SECRETS_KEY"] },
+      canaryGenerator,
+    );
+    expect(outcome).toEqual({ outcome: "created", name: "master-key", keys: ["MASTER_SECRETS_KEY"] });
+    expect(adapter.create).toHaveBeenCalledTimes(1);
+    expect(secrets.get("master-key")?.data).toEqual({
+      MASTER_SECRETS_KEY: `${CANARY}:MASTER_SECRETS_KEY`,
+    });
+  });
+
+  it("present and matching: stops without any write — a rerun is byte-identical and create never fires twice", async () => {
+    const { adapter, secrets } = fakeStore();
+    const spec = { name: "master-key", keys: ["a", "b"] };
+
+    await ensureSecretMaterialization(adapter, spec, canaryGenerator);
+    const afterFirstRun = JSON.stringify(secrets.get("master-key"));
+
+    // Second run of the whole ensure — the fountain-ops e2e shape.
+    const outcome = await ensureSecretMaterialization(adapter, spec, canaryGenerator);
+    expect(outcome.outcome).toBe("present");
+    expect(adapter.create).toHaveBeenCalledTimes(1);
+    expect(JSON.stringify(secrets.get("master-key"))).toBe(afterFirstRun);
+  });
+
+  it("present with a missing declared key: fails loudly naming the key, never minting over the existing value", async () => {
+    const { adapter, secrets } = fakeStore({
+      "master-key": { data: { a: "pre-existing-value" } },
+    });
+    await expect(
+      ensureSecretMaterialization(adapter, { name: "master-key", keys: ["a", "b"] }, canaryGenerator),
+    ).rejects.toThrowError(SecretContractMismatchError);
+    await expect(
+      ensureSecretMaterialization(adapter, { name: "master-key", keys: ["a", "b"] }, canaryGenerator),
+    ).rejects.toThrowError(/missing declared key\(s\): b/);
+    expect(adapter.create).not.toHaveBeenCalled();
+    expect(secrets.get("master-key")?.data).toEqual({ a: "pre-existing-value" });
+  });
+
+  it("present with an undeclared extra key: fails naming the extra key", async () => {
+    const { adapter } = fakeStore({
+      "master-key": { data: { a: "x", rogue: "y" } },
+    });
+    await expect(
+      ensureSecretMaterialization(adapter, { name: "master-key", keys: ["a"] }, canaryGenerator),
+    ).rejects.toThrowError(/undeclared key\(s\) present: rogue/);
+  });
+
+  it("declared metadata mismatch: fails naming the metadata KEY only, never its values", async () => {
+    const { adapter } = fakeStore({
+      "master-key": {
+        data: { a: "x" },
+        metadata: { "chant.dev/provenance": "hand-rolled" },
+      },
+    });
+    let thrown: unknown;
+    try {
+      await ensureSecretMaterialization(
+        adapter,
+        {
+          name: "master-key",
+          keys: ["a"],
+          metadata: { "chant.dev/provenance": "generated-once", "chant.dev/stack": "fountain" },
+        },
+        canaryGenerator,
+      );
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(SecretContractMismatchError);
+    const message = (thrown as Error).message;
+    expect(message).toContain("metadata key differs: chant.dev/provenance");
+    expect(message).toContain("missing declared metadata key: chant.dev/stack");
+    // The KEY is named; neither the declared nor the stored VALUE appears.
+    expect(message).not.toContain("hand-rolled");
+    expect(message).not.toContain("generated-once");
+  });
+
+  it("rejects an empty key-set — there is nothing to materialize", async () => {
+    const { adapter } = fakeStore();
+    await expect(
+      ensureSecretMaterialization(adapter, { name: "master-key", keys: [] }, canaryGenerator),
+    ).rejects.toThrowError(/at least one key/);
+    expect(adapter.exists).not.toHaveBeenCalled();
+  });
+
+  it("never emits the generated material on any log or error surface", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    const stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const { adapter } = fakeStore({ mismatched: { data: { wrong: "stored-value" } } });
+    await ensureSecretMaterialization(adapter, { name: "fresh", keys: ["k1", "k2"] }, canaryGenerator);
+    const failure = await ensureSecretMaterialization(
+      adapter,
+      { name: "mismatched", keys: ["right"] },
+      canaryGenerator,
+    ).catch((e: Error) => e);
+
+    const captured = [logSpy, errorSpy, warnSpy, infoSpy, stdoutSpy, stderrSpy]
+      .flatMap((spy) => spy.mock.calls)
+      .map((call) => call.map((arg) => inspect(arg)).join(" "))
+      .join("\n");
+    expect(captured).not.toContain(CANARY);
+    expect((failure as Error).message).not.toContain(CANARY);
+    expect((failure as Error).message).not.toContain("stored-value");
+  });
+});
+
+describe("SecretMaterial", () => {
+  it("holds the plaintext out of reach: enumeration, JSON, string coercion, and inspect all redact", () => {
+    const material = SecretMaterial.mint(CANARY);
+    expect(Object.keys(material)).toEqual([]);
+    expect(JSON.stringify(material)).toBe('"[secret material]"');
+    expect(String(material)).toBe("[secret material]");
+    expect(inspect(material)).toBe("[secret material]");
+    expect(inspect({ nested: material })).not.toContain(CANARY);
+  });
+
+  it("is consumable exactly once — the adapter takes it, nothing re-reads it", () => {
+    const material = SecretMaterial.mint(CANARY);
+    expect(consumeSecretMaterial(material)).toBe(CANARY);
+    expect(() => consumeSecretMaterial(material)).toThrowError(/already consumed/);
+  });
+
+  it("default generator mints 32 CSPRNG bytes as base64url", () => {
+    const material = defaultSecretMaterialGenerator("any-key");
+    expect(material).toBeInstanceOf(SecretMaterial);
+    const plaintext = consumeSecretMaterial(material as SecretMaterial);
+    expect(plaintext).toMatch(/^[A-Za-z0-9_-]{43}$/);
+  });
+});