@superblocksteam/workspace-sync 0.0.0-stage → 2.0.0-SNAPSHOT.e3d0ac5dd38ba62e

package/dist/sync-credential-provider.d.ts

@@ -0,0 +1,27 @@
+/** The credential the sync engine's transport authenticates DBFS calls with. */
+export interface SyncCredential {
+    token: string;
+    /** Epoch milliseconds after which the token is no longer accepted. */
+    expiresAt?: number;
+}
+/**
+ * Supplies the current sync credential. The interim implementation is a narrow
+ * server token the edge pushes before expiry; AR-1074 hardens or replaces it.
+ */
+export interface SyncCredentialProvider {
+    /** The latest credential, or undefined before the first one arrives. */
+    current(): SyncCredential | undefined;
+    /** Calls `listener` with each new credential; returns an unsubscribe. */
+    onRefresh(listener: (credential: SyncCredential) => void): () => void;
+}
+/** A provider the host feeds, e.g. from the edge's state snapshots. */
+export declare class PushedSyncCredentialProvider implements SyncCredentialProvider {
+    private credential;
+    private readonly listeners;
+    constructor(initial?: SyncCredential);
+    current(): SyncCredential | undefined;
+    onRefresh(listener: (credential: SyncCredential) => void): () => void;
+    /** Replaces the credential and notifies subscribers. */
+    push(credential: SyncCredential): void;
+}
+//# sourceMappingURL=sync-credential-provider.d.ts.map

package/dist/sync-credential-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-credential-provider.d.ts","sourceRoot":"","sources":["../src/sync-credential-provider.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,OAAO,IAAI,cAAc,GAAG,SAAS,CAAC;IACtC,yEAAyE;IACzE,SAAS,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACvE;AAED,uEAAuE;AACvE,qBAAa,4BAA6B,YAAW,sBAAsB;IACzE,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmD;IAE7E,YAAY,OAAO,CAAC,EAAE,cAAc,EAEnC;IAED,OAAO,IAAI,cAAc,GAAG,SAAS,CAEpC;IAED,SAAS,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAGpE;IAED,wDAAwD;IACxD,IAAI,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAGrC;CACF"}

package/dist/sync-credential-provider.js

@@ -0,0 +1,22 @@
+/** A provider the host feeds, e.g. from the edge's state snapshots. */
+export class PushedSyncCredentialProvider {
+    credential;
+    listeners = new Set();
+    constructor(initial) {
+        this.credential = initial;
+    }
+    current() {
+        return this.credential;
+    }
+    onRefresh(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Replaces the credential and notifies subscribers. */
+    push(credential) {
+        this.credential = credential;
+        for (const listener of this.listeners)
+            listener(credential);
+    }
+}
+//# sourceMappingURL=sync-credential-provider.js.map

package/dist/sync-credential-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-credential-provider.js","sourceRoot":"","sources":["../src/sync-credential-provider.ts"],"names":[],"mappings":"AAkBA,uEAAuE;AACvE,MAAM,OAAO,4BAA4B;IAC/B,UAAU,CAA6B;IAC9B,SAAS,GAAG,IAAI,GAAG,EAAwC,CAAC;IAE7E,YAAY,OAAwB;QAClC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC;IAC5B,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,SAAS,CAAC,QAA8C;QACtD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,wDAAwD;IACxD,IAAI,CAAC,UAA0B;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS;YAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC9D,CAAC;CACF"}

package/dist/sync-engine.d.ts

@@ -0,0 +1,141 @@
+import type { Meter, Tracer } from "@opentelemetry/api";
+import type { ApplicationHashChangeSource, CheckpointSkipReason } from "@superblocksteam/shared";
+import { type BranchWriteGuard } from "./branch-write-guard.js";
+import type { DbfsTransport } from "./dbfs-transport.js";
+import { HashCache } from "./hash-cache.js";
+import type { NativeDraftJournal } from "./native-draft-session.js";
+import { type DownloadStats } from "./server-tree.js";
+import type { WorkspaceStateStore } from "./workspace-state-store.js";
+/**
+ * Where a test can stop the engine to simulate the VM dying. A hook that
+ * throws aborts the operation at that point, leaving disk, DBFS and the state
+ * store exactly as a kill would.
+ */
+export type FaultPoint = 
+/** A write landed in the tree; nothing has been flushed or committed. */
+"after-write-before-flush"
+/** Blobs are in DBFS; the branch hash has not moved. */
+ | "after-put-before-set"
+/** The branch hash moved; the state store still holds the old hash. */
+ | "after-set-before-state";
+export type FaultPoints = Partial<Record<FaultPoint, () => void | Promise<void>>>;
+export interface WorkspaceSyncEngineOptions {
+    /** The application tree. */
+    root: string;
+    transport: DbfsTransport;
+    state: WorkspaceStateStore;
+    /** The native draft journal, when the host runs native sessions. */
+    journal?: NativeDraftJournal;
+    guard: BranchWriteGuard;
+    tracer?: Tracer;
+    meter?: Meter;
+    faults?: FaultPoints;
+    /** Seeded on rehydrate; a host may share one with other uploaders. */
+    hashCache?: HashCache;
+    /** Whether the tree holds unaccepted drafts. Defaults to its swap files. */
+    hasDraft?: () => Promise<boolean>;
+}
+export interface CommitOptions {
+    /**
+     * Finalize the draft journal before the snapshot (the turn ended). Pass
+     * false for a read-your-writes commit while a native session is still
+     * running; the journal then stays open. Defaults to true.
+     */
+    finalizeJournal?: boolean;
+    /**
+     * Send the hash even when it matches the stored one, and report the draft
+     * state even when it was already reported. The server records an accept or
+     * reject against its last checkpoint and drafts, not the branch hash: an
+     * accept of drafts the turn-end commit already uploaded must still reach it.
+     */
+    checkpoint?: boolean;
+    /**
+     * Settles the draft markers (accept, reject or clear) inside the commit
+     * queue, after the branch guard passes and the draft journal is dropped,
+     * and before the snapshot. No
+     * other commit can then reconcile the journal or report draft state between
+     * the markers changing and this commit.
+     */
+    settle?: () => Promise<void>;
+}
+export interface CommitResult {
+    dbfsHash: string;
+    commitId?: string;
+    /** Why the server made no checkpoint, when it skipped one by design. */
+    checkpointSkipped?: CheckpointSkipReason;
+    /** False when the tree already matched the stored hash. */
+    moved: boolean;
+    /** Paths the journal reconcile found changed, when a journal is active. */
+    journalChangedPaths?: string[];
+}
+export interface FlushResult {
+    /** Hash of the tree whose blobs were uploaded. */
+    hash: string;
+    /** putMany items sent; zero when DBFS already had everything. */
+    uploadedItems: number;
+}
+export type RehydrateKind = "fresh" | "resumed" | "replayed" | "reloaded";
+export interface RehydrateOutcome {
+    outcome: RehydrateKind;
+    /** The hash the state store holds afterwards. */
+    dbfsHash: string;
+    /** True when the local tree was replaced from DBFS. */
+    filesChanged: boolean;
+    /** `reloaded`: where the local diff that lost to the server was kept. */
+    orphanedPath?: string;
+    /**
+     * `replayed`: false when the guard refused the replay commit (typically the
+     * lock is not held yet at boot). The workspace stays unsynced and the next
+     * `commit` replays it.
+     */
+    replayCommitted?: boolean;
+    /** Set when a running journal (a killed native session) was reconciled. */
+    interruptedJournal?: {
+        changedPaths: string[];
+    };
+    /** The files written from DBFS and their bytes; zero when none were. */
+    downloaded: DownloadStats;
+}
+export interface RehydrateOptions {
+    /** Hash-change source for the replay commit. */
+    replaySource?: ApplicationHashChangeSource;
+}
+export interface WorkspaceSyncEvents {
+    committed: {
+        dbfsHash: string;
+        commitId?: string;
+    };
+    "unsynced-changed": {
+        unsynced: boolean;
+    };
+}
+export interface WorkspaceSyncEngine {
+    /** Reconciles the local tree, the stored hash and the server on boot. */
+    rehydrate(options?: RehydrateOptions): Promise<RehydrateOutcome>;
+    /** Uploads blobs for the current tree. Never moves the branch hash. */
+    interimFlush(): Promise<FlushResult>;
+    /** The turn-end commit. */
+    commit(source: ApplicationHashChangeSource, options?: CommitOptions): Promise<CommitResult>;
+    /**
+     * Reports whether the tree holds drafts, even when that was already
+     * reported. For a draft change that moves no hash, such as clearing markers.
+     */
+    resendDraftState(options?: Pick<CommitOptions, "settle">): Promise<void>;
+    /** True while the tree has changes the branch hash does not include. */
+    readonly unsynced: boolean;
+    /** The hash last committed or loaded, once known. */
+    readonly dbfsHash: string | undefined;
+    /** Cheap write notification for file watchers; no hashing. */
+    markDirty(): void;
+    readonly hashCache: HashCache;
+    on<E extends keyof WorkspaceSyncEvents>(event: E, listener: (payload: WorkspaceSyncEvents[E]) => void): () => void;
+}
+/**
+ * Creates the sync engine for one workspace. DBFS is the commit point: the
+ * engine moves the branch hash only in {@link WorkspaceSyncEngine.commit} (and
+ * the rehydrate replay), and the state store is a cache of the last hash it
+ * committed or loaded. Every operation is serialized, and each step is
+ * ordered so a kill at any point is recovered by `rehydrate`.
+ */
+export declare function createWorkspaceSyncEngine(options: WorkspaceSyncEngineOptions): WorkspaceSyncEngine;
+//# sourceMappingURL=sync-engine.d.ts.map

package/dist/sync-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../src/sync-engine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EACV,2BAA2B,EAC3B,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,kBAAkB,CAAC;AAgB1B,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,4BAA4B,CAAC;AAIpC;;;;GAIG;AACH,MAAM,MAAM,UAAU;AACpB,yEAAyE;AACvE,0BAA0B;AAC5B,wDAAwD;GACtD,sBAAsB;AACxB,uEAAuE;GACrE,wBAAwB,CAAC;AAE7B,MAAM,MAAM,WAAW,GAAG,OAAO,CAC/B,MAAM,CAAC,UAAU,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAC/C,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC;IACzB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,oEAAoE;IACpE,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,oBAAoB,CAAC;IACzC,2DAA2D;IAC3D,KAAK,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAI1E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,CAAC;IACvB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,YAAY,EAAE,OAAO,CAAC;IACtB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAChD,wEAAwE;IACxE,UAAU,EAAE,aAAa,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,YAAY,CAAC,EAAE,2BAA2B,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,kBAAkB,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACjE,uEAAuE;IACvE,YAAY,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IACrC,2BAA2B;IAC3B,MAAM,CACJ,MAAM,EAAE,2BAA2B,EACnC,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB;;;OAGG;IACH,gBAAgB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,8DAA8D;IAC9D,SAAS,IAAI,IAAI,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,EAAE,CAAC,CAAC,SAAS,MAAM,mBAAmB,EACpC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,GAClD,MAAM,IAAI,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,CAErB"}

package/dist/sync-engine.js

@@ -0,0 +1,447 @@
+import * as fsp from "node:fs/promises";
+import { BranchWriteRejectedError, } from "./branch-write-guard.js";
+import { hasDraftsFailClosed } from "./draft-helpers.js";
+import { HashCache } from "./hash-cache.js";
+import { hashLocalDirectory } from "./hash-dir-tree.js";
+import { downloadServerTree, flattenTree, readServerTree, } from "./server-tree.js";
+import { snapshotLocalDirectory, snapshotLocalDirectoryWithDrafts, } from "./snapshot/take-snapshot.js";
+import { collectSnapshotUploadItems, uploadSnapshotItems, } from "./snapshot/upload-snapshot.js";
+import { createSyncTelemetry, inSpan, } from "./sync-telemetry.js";
+const BLOB_BATCH = 64;
+const NOTHING_DOWNLOADED = { files: 0, bytes: 0 };
+/**
+ * Creates the sync engine for one workspace. DBFS is the commit point: the
+ * engine moves the branch hash only in {@link WorkspaceSyncEngine.commit} (and
+ * the rehydrate replay), and the state store is a cache of the last hash it
+ * committed or loaded. Every operation is serialized, and each step is
+ * ordered so a kill at any point is recovered by `rehydrate`.
+ */
+export function createWorkspaceSyncEngine(options) {
+    return new SyncEngine(options);
+}
+class SyncEngine {
+    options;
+    hashCache;
+    telemetry;
+    listeners = new Map();
+    queue = Promise.resolve();
+    committedHash;
+    localHash;
+    writes = 0;
+    committedWrites = 0;
+    lastUnsynced = false;
+    reportedDraft;
+    constructor(options) {
+        this.options = options;
+        this.hashCache = options.hashCache ?? new HashCache();
+        this.telemetry = createSyncTelemetry(options.tracer, options.meter);
+        this.telemetry.unsynced.record(0);
+    }
+    get unsynced() {
+        return (this.writes !== this.committedWrites ||
+            (this.localHash !== undefined && this.localHash !== this.committedHash));
+    }
+    get dbfsHash() {
+        return this.committedHash;
+    }
+    markDirty() {
+        this.writes++;
+        this.updateUnsynced();
+    }
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set)
+            this.listeners.set(event, (set = new Set()));
+        set.add(listener);
+        return () => set.delete(listener);
+    }
+    interimFlush() {
+        return this.serialize(() => inSpan(this.telemetry.tracer, "workspace.flush", async (span) => {
+            await this.fault("after-write-before-flush");
+            const snapshot = await snapshotLocalDirectoryWithDrafts(this.options.root);
+            const uploadedItems = await this.upload(snapshot);
+            this.localHash = snapshot.hash;
+            this.updateUnsynced();
+            span.setAttribute("workspace.sync.uploaded_items", uploadedItems);
+            return { hash: snapshot.hash, uploadedItems };
+        }));
+    }
+    commit(source, options = {}) {
+        const { settle } = options;
+        return this.serialize(async () => {
+            if (settle)
+                await this.settleNow(settle);
+            return this.commitNow(source, settle
+                ? "skip"
+                : options.finalizeJournal === false
+                    ? "keep"
+                    : "finalize", options.checkpoint ?? false);
+        });
+    }
+    resendDraftState(options = {}) {
+        const { settle } = options;
+        return this.serialize(async () => {
+            if (settle)
+                await this.settleNow(settle);
+            await this.reportDraftState({
+                force: true,
+                beforeSend: () => this.assertOwnsBranch(),
+            });
+        });
+    }
+    rehydrate(options = {}) {
+        return this.serialize(() => inSpan(this.telemetry.tracer, "workspace.rehydrate", async (span) => {
+            const outcome = await this.rehydrateNow(options);
+            span.setAttribute("workspace.sync.outcome", outcome.outcome);
+            span.setAttribute("workspace.sync.files_downloaded", outcome.downloaded.files);
+            span.setAttribute("workspace.sync.bytes_downloaded", outcome.downloaded.bytes);
+            this.telemetry.rehydrateOutcome.add(1, { outcome: outcome.outcome });
+            return outcome;
+        }));
+    }
+    async rehydrateNow({ replaySource = "ai:generate:post", }) {
+        const { root, transport, state, journal } = this.options;
+        const serverHash = await transport.getServerHash();
+        const storedHash = (await state.read())?.dbfsHash;
+        const local = await this.hashLocalTree();
+        const writesAtStart = this.writes;
+        let result;
+        if (local === undefined) {
+            const tree = await readServerTree(transport, serverHash);
+            const downloaded = await downloadServerTree({
+                transport,
+                tree,
+                local: undefined,
+                root,
+            });
+            await this.storeLoaded(serverHash, tree);
+            result = {
+                outcome: "fresh",
+                dbfsHash: serverHash,
+                filesChanged: true,
+                downloaded,
+            };
+        }
+        else if (local.hash === serverHash) {
+            this.hashCache.add_directory_recursive(await readServerTree(transport, serverHash));
+            if (storedHash !== serverHash)
+                await state.write({ dbfsHash: serverHash });
+            this.committedHash = serverHash;
+            this.localHash = serverHash;
+            result = {
+                outcome: "resumed",
+                dbfsHash: serverHash,
+                filesChanged: false,
+                downloaded: NOTHING_DOWNLOADED,
+            };
+        }
+        else if (storedHash === serverHash) {
+            // The kill landed after a write and before the commit finished: the
+            // server never moved past this workspace, so the local tree wins.
+            this.hashCache.add_directory_recursive(await readServerTree(transport, serverHash));
+            this.committedHash = serverHash;
+            this.localHash = local.hash;
+            let replayCommitted = true;
+            try {
+                await this.commitNow(replaySource, "skip");
+            }
+            catch (error) {
+                if (!(error instanceof BranchWriteRejectedError) ||
+                    error.reason !== "lock_not_held")
+                    throw error;
+                replayCommitted = false;
+            }
+            result = {
+                outcome: "replayed",
+                dbfsHash: this.committedHash ?? serverHash,
+                filesChanged: false,
+                replayCommitted,
+                downloaded: NOTHING_DOWNLOADED,
+            };
+        }
+        else {
+            // The server moved (or this workspace never recorded a hash): keep the
+            // local difference where an operator or agent can find it, then load
+            // the server tree.
+            const tree = await readServerTree(transport, serverHash);
+            const orphanedPath = await this.keepOrphan(serverHash, storedHash, tree);
+            const downloaded = await downloadServerTree({
+                transport,
+                tree,
+                local,
+                root,
+            });
+            await this.storeLoaded(serverHash, tree);
+            result = {
+                outcome: "reloaded",
+                dbfsHash: serverHash,
+                filesChanged: true,
+                orphanedPath,
+                downloaded,
+            };
+        }
+        if (journal && (await journal.phase()) === "running") {
+            const reconciled = await journal.reconcile(false);
+            if (reconciled) {
+                result.interruptedJournal = { changedPaths: reconciled.changedPaths };
+                // Without the branch the flag is not this workspace's to set; the
+                // next commit reports it once the guard passes.
+                if (reconciled.changedPaths.length > 0)
+                    await this.reportDraftState({
+                        only: true,
+                        beforeSend: () => this.assertOwnsBranch(),
+                    }).catch((error) => {
+                        if (!(error instanceof BranchWriteRejectedError))
+                            throw error;
+                    });
+            }
+        }
+        if (result.outcome !== "replayed" || result.replayCommitted)
+            this.committedWrites = writesAtStart;
+        this.updateUnsynced();
+        return result;
+    }
+    async commitNow(source, journalMode, checkpoint = false) {
+        const { root, transport, state, journal, guard } = this.options;
+        const started = performance.now();
+        let outcome = "error";
+        try {
+            return await inSpan(this.telemetry.tracer, "workspace.commit", async (span) => {
+                span.setAttribute("workspace.sync.source", source);
+                span.setAttribute("workspace.sync.checkpoint", checkpoint);
+                const writesAtStart = this.writes;
+                let journalChangedPaths;
+                if (journal && journalMode !== "skip") {
+                    const reconciled = await journal.reconcile(journalMode === "finalize");
+                    journalChangedPaths = reconciled?.changedPaths;
+                }
+                const baseHash = (await state.read())?.dbfsHash;
+                const assertCanCommit = async () => {
+                    try {
+                        await guard.assertCanCommit(baseHash);
+                    }
+                    catch (error) {
+                        if (error instanceof BranchWriteRejectedError) {
+                            outcome = "rejected";
+                            span.setAttribute("workspace.sync.rejection", error.reason);
+                        }
+                        throw error;
+                    }
+                };
+                // Drafts go before the hash: the server files an
+                // `ai:generate:post` as a draft only while it holds isDraft=true.
+                // Reported after, a turn's first drafts become a manual checkpoint,
+                // and the accept that follows finds nothing new to checkpoint. The
+                // guard runs first, so a workspace that lost the branch cannot
+                // flip the shared flag.
+                await this.reportDraftState({
+                    only: true,
+                    force: checkpoint,
+                    beforeSend: assertCanCommit,
+                });
+                await this.fault("after-write-before-flush");
+                const snapshot = await snapshotLocalDirectoryWithDrafts(root);
+                const hash = snapshot.hash;
+                this.localHash = hash;
+                if (hash === baseHash && !checkpoint) {
+                    this.committedHash = baseHash;
+                    await journal?.retireUploaded(hash);
+                    this.committedWrites = writesAtStart;
+                    this.updateUnsynced();
+                    outcome = "unchanged";
+                    span.setAttribute("workspace.sync.outcome", outcome);
+                    return {
+                        dbfsHash: hash,
+                        moved: false,
+                        ...(journalChangedPaths && { journalChangedPaths }),
+                    };
+                }
+                const uploadedItems = await this.upload(snapshot);
+                span.setAttribute("workspace.sync.uploaded_items", uploadedItems);
+                await this.fault("after-put-before-set");
+                await assertCanCommit();
+                const result = await transport.setHash({ hash, baseHash, source });
+                if (result.checkpointSkipped)
+                    span.setAttribute("workspace.sync.checkpoint_skipped", result.checkpointSkipped);
+                await this.fault("after-set-before-state");
+                await state.write({ dbfsHash: hash });
+                this.committedHash = hash;
+                await journal?.retireUploaded(hash);
+                this.committedWrites = writesAtStart;
+                this.updateUnsynced();
+                // Only an accept or reject checkpoint clears the flag, and only
+                // once the server has its hash. A plain commit never does: after a
+                // failed accept the markers are gone, and clearing then would make
+                // the AI tree publishable without its checkpoint.
+                if (checkpoint)
+                    await this.reportDraftState({
+                        only: false,
+                        force: true,
+                        beforeSend: () => this.assertOwnsBranch(),
+                    });
+                outcome = "committed";
+                span.setAttribute("workspace.sync.outcome", outcome);
+                this.emit("committed", {
+                    dbfsHash: hash,
+                    ...(result.commitId && { commitId: result.commitId }),
+                });
+                return {
+                    dbfsHash: hash,
+                    moved: hash !== baseHash,
+                    ...(result.commitId && { commitId: result.commitId }),
+                    ...(result.checkpointSkipped && {
+                        checkpointSkipped: result.checkpointSkipped,
+                    }),
+                    ...(journalChangedPaths && { journalChangedPaths }),
+                };
+            });
+        }
+        finally {
+            this.telemetry.commitDuration.record((performance.now() - started) / 1000, { outcome });
+        }
+    }
+    /** Puts what DBFS lacks for `snapshot`; returns the items sent. */
+    async upload(snapshot) {
+        const { transport } = this.options;
+        const sent = await uploadSnapshotItems({
+            validateMany: (items) => transport.validateMany(items),
+            putMany: async (items) => {
+                await transport.putMany(items);
+            },
+        }, collectSnapshotUploadItems(snapshot, this.hashCache));
+        this.hashCache.add_directory_recursive(snapshot);
+        return sent;
+    }
+    /** The local tree's hashed state, or undefined when it has no synced entries. */
+    async hashLocalTree() {
+        try {
+            await fsp.access(this.options.root);
+        }
+        catch {
+            return undefined;
+        }
+        const local = await hashLocalDirectory(this.options.root);
+        return local.contents.length === 0 ? undefined : local;
+    }
+    async storeLoaded(hash, tree) {
+        await this.options.state.write({ dbfsHash: hash });
+        this.hashCache.add_directory_recursive(tree);
+        this.committedHash = hash;
+        this.localHash = hash;
+    }
+    async keepOrphan(serverHash, storedHash, tree) {
+        const snapshot = await snapshotLocalDirectory(this.options.root);
+        const serverFiles = flattenTree(tree);
+        const localFiles = flattenTree(snapshot);
+        const contents = new Map();
+        const collect = (entries, prefix = "") => {
+            for (const entry of entries) {
+                if (entry.type === "d")
+                    collect(entry.contents, `${prefix}${entry.name}/`);
+                else if (entry.type === "-")
+                    contents.set(entry.hash, entry.contents);
+            }
+        };
+        collect(snapshot.contents);
+        const changed = [];
+        for (const [entryPath, entry] of localFiles) {
+            const server = serverFiles.get(entryPath);
+            const same = server !== undefined &&
+                (entry.type === "l"
+                    ? server.type === "l" && server.target === entry.target
+                    : server.type === "-" &&
+                        server.hash === entry.hash &&
+                        server.executable === entry.executable);
+            if (!same)
+                changed.push({ path: entryPath, ...entry });
+        }
+        const deleted = [...serverFiles.keys()].filter((entryPath) => !localFiles.has(entryPath));
+        const blobs = [];
+        const seen = new Set();
+        for (const entry of changed) {
+            if (entry.type !== "-" || seen.has(entry.hash))
+                continue;
+            seen.add(entry.hash);
+            if (this.hashCache.check_file_content(entry.hash))
+                continue;
+            blobs.push({
+                type: "fileContents",
+                contents: contents.get(entry.hash).toString("base64"),
+            });
+        }
+        for (let idx = 0; idx < blobs.length; idx += BLOB_BATCH)
+            await this.options.transport.putMany(blobs.slice(idx, idx + BLOB_BATCH));
+        for (const hash of seen)
+            this.hashCache.add_file_content(hash);
+        return this.options.state.writeOrphan({
+            createdAt: new Date().toISOString(),
+            serverHash,
+            storedHash,
+            localHash: snapshot.hash,
+            changed,
+            deleted,
+        });
+    }
+    /**
+     * Runs `settle` once the guard lets this workspace write the branch, so a
+     * refused settle leaves the markers and the server's draft flag as they
+     * were. A running journal (its turn-end reconcile failed) is reconciled
+     * first, so every marker is there to accept or restore. The journal is then
+     * dropped, since its next reconcile would rebuild the markers `settle`
+     * removes. Callers hold the queue.
+     */
+    async settleNow(settle) {
+        await this.assertOwnsBranch();
+        const { journal } = this.options;
+        if (journal && (await journal.phase()) === "running")
+            await journal.reconcile(false);
+        await journal?.clear();
+        await settle();
+    }
+    /**
+     * The server's draft flag is shared by the branch, so only the workspace
+     * the guard lets write the branch may change it: the lock holder, on the
+     * hash it last committed.
+     */
+    async assertOwnsBranch() {
+        await this.options.guard.assertCanCommit((await this.options.state.read())?.dbfsHash);
+    }
+    /**
+     * Sends the tree's draft state when it changed, or always with `force`.
+     * With `only`, sends it only when the tree's state is that value;
+     * `beforeSend` runs only when it is about to be sent.
+     */
+    async reportDraftState(options = {}) {
+        const { force = false, only, beforeSend } = options;
+        const hasDraft = await (this.options.hasDraft?.() ??
+            hasDraftsFailClosed(this.options.root));
+        if (only !== undefined && hasDraft !== only)
+            return;
+        if (!force && hasDraft === this.reportedDraft)
+            return;
+        await beforeSend?.();
+        await this.options.transport.setDraftState(hasDraft);
+        this.reportedDraft = hasDraft;
+    }
+    async fault(point) {
+        await this.options.faults?.[point]?.();
+    }
+    updateUnsynced() {
+        const unsynced = this.unsynced;
+        if (unsynced === this.lastUnsynced)
+            return;
+        this.lastUnsynced = unsynced;
+        this.telemetry.unsynced.record(unsynced ? 1 : 0);
+        this.emit("unsynced-changed", { unsynced });
+    }
+    emit(event, payload) {
+        for (const listener of this.listeners.get(event) ?? [])
+            listener(payload);
+    }
+    serialize(run) {
+        const result = this.queue.then(run, run);
+        this.queue = result.catch(() => undefined);
+        return result;
+    }
+}
+//# sourceMappingURL=sync-engine.js.map