@intentius/chant 0.114.1 → 0.116.0

package/dist/op/op-waves-run.d.ts

@@ -0,0 +1,115 @@
+/**
+ * What an Op waves job runs (#3679): `chant run wave --spec <file> --wave <k>`.
+ * `./op-waves.ts` holds the spec and the jobs; this plans a wave's runs,
+ * decides its gate and applies it.
+ *
+ * - Plan: each run's `plan` command writes a plan file; its `planDigest` is
+ *   the run's member digest, named by its target.
+ * - Decide: the wave's policy comes from the spec file at the base commit
+ *   (`git show <base>:<file>`), so a change cannot loosen its own gate. A
+ *   wave missing there, or a file missing there, is `always`. A wave that
+ *   needs an approval waits on `<gate>-wave-<k>` bound to
+ *   {@link waveSetDigest} over its members, and exits 3 when nobody approved
+ *   that digest.
+ * - Apply: each run's `apply` command. A share job (`--share i`) re-plans its
+ *   slice first and refuses, without applying it, a run whose plan digest is
+ *   not the one the deciding job recorded (exit 4).
+ */
+import { type WaveMember } from "../gated-waves.js";
+import { type GateLedgerPort } from "./gate.js";
+import { type OpWaveGatePolicy, type OpWavesSpec } from "./op-waves.js";
+/** What a run's plan command writes to `{plan}`. */
+export interface OpWavePlanFile {
+    planDigest: string;
+    /** The plan destroys, rewrites or otherwise needs a person under `on-destructive`. */
+    destructive?: boolean;
+    /** The plan changes nothing. */
+    empty?: boolean;
+}
+/** One run's plan, as the decision records it. */
+export interface OpWaveMember extends WaveMember {
+    op: string;
+    destructive?: boolean;
+    empty?: boolean;
+}
+/** Where a wave's policy came from. */
+export type OpWavePolicySource = "base" | "absent-at-base";
+/** A wave's decision: what was planned, the policy, and whether it may apply. */
+export interface OpWaveDecision {
+    wave: number;
+    name: string;
+    /** The op the gate is recorded under: the spec's name. */
+    op: string;
+    gate: string;
+    policy: OpWaveGatePolicy;
+    policySource: OpWavePolicySource;
+    /** The base commit the policy was read at. */
+    base: string;
+    digest: string;
+    members: OpWaveMember[];
+    /** `approved`: an approval of this digest stands. `not-required`: the policy lets it through. `waiting`: neither. */
+    status: "approved" | "not-required" | "waiting";
+    approvedBy?: string;
+    /** The command that approves this digest, when waiting. */
+    approve?: string;
+}
+/** Runs one argv; returns its exit code. Injected so tests run no processes. */
+export type OpWaveExec = (argv: string[], cwd: string) => number;
+/** Reads one file at one commit, or null when the commit has no such file. Injected for tests. */
+export type OpWaveShowAtBase = (base: string, path: string, cwd: string) => {
+    sha: string;
+    text: string | null;
+};
+/** Read a spec file, refusing anything that is not one. */
+export declare function parseOpWavesSpec(text: string, where: string): OpWavesSpec;
+/**
+ * The policy of wave `name`, as the spec file at `base` declares it. The
+ * file or the wave missing there reads as `always`: a change that adds a
+ * wave, or the file, waits for a person the first time.
+ */
+export declare function readOpWavePolicy(specFile: string, name: string, base: string, cwd: string, show?: OpWaveShowAtBase): {
+    policy: OpWaveGatePolicy;
+    source: OpWavePolicySource;
+    base: string;
+};
+/** Fill one argv template for one run. */
+export declare function opWaveArgv(template: readonly string[], values: {
+    op: string;
+    target: string;
+    wave: string;
+    plan: string;
+}): string[];
+/** Where a run's plan file goes. */
+export declare function opWavePlanPath(spec: Pick<OpWavesSpec, "name">, wave: number, target: string): string;
+export interface RunOpWaveOptions {
+    spec: OpWavesSpec;
+    specFile: string;
+    /** 1-based. */
+    wave: number;
+    /** Plan and decide only (a wide wave's deciding job). */
+    decide?: boolean;
+    /** Apply this 1-based share of a decided wave. */
+    share?: number;
+    /** Overrides the spec's base. */
+    base?: string;
+    cwd?: string;
+    gates?: GateLedgerPort;
+    exec?: OpWaveExec;
+    show?: OpWaveShowAtBase;
+    now?: string;
+    log?: (line: string) => void;
+}
+export interface RunOpWaveResult {
+    /** 0 applied (or decided), 1 a run failed, 3 waiting for an approval, 4 a plan moved since the decision. */
+    exitCode: number;
+    decision?: OpWaveDecision;
+    applied: string[];
+    failed: string[];
+    /** Runs a share job refused because their plan moved since the decision. */
+    moved: string[];
+}
+/** Whether `policy` lets a wave with these members through without an approval. */
+export declare function opWaveNeedsApproval(policy: OpWaveGatePolicy, members: readonly OpWaveMember[]): boolean;
+/** Plan, decide and apply one wave, or one part of a wide wave. */
+export declare function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveResult>;
+//# sourceMappingURL=op-waves-run.d.ts.map

package/dist/op/op-waves-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-waves-run.d.ts","sourceRoot":"","sources":["../../src/op/op-waves-run.ts"],"names":[],"mappings":"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"}

package/dist/op/op-waves.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Gated waves of Op runs (#3679): a pipeline that applies one Op per
+ * environment, or per target in a set, in order, each wave behind one gate.
+ *
+ * A product built on chant that applies a migration to dev, then staging, then
+ * prod, or the same change to every tenant database of an environment, used to
+ * render that ordering itself, once per forge, and compute each wave's set
+ * digest itself. This module holds the forge-neutral part: the spec, the jobs
+ * it becomes and the commands they run. Each forge lexicon (github, gitlab,
+ * forgejo) renders these jobs with its own transport, so the three cannot
+ * disagree about order or commands. `./op-waves-run.ts` is what the jobs run.
+ *
+ * ## Jobs
+ *
+ * A wave is one job, `wave-<k>-<name>`, running `chant run wave --spec <file>
+ * --wave <k>`: plan every run, decide the wave's gate, apply. A wide wave
+ * (`shares` > 1) is a deciding job that plans every run and decides the gate,
+ * plus `shares` jobs that each apply a slice of the runs and refuse a run
+ * whose plan moved since the decision. Each wave's jobs need the previous
+ * wave's last jobs, so a wave that waits (exit 3) or fails stops every later
+ * wave.
+ *
+ * ## The gate
+ *
+ * Wave k waits on `waveGateName(<gate>, k)`, recorded under the spec's name,
+ * bound to {@link waveSetDigest} over its runs' plan digests (`../gated-waves.ts`,
+ * the same digest a component fan-out's wave binds). Whether it waits at all
+ * is the wave's gate policy, read from the base commit's copy of the spec
+ * file, so a change cannot loosen the rule that gates its own merge.
+ */
+import type { OpEnvironment, OpSetupStep } from "../lexicon.js";
+/** When a wave waits for an approval. */
+export type OpWaveGatePolicy = 
+/** Whenever the wave changes something. */
+"always"
+/** When a run's plan says it is destructive. */
+ | "on-destructive"
+/** Never: only review and branch protection stand in front of the wave. */
+ | "never";
+export declare const OP_WAVE_GATE_POLICIES: readonly OpWaveGatePolicy[];
+/** One Op run in a wave: an Op applied to one target (an environment, a database, a tenant). */
+export interface OpWaveRun {
+    /** What the run applies to. Unique within its wave; it names the run in the set digest. */
+    target: string;
+    /** The Op to run. Default: the spec's `op`. */
+    op?: string;
+}
+/** One wave: runs that apply together, behind one gate. */
+export interface OpWave {
+    /** The wave's name, usually its environment. Lowercase letters, digits, `-` and `_`. */
+    name: string;
+    runs: OpWaveRun[];
+    /**
+     * When the wave waits. Default `"always"`. The runner reads this from the
+     * spec file at the base commit, never from the change being applied.
+     */
+    gate?: OpWaveGatePolicy;
+    /**
+     * Split the wave into a deciding job and this many share jobs, each
+     * applying a slice of the runs. Default 1: one job plans, decides and
+     * applies.
+     */
+    shares?: number;
+    /** The forge deployment environment the wave's jobs run in (GitHub and GitLab; Forgejo has none). */
+    environment?: OpEnvironment;
+    /** Variables for this wave's jobs alone. */
+    variables?: Record<string, string>;
+    /** Steps this wave's jobs run after the checkout, as `ScheduledOpSpec.setup`. */
+    setup?: OpSetupStep[];
+}
+/**
+ * An ordered list of waves of Op runs, as a pipeline and as the file its jobs
+ * read. Commands are argv templates; each `{op}`, `{target}`, `{wave}` and
+ * `{plan}` is replaced per run.
+ */
+export interface OpWavesSpec {
+    /** The pipeline's name, and the op the wave gates are recorded under (`chant approve <name> <gate>-wave-<k>`). */
+    name: string;
+    /** The Op a run runs when it names none. */
+    op: string;
+    /** The base gate name. Default: `name`. */
+    gate?: string;
+    /** Branches whose pushes run the waves. Default `["main"]`. */
+    branches?: string[];
+    /**
+     * The commit the gate policy is read from. Default `HEAD^1`, the first
+     * parent: on a merge or squash onto the branch, the branch before the change.
+     */
+    base?: string;
+    /**
+     * Plan one run and write its plan file to `{plan}`: JSON `{ "planDigest":
+     * string, "destructive"?: boolean, "empty"?: boolean }`. `destructive` is
+     * what `on-destructive` waits on; a wave whose runs are all `empty` never
+     * waits.
+     */
+    plan: string[];
+    /** Apply one run whose plan is at `{plan}`. Default `chant run {op} --env {target}`. */
+    apply?: string[];
+    waves: OpWave[];
+}
+/** The default apply command. */
+export declare const OP_WAVE_DEFAULT_APPLY: string[];
+/** Where the runner keeps a wave's decision; a wide wave's deciding job hands it to its share jobs. */
+export declare function opWaveRecordPath(spec: Pick<OpWavesSpec, "name">, wave: number): string;
+/** One generated job. */
+export interface OpWaveJob {
+    jobName: string;
+    /** 1-based wave number. */
+    wave: number;
+    /** The wave's name. */
+    waveName: string;
+    /** `wave`: plan, decide and apply. `decide`: plan and decide. `share`: apply one slice. */
+    kind: "wave" | "decide" | "share";
+    /** 1-based, on a share job. */
+    share?: number;
+    /** Jobs this one waits on. */
+    needs: string[];
+    /** The job's command, as argv. */
+    command: string[];
+    /** On a share job: the decision record to download. On a deciding job: the one to upload. */
+    record?: string;
+}
+/** Refuse a spec no job could run, naming what is wrong. */
+export declare function assertOpWavesSpec(spec: OpWavesSpec): void;
+/**
+ * The runs share `share` (1-based) of `shares` applies: the wave's runs sorted
+ * by target, cut into contiguous slices whose sizes differ by at most one.
+ */
+export declare function opWaveShare<T extends {
+    target: string;
+}>(runs: readonly T[], share: number, shares: number): T[];
+/**
+ * The jobs of an Op waves pipeline, in order. `specFile` is the spec's path
+ * from the job's working directory, which every command names.
+ */
+export declare function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[];
+/** The wave a job belongs to. */
+export declare function opWaveOf(spec: OpWavesSpec, job: Pick<OpWaveJob, "wave">): OpWave;
+//# sourceMappingURL=op-waves.d.ts.map

package/dist/op/op-waves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-waves.d.ts","sourceRoot":"","sources":["../../src/op/op-waves.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.114.1",
+  "version": "0.116.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/lifecycle.ts

@@ -1039,7 +1039,8 @@ function renderDeepDiff(
         // Both sides of the attribution, where each is known (#1443/#1189).
         const from = change.origin ? ` [from: ${describePathOrigin(change.origin)}]` : "";
         const owner = change.owner ? ` [owner: ${change.owner}]` : "";
-        console.log(`      ${change.path}: ${declared} → ${live}${baseline}${from}${owner}`);
+        const seen = change.seenOn ? ` [seen on: ${change.seenOn}]` : "";
+        console.log(`      ${change.path}: ${declared} → ${live}${baseline}${from}${owner}${seen}`);
         // chant #2161 — what may be done about it, when the origin says
         // something today's behaviour would get wrong. A field the author
         // declared directly is left unremarked: editing it IS today's

package/src/cli/handlers/run-generate.ts

@@ -26,7 +26,8 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
-import { generateOpsPipeline } from "../../op/generate-pipeline";
+import { generateOpsPipeline, generateOpWavesPipeline } from "../../op/generate-pipeline";
+import { parseOpWavesSpec } from "../../op/op-waves-run";
 import { GENERATED_MARKER } from "../../discovery/files";
 import { findWorkspaceRoot } from "../../project-root";
 import type { ComponentPipelineOptions, ScheduledOpSpec } from "../../lexicon";
@@ -71,10 +72,59 @@ export function readOpSpecFile(path: string): SpecFile {
   return { ops: ops as ScheduledOpSpec[], ...(options ? { options } : {}) };
 }
 
+/** True when a `--spec` file holds an Op waves spec (#3679) rather than a list of scheduled Ops. */
+function holdsOpWaves(path: string): boolean {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as { waves?: unknown } | null;
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && parsed.waves !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `chant run --generate <provider> --spec <waves.json>` (#3679): one pipeline
+ * file of ordered, gated waves of Op runs. Its jobs read the same file.
+ */
+async function runOpWavesGenerate(ctx: CommandContext, provider: string, specPath: string): Promise<number> {
+  const { args } = ctx;
+  let spec;
+  let options: Record<string, unknown> | undefined;
+  try {
+    const text = readFileSync(resolve(specPath), "utf-8");
+    spec = parseOpWavesSpec(text, `--spec ${specPath}`);
+    const parsed = JSON.parse(text) as { options?: Record<string, unknown> };
+    options = Array.isArray((parsed as { waves?: unknown }).waves) ? undefined : parsed.options;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+  const result = await generateOpWavesPipeline(spec, provider, { ...options, specFile: specPath.replace(/^\.\//, "") });
+  if (!result.success) {
+    console.error(formatError({ message: result.error ?? "Failed to generate the Op waves pipeline" }));
+    return 1;
+  }
+  const header = opPipelineHeader(provider, specPath);
+  const outDir = args.output ?? DEFAULT_OP_PIPELINE_DIRS[provider] ?? ".";
+  const files = (result.files ?? []).map((f) => ({ name: f.name, path: join(outDir, f.name), content: header + f.yaml }));
+  if (args.format === "json") {
+    console.log(JSON.stringify({ files, jobs: result.jobs ?? [] }, null, 2));
+    return 0;
+  }
+  for (const file of files) {
+    const target = resolve(file.path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.content);
+    console.error(formatSuccess(`wrote ${formatBold(file.path)}`));
+  }
+  return 0;
+}
+
 export async function runOpGenerate(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const provider = args.generate as string;
   const specPath = args.opsSpec;
+  if (specPath && holdsOpWaves(resolve(specPath))) return runOpWavesGenerate(ctx, provider, specPath);
 
   let ops: ScheduledOpSpec[];
   let options: ComponentPipelineOptions | undefined;

package/src/cli/handlers/run-wave.ts

@@ -0,0 +1,43 @@
+/**
+ * `chant run wave --spec <file> --wave <k>` (#3679): the command each job of
+ * a generated Op waves pipeline runs. See `../../op/op-waves-run.ts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { parseOpWavesSpec, runOpWave } from "../../op/op-waves-run";
+import { formatError } from "../format";
+import type { CommandContext } from "../registry";
+
+export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const specFile = args.opsSpec;
+  if (!specFile || args.wave === undefined) {
+    console.error(formatError({
+      message: "`chant run wave` needs --spec <file> and --wave <k>",
+      hint: "Run it as a generated Op waves pipeline does: chant run wave --spec <file> --wave <k> [--decide | --share <i>]",
+    }));
+    return 1;
+  }
+  if (args.decide && args.share !== undefined) {
+    console.error(formatError({ message: "--decide and --share are two different jobs; pass one" }));
+    return 1;
+  }
+  try {
+    const path = resolve(specFile);
+    const spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
+    const result = await runOpWave({
+      spec,
+      specFile: relative(process.cwd(), path),
+      wave: args.wave,
+      ...(args.decide ? { decide: true } : {}),
+      ...(args.share !== undefined ? { share: args.share } : {}),
+      ...(args.base ? { base: args.base } : {}),
+    });
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    return result.exitCode;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+}

package/src/cli/main.ts

@@ -36,6 +36,7 @@ import { runGraph } from "./handlers/graph";
 import { runExplain } from "./handlers/explain";
 import { runSearch } from "./handlers/search";
 import { runOp, runOpList, runOpStatus, runOpApprove, runOpSignalRenamed, runOpCancel, runOpLog } from "./handlers/run";
+import { runOpWaveCommand } from "./handlers/run-wave";
 import { runOperator, runOperatorStatus, runOperatorLog, runApprove } from "./handlers/operator";
 import { runEmulator } from "./handlers/emulator";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
@@ -106,6 +107,7 @@ const BOOLEAN_FLAGS = new Set([
   "--allow-code",
   "--root-only",
   "--generated",
+  "--decide",
 ]);
 
 /**
@@ -355,6 +357,13 @@ export function parseArgs(args: string[]): ParsedArgs {
       const wave = Number(raw);
       if (!Number.isInteger(wave) || wave < 1) throw new Error(`--wave needs a wave number from 1: got "${raw ?? ""}"`);
       result.wave = wave;
+    } else if (arg === "--decide") {
+      result.decide = true;
+    } else if (arg === "--share") {
+      const raw = args[++i];
+      const share = Number(raw);
+      if (!Number.isInteger(share) || share < 1) throw new Error(`--share needs a share number from 1: got "${raw ?? ""}"`);
+      result.share = share;
     } else if (arg === "--canary") {
       const raw = args[++i];
       if (!raw || raw.startsWith("-")) throw new Error("--canary needs a component name: --canary <name>[,<name>...]");
@@ -909,6 +918,10 @@ Ops:
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
   run cancel <name>     Cancel the active run (requires --force)
   run log <name>        Show run history for an Op
+  run wave --spec <file> --wave <k>  Plan, gate and apply wave k of an Op
+                        waves spec (#3679): the job a generated waves
+                        pipeline runs. --decide plans and decides only;
+                        --share <i> applies one share of a decided wave
   run --generate <provider>  Write one CI pipeline file per scheduled Op for
                         github, gitlab or forgejo (#2533), from every Op that
                         declares a schedule or from --spec <file.json>.
@@ -1815,6 +1828,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "run signal", handler: runOpSignalRenamed },
   { name: "run cancel", handler: runOpCancel },
   { name: "run log", handler: runOpLog },
+  { name: "run wave", handler: runOpWaveCommand },
   { name: "run", handler: runOp },
 
   { name: "operator status", handler: runOperatorStatus },

package/src/cli/registry.ts

@@ -248,8 +248,12 @@ export interface ParsedArgs {
    * <name>`, which generates one CI job per wave.
    */
   waveGate?: string;
-  /** `chant components fan-out --wave <n>` (#3049) — run wave `n` of a `--wave-gate` fan-out and no other. */
+  /** `chant components fan-out --wave <n>` (#3049) — run wave `n` of a `--wave-gate` fan-out and no other. Also `chant run wave --wave <k>` (#3679). */
   wave?: number;
+  /** `chant run wave --decide` (#3679) — plan a wide wave and decide its gate, applying nothing. */
+  decide?: boolean;
+  /** `chant run wave --share <i>` (#3679) — apply share `i` of a decided wide wave. */
+  share?: number;
   /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */
   canary?: string[];
   /**

package/src/deep-observation.ts

@@ -68,6 +68,14 @@ export interface DeepResourceObservation {
    * very different answers to an operator.
    */
   fieldOwners?: Record<string, string>;
+  /**
+   * The server the properties were read from, when a reader reads more than
+   * one copy of the entity and they disagree (#3664): a sql table on a
+   * ClickHouse cluster, read on every shard and replica, reports the copy
+   * that differs from the rest and names its server here. Absent when there
+   * is one copy, or every copy reads the same.
+   */
+  observedOn?: string;
   /**
    * The paths this entity's declaration claims (#2160) — every property chant
    * set, flattened into the diff's own grammar and sorted. Built by core in

package/src/lexicon.ts

@@ -10,6 +10,7 @@ import type { AgentConfigImporter } from "./agents/importer";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { GatedWavePipelineOptions } from "./components/gated-wave-pipeline";
 import type { PrLoopPipelineOptions } from "./components/pr-pipeline";
+import type { OpWaveJob, OpWavesSpec } from "./op/op-waves";
 import type { OkfFile } from "./okf";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
@@ -900,6 +901,23 @@ export interface OpPipelineResult {
   jobs: OpPipelineJob[];
 }
 
+/**
+ * Options for an Op waves pipeline (#3679): the generic knobs of
+ * {@link ComponentPipelineOptions} that apply to every wave job, and the path
+ * of the spec file the jobs read.
+ */
+export interface OpWavesPipelineOptions
+  extends Pick<ComponentPipelineOptions, "image" | "beforeScript" | "extraScript" | "variables" | "opsStage" | "opsFileName"> {
+  /** The spec's path from the repository root. Every job runs `chant run wave --spec <specFile>`. */
+  specFile: string;
+}
+
+/** An Op waves pipeline: one file, and its jobs in order. */
+export interface OpWavesPipelineResult {
+  files: OpPipelineFile[];
+  jobs: OpWaveJob[];
+}
+
 /**
  * Live status of a single deploy unit (a CloudFormation stack, a K8s release, …)
  * addressed by its deployed name — the per-component presence signal
@@ -1325,6 +1343,14 @@ export interface LexiconPlugin {
     options?: ComponentPipelineOptions,
   ): OpPipelineResult;
 
+  /**
+   * Render ordered waves of Op runs, each behind one gate (#3679,
+   * `./op/op-waves.ts`): one job per wave, or a deciding job and share jobs
+   * for a wide one, each wave needing the one before. Only CI-provider
+   * lexicons implement this.
+   */
+  generateOpWavesPipeline?(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult;
+
   /**
    * Host Op runs — the seam `chant run <op> --on <this lexicon>` dispatches to
    * (#2121, epic #2114). Core ships one provider of its own, `local`, and

package/src/lifecycle/deep-diff.test.ts

@@ -8,7 +8,7 @@ import type { BaselineLexicon } from "./observation-baseline";
 const held = (by: string, reason: string) => ({ heldElsewhere: HELD_ELSEWHERE_TAG, by, reason });
 
 const live = (
-  resources: Record<string, { type: string; properties: Record<string, unknown>; fieldOwners?: Record<string, string> }>,
+  resources: Record<string, { type: string; properties: Record<string, unknown>; fieldOwners?: Record<string, string>; observedOn?: string }>,
   unobserved: NormalizedDeepObservation["unobserved"] = {},
 ): NormalizedDeepObservation => ({ resources, unobserved });
 
@@ -242,6 +242,25 @@ describe("diffDeep — owning field manager (#1189)", () => {
   });
 });
 
+// #3664 — a reader that read several copies of an entity (a table on every
+// server of a ClickHouse cluster) names the server whose copy it reported.
+describe("diffDeep — the server a live value was seen on (#3664)", () => {
+  const declared = { events: { type: "ClickHouse::Table", properties: { ttl: "ts + INTERVAL 30 DAY" } } };
+
+  test("rides on every drifted path of that entity", () => {
+    const result = diffDeep({
+      declared,
+      live: live({ events: { type: "ClickHouse::Table", properties: { ttl: "ts + toIntervalDay(7)" }, observedOn: "shard-2" } }),
+    });
+    expect(result.drifted[0].changes[0]).toMatchObject({ path: "ttl", kind: "changed", seenOn: "shard-2" });
+  });
+
+  test("is absent when the reader read one copy", () => {
+    const result = diffDeep({ declared, live: live({ events: { type: "ClickHouse::Table", properties: { ttl: "ts + toIntervalDay(7)" } } }) });
+    expect(result.drifted[0].changes[0]).not.toHaveProperty("seenOn");
+  });
+});
+
 // #1443 — the declared-side counterpart of `owner`. Both sides of one
 // comparison get precise attribution, which is what makes the report actionable.
 describe("diffDeep — declared-side origin (#1443)", () => {

package/src/lifecycle/deep-diff.ts

@@ -107,6 +107,12 @@ export interface PropertyDrift {
    * child, have no expression to attribute (see `EntityProvenance.paths`).
    */
   origin?: PathOrigin;
+  /**
+   * The server the live value was read on, when the reader read the entity
+   * on several and reported the copy that differs (#3664,
+   * `DeepResourceObservation.observedOn`).
+   */
+  seenOn?: string;
 }
 
 /** Property-level drift for one declared entity. */
@@ -382,6 +388,7 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
         ...(hasLive ? { live: liveValue } : {}),
         ...(owner ? { owner } : {}),
         ...(origin ? { origin } : {}),
+        ...(hasLive && liveEntity.observedOn ? { seenOn: liveEntity.observedOn } : {}),
       };
 
       if (acceptedEntry) {

package/src/lifecycle/deep-observe.ts

@@ -160,6 +160,8 @@ export function diffDeepObservation(
         // up by the flattened path, so a keyed list element (`[#name]`) has
         // no owner today — its raw index path is what the reader recorded.
         ...(liveEntity.fieldOwners ? { fieldOwners: liveEntity.fieldOwners } : {}),
+        // Which server's copy was read, when the reader read several (#3664).
+        ...(liveEntity.observedOn ? { observedOn: liveEntity.observedOn } : {}),
         // The claimed-field set (#2160), computed from the declaration and
         // carried on the observation so a consumer holding only this envelope
         // can classify a live value three ways rather than two. Same normalized

package/src/op/activity-registry.test.ts

@@ -124,6 +124,27 @@ describe("loadActivities — multi-lexicon (#706)", () => {
     expect(a.has("waitForStack")).toBe(true); // base still loaded alongside
   });
 
+  // #3657 — the sql lexicon's receipt activities are fallbacks: a sql-only
+  // project's effect() receipts go to its database, and a project that also
+  // lists aws or k8s keeps them in that lexicon's row, in either order.
+  test("sql's fallback receipt activities give way to another lexicon's, in either order (#3657)", async () => {
+    const sql = await loadActivities(["sql"]);
+    const sqlRead = sql.get("receiptRead");
+    expect(typeof sqlRead).toBe("function");
+    expect(sql.has("sqlExec")).toBe(true);
+
+    const aws = (await loadActivities(["aws"])).get("receiptRead");
+    expect(aws).toBeDefined();
+    expect(aws).not.toBe(sqlRead);
+    for (const order of [["sql", "aws"], ["aws", "sql"]]) {
+      const a = await loadActivities(order);
+      expect(a.get("receiptRead"), order.join(",")).toBe(aws);
+      expect(a.get("sqlExec"), order.join(",")).toBe(sql.get("sqlExec"));
+    }
+    const k8s = await loadActivities(["sql", "k8s"]);
+    expect(k8s.get("receiptWrite")).toBe((await loadActivities(["k8s"])).get("receiptWrite"));
+  });
+
   test("unknown lexicon is skipped without throwing", async () => {
     const a = await loadActivities(["definitely-not-a-lexicon"]);
     expect(a.has("waitForStack")).toBe(true); // core base still loads