@intentius/chant 0.46.0 → 0.49.0

package/src/components/verbs/r2-sync.ts

@@ -0,0 +1,124 @@
+/**
+ * `r2-sync` — bulk object upload to a Cloudflare R2 bucket (chant #1293,
+ * epic #1296), the direct analogue of `s3-sync`
+ * (lexicons/aws/src/components/apply.ts): same input shape (`from`/`to`/
+ * `delete`), same mutating-no-native-rollback disposition
+ * (`rollbackPolicy: "needs-opt-out"`, ../../lint/rules/comp/comp003-mutating-no-rollback.ts),
+ * learnable as the same idea per #1293's own verification bullet. See
+ * ./wrangler.ts's module doc for why this lives in core rather than a
+ * cloudflare lexicon.
+ *
+ * R2 has no first-party bulk-sync CLI the way S3 has `aws s3 sync`, but its
+ * API is S3-compatible, so it takes any S3-compatible sync tool — this wraps
+ * `rclone` (its `sync`/`copy` distinguish "mirror, deleting extras" from
+ * "upload only" exactly the way `s3-sync`'s `delete` flag does) through the
+ * same injectable `ProcessRunner` (./process-runner.ts) `./sign.ts` and
+ * `./wrangler.ts` use. No live `rclone`, no network, ever, in a test run —
+ * every test substitutes `MockProcessRunner`.
+ */
+
+import type { Capability } from "../capability";
+import { defaultProcessRunner, q, requireTool, type ProcessRunner } from "./process-runner";
+
+const RCLONE_TOOL = "rclone";
+
+/** Matches an `r2://bucket[/prefix]` destination — mirrors `s3-sync`'s `s3://bucket/prefix` shape. */
+const R2_URI_RE = /^r2:\/\/([^/]+)(?:\/(.*))?$/;
+
+/** Thrown when `R2SyncInput.to` is not an `r2://bucket[/prefix]` URI. */
+export class R2SyncInvalidDestinationError extends Error {
+  constructor(public readonly to: string) {
+    super(
+      `r2-sync: destination "${to}" is not an "r2://bucket[/prefix]" URI — mirror s3-sync's "s3://bucket/prefix" shape.`,
+    );
+    this.name = "R2SyncInvalidDestinationError";
+  }
+}
+
+/**
+ * Translate an `r2://bucket/prefix` destination to rclone's `<remote>:<path>`
+ * form. `remote` is the name of an rclone remote already configured against
+ * R2's S3-compatible endpoint (`<account-id>.r2.cloudflarestorage.com`) —
+ * out of this capability's scope the same way `s3-sync` doesn't configure
+ * AWS credentials; default `"r2"` is the conventional alias. Exported for
+ * tests, mirroring ./sign.ts's `buildSignArgs`.
+ */
+export function toRcloneDest(to: string, remote = "r2"): string {
+  const match = R2_URI_RE.exec(to);
+  if (!match) throw new R2SyncInvalidDestinationError(to);
+  const [, bucket, prefix] = match;
+  return `${remote}:${bucket}${prefix ? `/${prefix}` : ""}`;
+}
+
+export interface R2SyncInput {
+  /** Local path, or archive-relative path, to sync from. */
+  from: string;
+  /** Destination bucket URI, `"r2://bucket/prefix"` — mirrors `s3-sync`'s `S3SyncInput.to` shape. */
+  to: string;
+  /** Delete destination keys not present in the source. Default: false. */
+  delete?: boolean;
+  /** rclone remote name pointed at R2. Default: `"r2"`. */
+  remote?: string;
+}
+
+export interface R2SyncOutput {
+  /** Number of objects uploaded (new or changed). */
+  uploaded: number;
+  /** Number of objects deleted (only possible when `delete: true`). */
+  deleted: number;
+}
+
+/**
+ * Build the `rclone` invocation for `input`. `rclone sync` deletes
+ * destination-only files by default (matching `s3-sync`'s opt-in `delete:
+ * true`); `rclone copy` never deletes (matching the `s3-sync` default) — so
+ * the verb dispatches on `input.delete` rather than passing a `--delete`
+ * flag rclone doesn't have. `-v` gives the per-file action lines
+ * `parseRcloneStats` reads. Exported for tests, mirroring ./sign.ts's
+ * `buildSignArgs`.
+ */
+export function buildR2SyncArgs(input: R2SyncInput): string {
+  const dest = toRcloneDest(input.to, input.remote);
+  const verb = input.delete ? "sync" : "copy";
+  return `rclone ${verb} ${q(input.from)} ${q(dest)} -v`;
+}
+
+// rclone's `-v` per-file log lines end e.g. "path/to/file: Copied (new)",
+// "path/to/file: Copied (replaced existing)", "path/to/file: Deleted".
+const COPIED_NEW_RE = /: Copied \(new\)/g;
+const COPIED_REPLACED_RE = /: Copied \(replaced existing\)/g;
+const DELETED_RE = /: Deleted$/gm;
+
+/** Count uploaded/deleted objects out of `rclone -v`'s stdout. Exported for tests. */
+export function parseRcloneStats(stdout: string): R2SyncOutput {
+  const uploaded = (stdout.match(COPIED_NEW_RE) ?? []).length + (stdout.match(COPIED_REPLACED_RE) ?? []).length;
+  const deleted = (stdout.match(DELETED_RE) ?? []).length;
+  return { uploaded, deleted };
+}
+
+/**
+ * Bulk-sync a directory of objects to an R2 bucket via `rclone`
+ * (endpoint-aware only through the rclone remote's own config — this
+ * capability never touches R2 credentials directly). Mutating, no native
+ * undo (an overwritten or deleted object is gone), so — like `s3-sync` —
+ * `rollbackPolicy: "needs-opt-out"`: COMP003 requires the component to
+ * acknowledge the compensation gap explicitly (a `noRollback` reason, a
+ * component-level `rollback` phase, or a sibling `rollback-previous`/
+ * `snapshot-before` step).
+ */
+export function createR2SyncCapability(
+  processRunner: ProcessRunner = defaultProcessRunner(),
+): Capability<R2SyncInput, R2SyncOutput> {
+  return {
+    kind: "r2-sync",
+    rollbackPolicy: "needs-opt-out",
+    async run(_ctx, input) {
+      await requireTool(processRunner, RCLONE_TOOL, `sync ${input.from} to ${input.to}`);
+      const { stdout } = await processRunner.run(buildR2SyncArgs(input));
+      return parseRcloneStats(stdout);
+    },
+  };
+}
+
+/** Default `r2-sync` capability, backed by the real `ProcessRunner`. */
+export const r2SyncCapability: Capability<R2SyncInput, R2SyncOutput> = createR2SyncCapability();

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/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" }]);

package/src/deep-observation.ts

@@ -266,6 +266,20 @@ export interface DeepNormalizationHooks {
    * reads as permanent drift.
    */
   unresolved?(node: DeepNode): boolean;
+  /**
+   * Return true when this value is secret material the diff must never hold —
+   * it is collapsed to {@link MASKED} on BOTH sides (the hook runs over the
+   * declared and the live tree alike), so presence and key names still
+   * classify while values never reach a diff row, a log line, or a snapshot.
+   *
+   * The pass masks by key name on its own ({@link isSensitiveKey}); this hook
+   * exists for the lexicons whose secret-bearing paths are structural rather
+   * than name-shaped — a Kubernetes Secret's `data` carries arbitrary key
+   * names (`app.conf`), and #1365 decision 6 draws the hard line: drift on a
+   * secret observes presence, declared key-set, and metadata — never a value
+   * or a value-derived hash.
+   */
+  mask?(node: DeepNode): boolean;
 }
 
 /** Everything the pass needs besides the tree itself. */
@@ -405,6 +419,9 @@ export function normalizeDeepProperties(
 
   const normalizeValue = (value: unknown, path: string, pattern: string, key: string): unknown => {
     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).
+    if (hooks?.mask?.(nodeOf(path, pattern, key, value))) return MASKED;
     // A value the lexicon says cannot be known without deploying — an
     // expression-string reference — collapses exactly like a class-instance
     // intrinsic does below.