@intentius/sql-yodeler 0.2.0 → 0.4.0

package/dist/notify/index.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Webhook events (#61). `notify` in yodel.config.ts names the environment
+ * variables that hold a webhook's URL and its signing key (never the values
+ * themselves); `yodel apply`, `yodel plan` and `yodel drift` post an event
+ * when an environment is waiting for approval, when a run was refused or
+ * failed, and when drift is found:
+ *
+ * ```ts
+ * notify: { webhook: "YODEL_WEBHOOK_URL", key: "YODEL_WEBHOOK_KEY", slack: "SLACK_WEBHOOK_URL" }
+ * ```
+ *
+ * The webhook gets the event as JSON, signed (`./verify.ts`); a Slack
+ * incoming webhook, when `slack` names one, gets a line of text. A delivery
+ * that fails is reported on stderr and never changes the command's exit
+ * code: the event is news about the run, not part of it.
+ */
+import type { Io } from "../command.js";
+export * from "./verify.js";
+export declare const NOTIFY_EVENTS: readonly ["waiting", "refused", "failed", "drift"];
+export type NotifyEventKind = (typeof NOTIFY_EVENTS)[number];
+/** `notify` in yodel.config.ts. Each value is the NAME of an environment variable; the config never holds a URL or a key. */
+export interface NotifyConfig {
+    /** The variable holding the webhook's URL. */
+    webhook?: string;
+    /** The variable holding the key the webhook's events are signed with (HMAC-SHA256). Required with `webhook`. */
+    key?: string;
+    /** The variable holding a Slack incoming webhook's URL. Its messages are text and unsigned (Slack does not check a signature). */
+    slack?: string;
+    /** The events to send. Default: all of them. */
+    events?: NotifyEventKind[];
+}
+/** What an event says. The JSON Schema is schemas/event.schema.json. */
+export interface NotifyEvent {
+    version: 1;
+    /** Unique per event; the `x-yodel-delivery` header carries it too, so a receiver can drop a repeat. */
+    id: string;
+    event: NotifyEventKind;
+    /** When yodel sent it, ISO 8601 UTC. */
+    at: string;
+    environment: string;
+    /** The command that sent it. */
+    command: "apply" | "plan" | "drift";
+    /** The command's own word for the outcome (`gated`, `refused`, `denied`, `failed`, `drifted`). */
+    status: string;
+    /** One line a person can read. */
+    summary: string;
+    /** The migrations concerned: the pending ones for apply and plan. */
+    migrations: string[];
+    /** The plan digest the run computed, when it computed one. */
+    digest?: string;
+    /** The command that approves the plan, on `waiting`. */
+    approve?: string;
+    /** Why it was refused or failed: the refusal's message, the failing exit code. */
+    reason?: string;
+    /** drift: the objects changed and missing, and the drift's fingerprint (the same drift, the same fingerprint, run after run). */
+    drift?: {
+        changed: string[];
+        missing: string[];
+        fingerprint?: string;
+    };
+    /** The CI run, when yodel runs in one (GitHub Actions, Forgejo Actions, GitLab CI). */
+    runUrl?: string;
+    /** The repository and commit, when CI says. */
+    repository?: string;
+    commit?: string;
+}
+/** Checks `notify` in yodel.config.ts; returns a message for the first problem, or undefined. */
+export declare function notifyConfigProblem(value: unknown): string | undefined;
+/** Where the CI run is, when yodel runs in one. */
+export declare function ciContext(env: NodeJS.ProcessEnv): Pick<NotifyEvent, "runUrl" | "repository" | "commit">;
+type Fields = Omit<NotifyEvent, "version" | "id" | "at" | "runUrl" | "repository" | "commit">;
+/**
+ * The event for what `yodel apply --json` (or `yodel plan --json`) printed,
+ * or undefined when the outcome is not one an event is sent for.
+ */
+export declare function eventFromRun(command: "apply" | "plan", doc: Record<string, unknown>): Fields | undefined;
+/** The event for what `yodel drift --json` printed, or undefined when nothing drifted. */
+export declare function eventFromDrift(doc: {
+    environment?: string;
+    drifted?: boolean;
+    changed?: Array<{
+        name: string;
+    }>;
+    missing?: string[];
+    fingerprint?: string;
+}): Fields | undefined;
+/** A whole event: the fields, with its id, time and the CI run. */
+export declare function makeEvent(fields: Fields, env?: NodeJS.ProcessEnv, now?: Date): NotifyEvent;
+/** The Slack message for an event: one line of text, with the approve command and the run on `waiting`. */
+export declare function slackMessage(e: NotifyEvent): {
+    text: string;
+};
+export type Fetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+export interface Delivery {
+    target: "webhook" | "slack";
+    ok: boolean;
+    /** The HTTP status, or why there was none. */
+    detail: string;
+}
+/** The request that delivers `event` to the webhook, signed with `key`. */
+export declare function webhookRequest(event: NotifyEvent, key: string, now?: number): {
+    headers: Record<string, string>;
+    body: string;
+};
+/**
+ * Sends the event to what `config` names. Reads the URLs and the key from
+ * `env` at send time. Never throws: each delivery's outcome is returned and
+ * a failed one is written to `io.err`.
+ */
+export declare function sendEvent(config: NotifyConfig | undefined, fields: Fields | undefined, options: {
+    io: Io;
+    verb: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: Fetch;
+    attempts?: number;
+}): Promise<Delivery[]>;

package/dist/notify/index.js

@@ -0,0 +1,210 @@
+/**
+ * Webhook events (#61). `notify` in yodel.config.ts names the environment
+ * variables that hold a webhook's URL and its signing key (never the values
+ * themselves); `yodel apply`, `yodel plan` and `yodel drift` post an event
+ * when an environment is waiting for approval, when a run was refused or
+ * failed, and when drift is found:
+ *
+ * ```ts
+ * notify: { webhook: "YODEL_WEBHOOK_URL", key: "YODEL_WEBHOOK_KEY", slack: "SLACK_WEBHOOK_URL" }
+ * ```
+ *
+ * The webhook gets the event as JSON, signed (`./verify.ts`); a Slack
+ * incoming webhook, when `slack` names one, gets a line of text. A delivery
+ * that fails is reported on stderr and never changes the command's exit
+ * code: the event is news about the run, not part of it.
+ */
+import { randomUUID } from "node:crypto";
+import { DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, signWebhook } from "./verify.js";
+export * from "./verify.js";
+export const NOTIFY_EVENTS = ["waiting", "refused", "failed", "drift"];
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Checks `notify` in yodel.config.ts; returns a message for the first problem, or undefined. */
+export function notifyConfigProblem(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return "notify: expected { webhook, key, slack?, events? }";
+    const v = value;
+    for (const k of Object.keys(v))
+        if (!["webhook", "key", "slack", "events"].includes(k))
+            return `notify.${k}: unknown setting (expected webhook, key, slack, events)`;
+    for (const k of ["webhook", "key", "slack"]) {
+        const n = v[k];
+        if (n === undefined)
+            continue;
+        if (typeof n !== "string" || n.includes("://") || !NAME.test(n)) {
+            return `notify.${k}: the name of the environment variable that holds the ${k === "key" ? "signing key" : "URL"} (such as ${k === "key" ? "YODEL_WEBHOOK_KEY" : k === "slack" ? "SLACK_WEBHOOK_URL" : "YODEL_WEBHOOK_URL"}), never the ${k === "key" ? "key" : "URL"} itself`;
+        }
+    }
+    if (v.webhook !== undefined && v.key === undefined)
+        return "notify.key: a webhook needs a signing key; name the variable that holds it";
+    if (v.key !== undefined && v.webhook === undefined)
+        return "notify.webhook: a key is for a webhook; name the variable that holds its URL";
+    if (v.webhook === undefined && v.slack === undefined)
+        return "notify: name a webhook (with its key) or a slack URL variable";
+    if (v.events !== undefined && !(Array.isArray(v.events) && v.events.every((e) => NOTIFY_EVENTS.includes(e)))) {
+        return `notify.events: a list of ${NOTIFY_EVENTS.join(", ")}`;
+    }
+    return undefined;
+}
+/** Where the CI run is, when yodel runs in one. */
+export function ciContext(env) {
+    const out = {};
+    if (env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY && env.GITHUB_RUN_ID)
+        out.runUrl = `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}`;
+    else if (env.CI_JOB_URL)
+        out.runUrl = env.CI_JOB_URL;
+    else if (env.CI_PIPELINE_URL)
+        out.runUrl = env.CI_PIPELINE_URL;
+    const repository = env.GITHUB_REPOSITORY ?? env.CI_PROJECT_PATH;
+    if (repository)
+        out.repository = repository;
+    const commit = env.GITHUB_SHA ?? env.CI_COMMIT_SHA;
+    if (commit)
+        out.commit = commit;
+    return out;
+}
+const ids = (list) => (Array.isArray(list) ? list.flatMap((p) => (typeof p === "object" && p !== null && typeof p.id === "string" ? [p.id] : [])) : []);
+const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
+const firstLine = (s) => s.split("\n")[0] ?? s;
+/**
+ * The event for what `yodel apply --json` (or `yodel plan --json`) printed,
+ * or undefined when the outcome is not one an event is sent for.
+ */
+export function eventFromRun(command, doc) {
+    const status = str(doc.status) ?? (doc.refusal ? "refused" : undefined);
+    const environment = str(doc.environment) ?? "";
+    const migrations = ids(doc.pending);
+    const digest = str(doc.gatePlanDigest) ?? str(doc.planDigest);
+    const base = { environment, command, migrations, ...(digest ? { digest } : {}) };
+    const refusal = doc.refusal?.message;
+    const deniedRules = Array.isArray(doc.policy) ? doc.policy.filter((r) => r.outcome === "denied").map((r) => r.id ?? "") : [];
+    if (status === "gated") {
+        const approve = str(doc.approve);
+        return { ...base, event: "waiting", status, summary: `${environment} is waiting for approval of ${digest ?? "its plan"} (${String(migrations.length)} migration${migrations.length === 1 ? "" : "s"})`, ...(approve ? { approve } : {}) };
+    }
+    if (status === "refused" || status === "denied" || (command === "plan" && (refusal !== undefined || deniedRules.length > 0))) {
+        const reason = typeof refusal === "string" ? refusal : deniedRules.length > 0 ? `policy rule ${deniedRules.join(", ")} denies the plan` : status === "refused" ? "refused" : "denied by policy";
+        return { ...base, event: "refused", status: status ?? (refusal !== undefined ? "refused" : "denied"), summary: `${command} in ${environment} was refused: ${firstLine(reason)}`, reason };
+    }
+    if (status === "failed" || status === "incomplete") {
+        const code = typeof doc.exitCode === "number" ? doc.exitCode : undefined;
+        const reason = `${command} ${status}${code !== undefined ? ` (exit ${String(code)})` : ""}`;
+        return { ...base, event: "failed", status, summary: `${command} in ${environment} ${status}${code !== undefined ? ` with exit ${String(code)}` : ""}`, reason };
+    }
+    return undefined;
+}
+/** The event for what `yodel drift --json` printed, or undefined when nothing drifted. */
+export function eventFromDrift(doc) {
+    if (!doc.drifted)
+        return undefined;
+    const changed = (doc.changed ?? []).map((c) => c.name);
+    const missing = doc.missing ?? [];
+    const environment = doc.environment ?? "";
+    return {
+        event: "drift",
+        environment,
+        command: "drift",
+        status: "drifted",
+        migrations: [],
+        summary: `${environment} drifted: ${[changed.length > 0 ? `${changed.join(", ")} changed` : "", missing.length > 0 ? `${missing.join(", ")} missing` : ""].filter(Boolean).join("; ")}`,
+        drift: { changed, missing, ...(doc.fingerprint ? { fingerprint: doc.fingerprint } : {}) },
+    };
+}
+/** A whole event: the fields, with its id, time and the CI run. */
+export function makeEvent(fields, env = process.env, now = new Date()) {
+    return { version: 1, id: randomUUID(), at: now.toISOString(), ...fields, ...ciContext(env) };
+}
+/** The Slack message for an event: one line of text, with the approve command and the run on `waiting`. */
+export function slackMessage(e) {
+    const lines = [`yodel ${e.event}: ${e.summary}`];
+    if (e.approve)
+        lines.push(`Approve with: \`${e.approve}\``);
+    if (e.runUrl)
+        lines.push(`Run: ${e.runUrl}`);
+    return { text: lines.join("\n") };
+}
+/** The request that delivers `event` to the webhook, signed with `key`. */
+export function webhookRequest(event, key, now = Math.floor(Date.now() / 1000)) {
+    const body = JSON.stringify(event);
+    return {
+        body,
+        headers: {
+            "content-type": "application/json",
+            "user-agent": "sql-yodeler",
+            [EVENT_HEADER]: event.event,
+            [DELIVERY_HEADER]: event.id,
+            [TIMESTAMP_HEADER]: String(now),
+            [SIGNATURE_HEADER]: signWebhook(key, now, body),
+        },
+    };
+}
+async function post(fetchFn, url, request, attempts) {
+    let last = "";
+    for (let i = 0; i < attempts; i++) {
+        if (i > 0)
+            await new Promise((r) => setTimeout(r, 500 * i));
+        try {
+            const res = await fetchFn(url, { method: "POST", ...request, signal: AbortSignal.timeout(10_000) });
+            if (res.ok)
+                return undefined;
+            last = `HTTP ${String(res.status)}`;
+            // A 4xx will not change on a retry: the receiver refused the event (a signature it does not accept, say).
+            if (res.status < 500)
+                return last;
+        }
+        catch (e) {
+            last = e instanceof Error ? e.message : String(e);
+        }
+    }
+    return last;
+}
+/**
+ * Sends the event to what `config` names. Reads the URLs and the key from
+ * `env` at send time. Never throws: each delivery's outcome is returned and
+ * a failed one is written to `io.err`.
+ */
+export async function sendEvent(config, fields, options) {
+    if (!config || !fields)
+        return [];
+    if (config.events && !config.events.includes(fields.event))
+        return [];
+    const env = options.env ?? process.env;
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    const attempts = options.attempts ?? 3;
+    const event = makeEvent(fields, env);
+    const out = [];
+    const warn = (d) => {
+        options.io.err(`yodel ${options.verb}: notify: the ${fields.event} event was not delivered to the ${d.target}: ${d.detail}\n`);
+    };
+    if (config.webhook) {
+        const url = env[config.webhook];
+        const key = config.key ? env[config.key] : undefined;
+        let d;
+        if (!url)
+            d = { target: "webhook", ok: false, detail: `${config.webhook} is not set` };
+        else if (!key)
+            d = { target: "webhook", ok: false, detail: `${config.key ?? "the key variable"} is not set, and yodel does not send an unsigned event` };
+        else {
+            const failed = await post(fetchFn, url, webhookRequest(event, key), attempts);
+            d = { target: "webhook", ok: failed === undefined, detail: failed ?? "delivered" };
+        }
+        if (!d.ok)
+            warn(d);
+        out.push(d);
+    }
+    if (config.slack) {
+        const url = env[config.slack];
+        let d;
+        if (!url)
+            d = { target: "slack", ok: false, detail: `${config.slack} is not set` };
+        else {
+            const failed = await post(fetchFn, url, { headers: { "content-type": "application/json" }, body: JSON.stringify(slackMessage(event)) }, attempts);
+            d = { target: "slack", ok: failed === undefined, detail: failed ?? "delivered" };
+        }
+        if (!d.ok)
+            warn(d);
+        out.push(d);
+    }
+    return out;
+}
+//# sourceMappingURL=index.js.map

package/dist/notify/index.js.map

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

package/dist/notify/verify.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Signing and checking a yodel webhook event (#61). This module needs only
+ * node:crypto, so a receiver can import it alone:
+ *
+ * ```ts
+ * import { verifyWebhook } from "@intentius/sql-yodeler/webhook";
+ *
+ * const checked = verifyWebhook({ body, headers: req.headers, key: process.env.YODEL_WEBHOOK_KEY });
+ * if (!checked.ok) return reply(401, checked.reason);
+ * handle(checked.event);
+ * ```
+ *
+ * The signature is HMAC-SHA256, keyed with the secret, over
+ * `<timestamp>.<body>`: the `x-yodel-timestamp` header (seconds since the
+ * epoch), a dot, and the request body exactly as sent. It travels as
+ * `x-yodel-signature: sha256=<hex>`. Signing the timestamp with the body
+ * lets a receiver refuse a delivery replayed later; {@link verifyWebhook}
+ * refuses one older than five minutes by default.
+ */
+export declare const SIGNATURE_HEADER = "x-yodel-signature";
+export declare const TIMESTAMP_HEADER = "x-yodel-timestamp";
+export declare const EVENT_HEADER = "x-yodel-event";
+export declare const DELIVERY_HEADER = "x-yodel-delivery";
+/** How old a delivery {@link verifyWebhook} still accepts, in seconds. */
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/** `sha256=<hex>` of `<timestamp>.<body>`, keyed with `key`. */
+export declare function signWebhook(key: string, timestamp: number | string, body: string): string;
+export type WebhookHeaders = Record<string, string | readonly string[] | undefined> | Headers;
+export interface VerifyInput {
+    /** The request body exactly as received, before any JSON parsing. */
+    body: string | Uint8Array;
+    /** The request's headers; names are matched without regard to case. */
+    headers: WebhookHeaders;
+    /** The shared secret. An empty or missing key never verifies. */
+    key: string | undefined;
+    /** Now, in seconds since the epoch. Default: the clock. */
+    now?: number;
+    /** How old a delivery may be, in seconds. Default {@link DEFAULT_TOLERANCE_SECONDS}. */
+    toleranceSeconds?: number;
+}
+export type VerifyResult = {
+    ok: true;
+    event: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether a delivery was signed with `key` and is recent: the signature
+ * header matches (compared in constant time) and the timestamp is within the
+ * tolerance either side of now. On success, the parsed event.
+ */
+export declare function verifyWebhook(input: VerifyInput): VerifyResult;

package/dist/notify/verify.js

@@ -0,0 +1,71 @@
+/**
+ * Signing and checking a yodel webhook event (#61). This module needs only
+ * node:crypto, so a receiver can import it alone:
+ *
+ * ```ts
+ * import { verifyWebhook } from "@intentius/sql-yodeler/webhook";
+ *
+ * const checked = verifyWebhook({ body, headers: req.headers, key: process.env.YODEL_WEBHOOK_KEY });
+ * if (!checked.ok) return reply(401, checked.reason);
+ * handle(checked.event);
+ * ```
+ *
+ * The signature is HMAC-SHA256, keyed with the secret, over
+ * `<timestamp>.<body>`: the `x-yodel-timestamp` header (seconds since the
+ * epoch), a dot, and the request body exactly as sent. It travels as
+ * `x-yodel-signature: sha256=<hex>`. Signing the timestamp with the body
+ * lets a receiver refuse a delivery replayed later; {@link verifyWebhook}
+ * refuses one older than five minutes by default.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const SIGNATURE_HEADER = "x-yodel-signature";
+export const TIMESTAMP_HEADER = "x-yodel-timestamp";
+export const EVENT_HEADER = "x-yodel-event";
+export const DELIVERY_HEADER = "x-yodel-delivery";
+/** How old a delivery {@link verifyWebhook} still accepts, in seconds. */
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+/** `sha256=<hex>` of `<timestamp>.<body>`, keyed with `key`. */
+export function signWebhook(key, timestamp, body) {
+    return `sha256=${createHmac("sha256", key).update(`${String(timestamp)}.${body}`, "utf8").digest("hex")}`;
+}
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? undefined;
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() !== name)
+            continue;
+        return Array.isArray(v) ? v[0] : v;
+    }
+    return undefined;
+}
+/**
+ * Whether a delivery was signed with `key` and is recent: the signature
+ * header matches (compared in constant time) and the timestamp is within the
+ * tolerance either side of now. On success, the parsed event.
+ */
+export function verifyWebhook(input) {
+    if (!input.key)
+        return { ok: false, reason: "no key to verify with" };
+    const body = typeof input.body === "string" ? input.body : Buffer.from(input.body).toString("utf8");
+    const signature = header(input.headers, SIGNATURE_HEADER);
+    const timestamp = header(input.headers, TIMESTAMP_HEADER);
+    if (!signature)
+        return { ok: false, reason: `no ${SIGNATURE_HEADER} header` };
+    if (!timestamp || !/^\d+$/.test(timestamp))
+        return { ok: false, reason: `no ${TIMESTAMP_HEADER} header, or not a number of seconds` };
+    const expected = Buffer.from(signWebhook(input.key, timestamp, body));
+    const given = Buffer.from(signature);
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+        return { ok: false, reason: "the signature does not match" };
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (Math.abs(now - Number(timestamp)) > tolerance)
+        return { ok: false, reason: `the timestamp is more than ${String(tolerance)}s from now` };
+    try {
+        return { ok: true, event: JSON.parse(body) };
+    }
+    catch {
+        return { ok: false, reason: "the body is not JSON" };
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/notify/verify.js.map

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

package/dist/pr/model.d.ts

@@ -10,6 +10,7 @@
  * no ledger entry.
  */
 import type { MigrationStep } from "@intentius/chant-lexicon-sql/migration-statements";
+import { type EnvironmentApprovalMode } from "../approval-mode/index.js";
 import type { GateLedgerPort } from "@intentius/chant/op/gate";
 import { type Environment, type Project, type SqlDialect } from "../project.js";
 import { type MigrationCheck } from "../migrations/index.js";
@@ -17,6 +18,7 @@ import { type MigrateOpRef, type RuleResult, type VersionedEnv } from "../versio
 import { type LatestApproval, type MoveExplanation } from "../versioned/explain.js";
 import type { DigestSubject } from "../versioned/digest.js";
 import type { ServerInfo } from "../server.js";
+import { type WaveView } from "../waves/index.js";
 export interface StepView {
     index: number;
     step: MigrationStep;
@@ -35,7 +37,7 @@ export interface PendingView {
     outOfOrder: boolean;
     /** Where a migration that ran part way resumes. */
     resumeAt?: number | undefined;
-    /** Its pre-migration checks (#52), run before its first statement. */
+    /** Its pre-migration checks (#52) and its statements' pre-checks (#51), run before its first statement. */
     checks?: MigrationCheck[] | undefined;
     steps: StepView[];
 }
@@ -54,6 +56,8 @@ export type ApprovalView = {
     }) | undefined;
     /** Why the ledger was not read. */
     ledgerNote?: string | undefined;
+    /** Which approvals of the gate count (#48), as yodel.config.ts at the base commit has it; absent, `ledger`. */
+    mode?: EnvironmentApprovalMode | undefined;
 };
 export interface VersionedPlan {
     environment: string;
@@ -80,6 +84,8 @@ export interface VersionedPlan {
     policy?: RuleResult[] | undefined;
     /** The comment this one replaces showed another digest: what moved since. */
     sinceLast?: MoveExplanation | undefined;
+    /** The environment's wave in the apply pipeline, when yodel.config.ts declares waves. */
+    wave?: WaveView | undefined;
     notes: string[];
 }
 export interface CollectOptions {

package/dist/pr/model.js

@@ -9,20 +9,25 @@
  * the post-merge apply needs. Nothing here writes: no lock, no history row,
  * no ledger entry.
  */
+import { migrationsApprovalAtBase, portFor, signFlag } from "../approval-mode/index.js";
 import { YodelError } from "../project.js";
-import { scanMigrations } from "../migrations/index.js";
+import { migrationChecks, scanMigrations } from "../migrations/index.js";
 import { describeTopology } from "../history/index.js";
 import { asBackfill } from "../steps/kinds.js";
+import { retainedNote } from "../cleanup/index.js";
 import { EXIT_REFUSED } from "../exit.js";
 import { BROKEN_CHAIN, findMigrateOp, inspect, gitLedger, judgePlan, migrateOpExample, migrationsDir, closeVersioned, openVersioned, outOfOrder, planDigest, sameDigest, statusReport, } from "../versioned/index.js";
 import { currentSubject, explainAgainst, explainMove, latestApproval } from "../versioned/explain.js";
+import { waveView } from "../waves/index.js";
+import { policyAtBase } from "../config/base.js";
 const viewOf = (m, done = [], outOfOrder = false, resumeAt, refused = []) => ({
     id: m.id,
     outOfOrder,
     resumeAt,
-    checks: m.document.checks ?? [],
+    checks: migrationChecks(m.document).map((c) => ({ name: c.name, sql: c.sql, ...(c.expect !== undefined ? { expect: c.expect } : {}) })),
     steps: m.document.steps.map((step, index) => {
-        const file = asBackfill(step)?.options.file;
+        const options = asBackfill(step)?.options;
+        const file = options && "file" in options ? options.file : undefined;
         const text = file === undefined ? undefined : m.files.extra?.[file];
         return { index, step, done: done.includes(index), refused: refused.find((r) => r.index === index)?.reason, ...(file !== undefined && text !== undefined ? { source: { file, text } } : {}) };
     }),
@@ -78,11 +83,18 @@ async function collectWith(project, env, options, venv, ordered, base, problems)
         if (!(await sameDigest(prev, report.digest)))
             plan.sinceLast = await explainMove({ approvedDigest: prev, now: subject, previous: options.previous, ordered, applied: status.applied });
     }
+    const kept = await retainedNote(venv);
+    if (kept)
+        plan.notes.push(kept);
     plan.approval = await approvalView(project, env, venv, ordered, plan, options);
-    if (project.yodel?.config.policy && !report.refusal) {
+    // The policy as the base commit has it (#73): a pull request that loosens a rule is judged by the old one.
+    const basePolicy = await policyAtBase(project, options.processEnv);
+    if (basePolicy.note)
+        plan.notes.push(basePolicy.note);
+    if (basePolicy.policy && !report.refusal) {
         const approval = plan.approval;
         plan.policy = await judgePlan({
-            policy: project.yodel.config.policy,
+            policy: basePolicy.policy,
             environment: env.name,
             dialect: project.dialect,
             toApply: status.pending,
@@ -99,6 +111,14 @@ async function collectWith(project, env, options, venv, ordered, base, problems)
             },
         });
     }
+    if (report.digest && !report.refusal) {
+        try {
+            plan.wave = await waveView(project, env.name, ordered, status.pending, report.digest);
+        }
+        catch (e) {
+            plan.notes.push(`The wave's gate could not be read at the base commit: ${e instanceof Error ? (e.message.split("\n")[0] ?? "") : String(e)}`);
+        }
+    }
     return plan;
 }
 async function approvalView(project, env, venv, ordered, plan, options) {
@@ -111,16 +131,18 @@ async function approvalView(project, env, venv, ordered, plan, options) {
             throw e;
         return { kind: "no-op", message: e.message.includes("no Op applies") ? `no Op applies the migrations to ${env.name}; declare one, for example:\n\n${migrateOpExample(env.name)}` : e.message };
     }
+    const mode = await migrationsApprovalAtBase(project, env.name);
     const view = {
         kind: "op",
         op: op.name,
         gate: op.gate,
-        command: plan.digest ? `chant approve ${op.name} ${op.gate} --plan ${plan.digest}` : undefined,
+        command: plan.digest ? `chant approve ${op.name} ${op.gate} --plan ${plan.digest}${signFlag(mode.mode)}` : undefined,
+        ...(mode.mode !== "ledger" ? { mode: mode.mode } : {}),
     };
     if (options.ledger === null)
         return view;
     try {
-        const ledger = options.ledger ?? (await gitLedger(project.dir));
+        const ledger = await portFor(options.ledger ?? (await gitLedger(project.dir)), mode.mode, project.dir, mode.base);
         const latest = await latestApproval(ledger, op, plan.digest);
         if (!latest)
             return view;