@intentius/chant 0.46.0 → 0.50.0

package/src/components/verbs/sign.test.ts

@@ -122,6 +122,25 @@ describe("buildProvenanceStatement — SLSA in-toto statement from #614 provenan
       }),
     ).toThrow(SignTargetNotDigestError);
   });
+
+  it("reserved parameter keys win over caller-supplied collisions (#1943)", () => {
+    const statement = buildProvenanceStatement({
+      imageRef: DIGEST_REF,
+      provenance: { sourceRef: "abc123def", artifactDigest: DIGEST_REF.split("@")[1]! },
+      builderId: "builder",
+      externalParameters: { sourceRef: "spoofed", agent: "reviewer" },
+      internalParameters: { artifactDigest: "spoofed", spriteId: "s-1" },
+    });
+
+    expect(statement.predicate.buildDefinition.externalParameters).toEqual({
+      sourceRef: "abc123def",
+      agent: "reviewer",
+    });
+    expect(statement.predicate.buildDefinition.internalParameters).toEqual({
+      artifactDigest: DIGEST_REF.split("@")[1]!,
+      spriteId: "s-1",
+    });
+  });
 });
 
 describe("attest-provenance — keyless cosign attest (#622)", () => {

package/src/components/verbs/sign.ts

@@ -40,6 +40,19 @@
  * `requireTool` throws `ToolNotAvailableError` with an actionable message if
  * `cosign` is absent, and no test here ever spawns a real process or talks
  * to Rekor/Fulcio.
+ *
+ * **#1943 extension (`run-agent` interop).** `BuildProvenanceStatementInput`
+ * gained two optional merge fields, `externalParameters`/`internalParameters`
+ * — additive only, every existing call site's statement is byte-identical
+ * without them. `run-agent` (./run-agent.ts's `buildRunAgentProvenanceStatement`)
+ * is the first caller to use them, plus `buildType` (already overridable,
+ * unchanged here) set to a `run-agent`-specific recipe URI. `predicateType`
+ * stays `"https://slsa.dev/provenance/v1"` for every caller, `run-agent`
+ * included — see ./run-agent.ts's own doc comment ("Attestation interop")
+ * for why a turn is attested as an SLSA-shaped provenance predicate rather
+ * than under a minted `run-agent`-specific `predicateType`, and why that
+ * decision means `sign`/`attestProvenance`/`../verbs/verify.ts` needed zero
+ * changes to their `cosign` invocations to attest/verify a turn.
  */
 
 import type { Capability } from "../capability";
@@ -235,6 +248,23 @@ export interface BuildProvenanceStatementInput {
   finishedOn?: string;
   /** CI invocation/run id, when available (e.g. a GitHub Actions run id). */
   invocationId?: string;
+  /**
+   * Additional `buildDefinition.externalParameters` merged in alongside the
+   * `{ sourceRef }` default (#1943: `run-agent`'s provenance statement folds
+   * in the fountain-supplied *declared* facts — the agent selector today,
+   * more once fountain `Agent` resolution lands — without run-agent needing
+   * its own predicate builder). `sourceRef` is reserved by this function: a
+   * caller-supplied `sourceRef` is overridden, never signed; any other key
+   * name is the caller's choice.
+   */
+  externalParameters?: Record<string, unknown>;
+  /**
+   * Additional `buildDefinition.internalParameters` merged in alongside the
+   * `{ artifactDigest }` default (#1943: `run-agent` folds in what actually
+   * happened — sprite id, checkpoint id, turn status/exit code — the
+   * *imperative* facts a build's `internalParameters` are for).
+   */
+  internalParameters?: Record<string, unknown>;
 }
 
 const DEFAULT_BUILD_TYPE = "https://chant.dev/build-archive/v1";
@@ -263,8 +293,10 @@ export function buildProvenanceStatement(input: BuildProvenanceStatementInput):
     predicate: {
       buildDefinition: {
         buildType: input.buildType ?? DEFAULT_BUILD_TYPE,
-        externalParameters: { sourceRef: input.provenance.sourceRef },
-        internalParameters: { artifactDigest: input.provenance.artifactDigest },
+        // Reserved keys spread LAST so a caller-supplied key can never clobber
+        // them into a signed statement that disagrees with resolvedDependencies.
+        externalParameters: { ...input.externalParameters, sourceRef: input.provenance.sourceRef },
+        internalParameters: { ...input.internalParameters, artifactDigest: input.provenance.artifactDigest },
         resolvedDependencies: [{ uri: input.provenance.sourceRef, digest: { sha256: digest } }],
       },
       runDetails: {

package/src/components/verbs/wrangler.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Tests `wrangler-deploy`/`wrangler-versions-promote` (#1293, epic #1296,
+ * ./wrangler.ts) against a `MockProcessRunner` — no live `wrangler`, no
+ * network call, ever. Asserts the constructed invocations, the version-id
+ * extraction, the wired output -> promote input handoff, and the
+ * captured-previous-version rollback (the "no hand-written compensation"
+ * claim from #1293's verification section).
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  createWranglerDeployCapability,
+  createWranglerVersionsPromoteCapability,
+  parseWranglerVersionId,
+  WranglerVersionIdNotFoundError,
+} from "./wrangler";
+import { ToolNotAvailableError } from "./process-runner";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+const ctx = { env: "prod", component: "api-worker" };
+const VERSION_A = "07bcb198-9633-4172-a1f0-b09f6f1a1a11";
+const VERSION_B = "aa11bb22-cc33-dd44-ee55-ff6677889900";
+
+describe("wrangler-deploy", () => {
+  it("shells `wrangler deploy` with --config, extracts the Version ID from stdout", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "wrangler deploy": `Uploaded api-worker (1.23 sec)\nVersion ID: ${VERSION_A}\n` },
+    });
+    const capability = createWranglerDeployCapability(mock.runner);
+
+    const output = await capability.run(ctx, { config: "api/wrangler.jsonc" });
+
+    expect(output).toEqual({ versionId: VERSION_A });
+    const deployCall = mock.calls.find((c) => c.command.startsWith("wrangler deploy"))!;
+    expect(deployCall.command).toBe(`wrangler deploy --config 'api/wrangler.jsonc'`);
+  });
+
+  it("passes --env through when supplied", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "wrangler deploy": `Version ID: ${VERSION_A}\n` },
+    });
+    const capability = createWranglerDeployCapability(mock.runner);
+
+    await capability.run(ctx, { config: "api/wrangler.jsonc", env: "staging" });
+
+    const deployCall = mock.calls.find((c) => c.command.startsWith("wrangler deploy"))!;
+    expect(deployCall.command).toBe(`wrangler deploy --config 'api/wrangler.jsonc' --env 'staging'`);
+  });
+
+  it("throws WranglerVersionIdNotFoundError when stdout carries no Version ID", async () => {
+    const mock = createMockProcessRunner({ responses: { "wrangler deploy": "Uploaded, nothing else.\n" } });
+    const capability = createWranglerDeployCapability(mock.runner);
+
+    await expect(capability.run(ctx, { config: "api/wrangler.jsonc" })).rejects.toBeInstanceOf(
+      WranglerVersionIdNotFoundError,
+    );
+  });
+
+  it("throws ToolNotAvailableError when wrangler is absent, rather than silently no-op'ing", async () => {
+    const mock = createMockProcessRunner({ tools: { wrangler: false } });
+    const capability = createWranglerDeployCapability(mock.runner);
+
+    await expect(capability.run(ctx, { config: "api/wrangler.jsonc" })).rejects.toBeInstanceOf(
+      ToolNotAvailableError,
+    );
+  });
+
+  it("declares a rollback (native rollback disposition, no rollbackPolicy override needed)", () => {
+    const capability = createWranglerDeployCapability(createMockProcessRunner().runner);
+    expect(typeof capability.rollback).toBe("function");
+    expect(capability.rollbackPolicy).toBeUndefined();
+  });
+
+  it("rollback is a no-op on a first deploy — nothing was live before it", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "versions list": "[]", "wrangler deploy": `Version ID: ${VERSION_A}\n` },
+    });
+    const capability = createWranglerDeployCapability(mock.runner);
+    await capability.run(ctx, { config: "api/wrangler.jsonc" });
+
+    await capability.rollback!(ctx, { config: "api/wrangler.jsonc" });
+
+    expect(mock.calls.some((c) => c.command.includes("versions deploy"))).toBe(false);
+  });
+
+  it("rollback promotes back to whichever version was live before this deploy — the wrangler-versions-promote back-to-prior-version claim, with no hand-written compensation", async () => {
+    const mock = createMockProcessRunner({
+      responses: {
+        "versions list": JSON.stringify([{ id: VERSION_A, percentage: 100 }]),
+        "wrangler deploy": `Version ID: ${VERSION_B}\n`,
+      },
+    });
+    const capability = createWranglerDeployCapability(mock.runner);
+    await capability.run(ctx, { config: "api/wrangler.jsonc" });
+
+    await capability.rollback!(ctx, { config: "api/wrangler.jsonc" });
+
+    const promoteCall = mock.calls.find((c) => c.command.startsWith("wrangler versions deploy"))!;
+    expect(promoteCall.command).toBe(
+      `wrangler versions deploy '${VERSION_A}@100' --config 'api/wrangler.jsonc' --yes`,
+    );
+  });
+});
+
+describe("wrangler-versions-promote", () => {
+  it("shells `wrangler versions deploy <id>@<pct> --yes`, defaulting percentage to 100", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createWranglerVersionsPromoteCapability(mock.runner);
+
+    const output = await capability.run(ctx, { config: "api/wrangler.jsonc", versionId: VERSION_A });
+
+    expect(output).toEqual({ versionId: VERSION_A, percentage: 100 });
+    const promoteCall = mock.calls.find((c) => c.command.startsWith("wrangler versions deploy"))!;
+    expect(promoteCall.command).toBe(
+      `wrangler versions deploy '${VERSION_A}@100' --config 'api/wrangler.jsonc' --yes`,
+    );
+  });
+
+  it("consumes a wired wrangler-deploy output as its versionId input", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "wrangler deploy": `Version ID: ${VERSION_A}\n` },
+    });
+    const deploy = createWranglerDeployCapability(mock.runner);
+    const promote = createWranglerVersionsPromoteCapability(mock.runner);
+
+    const { versionId } = await deploy.run(ctx, { config: "api/wrangler.jsonc" });
+    const promoted = await promote.run(ctx, { config: "api/wrangler.jsonc", versionId, percentage: 10 });
+
+    expect(promoted).toEqual({ versionId: VERSION_A, percentage: 10 });
+    const promoteCall = mock.calls.find((c) => c.command.startsWith("wrangler versions deploy"))!;
+    expect(promoteCall.command).toContain(`'${VERSION_A}@10'`);
+  });
+
+  it("declares a rollback (native): re-promotes to whichever version was live before this promote call", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "versions list": JSON.stringify([{ id: VERSION_A, percentage: 100 }]) },
+    });
+    const capability = createWranglerVersionsPromoteCapability(mock.runner);
+    await capability.run(ctx, { config: "api/wrangler.jsonc", versionId: VERSION_B });
+
+    await capability.rollback!(ctx, { config: "api/wrangler.jsonc", versionId: VERSION_B });
+
+    const calls = mock.calls.filter((c) => c.command.startsWith("wrangler versions deploy"));
+    expect(calls).toHaveLength(2);
+    expect(calls[0]!.command).toContain(`'${VERSION_B}@100'`);
+    expect(calls[1]!.command).toContain(`'${VERSION_A}@100'`);
+  });
+
+  it("throws ToolNotAvailableError when wrangler is absent", async () => {
+    const mock = createMockProcessRunner({ tools: { wrangler: false } });
+    const capability = createWranglerVersionsPromoteCapability(mock.runner);
+
+    await expect(
+      capability.run(ctx, { config: "api/wrangler.jsonc", versionId: VERSION_A }),
+    ).rejects.toBeInstanceOf(ToolNotAvailableError);
+  });
+});
+
+describe("parseWranglerVersionId", () => {
+  it("accepts both 'Version ID:' and bare 'Version:' wording", () => {
+    expect(parseWranglerVersionId(`Version ID: ${VERSION_A}`)).toBe(VERSION_A);
+    expect(parseWranglerVersionId(`Version: ${VERSION_A}`)).toBe(VERSION_A);
+  });
+
+  it("throws on stdout with no UUID-shaped version token", () => {
+    expect(() => parseWranglerVersionId("Version: 2 (a plain counter, not a version id)")).toThrow(
+      WranglerVersionIdNotFoundError,
+    );
+  });
+});

package/src/components/verbs/wrangler.ts

@@ -0,0 +1,241 @@
+/**
+ * `wrangler-deploy` / `wrangler-versions-promote` — the Cloudflare Workers
+ * apply leaves (chant #1293, epic #1296). The epic cedes the Workers plane
+ * entirely to `wrangler` (first-party, schema-backed, already owns the
+ * config format, bindings model, local dev, and deploy) — these two verbs
+ * are a typed wrapper over that CLI, not a reimplementation of it.
+ *
+ * Placement: core, not a cloudflare lexicon. #1293's own analysis weighed
+ * three options — core (generic verb, fastest, costs a little conceptual
+ * tidiness since `wrangler-deploy` shells a specific vendor CLI), a
+ * capability-only cloudflare lexicon (the "correct" home, but `LexiconPlugin`
+ * tier-1 completeness — serializer, lint rules, post-synth, LSP, examples,
+ * docs — is heavy ceremony for three verbs and no resource types), or
+ * generalizing to a `cli-deploy` verb parameterised by tool (tempting, but
+ * premature and it re-opens the verb set the bounded-primitives thesis
+ * depends on staying closed). Core wins on the same precedent `sign`/
+ * `attest-provenance` (./sign.ts) already set: a specific vendor CLI
+ * (`cosign`) shelled out through the injectable `ProcessRunner`
+ * (./process-runner.ts), no cloud-specific SDK client needed the way AWS's
+ * `CloudExecutor` (./cloud-executor.ts) models CloudFormation/ECS/Lambda.
+ * `wrangler` fits that exact shape. Revisit if/when the zone-plane lexicon
+ * (#1294) lands and gives these three verbs a natural cloudflare-owned home.
+ *
+ * `wrangler-versions-promote` is also the direct evidence for #1296's
+ * "three new verbs cover a whole new cloud" claim: Cloudflare's native
+ * Worker version rollback maps onto the existing `RollbackPolicy: "native"`
+ * (../capability.ts) with no compensation code to hand-write — both verbs
+ * here declare a `rollback` (auto-derived "native" per ../capability.ts's
+ * `Capability.rollbackPolicy` doc) that re-promotes to whichever version was
+ * live before the step ran, the same best-effort captured-previous-state
+ * pattern lexicons/aws/src/components/apply.ts's `lambda-deploy` uses for
+ * its alias rollback.
+ *
+ * No real Cloudflare control-plane emulator exists yet (#1295, epic #1296),
+ * so — like ./sign.ts — every real path here shells out through the
+ * injectable `ProcessRunner` and every test substitutes `MockProcessRunner`
+ * (./__tests__/mock-process-runner.ts): no live `wrangler`, no network, ever,
+ * in a test run. CI coverage is plan-shape/invocation-shape assertions only,
+ * per #1293's own "Verification" section.
+ */
+
+import type { Capability } from "../capability";
+import { defaultProcessRunner, q, requireTool, type ProcessRunner } from "./process-runner";
+
+const WRANGLER_TOOL = "wrangler";
+
+/** Distinguishes one deploy target (a wrangler config + optional named environment) from another, so the best-effort previous-version tracking below never conflates two different Workers sharing a process. */
+function targetKey(config: string, env?: string): string {
+  return env ? `${config}#${env}` : config;
+}
+
+function buildWranglerDeployArgs(input: WranglerDeployInput): string {
+  const args = ["wrangler", "deploy", "--config", q(input.config)];
+  if (input.env) args.push("--env", q(input.env));
+  return args.join(" ");
+}
+
+function buildVersionsListArgs(config: string, env?: string): string {
+  const args = ["wrangler", "versions", "list", "--config", q(config), "--json"];
+  if (env) args.push("--env", q(env));
+  return args.join(" ");
+}
+
+function buildVersionsPromoteArgs(config: string, versionId: string, percentage: number, env?: string): string {
+  const args = ["wrangler", "versions", "deploy", q(`${versionId}@${percentage}`), "--config", q(config), "--yes"];
+  if (env) args.push("--env", q(env));
+  return args.join(" ");
+}
+
+/** Thrown when `wrangler deploy`'s stdout carries no parseable Version ID — fail-closed rather than returning a capability output downstream steps (`wrangler-versions-promote`, wired via `"@Deploy.versionId"`) would silently receive as `undefined`. */
+export class WranglerVersionIdNotFoundError extends Error {
+  constructor(public readonly stdout: string) {
+    super(`wrangler-deploy: could not find a Version ID in wrangler's output. Got:\n${stdout}`);
+    this.name = "WranglerVersionIdNotFoundError";
+  }
+}
+
+// wrangler's deploy/versions-upload output names the new version as e.g.
+// "Version ID: 07bcb198-... " (gradual deployments) — accept either "Version
+// ID:" or the bare "Version:" wording across wrangler versions, and require a
+// UUID-shaped token so a stray "Version: 2" summary line can't be mistaken
+// for it.
+const VERSION_ID_RE = /Version(?: ID)?:\s*([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})/;
+
+/** Extract the deployed Worker version id from `wrangler deploy`'s stdout. Exported so tests can assert on it directly, mirroring ./sign.ts's `buildSignArgs`. */
+export function parseWranglerVersionId(stdout: string): string {
+  const match = VERSION_ID_RE.exec(stdout);
+  if (!match) throw new WranglerVersionIdNotFoundError(stdout);
+  return match[1]!;
+}
+
+interface WranglerVersionsListEntry {
+  id: string;
+  percentage?: number;
+}
+
+/**
+ * Best-effort: the currently-live (100%) version id, from `wrangler versions
+ * list --json` — `undefined` for a first deploy (no versions yet) or if
+ * listing fails/parses oddly. Never throws: capturing "what to roll back to"
+ * must not block the deploy/promote itself, the same fail-soft stance
+ * `lambda-deploy`'s alias-version capture takes.
+ */
+async function currentLiveVersionId(
+  runner: ProcessRunner,
+  config: string,
+  env?: string,
+): Promise<string | undefined> {
+  try {
+    const { stdout } = await runner.run(buildVersionsListArgs(config, env));
+    const entries = JSON.parse(stdout) as WranglerVersionsListEntry[];
+    return entries.find((entry) => entry.percentage === 100)?.id;
+  } catch {
+    return undefined;
+  }
+}
+
+// ── wrangler-deploy ──────────────────────────────────────────────────────────
+
+export interface WranglerDeployInput {
+  /** Path to the Worker's `wrangler.jsonc`/`wrangler.toml`. */
+  config: string;
+  /** Named environment within the config (`wrangler deploy --env <env>`). */
+  env?: string;
+}
+
+export interface WranglerDeployOutput {
+  /** The version id wrangler assigned this deploy — wire into `wrangler-versions-promote` (e.g. `"@Deploy.versionId"`). */
+  versionId: string;
+}
+
+/**
+ * Deploy a Worker from a `wrangler.jsonc`/`wrangler.toml` via `wrangler
+ * deploy`, and return the version id it published — the analogue of
+ * `lambda-deploy` (../../lexicons/aws/src/components/apply.ts) for the
+ * Workers plane.
+ *
+ * Rollback: `wrangler-versions-promote` back to whichever version was live
+ * before this step ran (captured up front via `wrangler versions list`, the
+ * same best-effort captured-previous pattern `lambda-deploy` uses for its
+ * alias). A no-op on a first deploy — nothing was live to restore.
+ */
+export function createWranglerDeployCapability(
+  processRunner: ProcessRunner = defaultProcessRunner(),
+): Capability<WranglerDeployInput, WranglerDeployOutput> {
+  const previousVersionByTarget = new Map<string, string | undefined>();
+
+  return {
+    kind: "wrangler-deploy",
+    async run(_ctx, input) {
+      await requireTool(processRunner, WRANGLER_TOOL, `deploy the Worker in ${input.config}`);
+      const target = targetKey(input.config, input.env);
+      if (!previousVersionByTarget.has(target)) {
+        previousVersionByTarget.set(target, await currentLiveVersionId(processRunner, input.config, input.env));
+      }
+
+      const { stdout } = await processRunner.run(buildWranglerDeployArgs(input));
+      return { versionId: parseWranglerVersionId(stdout) };
+    },
+    async rollback(_ctx, input) {
+      const target = targetKey(input.config, input.env);
+      const previousVersionId = previousVersionByTarget.get(target);
+      if (!previousVersionId) return; // first deploy — nothing was live before it.
+      await requireTool(processRunner, WRANGLER_TOOL, `roll back the Worker in ${input.config}`);
+      await processRunner.run(buildVersionsPromoteArgs(input.config, previousVersionId, 100, input.env));
+    },
+  };
+}
+
+/** Default `wrangler-deploy` capability, backed by the real `ProcessRunner`. */
+export const wranglerDeployCapability: Capability<WranglerDeployInput, WranglerDeployOutput> =
+  createWranglerDeployCapability();
+
+// ── wrangler-versions-promote ─────────────────────────────────────────────────
+
+export interface WranglerVersionsPromoteInput {
+  /** Path to the Worker's `wrangler.jsonc`/`wrangler.toml`. */
+  config: string;
+  /** Version id to promote — typically wired from a prior `wrangler-deploy` step (`"@Deploy.versionId"`) or a prior version id when this step composes as an explicit rollback. */
+  versionId: string;
+  /** Traffic percentage to route to `versionId`. Default: 100 (full promote/rollback). Below 100 is the gradual-deployment lever. */
+  percentage?: number;
+  /** Named environment within the config (`wrangler versions deploy --env <env>`). */
+  env?: string;
+}
+
+export interface WranglerVersionsPromoteOutput {
+  /** The version id that was promoted. */
+  versionId: string;
+  /** The traffic percentage actually routed to it. */
+  percentage: number;
+}
+
+/**
+ * Promote a Worker version to (some percentage of) live traffic via
+ * `wrangler versions deploy <version-id>@<percentage> --yes` — both the
+ * gradual-deployment lever (`percentage` < 100) and, at `percentage: 100`,
+ * the rollback mechanism: Cloudflare's native version rollback is a promote
+ * to a prior version id, not a redeploy, so this same verb composes as the
+ * explicit compensation step a component wires up (#1293's "verification"
+ * example: forced failure after `wrangler-deploy` -> `wrangler-versions-promote`
+ * back to the prior version, no hand-written compensation needed).
+ *
+ * Also declares its own `rollback` (native, no `rollbackPolicy` override
+ * needed — see ../capability.ts): re-promotes to whichever version was live
+ * before *this* promote call, for the case where the promote step itself is
+ * composed directly (not just as `wrangler-deploy`'s compensation).
+ */
+export function createWranglerVersionsPromoteCapability(
+  processRunner: ProcessRunner = defaultProcessRunner(),
+): Capability<WranglerVersionsPromoteInput, WranglerVersionsPromoteOutput> {
+  const previousVersionByTarget = new Map<string, string | undefined>();
+
+  return {
+    kind: "wrangler-versions-promote",
+    async run(_ctx, input) {
+      await requireTool(processRunner, WRANGLER_TOOL, `promote version ${input.versionId} in ${input.config}`);
+      const percentage = input.percentage ?? 100;
+      const target = targetKey(input.config, input.env);
+      if (!previousVersionByTarget.has(target)) {
+        previousVersionByTarget.set(target, await currentLiveVersionId(processRunner, input.config, input.env));
+      }
+
+      await processRunner.run(buildVersionsPromoteArgs(input.config, input.versionId, percentage, input.env));
+      return { versionId: input.versionId, percentage };
+    },
+    async rollback(_ctx, input) {
+      const target = targetKey(input.config, input.env);
+      const previousVersionId = previousVersionByTarget.get(target);
+      if (!previousVersionId) return; // nothing was live before this promote.
+      await requireTool(processRunner, WRANGLER_TOOL, `roll back version promotion in ${input.config}`);
+      await processRunner.run(buildVersionsPromoteArgs(input.config, previousVersionId, 100, input.env));
+    },
+  };
+}
+
+/** Default `wrangler-versions-promote` capability, backed by the real `ProcessRunner`. */
+export const wranglerVersionsPromoteCapability: Capability<
+  WranglerVersionsPromoteInput,
+  WranglerVersionsPromoteOutput
+> = createWranglerVersionsPromoteCapability();

package/src/composite.ts

@@ -1,5 +1,5 @@
 import { isDeclarable, type Declarable } from "./declarable";
-import { setProvenance } from "./provenance";
+import { setPathProvenance, setProvenance } from "./provenance";
 
 /**
  * Marker symbol for Composite type identification.
@@ -150,10 +150,16 @@ export function Composite<P, M extends CompositeFactoryMembers = CompositeMember
 /**
  * Expands a CompositeInstance into a flat Map of prefixed entity names to Declarables.
  * Handles nested composites recursively.
+ *
+ * @param instanceName - The composite INSTANCE every member belongs to (chant
+ *   #1443), which at the top call is the export name and stays that name
+ *   through nesting — `prefix` grows per member and is not an instance
+ *   identity. Defaults to `prefix` so the top call needs no extra argument.
  */
 export function expandComposite(
   prefix: string,
   instance: CompositeInstance,
+  instanceName: string = prefix,
 ): Map<string, Declarable> {
   const result = new Map<string, Declarable>();
   const shared = (instance as unknown as Record<symbol, unknown>)[SHARED_PROPS] as Record<string, unknown> | undefined;
@@ -164,7 +170,7 @@ export function expandComposite(
     const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
 
     if (isCompositeInstance(member)) {
-      const nested = expandComposite(fullName, member);
+      const nested = expandComposite(fullName, member, instanceName);
       for (const [nestedName, nestedEntity] of nested) {
         // Inner composite already stamped; `??=` keeps the most-specific one.
         if (compositeName) setProvenance(nestedEntity, { composite: compositeName });
@@ -176,6 +182,15 @@ export function expandComposite(
     }
   }
 
+  // Whole-entity origin (chant #1443). Recorded after the loop so a nested
+  // member carries its INNER composite here — the recursive call above already
+  // ran and `setPathProvenance` keeps the first writer.
+  if (compositeName) {
+    for (const entity of result.values()) {
+      setPathProvenance(entity, "", { kind: "composite", composite: compositeName, instance: instanceName });
+    }
+  }
+
   if (shared) {
     for (const entity of result.values()) {
       if ("props" in entity) {
@@ -211,6 +226,20 @@ export function expandComposite(
         Object.defineProperty(entity, "props", {
           value: merged, enumerable: false, configurable: true,
         });
+        // A key the member did not set is the propagating instance's alone, so
+        // it is attributable exactly (chant #1443). A key both sides wrote —
+        // an override, or the array concatenation above — is left to the
+        // whole-entity origin rather than credited to one contributor.
+        if (compositeName) {
+          for (const k of Object.keys(shared)) {
+            if (shared[k] === undefined || existing[k] !== undefined) continue;
+            setPathProvenance(entity, k, {
+              kind: "composite",
+              composite: compositeName,
+              instance: instanceName,
+            });
+          }
+        }
       }
     }
   }

package/src/config.test.ts

@@ -6,6 +6,7 @@ import {
   resolveAutoReleaseDisabled,
   resolveFoldEnabled,
   resolveSbomFormat,
+  resolveKnowledgeDir,
   environmentName,
   environmentNames,
   environmentEndpoint,
@@ -433,3 +434,17 @@ describe("resolveSbomFormat (#606)", () => {
     expect(resolveSbomFormat({}, "cyclonedx")).toBe("cyclonedx");
   });
 });
+
+describe("resolveKnowledgeDir (#1864, design #1059)", () => {
+  test("convention: knowledge/ beside the project root when config is silent", () => {
+    expect(resolveKnowledgeDir({}, "/proj")).toBe(join("/proj", "knowledge"));
+  });
+
+  test("config override honored", () => {
+    expect(resolveKnowledgeDir({ knowledge: { dir: "docs/knowledge" } }, "/proj")).toBe(join("/proj", "docs/knowledge"));
+  });
+
+  test("an empty knowledge object still falls back to the convention name", () => {
+    expect(resolveKnowledgeDir({ knowledge: {} }, "/proj")).toBe(join("/proj", "knowledge"));
+  });
+});

package/src/config.ts

@@ -181,6 +181,9 @@ export const ChantConfigSchema = z.object({
     scanner: z.enum(["grype", "trivy"]).optional(),
     vexSources: z.array(z.string()).optional(),
   }).optional(),
+  knowledge: z.object({
+    dir: z.string().min(1).optional(),
+  }).optional(),
 }).passthrough();
 
 /**
@@ -400,6 +403,21 @@ export interface ChantConfig {
     /** Default VEX document paths (OpenVEX/CycloneDX) applied to every gate. Read where the gate step is composed. */
     vexSources?: string[];
   };
+
+  /**
+   * OKF knowledge bundle location (#1864, design #1059, epic #1057) — the
+   * *input* side of `chant explain --format okf` (#1058): a project may
+   * author knowledge as an OKF v0.2 bundle (a directory of markdown files
+   * with YAML frontmatter) that `./okf-read.ts`'s `loadOkfBundle` reads and
+   * binds to discovered entities via each concept's `binds` frontmatter key.
+   * Convention-first: `knowledge/` beside `chant.config.ts` is used when this
+   * is unset. Set `dir` only when that name is already taken by something
+   * else in the project. See {@link resolveKnowledgeDir}.
+   */
+  knowledge?: {
+    /** Bundle directory, relative to the project root. Defaults to `"knowledge"`. */
+    dir?: string;
+  };
 }
 
 /**
@@ -783,6 +801,18 @@ export function resolveVulnPolicy(config: ChantConfig): Partial<VulnPolicy> {
   return out;
 }
 
+/**
+ * Resolve the OKF knowledge bundle directory (#1864, design #1059):
+ * `knowledge.dir` relative to `projectPath` when configured, else the
+ * `knowledge/` convention beside `chant.config.ts`. Never checks existence —
+ * a project with no bundle yet resolves a path all the same, and
+ * `okf-read.ts`'s `loadOkfBundle` treats a missing directory as an empty
+ * bundle rather than an error.
+ */
+export function resolveKnowledgeDir(config: ChantConfig, projectPath: string): string {
+  return join(projectPath, config.knowledge?.dir ?? "knowledge");
+}
+
 /**
  * Validate and normalize a raw config object into ChantConfig shape.
  */

package/src/deep-observation.test.ts

@@ -48,6 +48,25 @@ describe("normalizeDeepProperties", () => {
     expect(Object.keys(out.mid as Record<string, unknown>)).toEqual(["a", "z"]);
   });
 
+  test("the mask hook collapses a structural secret path to MASKED, on either side (#1830)", () => {
+    const hooks: DeepNormalizationHooks = {
+      mask: (n) => n.entityType === "K8s::Core::Secret" && n.pattern.startsWith("data."),
+    };
+    for (const side of ["declared", "live"] as const) {
+      const out = normalizeDeepProperties(
+        { data: { "app.conf": "c2VjcmV0LWJ5dGVz" }, type: "Opaque" },
+        { entityType: "K8s::Core::Secret", side, hooks },
+      );
+      expect(out).toEqual({ data: { "app.conf": MASKED }, type: "Opaque" });
+    }
+    // Another entity type sails through the same hook untouched.
+    const other = normalizeDeepProperties(
+      { data: { "app.conf": "plain" } },
+      { entityType: "K8s::Core::ConfigMap", side: "live", hooks },
+    );
+    expect(other).toEqual({ data: { "app.conf": "plain" } });
+  });
+
   test("leaves array order alone with no ordering hook", () => {
     const out = normalizeDeepProperties({ Tags: [{ Key: "z" }, { Key: "a" }] }, { entityType: "T", side: "live" });
     expect(out.Tags).toEqual([{ Key: "z" }, { Key: "a" }]);