primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/snapshot-audit.js

@@ -0,0 +1,431 @@
+/**
+ * `snapshot ⊕ overlays == table`, recomputed and compared (#3433, criterion 10).
+ *
+ * Per-build verification checks a base against the table it was built FROM:
+ * the chunks are read back, their digests match, their id sequences cover the
+ * ranges. What it cannot check is the other half of the contract — that
+ * folding the overlays onto that base, the way a CLIENT folds them, arrives at
+ * the document the server holds. A fold that means something slightly
+ * different on the two ends puts records into a client's authoritative table
+ * that the server never wrote, silently, because on a format-2 document there
+ * is no whole-document comparison left downstream to catch it.
+ *
+ * So this runs OUTSIDE the Durable Object, on the CLI:
+ *
+ * 0. Read the document's schema, which is the same permission the table pages
+ *    need. The chain export takes the app-admin arm and the pages take the
+ *    console arm or a read grant on the document, so a caller holding only the
+ *    first is refused here rather than after downloading the whole chain
+ *    (3433-C08).
+ * 1. Export the chain — the newest complete base, every overlay sealed after
+ *    it, and the open epoch's overlay inline.
+ * 2. Load the base through the checked-in loader into a local record store,
+ *    then fold each overlay in order with the client's own fold.
+ * 3. Page the authoritative table through the records API and compare it,
+ *    record by record, with the recomputed view.
+ *
+ * Running it inside the room would need a scratch copy of up to 2 GB of rows
+ * and a new multi-tick state machine; running it with the SERVER's fold would
+ * make it agree with the room by construction.
+ *
+ * ## The fence, and why there is one
+ *
+ * The chain export captures the open overlay once (`Y.encodeStateAsUpdate` at
+ * one moment); each records page is an independent query of the live table
+ * later (3433-R03). An ordinary write in between would read as corruption. The
+ * export is therefore its own fence: after the last page the chain is exported
+ * AGAIN and the open epoch number and a fingerprint of the inline overlay are
+ * compared with the capture. The fingerprint is the overlay's state vector AND
+ * its delete set, because a Yjs deletion creates no struct and therefore never
+ * moves a state vector (3433-C05) — and a record deleted under the comparison
+ * is precisely what a divergence looks like. The epoch moves on every
+ * rotation, so it is checked on its own. Either moving means the document
+ * changed under the comparison: that attempt yields NO VERDICT and is retried
+ * from a fresh capture; a document that moves on every attempt is reported as
+ * `none` rather than as a divergence.
+ */
+import { chunkAddressOf, } from "./snapshot-manifest-layout.js";
+/** The server refused to export a chain; there is nothing to audit. */
+export const EXPORT_CHAIN_INCOMPLETE = "EXPORT_CHAIN_INCOMPLETE";
+/**
+ * The stringset fields a schema response declares, per model.
+ *
+ * `GET documents/:id/schema` answers `{ schema: { models: { Note: { fields:
+ * { tags: { type: "stringset" } } } } } }` — the declarations the document's
+ * `_meta_` maps carry, which is where a field added after the base snapshot
+ * says what it is. A model with no stringset is left out rather than mapped to
+ * an empty list, so the union with the manifest's is a plain spread.
+ */
+export function stringSetFieldsFromSchema(schema) {
+    const models = schema?.schema?.models ?? schema?.models ?? {};
+    // A model's name is DATA — an undeclared model is whatever `_type` the
+    // records route was handed — so `constructor` and `toString` are names this
+    // dictionary can be asked for. On a plain object either answers a function
+    // off the prototype rather than `undefined`, which the caller's `?? []`
+    // cannot see and its spread cannot iterate (3433-C11). Nothing is inherited
+    // here, so a lookup answers only what a schema actually declared.
+    const out = Object.create(null);
+    for (const [model, declaration] of Object.entries(models)) {
+        const fields = declaration?.fields ?? {};
+        const sets = Object.entries(fields)
+            .filter(([, field]) => String(field?.type ?? "").toLowerCase() === "stringset")
+            .map(([name]) => name);
+        if (sets.length > 0)
+            out[model] = sets;
+    }
+    return out;
+}
+const DEFAULT_MAX_DIVERGENCES = 20;
+const DEFAULT_RETRIES = 3;
+const DEFAULT_PAGE_SIZE = 200;
+function decodeBase64(value) {
+    const binary = Buffer.from(value, "base64");
+    return new Uint8Array(binary.buffer, binary.byteOffset, binary.byteLength);
+}
+/**
+ * The value of one field, in a form two sides can be compared by.
+ *
+ * Canonical JSON — object keys sorted — because the two sides reach the same
+ * record by different routes (one out of SQLite's `json_patch`, one through
+ * the records route's serialisation) and key order is not a difference a
+ * reader would call corruption.
+ */
+function canonical(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const entries = Object.entries(value).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    return `{${entries.map(([key, inner]) => `${JSON.stringify(key)}:${canonical(inner)}`).join(",")}}`;
+}
+/** A stringset is a SET: the order its members come back in means nothing. */
+function canonicalSet(value) {
+    if (!Array.isArray(value))
+        return canonical(value);
+    return `[${[...value].map(canonical).sort().join(",")}]`;
+}
+/**
+ * The fields of a record that mean something to a comparison.
+ *
+ * `id` is the key both sides are looked up by, not a field; a `_`-prefixed key
+ * is the route's own bookkeeping (`_type`, `_meta_doc_id`), not the record.
+ * `type` is the ORM's own column for the model name — written beside `id` on
+ * every projected row and reserved from a model's fields — so it is dropped
+ * when it says what the model already says, and compared like any other field
+ * when it does not.
+ */
+function comparableFields(record, model) {
+    const out = {};
+    for (const [field, value] of Object.entries(record)) {
+        if (field === "id" || field.startsWith("_"))
+            continue;
+        if (field === "type" && value === model)
+            continue;
+        if (value === undefined)
+            continue;
+        out[field] = value;
+    }
+    return out;
+}
+/** Which fields of two records disagree. */
+function differingFields(left, right, stringSets) {
+    const fields = new Set([...Object.keys(left), ...Object.keys(right)]);
+    const out = [];
+    for (const field of Array.from(fields).sort()) {
+        const render = stringSets.has(field) ? canonicalSet : canonical;
+        if (render(left[field]) !== render(right[field]))
+            out.push(field);
+    }
+    return out;
+}
+/** The stringset fields declared for one model, and nothing inherited. */
+function declaredFields(declared, model) {
+    const fields = Object.prototype.hasOwnProperty.call(declared, model)
+        ? declared[model]
+        : undefined;
+    return Array.isArray(fields) ? fields : [];
+}
+/**
+ * A read of the server that did not finish — never a divergence (3433-C10).
+ *
+ * Exit 1 means "the table is not the chain". A page the server refused, an
+ * artifact that would not download, a grant withdrawn mid-run: none of them
+ * says anything whatever about that, and an error escaping this library used
+ * to reach the CLI's top-level handler and exit 1 all the same. Tagged here,
+ * caught at the attempt, and answered as the third verdict with its reason and
+ * no per-model report.
+ */
+class AuditSourceError extends Error {
+    what;
+    failure;
+    constructor(what, failure) {
+        super(`${what}: ${failure?.message ?? String(failure)}`);
+        this.what = what;
+        this.failure = failure;
+        this.name = "AuditSourceError";
+    }
+    /** Why there is no verdict, in the operator's terms. */
+    describe() {
+        const detail = this.failure?.message ?? String(this.failure);
+        const status = this.failure?.statusCode ?? this.failure?.status;
+        if (status === 403) {
+            return `${this.what} could not be read: ${missingGrant(detail)}`;
+        }
+        return `${this.what} could not be read: ${detail}`;
+    }
+}
+/** The permission the comparison needs, which the chain export does not give. */
+function missingGrant(detail) {
+    return (`this account may export the document's chain but not read its table: ` +
+        `comparing them needs the console-admin arm or a read grant on this ` +
+        `document (${detail})`);
+}
+/** One read of the server, tagged so a failure is no verdict rather than one. */
+async function read(what, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        throw new AuditSourceError(what, error);
+    }
+}
+/** The id the records route gives a record. */
+function recordId(item) {
+    const id = item.id ?? item._id;
+    return typeof id === "string" || typeof id === "number" ? String(id) : null;
+}
+/**
+ * Recompute a document's chain locally and compare it with its table.
+ *
+ * Returns a verdict rather than throwing: a divergence is the answer the
+ * command exists to give, and "no verdict" is a third answer the validation
+ * child scripts on, not an error to catch.
+ */
+export async function auditSnapshotChain(source, options) {
+    const retries = Math.max(1, options.retries ?? DEFAULT_RETRIES);
+    const maxDivergences = options.maxDivergences ?? DEFAULT_MAX_DIVERGENCES;
+    const pageSize = options.pageSize ?? DEFAULT_PAGE_SIZE;
+    const none = (reason, attempts) => ({
+        verdict: "none",
+        attempts,
+        reason,
+        buildId: null,
+        epoch: null,
+        models: [],
+    });
+    let attempts = 0;
+    let lastMoved = "";
+    for (let attempt = 0; attempt < retries; attempt++) {
+        attempts++;
+        // The table FIRST, before anything is exported (3433-C08).
+        //
+        // The audit is two reads with two different answers: the chain export
+        // takes the app-admin arm, and the records pages take the console arm or a
+        // read grant on the document, because the documents surface grants no
+        // app-role bypass on a read (#3279, D3279-002). Reading the schema is the
+        // same permission the pages need, so a caller who would be refused halfway
+        // is refused here — with the grant named, and with nothing downloaded.
+        let tableModels;
+        try {
+            tableModels = await source.tableModels();
+        }
+        catch (error) {
+            const status = error?.statusCode ?? error?.status;
+            const reason = status === 403
+                ? missingGrant(error?.message ?? "forbidden")
+                : `the document's table could not be read: ${error?.message ?? String(error)}`;
+            return none(reason, attempts);
+        }
+        let captured;
+        try {
+            captured = await source.chain();
+        }
+        catch (error) {
+            // The server's own refusal, not a shape this library decides. A chain it
+            // will not export is no verdict — never a divergence.
+            const code = error?.code ?? error?.body?.code;
+            const reason = code === EXPORT_CHAIN_INCOMPLETE
+                ? `the server will not export this document's chain (${EXPORT_CHAIN_INCOMPLETE}): ${error?.message ?? "incomplete"}`
+                : `the chain could not be exported: ${error?.message ?? String(error)}`;
+            return none(reason, attempts);
+        }
+        if (captured.documentFormat !== undefined && Number(captured.documentFormat) !== 2) {
+            return none("this is an ordinary document: it has no snapshot chain to recompute", attempts);
+        }
+        if (!captured.base) {
+            return none("this document has no completed base snapshot yet, so there is nothing to fold onto", attempts);
+        }
+        const fence = {
+            epoch: Number(captured.current?.epoch ?? captured.epoch),
+            fingerprint: options.fingerprint(decodeBase64(captured.current.update)),
+        };
+        const store = await options.store();
+        // A failure inside the loader's own callback can reach the catch below
+        // through the loader rather than as itself, so the tag is carried here too.
+        let carried = null;
+        const chainArtifact = async (path) => {
+            try {
+                return await read("an artifact of the chain", () => source.download(path));
+            }
+            catch (error) {
+                if (error instanceof AuditSourceError)
+                    carried = error;
+                throw error;
+            }
+        };
+        try {
+            const manifest = JSON.parse(Buffer.from(await chainArtifact(captured.base.download.path)).toString("utf-8"));
+            const basePath = captured.base.download.path;
+            await store.loadSnapshot(manifest, async (chunk) => {
+                // Addressed by the entry's own path within the granted build — the
+                // own-build `{model}/{n}` or the `{epoch}-{buildId}/{model}/{n}` of a
+                // chunk carried forward — never re-derived from the key, which for a
+                // reused entry names a DIFFERENT build's object (the real cause of
+                // what was escalated as 3433-C01).
+                return await chainArtifact(`${basePath}/${chunkAddressOf(chunk).path}`);
+            });
+            // Every overlay sealed after the base, then the open one, in order: a
+            // fold applied out of order is a different document.
+            for (const overlay of captured.overlays) {
+                await store.applyOverlay(await chainArtifact(overlay.download.path));
+            }
+            await store.applyOverlay(decodeBase64(captured.current.update));
+            // The model list is the UNION. A model the table holds and the chain
+            // does not is exactly the case an audit exists to catch, and a model the
+            // chain holds and the table does not is its mirror; taking either side
+            // alone would skip one of them (3433-R04).
+            const models = Array.from(new Set([...tableModels, ...(await store.models())])).sort();
+            // What the document declares a stringset NOW, beside what the base
+            // manifest recorded: a field declared after the base is a set on both
+            // sides and an ordered array to nobody (3433-C06).
+            const declaredSets = source.stringSetFields
+                ? await read("the document's schema", () => source.stringSetFields())
+                : {};
+            const reports = [];
+            for (const model of models) {
+                const stringSets = new Set([
+                    ...store.stringSetFields(model),
+                    ...declaredFields(declaredSets, model),
+                ]);
+                reports.push(await compareModel(source, store, model, pageSize, maxDivergences, stringSets));
+            }
+            // The fence: nothing may have moved between the capture and here.
+            let after;
+            try {
+                after = await source.chain();
+            }
+            catch (error) {
+                return none(`the chain could not be re-exported to confirm the document held still: ${error?.message ?? String(error)}`, attempts);
+            }
+            const moved = fenceMoved(fence, after, options.fingerprint);
+            if (moved) {
+                lastMoved = moved;
+                continue;
+            }
+            const diverged = reports.some((report) => report.onlyRecomputed.length > 0 ||
+                report.onlyTable.length > 0 ||
+                report.differing.length > 0);
+            return {
+                verdict: diverged ? "divergence" : "match",
+                attempts,
+                buildId: captured.base.buildId,
+                epoch: captured.base.epoch,
+                models: reports,
+            };
+        }
+        catch (error) {
+            // A side that could not be read to the end is no verdict, and the
+            // partial comparison behind it is thrown away with the attempt: nothing
+            // it found could be said to cover one state of the document.
+            const failure = error instanceof AuditSourceError ? error : carried;
+            if (!failure)
+                throw error;
+            return none(failure.describe(), attempts);
+        }
+        finally {
+            await store.close();
+        }
+    }
+    return none(`the document changed during every attempt (${lastMoved}), so no comparison ` +
+        `covers one state of it`, attempts);
+}
+/** Where the document moved between the capture and the re-export, if it did. */
+function fenceMoved(captured, after, fingerprint) {
+    const epoch = Number(after.current?.epoch ?? after.epoch);
+    if (epoch !== captured.epoch) {
+        // A seal with no write still moves the epoch, and the new open overlay's
+        // state vector is empty — so the epoch is checked on its own (edge E14).
+        return `the open epoch moved from ${captured.epoch} to ${epoch}`;
+    }
+    if (fingerprint(decodeBase64(after.current.update)) !== captured.fingerprint) {
+        // A write or a deletion: the fingerprint covers the delete set, which a
+        // state vector does not move for (3433-C05).
+        return "the open overlay changed";
+    }
+    return null;
+}
+/** One model's two sides, compared a page at a time. */
+async function compareModel(source, store, model, pageSize, maxDivergences, stringSets) {
+    const report = {
+        model,
+        compared: 0,
+        onlyRecomputed: [],
+        onlyTable: [],
+        differing: [],
+        truncated: false,
+    };
+    const note = (list, id) => {
+        if (list.length >= maxDivergences) {
+            report.truncated = true;
+            return;
+        }
+        list.push(id);
+    };
+    let cursor;
+    for (;;) {
+        const page = await read("the document's table", () => source.readPage(model, cursor));
+        const items = page.items ?? [];
+        const ids = [];
+        const byId = new Map();
+        for (const item of items) {
+            const id = recordId(item);
+            if (id === null)
+                continue;
+            ids.push(id);
+            byId.set(id, item);
+        }
+        const recomputed = await store.take(model, ids);
+        for (const id of ids) {
+            const local = recomputed.get(id);
+            if (!local) {
+                note(report.onlyTable, id);
+                continue;
+            }
+            report.compared++;
+            const fields = differingFields(comparableFields(local, model), comparableFields(byId.get(id), model), stringSets);
+            if (fields.length === 0)
+                continue;
+            if (report.differing.length >= maxDivergences)
+                report.truncated = true;
+            else
+                report.differing.push({ id, fields });
+        }
+        if (!page.nextCursor || items.length === 0)
+            break;
+        cursor = page.nextCursor;
+    }
+    // What the recomputed view holds that no page ever showed.
+    let after = null;
+    for (;;) {
+        const rows = await store.remaining(model, after, pageSize);
+        if (rows.length === 0)
+            break;
+        for (const row of rows)
+            note(report.onlyRecomputed, row.id);
+        after = rows[rows.length - 1].id;
+        if (rows.length < pageSize)
+            break;
+    }
+    return report;
+}
+//# sourceMappingURL=snapshot-audit.js.map

package/dist/src/lib/snapshot-audit.js.map

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

package/dist/src/lib/snapshot-build-rows.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What `documents snapshots get` shows an operator, as data (#3435).
+ *
+ * The rows were composed inline in the command's action, which made the only
+ * way to check one a spawned CLI against a live server with a build in exactly
+ * the right state. They are a pure function of the payload now, so what a
+ * terminal shows is checkable where the decision is made; the command still
+ * owns the printing, and the live suite still owns "a real terminal really
+ * shows this".
+ *
+ * Label and value, in the order they print. A row that would say nothing is
+ * not emitted at all rather than emitted empty: an operator who learns that a
+ * block is usually blank stops reading the block.
+ */
+/** One printed row: its label and the value beside it. */
+export type SnapshotBuildRow = [string, unknown];
+/**
+ * The payload `GET .../snapshots/{buildId}` answers with.
+ *
+ * Every field past the first block is optional here because a build row
+ * written before that field existed carries none, and an operator inspecting
+ * an old build should see the build rather than a crash.
+ */
+export interface SnapshotBuildPayload {
+    buildId: string;
+    epoch: number;
+    state: string;
+    source: string;
+    manifestVersion: number;
+    startedAt: number;
+    completedAt?: number | null;
+    rows: number;
+    bytes: number;
+    chunks: number;
+    baseBuildId?: string | null;
+    chunksReused?: number;
+    rowsWalked?: number;
+    /** The bulk-load session this base was built for (#3435); never its ranges. */
+    ingestSessionId?: string | null;
+    verification?: {
+        state: string;
+        checkedAt: number;
+        chunksChecked: number;
+        chunksReused?: number;
+        code?: string;
+        reason?: string;
+    } | null;
+    failure?: {
+        at: number;
+        chunk?: {
+            model: string;
+            ordinal: number;
+        };
+    } | null;
+    timings?: {
+        ticks: number;
+        totals?: Record<string, number>;
+    };
+}
+export declare function snapshotBuildRows(build: SnapshotBuildPayload): SnapshotBuildRow[];

package/dist/src/lib/snapshot-build-rows.js

@@ -0,0 +1,87 @@
+/**
+ * What `documents snapshots get` shows an operator, as data (#3435).
+ *
+ * The rows were composed inline in the command's action, which made the only
+ * way to check one a spawned CLI against a live server with a build in exactly
+ * the right state. They are a pure function of the payload now, so what a
+ * terminal shows is checkable where the decision is made; the command still
+ * owns the printing, and the live suite still owns "a real terminal really
+ * shows this".
+ *
+ * Label and value, in the order they print. A row that would say nothing is
+ * not emitted at all rather than emitted empty: an operator who learns that a
+ * block is usually blank stops reading the block.
+ */
+import { formatDate } from "./output.js";
+/** The per-stage timing rows, in the order a tick spends them. */
+const STAGES = [
+    ["Read (ms)", "readMs"],
+    ["Encode (ms)", "encodeMs"],
+    ["Compress (ms)", "compressMs"],
+    ["Hash (ms)", "hashMs"],
+    ["Upload (ms)", "uploadMs"],
+    ["Manifest (ms)", "manifestMs"],
+    ["Verify read (ms)", "verifyReadMs"],
+    ["Verify digest (ms)", "verifyDigestMs"],
+    ["Verify coverage (ms)", "verifyCoverageMs"],
+];
+export function snapshotBuildRows(build) {
+    const rows = [
+        ["Build", build.buildId],
+        ["Epoch", build.epoch],
+        ["State", build.state],
+        ["Source", build.source],
+        ["Manifest version", build.manifestVersion],
+        ["Started", formatDate(build.startedAt)],
+        [
+            "Completed",
+            build.completedAt
+                ? formatDate(build.completedAt)
+                : "—",
+        ],
+        ["Rows", build.rows],
+        ["Bytes", build.bytes],
+        ["Chunks", build.chunks],
+        // #3433 — what this build reused from an earlier one, and what the walk
+        // cost: on an incremental rebuild the two together say why it was cheap.
+        ["Base build", build.baseBuildId ?? "—"],
+        ["Chunks reused", build.chunksReused ?? 0],
+        ["Rows walked", build.rowsWalked ?? 0],
+    ];
+    // #3435 — which bulk load this base was built for, when it was one. Only
+    // when present: "why did this document rebuild itself whole" has a different
+    // answer when the answer is "a bulk load swapped it", and a row reading "—"
+    // on every ordinary build teaches an operator to skip it.
+    if (build.ingestSessionId) {
+        rows.push(["Ingest session", build.ingestSessionId]);
+    }
+    const verification = build.verification;
+    rows.push(["Verification", verification ? verification.state : "not started"]);
+    if (verification) {
+        rows.push(["Checked at", formatDate(verification.checkedAt)]);
+        rows.push(["Chunks checked", verification.chunksChecked]);
+        if (verification.chunksReused !== undefined) {
+            rows.push(["Chunks trusted", verification.chunksReused]);
+        }
+        if (verification.code)
+            rows.push(["Code", verification.code]);
+        if (verification.reason)
+            rows.push(["Reason", verification.reason]);
+    }
+    if (build.failure) {
+        rows.push(["Failed at", formatDate(build.failure.at)]);
+        if (build.failure.chunk) {
+            rows.push([
+                "Failed on",
+                `${build.failure.chunk.model} chunk ${build.failure.chunk.ordinal}`,
+            ]);
+        }
+    }
+    const timings = build.timings ?? { ticks: 0, totals: {} };
+    rows.push(["Ticks", timings.ticks]);
+    for (const [label, key] of STAGES) {
+        rows.push([label, timings.totals?.[key] ?? 0]);
+    }
+    return rows;
+}
+//# sourceMappingURL=snapshot-build-rows.js.map

package/dist/src/lib/snapshot-build-rows.js.map

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

package/dist/src/lib/snapshot-build.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Asking for a snapshot and, optionally, watching the build that follows
+ * (#3666, criterion 7).
+ *
+ * The request itself is one call; what this module is for is the waiting.
+ * The build does not exist when the route answers — a seal arms the alarm and
+ * the alarm's first tick begins the build — so the id the caller holds names
+ * nothing for a moment, and a read that says "no such build" is `not yet`
+ * rather than a failure.
+ *
+ * Exit codes follow `documents ingest`, as `docs/cli-design.md` records them:
+ * 0 the build verified, 1 it failed, 124 a wait that gave up, 130 Ctrl-C.
+ * Both ways of giving up on the WATCHING are 124/130 and both say the build
+ * keeps running; only the build itself failing is 1. The word `failed`
+ * belongs to the build, so nothing this module prints about giving up uses it.
+ */
+/** The two calls driving a request; `ApiClient` supplies them in the verb. */
+export interface SnapshotBuildDriverClient {
+    requestSnapshot(documentId: string): Promise<any>;
+    getSnapshot(documentId: string, buildId: string): Promise<any>;
+}
+export interface DriveSnapshotBuildOptions {
+    client: SnapshotBuildDriverClient;
+    documentId: string;
+    /** Poll until the build settles; `--wait` sets this. */
+    wait?: boolean;
+    /** `--timeout`, in milliseconds; null waits indefinitely. */
+    timeoutMs?: number | null;
+    /** Ctrl-C. */
+    signal?: AbortSignal;
+    /** State changes and progress; stderr in the verb. */
+    onProgress?: (line: string) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** What the run settled on. */
+export interface SnapshotBuildOutcome {
+    /** 0 verified, 1 the build failed, 124 timed out, 130 interrupted. */
+    exitCode: number;
+    /** The route's answer, as received. */
+    response: any;
+    /** The terminal build view, when the wait read one. */
+    build: any | null;
+    /** The reason, for stderr. */
+    message?: string;
+}
+/**
+ * Ask for a snapshot, and watch the build if the caller asked to (#3666).
+ */
+export declare function driveSnapshotBuild(options: DriveSnapshotBuildOptions): Promise<SnapshotBuildOutcome>;