@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/steps/rebuild.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A `ClickHouseRebuildOp` step: the change ClickHouse cannot make with
+ * `ALTER` (a sort key, an engine, a key column's type or name), run inside
+ * the migration as chant's rebuild Op.
+ *
+ * The Op is chant's own (`ClickHouseRebuildOp` from the sql lexicon), built
+ * from the step's options with the apply's environment, and run by chant's
+ * local executor with the lexicon's rebuild activities:
+ *
+ *   Plan, Create, Dual write (materialized-view mode), Backfill, Verify, Swap, Retain
+ *
+ * Three things differ from running the Op with `chant run`:
+ *
+ * - The declaration is the migration's recorded schema (`migration.json`'s
+ *   `schema`), written to a temporary build file, not a fresh `chant build`:
+ *   the table is rebuilt as this migration declares it, however far the
+ *   declared schema has moved on since.
+ * - Its gates are left out. The swap gate's approval is the migration's:
+ *   the step's options are in the migration's checksum, which is in the plan
+ *   digest the migrations Op's gate approved. The verification still runs
+ *   before the swap, and a difference fails the step with nothing swapped.
+ *   The old table is kept, `<table>__chant_old`, until its retention date
+ *   (7 days); the Op's drop gate and Drop phase are not part of the step.
+ * - Its onFailure (which drops the new table) is left out, so a step that
+ *   failed or was killed part way resumes from the backfill's receipts on
+ *   the next `yodel apply`: every partition with a receipt is skipped. To
+ *   start the rebuild over instead, drop `<table>__chant_new` and
+ *   `<table>__chant_dual`.
+ *
+ * The activities render their DDL for the topology chant resolves from
+ * `sql.profiles.<env>.topology`. When the environment's topology comes from
+ * elsewhere (`yodel.config.ts`, or `YODEL_TOPOLOGY`, #9), the step hands
+ * every rebuild activity chant's config with that topology set on the
+ * profile ({@link rebuildChantConfig}), so the rebuild renders for the same
+ * topology as the migration's statements.
+ */
+import type { OpConfig, PhaseDefinition } from "@intentius/chant/op/types";
+import type { ActivityFn } from "@intentius/chant/op/activity-registry";
+import type { StepRecord } from "@intentius/chant/op/local-executor";
+import type { Topology } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+import type { RebuildOptions } from "./kinds.js";
+import { type ProjectConfig } from "../project.js";
+import { type RunOpOptions } from "./run.js";
+/** `config` with `sql.profiles.<environment>.topology` set to `topology`. Pure; `config` is not changed. */
+export declare function withProfileTopology(config: ProjectConfig, environment: string, topology: Topology): ProjectConfig;
+/**
+ * The chant config a rebuild step's activities bind with: the project's,
+ * with the environment's resolved topology on its profile when chant would
+ * not find it there itself. `undefined` when chant's own resolution already
+ * gives the same topology (set in the profile, or no topology anywhere).
+ */
+export declare function rebuildChantConfig(projectDir: string, environment: string, env?: NodeJS.ProcessEnv): Promise<ProjectConfig | undefined>;
+/** `ClickHouseRebuildOp`'s phases as a step runs them: no gates, no Drop, no onFailure. */
+export declare function stepPhases(config: OpConfig): PhaseDefinition[];
+/** The Op a rebuild step runs. `buildPath` is the recorded schema's file; `projectDir` holds chant.config.ts. */
+export declare function rebuildOpConfig(options: RebuildOptions, ctx: {
+    environment: string;
+    projectDir: string;
+    buildPath: string;
+}): Promise<OpConfig>;
+export interface RebuildSummary {
+    op: "ClickHouseRebuildOp";
+    table: string;
+    /** The Plan's state when the step began: `rebuild`, or `swapped` / `done` when an earlier run got that far. */
+    state?: string;
+    partitions?: number;
+    /** Partitions copied in this run. */
+    copied?: number;
+    /** Partitions skipped: their receipt matched (copied by an earlier run). */
+    skipped?: number;
+    /** Partitions found partly copied and cleared before copying again. */
+    cleared?: number;
+    /** Rows copied by both the backfill and the dual-write view, deleted and copied again. */
+    repaired?: number;
+    /** Rows compared in the whole table, old against new. */
+    verifiedRows?: number;
+    swapped?: boolean;
+    oldTable?: string;
+    retainUntil?: string;
+}
+/** Folds one rebuild activity's result into the summary. */
+export declare function summarize(summary: RebuildSummary, fn: string, result: unknown): void;
+export interface RunRebuildOptions extends Omit<RunOpOptions, "activities" | "cwd"> {
+    projectDir: string;
+    /** The migration's recorded schema: the `chant build` output after it. */
+    schema: unknown;
+    /** Activities to use in place of the lexicon's, for a test. */
+    activities?: Record<string, ActivityFn>;
+    log?: (line: string) => void;
+    /** The chant config the rebuild activities bind with (see {@link rebuildChantConfig}). Default: they load chant.config.ts. */
+    config?: ProjectConfig | undefined;
+}
+/** Runs a rebuild step to the end. The summary is filled in as the activities return, so a failure still says how far it got. */
+export declare function runRebuild(options: RebuildOptions, run: RunRebuildOptions, summary?: RebuildSummary): Promise<{
+    summary: RebuildSummary;
+    records: StepRecord[];
+}>;

package/dist/steps/rebuild.js

@@ -0,0 +1,162 @@
+/**
+ * A `ClickHouseRebuildOp` step: the change ClickHouse cannot make with
+ * `ALTER` (a sort key, an engine, a key column's type or name), run inside
+ * the migration as chant's rebuild Op.
+ *
+ * The Op is chant's own (`ClickHouseRebuildOp` from the sql lexicon), built
+ * from the step's options with the apply's environment, and run by chant's
+ * local executor with the lexicon's rebuild activities:
+ *
+ *   Plan, Create, Dual write (materialized-view mode), Backfill, Verify, Swap, Retain
+ *
+ * Three things differ from running the Op with `chant run`:
+ *
+ * - The declaration is the migration's recorded schema (`migration.json`'s
+ *   `schema`), written to a temporary build file, not a fresh `chant build`:
+ *   the table is rebuilt as this migration declares it, however far the
+ *   declared schema has moved on since.
+ * - Its gates are left out. The swap gate's approval is the migration's:
+ *   the step's options are in the migration's checksum, which is in the plan
+ *   digest the migrations Op's gate approved. The verification still runs
+ *   before the swap, and a difference fails the step with nothing swapped.
+ *   The old table is kept, `<table>__chant_old`, until its retention date
+ *   (7 days); the Op's drop gate and Drop phase are not part of the step.
+ * - Its onFailure (which drops the new table) is left out, so a step that
+ *   failed or was killed part way resumes from the backfill's receipts on
+ *   the next `yodel apply`: every partition with a receipt is skipped. To
+ *   start the rebuild over instead, drop `<table>__chant_new` and
+ *   `<table>__chant_dual`.
+ *
+ * The activities render their DDL for the topology chant resolves from
+ * `sql.profiles.<env>.topology`. When the environment's topology comes from
+ * elsewhere (`yodel.config.ts`, or `YODEL_TOPOLOGY`, #9), the step hands
+ * every rebuild activity chant's config with that topology set on the
+ * profile ({@link rebuildChantConfig}), so the rebuild renders for the same
+ * topology as the migration's statements.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { environmentSettings } from "../config/settings.js";
+import { loadProject } from "../project.js";
+import { runOp, StepOpFailed } from "./run.js";
+/** The rebuild activities whose results the history's summary keeps. */
+const SUMMARIZED = ["clickhouseRebuildPlan", "clickhouseRebuildBackfill", "clickhouseRebuildVerify", "clickhouseRebuildSwap", "clickhouseRebuildRetain"];
+/** `config` with `sql.profiles.<environment>.topology` set to `topology`. Pure; `config` is not changed. */
+export function withProfileTopology(config, environment, topology) {
+    const profiles = config.sql?.profiles ?? {};
+    const profile = profiles[environment];
+    if (!profile)
+        return config;
+    return { ...config, sql: { ...config.sql, profiles: { ...profiles, [environment]: { ...profile, topology } } } };
+}
+/**
+ * The chant config a rebuild step's activities bind with: the project's,
+ * with the environment's resolved topology on its profile when chant would
+ * not find it there itself. `undefined` when chant's own resolution already
+ * gives the same topology (set in the profile, or no topology anywhere).
+ */
+export async function rebuildChantConfig(projectDir, environment, env = process.env) {
+    const project = await loadProject(projectDir);
+    const settings = environmentSettings(project, environment, env);
+    if (settings.topologySource === "default" || settings.topologySource === `sql.profiles.${environment}.topology`)
+        return undefined;
+    return withProfileTopology(project.config, environment, settings.topology);
+}
+/** The activity of the phase left out: the old table's drop, which waits for its retention and its own gate. */
+const LEFT_OUT = new Set(["clickhouseRebuildDrop"]);
+/** `ClickHouseRebuildOp`'s phases as a step runs them: no gates, no Drop, no onFailure. */
+export function stepPhases(config) {
+    return config.phases
+        .map((p) => ({ ...p, steps: p.steps.filter((s) => s.kind !== "gate" && !(s.kind === "activity" && LEFT_OUT.has(s.fn))) }))
+        .filter((p) => p.steps.length > 0);
+}
+/** The Op a rebuild step runs. `buildPath` is the recorded schema's file; `projectDir` holds chant.config.ts. */
+export async function rebuildOpConfig(options, ctx) {
+    const { ClickHouseRebuildOp } = await import("@intentius/chant-lexicon-sql/clickhouse/rebuild/op");
+    const { op } = ClickHouseRebuildOp({
+        name: options.name,
+        env: ctx.environment,
+        table: options.table,
+        dualWrite: options.dualWrite,
+        build: false,
+        output: ctx.buildPath,
+        path: ctx.projectDir,
+    });
+    const full = op.props;
+    const rest = { ...full, phases: stepPhases(full) };
+    delete rest.onFailure;
+    return rest;
+}
+const num = (v) => (typeof v === "number" ? v : undefined);
+const str = (v) => (typeof v === "string" ? v : undefined);
+/** Folds one rebuild activity's result into the summary. */
+export function summarize(summary, fn, result) {
+    const r = (typeof result === "object" && result !== null ? result : {});
+    const put = (k, v) => {
+        if (v !== undefined)
+            summary[k] = v;
+    };
+    if (fn === "clickhouseRebuildPlan")
+        put("state", str(r.state));
+    if (fn === "clickhouseRebuildBackfill") {
+        put("partitions", num(r.partitions));
+        put("copied", num(r.copied));
+        put("skipped", num(r.skipped));
+        put("cleared", num(r.cleared));
+        put("repaired", num(r.repaired));
+    }
+    if (fn === "clickhouseRebuildVerify")
+        put("verifiedRows", num(r.rows));
+    if (fn === "clickhouseRebuildSwap") {
+        put("swapped", typeof r.swapped === "boolean" ? r.swapped : undefined);
+        put("oldTable", str(r.oldTable));
+        put("retainUntil", str(r.retainUntil));
+    }
+    if (fn === "clickhouseRebuildRetain") {
+        put("oldTable", str(r.oldTable));
+        put("retainUntil", str(r.retainUntil));
+    }
+}
+/** Runs a rebuild step to the end. The summary is filled in as the activities return, so a failure still says how far it got. */
+export async function runRebuild(options, run, summary = { op: "ClickHouseRebuildOp", table: options.table }) {
+    const dir = mkdtempSync(join(tmpdir(), "yodel-rebuild-"));
+    try {
+        const buildPath = join(dir, "schema.json");
+        writeFileSync(buildPath, JSON.stringify(run.schema));
+        const config = await rebuildOpConfig(options, { environment: run.environment, projectDir: run.projectDir, buildPath });
+        const lexicon = run.activities ?? (await import("@intentius/chant-lexicon-sql/op/activities"));
+        const wrapped = {};
+        // A rebuild activity takes its config as a third argument (chant's ClickHouseRebuildDeps).
+        const deps = run.config ? { config: run.config } : undefined;
+        const summarized = SUMMARIZED;
+        for (const fn of Object.keys(lexicon).filter((f) => f.startsWith("clickhouseRebuild") && (deps !== undefined || summarized.includes(f)))) {
+            const inner = lexicon[fn];
+            if (!inner)
+                continue;
+            wrapped[fn] = async (args, signal) => {
+                const result = await (deps ? inner(args, signal, deps) : inner(args, signal));
+                if (summarized.includes(fn))
+                    summarize(summary, fn, result);
+                return result;
+            };
+        }
+        const records = await runOp(config, {
+            cwd: run.projectDir,
+            environment: run.environment,
+            activities: { ...(run.activities ?? {}), ...wrapped },
+            ...(run.base ? { base: run.base } : {}),
+            ...(run.signal ? { signal: run.signal } : {}),
+            ...(run.onRecord ? { onRecord: run.onRecord } : {}),
+        }).catch((e) => {
+            if (e instanceof StepOpFailed)
+                e.summary = summary;
+            throw e;
+        });
+        return { summary, records };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=rebuild.js.map

package/dist/steps/rebuild.js.map

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

package/dist/steps/run.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Running an Op step's Op in this process, with chant's local executor
+ * (`runOpLocally`, the executor `chant run` uses), inside the versioned
+ * apply that holds the lock.
+ *
+ * The activities are the ones `chant run` loads for a sql project (core's,
+ * and the sql lexicon's, the rebuild's among them), plus what the step adds
+ * (a backfill's receipt store and its `yodelSql`). Nothing is written to the
+ * run ledger: the history table is the record of what ran.
+ *
+ * A step's Op has no gate of its own here. The migration it is part of was
+ * approved under the plan digest, which covers the step through the
+ * migration's checksum; a gate left in the Op is refused before it runs.
+ */
+import type { OpConfig } from "@intentius/chant/op/types";
+import type { ActivityFn } from "@intentius/chant/op/activity-registry";
+import type { StepRecord } from "@intentius/chant/op/local-executor";
+import { YodelError } from "../project.js";
+/** A step's Op stopped part way. The history records it failed; the next run resumes it. */
+export declare class StepOpFailed extends YodelError {
+    readonly op: string;
+    readonly detail: string;
+    readonly records: StepRecord[];
+    /** How far it got, for the history's note: set by the step that ran it. */
+    summary: unknown;
+    constructor(op: string, detail: string, records: StepRecord[]);
+}
+/** The gates in an Op, by name. */
+export declare const gatesOf: (config: Pick<OpConfig, "phases" | "onFailure">) => string[];
+/** The first failing record's error, for the message. */
+export declare function failureOf(records: readonly StepRecord[]): string;
+export interface RunOpOptions {
+    /** The project directory: chant's config is read from it. */
+    cwd: string;
+    /** The environment, handed to the activities through the run context. */
+    environment: string;
+    /** Activities added to (or replacing) the ones chant loads. */
+    activities?: Record<string, ActivityFn>;
+    /** The activities to use instead of loading chant's, for a test. */
+    base?: Map<string, ActivityFn>;
+    signal?: AbortSignal;
+    onRecord?: (record: StepRecord) => void;
+}
+/** Runs `config` to the end. Resolves with its records; throws {@link StepOpFailed} when it fails, or stops at a gate or a decision point. */
+export declare function runOp(config: OpConfig, options: RunOpOptions): Promise<StepRecord[]>;

package/dist/steps/run.js

@@ -0,0 +1,72 @@
+/**
+ * Running an Op step's Op in this process, with chant's local executor
+ * (`runOpLocally`, the executor `chant run` uses), inside the versioned
+ * apply that holds the lock.
+ *
+ * The activities are the ones `chant run` loads for a sql project (core's,
+ * and the sql lexicon's, the rebuild's among them), plus what the step adds
+ * (a backfill's receipt store and its `yodelSql`). Nothing is written to the
+ * run ledger: the history table is the record of what ran.
+ *
+ * A step's Op has no gate of its own here. The migration it is part of was
+ * approved under the plan digest, which covers the step through the
+ * migration's checksum; a gate left in the Op is refused before it runs.
+ */
+import { YodelError } from "../project.js";
+/** A step's Op stopped part way. The history records it failed; the next run resumes it. */
+export class StepOpFailed extends YodelError {
+    op;
+    detail;
+    records;
+    /** How far it got, for the history's note: set by the step that ran it. */
+    summary;
+    constructor(op, detail, records) {
+        super(`${op}: ${detail}`, 1);
+        this.op = op;
+        this.detail = detail;
+        this.records = records;
+        this.name = "StepOpFailed";
+    }
+}
+const allSteps = (config) => [...config.phases, ...(config.onFailure ?? [])].flatMap((p) => p.steps.flatMap((s) => (s.kind === "effect" ? [s, ...s.steps] : [s])));
+/** The gates in an Op, by name. */
+export const gatesOf = (config) => allSteps(config).flatMap((s) => (s.kind === "gate" ? [s.gate ?? "unnamed"] : []));
+/** The first failing record's error, for the message. */
+export function failureOf(records) {
+    const failed = records.find((r) => r.status === "fail");
+    return failed ? `${failed.phase} / ${failed.fn} failed: ${failed.error ?? "no error given"}` : "the Op failed";
+}
+/** Runs `config` to the end. Resolves with its records; throws {@link StepOpFailed} when it fails, or stops at a gate or a decision point. */
+export async function runOp(config, options) {
+    const gates = gatesOf(config);
+    if (gates.length > 0) {
+        throw new StepOpFailed(config.name, `it has a gate (${gates.join(", ")}); a step's Op runs behind the migration's own gate and may not have one of its own`, []);
+    }
+    const { loadActivities, loadProfiles } = await import("@intentius/chant/op/activity-registry");
+    const { runOpLocally, OpRunFailure } = await import("@intentius/chant/op/local-executor");
+    const activities = options.base ? new Map(options.base) : await loadActivities(["sql"]);
+    for (const [name, fn] of Object.entries(options.activities ?? {}))
+        activities.set(name, fn);
+    const profiles = await loadProfiles();
+    try {
+        const result = await runOpLocally(config, activities, profiles, options.signal, {
+            cwd: options.cwd,
+            env: options.environment,
+            ...(options.onRecord ? { onRecord: options.onRecord } : {}),
+        });
+        if (result.status !== "ok")
+            throw new StepOpFailed(config.name, `it stopped (${result.status}) instead of running to the end`, result.records);
+        return result.records;
+    }
+    catch (e) {
+        if (e instanceof StepOpFailed)
+            throw e;
+        if (e instanceof OpRunFailure) {
+            const cause = e.cause instanceof Error ? e.cause.message : typeof e.cause === "string" ? e.cause : undefined;
+            const failedStep = e.result.records.some((r) => r.status === "fail");
+            throw new StepOpFailed(config.name, failedStep ? failureOf(e.result.records) : (cause ?? "the Op failed"), e.result.records);
+        }
+        throw new StepOpFailed(config.name, e instanceof Error ? e.message : String(e), []);
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/steps/run.js.map

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

package/dist/topology/render.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A migration's statements as one environment runs them. The source is
+ * topology-neutral: `yodel new` writes each statement for a single node,
+ * and at apply time each is rendered for the environment's topology with
+ * chant's renderer (`ON CLUSTER` added or removed, the replicated engine
+ * written). Pure.
+ *
+ * The history records a statement by the neutral statement's sha, so a
+ * migration resumes the same way on every topology; the topology it was
+ * sent for goes in the row's note ({@link topologyNote}).
+ */
+import { type Topology } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+export type { Topology };
+/** One neutral statement, as `topology` runs it. */
+export declare const renderForEnvironment: (sql: string, topology: Topology) => string;
+/** The `note` a statement row carries: the topology the statement was rendered for. */
+export declare const topologyNote: (topology: Topology) => string;

package/dist/topology/render.js

@@ -0,0 +1,17 @@
+/**
+ * A migration's statements as one environment runs them. The source is
+ * topology-neutral: `yodel new` writes each statement for a single node,
+ * and at apply time each is rendered for the environment's topology with
+ * chant's renderer (`ON CLUSTER` added or removed, the replicated engine
+ * written). Pure.
+ *
+ * The history records a statement by the neutral statement's sha, so a
+ * migration resumes the same way on every topology; the topology it was
+ * sent for goes in the row's note ({@link topologyNote}).
+ */
+import { renderStatement, topologyLabel } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+/** One neutral statement, as `topology` runs it. */
+export const renderForEnvironment = (sql, topology) => renderStatement(sql, topology);
+/** The `note` a statement row carries: the topology the statement was rendered for. */
+export const topologyNote = (topology) => `topology=${topologyLabel(topology)}`;
+//# sourceMappingURL=render.js.map

package/dist/topology/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/topology/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,kDAAkD,CAAC;AAIjH,oDAAoD;AACpD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAW,EAAE,QAAkB,EAAU,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAEhH,uFAAuF;AACvF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAkB,EAAU,EAAE,CAAC,YAAY,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The package version, read from package.json (one level above both src/ and dist/). */
+export declare function version(): string;

package/dist/version.js

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+/** The package version, read from package.json (one level above both src/ and dist/). */
+export function version() {
+    const url = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(url, "utf8"));
+    if (typeof pkg.version !== "string") {
+        throw new Error(`no version in ${url.pathname}`);
+    }
+    return pkg.version;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,yFAAyF;AACzF,MAAM,UAAU,OAAO;IACrB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAA0B,CAAC;IAC3E,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC"}

package/dist/versioned/approval.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The approval check `yodel apply <env> --execute` makes itself, against
+ * chant's gate ledger, before it sends anything.
+ *
+ * `YODEL_APPROVED_PLAN` is how the Op hands the digest to the Apply step, but
+ * it is never enough on its own: anyone can set an environment variable.
+ * `--execute` reads the ledger the gate step reads (the `chant/lifecycle`
+ * branch, through chant's `gitGateLedgerPort`) for the environment's
+ * migrations Op, and requires an approval of its gate for exactly the digest
+ * it computes under the lock, by the rule chant's gate applies
+ * (`evaluateGate`):
+ *
+ * - the resolution is for this gate and for this plan digest
+ *   (`latestResolutionForPlan`; one recorded before plan-bound gates never
+ *   counts);
+ * - it is newer than the newest pending fact for the gate, so an approval
+ *   from before the gate last asked does not answer it;
+ * - the workspace's approval rule for the gate (`identity.gates`), when one
+ *   applies, accepts it.
+ *
+ * A gate with a quorum or policy (`approval`) is refused here: counting a
+ * quorum is the gate step's, and `--execute` fails closed rather than
+ * approximate it.
+ */
+import type { GateLedgerPort } from "@intentius/chant/op/gate";
+import type { MigrateOpRef } from "./op.js";
+/** Exit code of a refusal for want of an approval: the same as a run stopped at the gate. */
+export declare const NOT_APPROVED = 3;
+/** Throws unless the ledger holds an approval of `op`'s gate for `digest`. Returns who approved it. */
+export declare function verifyApproval(port: GateLedgerPort, op: MigrateOpRef, digest: string): Promise<{
+    resolvedBy: string;
+    timestamp: string;
+}>;
+/** The ledger as the gate step reads it, in the project's checkout. */
+export declare function gitLedger(cwd: string): Promise<GateLedgerPort>;

package/dist/versioned/approval.js

@@ -0,0 +1,53 @@
+/**
+ * The approval check `yodel apply <env> --execute` makes itself, against
+ * chant's gate ledger, before it sends anything.
+ *
+ * `YODEL_APPROVED_PLAN` is how the Op hands the digest to the Apply step, but
+ * it is never enough on its own: anyone can set an environment variable.
+ * `--execute` reads the ledger the gate step reads (the `chant/lifecycle`
+ * branch, through chant's `gitGateLedgerPort`) for the environment's
+ * migrations Op, and requires an approval of its gate for exactly the digest
+ * it computes under the lock, by the rule chant's gate applies
+ * (`evaluateGate`):
+ *
+ * - the resolution is for this gate and for this plan digest
+ *   (`latestResolutionForPlan`; one recorded before plan-bound gates never
+ *   counts);
+ * - it is newer than the newest pending fact for the gate, so an approval
+ *   from before the gate last asked does not answer it;
+ * - the workspace's approval rule for the gate (`identity.gates`), when one
+ *   applies, accepts it.
+ *
+ * A gate with a quorum or policy (`approval`) is refused here: counting a
+ * quorum is the gate step's, and `--execute` fails closed rather than
+ * approximate it.
+ */
+import { YodelError } from "../project.js";
+const EPOCH = new Date(0).toISOString();
+/** Exit code of a refusal for want of an approval: the same as a run stopped at the gate. */
+export const NOT_APPROVED = 3;
+/** Throws unless the ledger holds an approval of `op`'s gate for `digest`. Returns who approved it. */
+export async function verifyApproval(port, op, digest) {
+    if (op.quorum) {
+        throw new YodelError(`--execute cannot check gate "${op.gate}" of ${op.name}: it declares an approval quorum or policy, which only the gate step counts; run yodel apply without --execute`, NOT_APPROVED);
+    }
+    const { latestPendingGate, latestResolutionForPlan } = await import("@intentius/chant/lifecycle/gate-ledger");
+    const ledger = await port.read(op.name);
+    const rule = (await port.approvalRule?.(op.gate)) ?? null;
+    const resolutions = ledger.resolutions.filter((r) => r.gate !== op.gate || rule === null || rule.refuses(r) === null);
+    const since = latestPendingGate(ledger.pending, op.gate)?.timestamp ?? EPOCH;
+    const found = latestResolutionForPlan(resolutions, op.gate, since, digest);
+    if (found.resolution)
+        return { resolvedBy: found.resolution.resolvedBy, timestamp: found.resolution.timestamp };
+    const other = found.mismatched
+        ? ` (the newest approval of that gate is for ${found.mismatched.planDigest ?? "no plan"}, by ${found.mismatched.resolvedBy} at ${found.mismatched.timestamp})`
+        : "";
+    throw new YodelError(`refused: chant's gate ledger holds no approval of ${op.name} / ${op.gate} for plan ${digest}${other}. Nothing was applied. ` +
+        `Run yodel apply without --execute; it stops at the gate and prints the chant approve command.`, NOT_APPROVED);
+}
+/** The ledger as the gate step reads it, in the project's checkout. */
+export async function gitLedger(cwd) {
+    const { gitGateLedgerPort } = await import("@intentius/chant/op/gate");
+    return gitGateLedgerPort({ cwd });
+}
+//# sourceMappingURL=approval.js.map

package/dist/versioned/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../src/versioned/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAExC,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B,uGAAuG;AACvG,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAoB,EAAE,EAAgB,EAAE,MAAc;IACzF,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;QACd,MAAM,IAAI,UAAU,CAAC,gCAAgC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,IAAI,gHAAgH,EAAE,YAAY,CAAC,CAAC;IAC7M,CAAC;IACD,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,wCAAwC,CAAC,CAAC;IAC9G,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC;IAC1D,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IACtH,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,SAAS,IAAI,KAAK,CAAC;IAC7E,MAAM,KAAK,GAAG,uBAAuB,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC3E,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;IAChH,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU;QAC5B,CAAC,CAAC,6CAA6C,KAAK,CAAC,UAAU,CAAC,UAAU,IAAI,SAAS,QAAQ,KAAK,CAAC,UAAU,CAAC,UAAU,OAAO,KAAK,CAAC,UAAU,CAAC,SAAS,GAAG;QAC9J,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,IAAI,UAAU,CAClB,qDAAqD,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC,IAAI,aAAa,MAAM,GAAG,KAAK,yBAAyB;QAC3H,+FAA+F,EACjG,YAAY,CACb,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACvE,OAAO,iBAAiB,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/dist/versioned/clickhouse.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The versioned apply's ClickHouse driver: the Keeper (or local) lock
+ * (`../history/lock.ts`), the catalog fingerprint over `system.tables`
+ * (`./digest.ts`), and each statement rendered for the environment's
+ * topology (#9) and sent, then its `succeeded` row appended. ClickHouse DDL
+ * is not transactional, so the row follows the statement; a runner killed
+ * between the two leaves the statement's latest row `started`, and the next
+ * run sends it again.
+ */
+import type { ClickHouseEndpoint } from "@intentius/chant-lexicon-sql/clickhouse/http";
+import { type ClickHousePort, type HistoryLocation } from "../history/index.js";
+import { type Topology } from "../topology/render.js";
+import { type LiveScope } from "./digest.js";
+import type { VersionedDriver } from "./driver.js";
+export interface ClickHouseDriverInput {
+    port: ClickHousePort;
+    location: HistoryLocation;
+    scope: LiveScope;
+    serverKey: string;
+    lockTtlMs: number;
+    endpoint?: ClickHouseEndpoint | undefined;
+    topology?: Topology | undefined;
+}
+export declare function clickhouseDriver(input: ClickHouseDriverInput): VersionedDriver;

package/dist/versioned/clickhouse.js

@@ -0,0 +1,34 @@
+/**
+ * The versioned apply's ClickHouse driver: the Keeper (or local) lock
+ * (`../history/lock.ts`), the catalog fingerprint over `system.tables`
+ * (`./digest.ts`), and each statement rendered for the environment's
+ * topology (#9) and sent, then its `succeeded` row appended. ClickHouse DDL
+ * is not transactional, so the row follows the statement; a runner killed
+ * between the two leaves the statement's latest row `started`, and the next
+ * run sends it again.
+ */
+import { acquireLock, SINGLE, serverMessage } from "../history/index.js";
+import { renderForEnvironment, topologyNote } from "../topology/render.js";
+import { catalogFingerprint, readLiveCatalog } from "./digest.js";
+export function clickhouseDriver(input) {
+    const { port } = input;
+    const topology = input.topology ?? SINGLE;
+    return {
+        dialect: "clickhouse",
+        rowNote: topologyNote(topology),
+        acquireLock: (holder) => acquireLock(port, { database: input.location.database, topology: input.location.topology, holder, ttlMs: input.lockTtlMs, serverKey: input.serverKey }),
+        liveFingerprint: async () => catalogFingerprint(await readLiveCatalog(port, input.scope)),
+        async runStatement(step, run) {
+            try {
+                await port.query(renderForEnvironment(step.sql, topology), step.waitsForMutation ? { settings: { mutations_sync: "2" } } : {});
+            }
+            catch (e) {
+                throw new Error(serverMessage(e), { cause: e });
+            }
+            await run.succeeded("");
+        },
+        stepContext: () => ({ port, endpoint: input.endpoint }),
+        close: () => Promise.resolve(),
+    };
+}
+//# sourceMappingURL=clickhouse.js.map

package/dist/versioned/clickhouse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse.js","sourceRoot":"","sources":["../../src/versioned/clickhouse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAA6C,MAAM,qBAAqB,CAAC;AACpH,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAiB,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAkB,MAAM,aAAa,CAAC;AAalF,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACvB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,MAAM,CAAC;IAC1C,OAAO;QACL,OAAO,EAAE,YAAY;QACrB,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC;QAC/B,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CACtB,WAAW,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;QACzJ,eAAe,EAAE,KAAK,IAAI,EAAE,CAAC,kBAAkB,CAAC,MAAM,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACzF,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,GAAG;YAC1B,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACjI,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAClD,CAAC;YACD,MAAM,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;QACvD,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE;KAC/B,CAAC;AACJ,CAAC"}