primitive-admin 1.0.62 → 1.0.64

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

@@ -0,0 +1,111 @@
+/**
+ * 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.
+ */
+const POLL_MS = 2_000;
+/**
+ * How long CONSECUTIVE failed build reads may run before the wait gives up,
+ * and the backoff between them.
+ *
+ * #3597's lesson, one route along: a read failing says nothing about the
+ * build, and a wait that ends on the first one reports a running build as
+ * over. The bound is a wall-clock window and any successful read resets it,
+ * so an isolated blip costs nothing and only an outage that never lifts ends
+ * the watching — as 124, never 1.
+ */
+const READ_FAILURE_WINDOW_MS = 120_000;
+const READ_RETRY_MS = 2_000;
+/** The answer to a request that sealed nothing. */
+function sealedNothing(response) {
+    return response?.sealed === false;
+}
+/** A read that says the build has not begun yet, rather than one that broke. */
+function notStartedYet(error) {
+    const status = Number(error?.statusCode ?? error?.status);
+    return status === 404;
+}
+/** What a failed build should say, from whichever field carries the reason. */
+function failureLine(build) {
+    const detail = build?.verification?.state === "failed" ? build.verification : build?.failure;
+    const parts = [detail?.code, detail?.reason].filter(Boolean);
+    return parts.length > 0
+        ? `The snapshot build failed: ${parts.join(" — ")}`
+        : "The snapshot build failed.";
+}
+/**
+ * Ask for a snapshot, and watch the build if the caller asked to (#3666).
+ */
+export async function driveSnapshotBuild(options) {
+    const { client, documentId, wait = false, timeoutMs = null, signal, onProgress, } = options;
+    const now = options.now ?? (() => Date.now());
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const response = await client.requestSnapshot(documentId);
+    // Nothing was sealed, so there is no build and nothing to watch. Not a
+    // failure: the document already has a base that describes it.
+    if (sealedNothing(response)) {
+        onProgress?.("The open epoch carried nothing, so it was not sealed and no build was started.");
+        return { exitCode: 0, response, build: null };
+    }
+    const buildId = String(response?.buildId ?? "");
+    onProgress?.(`Sealed epoch ${response?.sealedEpoch}; build ${buildId}.`);
+    if (!wait || !buildId)
+        return { exitCode: 0, response, build: null };
+    const startedAt = now();
+    const stillRunning = `The build is still running as ${buildId}; ` +
+        `follow it with \`documents snapshots get ${documentId} ${buildId}\`.`;
+    let failingSince = null;
+    for (;;) {
+        if (signal?.aborted) {
+            return { exitCode: 130, response, build: null, message: stillRunning };
+        }
+        if (timeoutMs !== null && now() - startedAt >= timeoutMs) {
+            return { exitCode: 124, response, build: null, message: stillRunning };
+        }
+        let build;
+        try {
+            build = await client.getSnapshot(documentId, buildId);
+            failingSince = null;
+        }
+        catch (error) {
+            if (notStartedYet(error)) {
+                // The alarm has not reached its first tick. Keep waiting, and do NOT
+                // count it against the read-failure window: nothing failed.
+                failingSince = null;
+                await sleep(POLL_MS);
+                continue;
+            }
+            failingSince ??= now();
+            if (now() - failingSince >= READ_FAILURE_WINDOW_MS) {
+                return {
+                    exitCode: 124,
+                    response,
+                    build: null,
+                    message: `The build could not be read for ${Math.round(READ_FAILURE_WINDOW_MS / 1000)}s (${error?.message ?? error}). ${stillRunning}`,
+                };
+            }
+            await sleep(READ_RETRY_MS);
+            continue;
+        }
+        const verification = build?.verification;
+        if (verification?.state === "passed") {
+            return { exitCode: 0, response, build };
+        }
+        if (verification?.state === "failed" || build?.state === "failed") {
+            return { exitCode: 1, response, build, message: failureLine(build) };
+        }
+        await sleep(POLL_MS);
+    }
+}
+//# sourceMappingURL=snapshot-build.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-build.js","sourceRoot":"","sources":["../../../src/lib/snapshot-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmCH,MAAM,OAAO,GAAG,KAAK,CAAC;AAEtB;;;;;;;;;GASG;AACH,MAAM,sBAAsB,GAAG,OAAO,CAAC;AACvC,MAAM,aAAa,GAAG,KAAK,CAAC;AAE5B,mDAAmD;AACnD,SAAS,aAAa,CAAC,QAAa;IAClC,OAAO,QAAQ,EAAE,MAAM,KAAK,KAAK,CAAC;AACpC,CAAC;AAED,gFAAgF;AAChF,SAAS,aAAa,CAAC,KAAU;IAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,CAAC,CAAC;IAC1D,OAAO,MAAM,KAAK,GAAG,CAAC;AACxB,CAAC;AAED,+EAA+E;AAC/E,SAAS,WAAW,CAAC,KAAU;IAC7B,MAAM,MAAM,GAAG,KAAK,EAAE,YAAY,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC;IAC7F,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7D,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC;QACrB,CAAC,CAAC,8BAA8B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;QACnD,CAAC,CAAC,4BAA4B,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAkC;IAElC,MAAM,EACJ,MAAM,EACN,UAAU,EACV,IAAI,GAAG,KAAK,EACZ,SAAS,GAAG,IAAI,EAChB,MAAM,EACN,UAAU,GACX,GAAG,OAAO,CAAC;IACZ,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,MAAM,KAAK,GACT,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAE3E,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;IAE1D,uEAAuE;IACvE,8DAA8D;IAC9D,IAAI,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,UAAU,EAAE,CACV,gFAAgF,CACjF,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;IAChD,UAAU,EAAE,CAAC,gBAAgB,QAAQ,EAAE,WAAW,WAAW,OAAO,GAAG,CAAC,CAAC;IACzE,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAErE,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;IACxB,MAAM,YAAY,GAAG,iCAAiC,OAAO,IAAI;QAC/D,4CAA4C,UAAU,IAAI,OAAO,KAAK,CAAC;IACzE,IAAI,YAAY,GAAkB,IAAI,CAAC;IAEvC,SAAS,CAAC;QACR,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QACzE,CAAC;QACD,IAAI,SAAS,KAAK,IAAI,IAAI,GAAG,EAAE,GAAG,SAAS,IAAI,SAAS,EAAE,CAAC;YACzD,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;QACzE,CAAC;QAED,IAAI,KAAU,CAAC;QACf,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YACtD,YAAY,GAAG,IAAI,CAAC;QACtB,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzB,qEAAqE;gBACrE,4DAA4D;gBAC5D,YAAY,GAAG,IAAI,CAAC;gBACpB,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;gBACrB,SAAS;YACX,CAAC;YACD,YAAY,KAAK,GAAG,EAAE,CAAC;YACvB,IAAI,GAAG,EAAE,GAAG,YAAY,IAAI,sBAAsB,EAAE,CAAC;gBACnD,OAAO;oBACL,QAAQ,EAAE,GAAG;oBACb,QAAQ;oBACR,KAAK,EAAE,IAAI;oBACX,OAAO,EACL,mCAAmC,IAAI,CAAC,KAAK,CAC3C,sBAAsB,GAAG,IAAI,CAC9B,MAAM,KAAK,EAAE,OAAO,IAAI,KAAK,MAAM,YAAY,EAAE;iBACrD,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,MAAM,YAAY,GAAG,KAAK,EAAE,YAAY,CAAC;QACzC,IAAI,YAAY,EAAE,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QAC1C,CAAC;QACD,IAAI,YAAY,EAAE,KAAK,KAAK,QAAQ,IAAI,KAAK,EAAE,KAAK,KAAK,QAAQ,EAAE,CAAC;YAClE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACvE,CAAC;QACD,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/src/lib/snapshot-manifest-layout.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Where a snapshot's chunks are, and where an export puts them (#3432).
+ *
+ * A manifest entry is addressed within its build's grant by its `path`:
+ * `{model}/{n}` for a chunk the build wrote, `{epoch}-{buildId}/{model}/{n}`
+ * for one carried forward from an earlier build of the same document. A
+ * manifest written before the field existed is addressed by its key. Two
+ * entries of one manifest can share `{model}/{n}` (one own, one reused), so
+ * an export cannot write them by that pair: it RENUMBERS each model 0..n-1 in
+ * manifest order and stores a manifest whose paths and keys say so, which is
+ * the layout `documents import` and the ingest CLI read — one on-disk shape
+ * whatever the manifest reused.
+ */
+/** The fields of a manifest entry this module reads. */
+export interface ManifestChunkLike {
+    key: string;
+    path?: string;
+    ordinal?: number;
+    model: string;
+    [field: string]: unknown;
+}
+/** The fields of a manifest this module reads and rewrites. */
+export interface ManifestLike<Chunk extends ManifestChunkLike = ManifestChunkLike> {
+    version: number;
+    epoch: number;
+    buildId: string;
+    chunks: Chunk[];
+    [field: string]: unknown;
+}
+/** Where one chunk is fetched from, within its build's grant. */
+export interface ChunkAddress {
+    model: string;
+    index: number;
+    /** The download path relative to the grant: `{model}/{n}` or the sourced form. */
+    path: string;
+    source?: {
+        epoch: number;
+        buildId: string;
+    };
+}
+/** A chunk's address: its `path` first, its key for an older manifest. */
+export declare function chunkAddressOf(chunk: ManifestChunkLike): ChunkAddress;
+/** One chunk of an export: where it is fetched from and where it is written. */
+export interface ExportedChunkFile {
+    download: string;
+    file: string;
+}
+/**
+ * The manifest an export stores, and the file each entry's bytes go to.
+ *
+ * Numbering is per model in manifest order; the stored entry carries the
+ * own-build `path`, a key under the build's own prefix that agrees with it,
+ * and its resolved `ordinal`. Everything content-addressed — the digest, the
+ * counts, the range — is carried verbatim, and a manifest that reused nothing
+ * comes out exactly as it went in. The stored version is 2: on disk every
+ * chunk is the build's own.
+ */
+export declare function renumberManifestForExport<Chunk extends ManifestChunkLike, Manifest extends ManifestLike<Chunk>>(manifest: Manifest): {
+    manifest: Manifest;
+    files: ExportedChunkFile[];
+};

package/dist/src/lib/snapshot-manifest-layout.js

@@ -0,0 +1,70 @@
+/**
+ * Where a snapshot's chunks are, and where an export puts them (#3432).
+ *
+ * A manifest entry is addressed within its build's grant by its `path`:
+ * `{model}/{n}` for a chunk the build wrote, `{epoch}-{buildId}/{model}/{n}`
+ * for one carried forward from an earlier build of the same document. A
+ * manifest written before the field existed is addressed by its key. Two
+ * entries of one manifest can share `{model}/{n}` (one own, one reused), so
+ * an export cannot write them by that pair: it RENUMBERS each model 0..n-1 in
+ * manifest order and stores a manifest whose paths and keys say so, which is
+ * the layout `documents import` and the ingest CLI read — one on-disk shape
+ * whatever the manifest reused.
+ */
+import { parseSnapshotChunkPath, resolveChunkOrdinal } from "js-bao";
+/** A chunk's address: its `path` first, its key for an older manifest. */
+export function chunkAddressOf(chunk) {
+    if (chunk.path !== undefined) {
+        const parsed = parseSnapshotChunkPath(chunk.path);
+        if (!parsed) {
+            throw new Error(`Snapshot manifest names a chunk this CLI cannot address: ${chunk.path}`);
+        }
+        return {
+            model: parsed.model,
+            index: parsed.index,
+            path: chunk.path,
+            ...(parsed.source ? { source: parsed.source } : {}),
+        };
+    }
+    const match = /\/([A-Za-z][A-Za-z0-9_]*)\/(\d+)\.ndjson\.gz$/.exec(String(chunk.key ?? ""));
+    if (!match) {
+        throw new Error(`Snapshot manifest names a chunk this CLI cannot address: ${chunk.key}`);
+    }
+    return {
+        model: match[1],
+        index: Number(match[2]),
+        path: `${match[1]}/${match[2]}`,
+    };
+}
+/**
+ * The manifest an export stores, and the file each entry's bytes go to.
+ *
+ * Numbering is per model in manifest order; the stored entry carries the
+ * own-build `path`, a key under the build's own prefix that agrees with it,
+ * and its resolved `ordinal`. Everything content-addressed — the digest, the
+ * counts, the range — is carried verbatim, and a manifest that reused nothing
+ * comes out exactly as it went in. The stored version is 2: on disk every
+ * chunk is the build's own.
+ */
+export function renumberManifestForExport(manifest) {
+    const perModel = new Map();
+    const files = [];
+    const chunks = manifest.chunks.map((chunk, index) => {
+        const address = chunkAddressOf(chunk);
+        const n = perModel.get(chunk.model) ?? 0;
+        perModel.set(chunk.model, n + 1);
+        files.push({ download: address.path, file: `${chunk.model}/${n}.ndjson.gz` });
+        const prefix = String(chunk.key).replace(/\/snapshots\/.*$/, "");
+        return {
+            ...chunk,
+            key: `${prefix}/snapshots/${manifest.epoch}-${manifest.buildId}/${chunk.model}/${n}.ndjson.gz`,
+            path: `${chunk.model}/${n}`,
+            ordinal: resolveChunkOrdinal(chunk, index),
+        };
+    });
+    return {
+        manifest: { ...manifest, version: 2, chunks },
+        files,
+    };
+}
+//# sourceMappingURL=snapshot-manifest-layout.js.map

package/dist/src/lib/snapshot-manifest-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-manifest-layout.js","sourceRoot":"","sources":["../../../src/lib/snapshot-manifest-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AA6BrE,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,KAAwB;IACrD,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,4DAA4D,KAAK,CAAC,IAAI,EAAE,CACzE,CAAC;QACJ,CAAC;QACD,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpD,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,+CAA+C,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC;IAC5F,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,4DAA4D,KAAK,CAAC,GAAG,EAAE,CACxE,CAAC;IACJ,CAAC;IACD,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QACf,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE;KAChC,CAAC;AACJ,CAAC;AAQD;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAGvC,QAAkB;IAClB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,KAAK,GAAwB,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAClD,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAC9E,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;QACjE,OAAO;YACL,GAAG,KAAK;YACR,GAAG,EAAE,GAAG,MAAM,cAAc,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,YAAY;YAC9F,IAAI,EAAE,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,EAAE;YAC3B,OAAO,EAAE,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC;SAC3C,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO;QACL,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE;QAC7C,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/src/lib/snapshots.d.ts

@@ -3,11 +3,11 @@
  * destructive `config pull` overwrites local TOML state (issue #578, Phase 1).
  *
  * A snapshot is a full recursive copy of the live sync tree (including
- * `.primitive-sync.json`, the content-hash baseline) into a timestamped slot
+ * `.sync-state.json`, the content-hash baseline) into a timestamped slot
  * under the snapshots root:
  *
  *   <snapshotsRoot>/<YYYY-MM-DDTHH-MM-SS>/
- *       <full pre-pull copy of the sync tree, incl. .primitive-sync.json>
+ *       <full pre-pull copy of the sync tree, incl. .sync-state.json>
  *       .snapshot-complete        # integrity marker, written LAST
  *       .audit-id                 # ULID cross-link (Phase 2; absent in P1)
  *
@@ -83,14 +83,13 @@ export declare function resolveSnapshot(snapshotsRoot: string, id: string | unde
  * then `syncDir` is atomically replaced, so a mid-restore crash never leaves a
  * half-written tree.
  *
- * `opts.preserveDir` names a directory (the snapshots root) that lives INSIDE
- * `syncDir` and must survive the full-tree swap — the Fork-4 legacy `--dir`
- * case, where backups sit at `<syncDir>/.snapshots/`. Without preserving it,
- * the swap would wipe the user's entire snapshot history on restore.
+ * Nothing has to survive the swap. Backups live under the project's
+ * machine-local `.primitive/`, outside the committed tree entirely, so the
+ * `preserveDir` parameter this took went with `--dir` (#3154) — it existed
+ * only for the case where the snapshots root sat inside the directory being
+ * replaced.
  */
-export declare function restoreSnapshot(snapshotPath: string, syncDir: string, opts?: {
-    preserveDir?: string;
-}): void;
+export declare function restoreSnapshot(snapshotPath: string, syncDir: string): void;
 /**
  * Prune snapshots older than `retentionDays` from `snapshotsRoot`. Only the
  * given slot is touched (cross-slot retention is independent — each slot has

package/dist/src/lib/snapshots.js

@@ -3,11 +3,11 @@
  * destructive `config pull` overwrites local TOML state (issue #578, Phase 1).
  *
  * A snapshot is a full recursive copy of the live sync tree (including
- * `.primitive-sync.json`, the content-hash baseline) into a timestamped slot
+ * `.sync-state.json`, the content-hash baseline) into a timestamped slot
  * under the snapshots root:
  *
  *   <snapshotsRoot>/<YYYY-MM-DDTHH-MM-SS>/
- *       <full pre-pull copy of the sync tree, incl. .primitive-sync.json>
+ *       <full pre-pull copy of the sync tree, incl. .sync-state.json>
  *       .snapshot-complete        # integrity marker, written LAST
  *       .audit-id                 # ULID cross-link (Phase 2; absent in P1)
  *
@@ -22,18 +22,8 @@
  * temp dir, then the live `configDir` is atomically replaced, so a mid-restore
  * crash never leaves a half-written tree.
  */
-import { existsSync, readdirSync, statSync, writeFileSync, readFileSync, cpSync, rmSync, renameSync, mkdirSync, mkdtempSync, } from "fs";
-import { join, dirname, resolve, relative, isAbsolute } from "path";
-/**
- * Returns true if `child` is `parent` or lives somewhere beneath it. Used to
- * detect the legacy `--dir` case where the snapshots root sits INSIDE the sync
- * tree (`<userDir>/.snapshots/`) — we must not copy that subtree into the
- * snapshot, or `cpSync` recurses into itself.
- */
-function isInside(parent, child) {
-    const rel = relative(resolve(parent), resolve(child));
-    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
-}
+import { existsSync, readdirSync, statSync, writeFileSync, readFileSync, cpSync, rmSync, renameSync, mkdirSync, } from "fs";
+import { join, dirname } from "path";
 /** Marker file written LAST inside a snapshot to prove it completed. */
 export const SNAPSHOT_COMPLETE_MARKER = ".snapshot-complete";
 /** Cross-link to the audit entry that produced the snapshot (Phase 2). */
@@ -87,40 +77,16 @@ export function createSnapshot(syncDir, snapshotsRoot, opts = {}) {
         finalDest = join(snapshotsRoot, finalId);
         suffix += 1;
     }
-    // Fork 4: under legacy `--dir`, the snapshots root lives INSIDE the sync
-    // tree (`<userDir>/.snapshots/`). Node's cpSync refuses to copy a directory
-    // into its own subtree (ERR_FS_CP_EINVAL) even with a filter, so in that
-    // case we stage the copy into an external temp dir (excluding the backups
-    // subtree) and then move it into place.
-    const rootIsInside = isInside(syncDir, snapshotsRoot);
-    const snapshotsRootResolved = resolve(snapshotsRoot);
-    const filter = rootIsInside
-        ? (src) => !isInside(snapshotsRootResolved, src)
-        : undefined;
-    let externalStage = null;
+    // The backups root is machine-local, under `.primitive/backups/<env>/<appId>/`,
+    // and the tree it copies is the committed `primitive/<env>/`. The two are
+    // disjoint, so the copy can never recurse into itself — the staged-into-a-
+    // temp-dir fork this used to need existed only for `--dir`, whose snapshots
+    // root sat INSIDE the tree it was snapshotting (#3154).
     try {
         mkdirSync(snapshotsRoot, { recursive: true });
-        if (rootIsInside) {
-            // Copy to a sibling of syncDir first (outside the sync tree, so no
-            // self-recursion), then move into the inside-the-tree slot. Staging in
-            // the parent keeps the move same-filesystem (avoids cross-device EXDEV
-            // that a tmpdir stage could hit).
-            const parent = dirname(resolve(syncDir));
-            mkdirSync(parent, { recursive: true });
-            externalStage = mkdtempSync(join(parent, ".primitive-snapshot-stage-"));
-            const stageTree = join(externalStage, "tree");
-            cpSync(syncDir, stageTree, {
-                recursive: true,
-                dereference: false,
-                ...(filter ? { filter } : {}),
-            });
-            renameSync(stageTree, finalDest);
-        }
-        else {
-            // Full recursive copy. `dereference: false` keeps symlinks from being
-            // silently followed (edge case: symlinks inside the sync tree).
-            cpSync(syncDir, finalDest, { recursive: true, dereference: false });
-        }
+        // Full recursive copy. `dereference: false` keeps symlinks from being
+        // silently followed (edge case: symlinks inside the sync tree).
+        cpSync(syncDir, finalDest, { recursive: true, dereference: false });
         if (opts.auditId) {
             writeFileSync(join(finalDest, SNAPSHOT_AUDIT_ID_MARKER), opts.auditId);
         }
@@ -138,16 +104,6 @@ export function createSnapshot(syncDir, snapshotsRoot, opts = {}) {
         }
         throw err;
     }
-    finally {
-        if (externalStage) {
-            try {
-                rmSync(externalStage, { recursive: true, force: true });
-            }
-            catch {
-                // ignore
-            }
-        }
-    }
     return { id: finalId, path: finalDest };
 }
 /**
@@ -246,12 +202,13 @@ export function resolveSnapshot(snapshotsRoot, id, minPrefix = 8) {
  * then `syncDir` is atomically replaced, so a mid-restore crash never leaves a
  * half-written tree.
  *
- * `opts.preserveDir` names a directory (the snapshots root) that lives INSIDE
- * `syncDir` and must survive the full-tree swap — the Fork-4 legacy `--dir`
- * case, where backups sit at `<syncDir>/.snapshots/`. Without preserving it,
- * the swap would wipe the user's entire snapshot history on restore.
+ * Nothing has to survive the swap. Backups live under the project's
+ * machine-local `.primitive/`, outside the committed tree entirely, so the
+ * `preserveDir` parameter this took went with `--dir` (#3154) — it existed
+ * only for the case where the snapshots root sat inside the directory being
+ * replaced.
  */
-export function restoreSnapshot(snapshotPath, syncDir, opts = {}) {
+export function restoreSnapshot(snapshotPath, syncDir) {
     if (!existsSync(snapshotPath)) {
         throw new Error(`Snapshot not found: ${snapshotPath}`);
     }
@@ -263,15 +220,6 @@ export function restoreSnapshot(snapshotPath, syncDir, opts = {}) {
     const unique = `${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
     const stageDir = join(parent, `.primitive-restore-stage-${unique}`);
     const oldDir = join(parent, `.primitive-restore-old-${unique}`);
-    // Determine whether a backups dir living inside syncDir needs preserving.
-    const preserve = opts.preserveDir &&
-        isInside(syncDir, opts.preserveDir) &&
-        !isInside(snapshotPath, opts.preserveDir) // don't preserve a dir that's part of the snapshot
-        ? resolve(opts.preserveDir)
-        : null;
-    const preserveStash = preserve
-        ? join(parent, `.primitive-restore-keep-${unique}`)
-        : null;
     try {
         // Materialize the snapshot into the staging dir.
         cpSync(snapshotPath, stageDir, { recursive: true, dereference: false });
@@ -303,25 +251,14 @@ export function restoreSnapshot(snapshotPath, syncDir, opts = {}) {
             }
             throw err;
         }
-        // Re-attach the preserved backups dir (Fork-4 `--dir` mode) into the
-        // freshly-restored tree, pulling it out of the displaced original.
-        if (preserve && preserveStash) {
-            const rel = relative(resolve(syncDir), preserve);
-            const fromOld = join(oldDir, rel);
-            const intoNew = join(syncDir, rel);
-            if (existsSync(fromOld) && !existsSync(intoNew)) {
-                mkdirSync(dirname(intoNew), { recursive: true });
-                renameSync(fromOld, intoNew);
-            }
-        }
         // Success — remove the displaced original.
         if (existsSync(oldDir)) {
             rmSync(oldDir, { recursive: true, force: true });
         }
     }
     finally {
-        // Clean up any leftover staging/old/stash dirs on failure.
-        for (const dir of [stageDir, oldDir, preserveStash].filter((d) => Boolean(d))) {
+        // Clean up any leftover staging/old dirs on failure.
+        for (const dir of [stageDir, oldDir]) {
             if (existsSync(dir)) {
                 try {
                     rmSync(dir, { recursive: true, force: true });

package/dist/src/lib/snapshots.js.map

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

package/dist/src/lib/step-run-table.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The step table — one renderer, two commands.
+ *
+ * Extracted in #3348, when `functions runs steps` joined `workflows runs
+ * steps`. A durable function run's steps are the SAME rows in the same
+ * envelope, and the issue's ask is that they read "in the same shape a DSL
+ * workflow run's steps come back in": two hand-kept tables would have made that
+ * a resemblance, and this makes it the same code.
+ *
+ * `annotateStepGaps` (#1367) and `stepRunDisplayDurationMs` (#2771) moved here
+ * with it and are re-exported from `commands/workflows.ts`, which is where they
+ * were first exported for testability.
+ */
+/**
+ * #2771 — how long a step row has been going.
+ *
+ * A step that is still executing is persisted with status `running` and a
+ * `durationMs` of 0 (the column is required; the real value is written when the
+ * step ends). Printing that 0 hides the one number that matters while a run is
+ * in flight — how long the current step has been stuck — so a running row is
+ * measured from its `startedAt` instead. Finished rows keep their stored
+ * duration.
+ */
+export declare function stepRunDisplayDurationMs(step: any, now?: number): number | null;
+/**
+ * #1367 — annotate step-run rows with the inter-step gap: the wall-clock time
+ * between the previous step's `endedAt` and this step's `startedAt`. Sorts by
+ * `startedAt` when every row has a parseable one (tie-break `stepIndex`),
+ * otherwise by `stepIndex` for the whole list — the ordering mode must be
+ * chosen once for all rows, not per pair: a per-pair timestamp-vs-index
+ * fallback is not transitive when some rows lack a timestamp (A<B by index,
+ * B<C by index, C<A by time), and a non-transitive comparator leaves
+ * Array.prototype.sort free to return an arbitrary order, computing gaps
+ * against the wrong predecessor. The first step has no predecessor, so its
+ * `gapMs` is `null`. A gap is only meaningful when both adjacent timestamps
+ * parse and the gap is positive. When the immediate predecessor lacks a valid
+ * `endedAt`, the gap is left `null` rather than measured from an older,
+ * non-adjacent step — otherwise a later step could raise a false stall
+ * warning against a step it does not actually follow.
+ */
+export declare function annotateStepGaps(steps: any[]): any[];
+/** The step table both `runs steps` verbs print. */
+export declare function renderStepRunTable(items: any[]): string;