@cuna_labs/cli 0.1.0

package/dist/sync/continuous-sync-supervisor.js

@@ -0,0 +1,1117 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants as fileConstants, watch } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rmdir, unlink, writeFile, } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { EXIT_CODES, CunaError } from "../core/errors.js";
+import { createWorkspaceManifest } from "../workspace/manifest.js";
+import { assertLexicallyInsideRoot, normalizeWirePath, } from "../workspace/paths.js";
+import { DurableSyncJournal } from "./journal.js";
+import { decodeChangePage } from "./workspace-sync-protocol.js";
+const STATE_SCHEMA = 1;
+const ZERO_DIGEST = "0".repeat(64);
+const DEFAULT_DEBOUNCE_MS = 250;
+const DEFAULT_RECONCILE_MS = 60_000;
+const DEFAULT_REMOTE_POLL_MS = 750;
+const DEFAULT_OPERATION_LIMIT = 10_000;
+const DEFAULT_BYTE_LIMIT = 256 * 1024 * 1024;
+/**
+ * One foreground supervisor owns one WorkspaceBinding writer lease. It keeps
+ * synchronization on an independent asynchronous control path: terminal I/O
+ * never enters this queue, and every scan/poll batch yields before continuing.
+ */
+export class ContinuousWorkspaceSyncSupervisor {
+    #input;
+    #clock;
+    #sleep;
+    #manifestBuilder;
+    #listeners = new Set();
+    #controller = new AbortController();
+    #statePath;
+    #journalDirectory;
+    #state;
+    #journal;
+    #writerLease;
+    #watcher;
+    #loop;
+    #wake;
+    #scanRequested = false;
+    #reconcileRequested = false;
+    #closed = false;
+    constructor(input, state) {
+        this.#input = input;
+        this.#clock = input.clock ?? Date.now;
+        this.#sleep = input.sleep ?? abortableSleep;
+        this.#manifestBuilder = input.manifestBuilder ?? createWorkspaceManifest;
+        this.#state = state;
+        this.#statePath = join(input.stateDirectory, "continuous-sync.state.json");
+        this.#journalDirectory = join(input.stateDirectory, "operation-journal");
+    }
+    static async start(input) {
+        validateInput(input);
+        const root = await canonicalPlainDirectory(input.canonicalRoot);
+        const stateDirectory = await preparePrivateDirectory(input.stateDirectory, root);
+        const normalizedInput = Object.freeze({ ...input, canonicalRoot: root, stateDirectory });
+        const initialManifest = input.initialManifest ?? await (input.manifestBuilder ?? createWorkspaceManifest)({
+            root,
+            policy: input.policy,
+            capabilities: input.filesystemCapabilities,
+        });
+        if (initialManifest.policyDigest !== input.policy.digest ||
+            initialManifest.manifestRoot !== input.initialManifestRoot) {
+            throw syncFailure("initial_manifest_unproven", EXIT_CODES.conflict);
+        }
+        const statePath = join(stateDirectory, "continuous-sync.state.json");
+        const loaded = await loadState(statePath);
+        const state = loaded === undefined
+            ? createInitialState(normalizedInput, initialManifest)
+            : admitState(loaded, normalizedInput);
+        if (loaded === undefined)
+            await atomicWriteState(statePath, state);
+        const supervisor = new ContinuousWorkspaceSyncSupervisor(normalizedInput, state);
+        try {
+            await supervisor.#open();
+            return supervisor;
+        }
+        catch (error) {
+            try {
+                await supervisor.stop();
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "Continuous synchronization startup cleanup was incomplete.");
+            }
+            throw error;
+        }
+    }
+    get snapshot() {
+        return Object.freeze({
+            state: this.#closed ? "stopped" : this.#state.status,
+            generation: this.#state.generation,
+            manifestRoot: this.#state.manifest_root,
+            dirty: this.#state.dirty,
+            pendingLocalOperations: this.#state.pending_local.length,
+            pendingRemoteChanges: this.#state.pending_remote === null
+                ? 0
+                : this.#state.pending_remote.items.length - this.#state.pending_remote.nextIndex,
+            ...(this.#state.reason === null ? {} : { reason: this.#state.reason }),
+            observedAt: this.#state.updated_at,
+        });
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        try {
+            listener(this.snapshot);
+        }
+        catch { /* Projection observers cannot own sync correctness. */ }
+        return () => this.#listeners.delete(listener);
+    }
+    requestScan() {
+        if (this.#closed)
+            return;
+        this.#scanRequested = true;
+        this.#wake?.();
+    }
+    requestReconciliation(reason = "explicit_reconciliation") {
+        if (this.#closed)
+            return;
+        this.#reconcileRequested = true;
+        // The run loop is the sole durable-state writer. Publishing an optimistic
+        // transition here would race a concurrent apply/checkpoint write.
+        void reason;
+        this.#wake?.();
+    }
+    async stop() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#controller.abort(syncFailure("cancelled", EXIT_CODES.network));
+        this.#wake?.();
+        const failures = [];
+        try {
+            await this.#watcher?.close();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await this.#loop;
+        }
+        catch (error) {
+            if (!isAbort(error))
+                failures.push(error);
+        }
+        try {
+            await this.#journal?.close();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await this.#writerLease?.close();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        this.#publish();
+        if (failures.length > 0)
+            throw new AggregateError(failures, "Continuous synchronization cleanup was incomplete.");
+    }
+    async waitForStop() {
+        await this.#loop;
+    }
+    async #open() {
+        if (this.#input.writerLeaseDirectory !== undefined) {
+            this.#writerLease = await DurableSyncJournal.open({
+                directory: this.#input.writerLeaseDirectory,
+                bindingId: this.#input.bindingId,
+                // This journal is only the stable per-binding writer authority; its
+                // metadata generation deliberately does not follow content revisions.
+                bindingGeneration: 1,
+                ownerId: `continuous-sync-authority:${process.pid}:${randomUUID()}`,
+                clock: this.#clock,
+            });
+        }
+        try {
+            this.#journal = await DurableSyncJournal.open({
+                directory: this.#journalDirectory,
+                bindingId: this.#input.bindingId,
+                bindingGeneration: this.#input.bindingGeneration,
+                ownerId: `continuous-sync:${process.pid}:${randomUUID()}`,
+                clock: this.#clock,
+            });
+        }
+        catch (error) {
+            await this.#writerLease?.close();
+            throw error;
+        }
+        if (this.#state.pending_remote !== null)
+            await this.#resumeRemoteApply();
+        await this.#recoverPendingLocal();
+        const watchFactory = this.#input.watchFactory ?? createNodeWorkspaceWatcher;
+        this.#watcher = await watchFactory({
+            root: this.#input.canonicalRoot,
+            onEvent: (event) => {
+                if (event.kind === "overflow" || event.path === undefined) {
+                    this.requestReconciliation("watcher_overflow");
+                    return;
+                }
+                try {
+                    const path = normalizeWirePath(event.path.replaceAll("\\", "/"), this.#input.filesystemCapabilities);
+                    const decision = this.#input.policy.decide(path);
+                    if (!decision.excluded)
+                        this.requestScan();
+                }
+                catch {
+                    this.requestReconciliation("watcher_path_untrusted");
+                }
+            },
+            onError: () => this.requestReconciliation("watcher_failed"),
+        });
+        this.#scanRequested = true;
+        this.#loop = this.#runLoop();
+    }
+    async #runLoop() {
+        const signal = this.#controller.signal;
+        let lastReconciliation = this.#clock();
+        while (!signal.aborted) {
+            try {
+                if (this.#reconcileRequested || this.#clock() - lastReconciliation >= (this.#input.reconciliationIntervalMs ?? DEFAULT_RECONCILE_MS)) {
+                    this.#reconcileRequested = false;
+                    await this.#reconcile(signal);
+                    lastReconciliation = this.#clock();
+                }
+                if (this.#scanRequested && this.#state.status !== "conflicted" && this.#state.status !== "recovery_required") {
+                    this.#scanRequested = false;
+                    await this.#sleep(this.#input.debounceMs ?? DEFAULT_DEBOUNCE_MS, signal);
+                    await this.#scanAndCommit(signal);
+                }
+                if (this.#state.status !== "conflicted" && this.#state.status !== "recovery_required" && this.#state.status !== "paused") {
+                    await this.#consumeRemote(signal);
+                }
+                await this.#journal?.renew();
+                await this.#waitForWake(this.#input.remotePollIntervalMs ?? DEFAULT_REMOTE_POLL_MS, signal);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    break;
+                const classification = classifyFailure(error);
+                await this.#transition({
+                    status: classification.status,
+                    dirty: true,
+                    reason: classification.reason,
+                });
+                if (classification.status === "recovery_required" || classification.status === "conflicted")
+                    break;
+                await this.#waitForWake(this.#input.remotePollIntervalMs ?? DEFAULT_REMOTE_POLL_MS, signal);
+            }
+        }
+    }
+    async #scanAndCommit(signal) {
+        await this.#transition({ status: "catching_up", reason: null });
+        const manifest = await this.#buildManifest();
+        if (manifest.manifestRoot === this.#state.manifest_root) {
+            if (!this.#state.dirty)
+                await this.#transition({ status: "live_unverified", reason: null });
+            else
+                this.#reconcileRequested = true;
+            return;
+        }
+        const observedOperations = diffManifest(this.#state.baseline, manifest, this.#state.generation);
+        const operations = this.#state.pending_local.length === 0
+            ? observedOperations
+            : samePendingIntent(this.#state.pending_local, observedOperations)
+                ? this.#state.pending_local
+                : (() => { throw syncFailure("pending_local_intent_changed", EXIT_CODES.conflict); })();
+        const maximumOperations = this.#input.maximumPendingOperations ?? DEFAULT_OPERATION_LIMIT;
+        const maximumBytes = this.#input.maximumPendingBytes ?? DEFAULT_BYTE_LIMIT;
+        const bytes = operations.reduce((total, operation) => total + operation.byteLength, 0);
+        if (operations.length > maximumOperations || bytes > maximumBytes) {
+            await this.#transition({ status: "paused", dirty: true, reason: operations.length > maximumOperations ? "operation_limit" : "byte_limit" });
+            return;
+        }
+        if (this.#state.pending_local.length === 0) {
+            for (const operation of operations) {
+                await this.#journal?.append({
+                    operationId: operation.operationId,
+                    baseGeneration: operation.baseGeneration,
+                    digest: operation.fingerprint,
+                    byteLength: operation.byteLength,
+                });
+            }
+            await this.#replaceState({ pending_local: operations, status: "catching_up", dirty: this.#state.dirty, reason: null });
+        }
+        for (const operation of operations)
+            await transitionIfQueued(this.#journal, operation.operationId);
+        let receipt;
+        try {
+            receipt = await this.#input.authority.commitLocalSnapshot({
+                baseGeneration: this.#state.generation,
+                manifest,
+                signal,
+            });
+        }
+        catch (error) {
+            for (const operation of operations)
+                await transitionIfPossible(this.#journal, operation.operationId, "uncertain");
+            throw error;
+        }
+        if (receipt.generation !== this.#state.generation + 1 ||
+            receipt.manifestRoot !== manifest.manifestRoot ||
+            !isUuid(receipt.syncId)) {
+            throw syncFailure("commit_receipt_mismatch", EXIT_CODES.remote);
+        }
+        for (const operation of operations) {
+            await this.#journal?.transition(operation.operationId, "acknowledged");
+            await this.#journal?.transition(operation.operationId, "applied");
+        }
+        await this.#replaceState({
+            sync_id: receipt.syncId,
+            generation: receipt.generation,
+            manifest_root: receipt.manifestRoot,
+            baseline: projectManifest(manifest),
+            pending_local: [],
+            cursor: null,
+            status: "live_unverified",
+            dirty: false,
+            reason: null,
+        });
+    }
+    async #consumeRemote(signal) {
+        const items = [];
+        let cursor = this.#state.cursor ?? undefined;
+        let terminalCursor = null;
+        for (let pageIndex = 0; pageIndex < 256; pageIndex += 1) {
+            const page = await this.#input.authority.listChanges({
+                syncId: this.#state.sync_id,
+                ...(cursor === undefined ? {} : { cursor }),
+                afterGeneration: this.#state.generation,
+                signal,
+            });
+            items.push(...page.items.filter((item) => item.generation > this.#state.generation));
+            terminalCursor = page.next_cursor;
+            if (page.next_cursor === null)
+                break;
+            if (page.next_cursor === cursor)
+                throw syncFailure("remote_cursor_stalled", EXIT_CODES.conflict);
+            cursor = page.next_cursor;
+            if (pageIndex === 255)
+                throw syncFailure("remote_page_limit", EXIT_CODES.conflict);
+        }
+        const unseen = items;
+        if (unseen.length === 0) {
+            if (!this.#state.dirty && this.#state.status !== "converged") {
+                await this.#transition({ status: "live_unverified", reason: null });
+            }
+            return;
+        }
+        let offset = 0;
+        while (offset < unseen.length) {
+            const generation = unseen[offset]?.generation;
+            if (generation === undefined || generation !== this.#state.generation + 1) {
+                throw syncFailure("remote_sequence_gap", EXIT_CODES.conflict);
+            }
+            const items = [];
+            while (offset < unseen.length && unseen[offset]?.generation === generation) {
+                const item = unseen[offset];
+                if (item !== undefined)
+                    items.push(item);
+                offset += 1;
+            }
+            const manifestRoot = commonRemoteField(items, "manifest_root");
+            const policyDigest = commonRemoteField(items, "exclusion_policy_digest");
+            if (policyDigest !== this.#input.policy.digest)
+                throw syncFailure("remote_policy_changed", EXIT_CODES.conflict);
+            await this.#replaceState({
+                status: "catching_up",
+                pending_remote: Object.freeze({
+                    generation,
+                    manifestRoot,
+                    cursor: offset === unseen.length ? terminalCursor : this.#state.cursor,
+                    items: Object.freeze(items),
+                    nextIndex: 0,
+                }),
+                reason: null,
+            });
+            await this.#resumeRemoteApply();
+        }
+    }
+    async #resumeRemoteApply() {
+        const pending = this.#state.pending_remote;
+        if (pending === null)
+            return;
+        const signal = this.#controller.signal;
+        const current = await this.#buildManifest();
+        const currentEntries = new Map(projectManifest(current).map((entry) => [entry.path, entry]));
+        const baseline = new Map(this.#state.baseline.map((entry) => [entry.path, entry]));
+        const ordered = orderRemoteItems(pending.items);
+        for (let index = pending.nextIndex; index < ordered.length; index += 1) {
+            const item = ordered[index];
+            if (item === undefined)
+                continue;
+            if (item.operation !== "revision") {
+                const path = item.path;
+                if (path === null)
+                    throw syncFailure("remote_change_shape", EXIT_CODES.remote);
+                const prior = baseline.get(path);
+                const observed = currentEntries.get(path);
+                if (!sameProjection(prior, observed)) {
+                    await this.#retainConflict(item, signal);
+                    await this.#replaceState({
+                        pending_remote: Object.freeze({ ...pending, items: Object.freeze(ordered), nextIndex: index + 1 }),
+                        status: "conflicted",
+                        dirty: true,
+                        reason: "same_path_diverged",
+                    });
+                    throw syncFailure("same_path_diverged", EXIT_CODES.conflict);
+                }
+                await this.#applyRemoteItem(item, signal);
+            }
+            await this.#replaceState({
+                pending_remote: Object.freeze({ ...pending, items: Object.freeze(ordered), nextIndex: index + 1 }),
+            });
+        }
+        const manifest = await this.#buildManifest();
+        if (manifest.manifestRoot !== pending.manifestRoot) {
+            throw syncFailure("remote_apply_manifest_mismatch", EXIT_CODES.conflict);
+        }
+        await this.#replaceState({
+            generation: pending.generation,
+            manifest_root: pending.manifestRoot,
+            baseline: projectManifest(manifest),
+            cursor: pending.cursor,
+            pending_remote: null,
+            dirty: false,
+            status: "live_unverified",
+            reason: null,
+        });
+    }
+    async #applyRemoteItem(item, signal) {
+        if (item.path === null)
+            return;
+        const path = normalizeWirePath(item.path, this.#input.filesystemCapabilities);
+        const physical = assertLexicallyInsideRoot(this.#input.canonicalRoot, join(this.#input.canonicalRoot, path));
+        if (item.operation === "delete") {
+            await safeDelete(this.#input.canonicalRoot, physical);
+            return;
+        }
+        const entry = item.entry;
+        if (entry === null)
+            throw syncFailure("remote_change_shape", EXIT_CODES.remote);
+        const decision = this.#input.policy.decide(path, entry.kind);
+        if (decision.excluded)
+            throw syncFailure("remote_excluded_path", EXIT_CODES.policy);
+        if (entry.kind === "symlink")
+            throw syncFailure("remote_symlink_unsupported", EXIT_CODES.policy);
+        if (entry.kind === "directory") {
+            await ensureSafeDirectory(this.#input.canonicalRoot, physical);
+            return;
+        }
+        const chunks = [];
+        let total = 0;
+        for (const chunk of entry.chunks) {
+            const bytes = await this.#input.authority.readChunk({
+                syncId: this.#state.sync_id,
+                digest: chunk.digest,
+                byteLength: chunk.byte_length,
+                signal,
+            });
+            if (bytes.byteLength !== chunk.byte_length || sha256(bytes) !== chunk.digest) {
+                throw syncFailure("remote_chunk_mismatch", EXIT_CODES.policy);
+            }
+            chunks.push(bytes);
+            total += bytes.byteLength;
+        }
+        if (total !== entry.byte_length)
+            throw syncFailure("remote_content_length_mismatch", EXIT_CODES.remote);
+        await atomicReplaceFile(this.#input.canonicalRoot, physical, chunks, entry.executable);
+    }
+    async #retainConflict(item, signal) {
+        if (item.operation !== "upsert" || item.entry === null || item.path === null || item.entry.kind !== "file")
+            return;
+        const suffix = createHash("sha256")
+            .update(`${this.#input.bindingId}\0${item.generation}\0${item.path}`)
+            .digest("hex")
+            .slice(0, 12);
+        const retained = `${item.path}.cuna-conflict-${item.generation}-${suffix}`;
+        const physical = assertLexicallyInsideRoot(this.#input.canonicalRoot, join(this.#input.canonicalRoot, retained));
+        const chunks = [];
+        for (const chunk of item.entry.chunks) {
+            const bytes = await this.#input.authority.readChunk({
+                syncId: this.#state.sync_id,
+                digest: chunk.digest,
+                byteLength: chunk.byte_length,
+                signal,
+            });
+            if (bytes.byteLength !== chunk.byte_length || sha256(bytes) !== chunk.digest) {
+                throw syncFailure("remote_chunk_mismatch", EXIT_CODES.policy);
+            }
+            chunks.push(bytes);
+        }
+        await atomicReplaceFile(this.#input.canonicalRoot, physical, chunks, item.entry.executable, true);
+    }
+    async #reconcile(signal) {
+        await this.#transition({ status: "reconciling", dirty: true, reason: "manifest_reconciliation" });
+        const manifest = await this.#buildManifest();
+        const receipt = await this.#input.authority.reconcile({
+            generation: this.#state.generation,
+            manifestRoot: manifest.manifestRoot,
+            signal,
+        });
+        if (receipt.status === "converged") {
+            if (receipt.generation !== this.#state.generation || receipt.manifestRoot !== manifest.manifestRoot) {
+                throw syncFailure("reconcile_receipt_mismatch", EXIT_CODES.remote);
+            }
+            await this.#replaceState({
+                manifest_root: manifest.manifestRoot,
+                baseline: projectManifest(manifest),
+                dirty: false,
+                status: "converged",
+                reason: null,
+            });
+            return;
+        }
+        if (receipt.generation < this.#state.generation)
+            throw syncFailure("remote_generation_rollback", EXIT_CODES.policy);
+        if (this.#state.pending_local.length > 0 &&
+            receipt.generation === this.#state.generation + 1 &&
+            receipt.manifestRoot === manifest.manifestRoot) {
+            for (const operation of this.#state.pending_local) {
+                await transitionToApplied(this.#journal, operation.operationId);
+            }
+            await this.#replaceState({
+                generation: receipt.generation,
+                manifest_root: receipt.manifestRoot,
+                baseline: projectManifest(manifest),
+                pending_local: [],
+                cursor: null,
+                dirty: false,
+                status: "converged",
+                reason: null,
+            });
+            return;
+        }
+        await this.#replaceState({ status: "reconciling", dirty: true, reason: "canonical_divergence" });
+    }
+    async #recoverPendingLocal() {
+        if (this.#state.pending_local.length === 0)
+            return;
+        const latest = latestJournalStates(this.#journal?.records ?? []);
+        const uncertain = this.#state.pending_local.some((operation) => {
+            const state = latest.get(operation.operationId);
+            return state === "sending" || state === "uncertain" || state === "acknowledged";
+        });
+        if (uncertain) {
+            await this.#transition({ status: "reconciling", dirty: true, reason: "uncertain_local_commit" });
+            this.#reconcileRequested = true;
+            return;
+        }
+        this.#scanRequested = true;
+    }
+    async #buildManifest() {
+        return this.#manifestBuilder({
+            root: this.#input.canonicalRoot,
+            policy: this.#input.policy,
+            capabilities: this.#input.filesystemCapabilities,
+        });
+    }
+    async #transition(input) {
+        await this.#replaceState({
+            status: input.status,
+            ...(input.dirty === undefined ? {} : { dirty: input.dirty }),
+            reason: input.reason,
+        });
+    }
+    async #replaceState(patch) {
+        const next = Object.freeze({
+            ...this.#state,
+            ...patch,
+            schema_version: STATE_SCHEMA,
+            updated_at: new Date(this.#clock()).toISOString(),
+        });
+        this.#state = admitState(next, this.#input);
+        await atomicWriteState(this.#statePath, this.#state);
+        this.#publish();
+    }
+    #publish() {
+        const snapshot = this.snapshot;
+        for (const listener of this.#listeners) {
+            try {
+                listener(snapshot);
+            }
+            catch { /* Projection observers cannot own sync correctness. */ }
+        }
+    }
+    async #waitForWake(milliseconds, signal) {
+        if (this.#scanRequested || this.#reconcileRequested)
+            return;
+        await new Promise((resolveWake, rejectWake) => {
+            let timer;
+            const abort = () => finish(signal.reason);
+            const wake = () => finish();
+            const finish = (error) => {
+                clearTimeout(timer);
+                signal.removeEventListener("abort", abort);
+                if (this.#wake === wake)
+                    this.#wake = undefined;
+                if (error === undefined)
+                    resolveWake();
+                else
+                    rejectWake(error);
+            };
+            timer = setTimeout(finish, milliseconds);
+            this.#wake = wake;
+            signal.addEventListener("abort", abort, { once: true });
+        });
+    }
+}
+function createInitialState(input, manifest) {
+    return Object.freeze({
+        schema_version: 1,
+        binding_id: input.bindingId,
+        binding_generation: input.bindingGeneration,
+        policy_digest: input.policy.digest,
+        sync_id: input.syncId,
+        generation: input.initialGeneration,
+        manifest_root: input.initialManifestRoot,
+        cursor: null,
+        dirty: false,
+        status: "recovering",
+        reason: null,
+        baseline: projectManifest(manifest),
+        pending_local: Object.freeze([]),
+        pending_remote: null,
+        updated_at: new Date(input.clock?.() ?? Date.now()).toISOString(),
+    });
+}
+function projectManifest(manifest) {
+    return Object.freeze(manifest.entries.map((entry) => Object.freeze({
+        path: entry.path,
+        kind: entry.kind,
+        fingerprint: entryFingerprint(entry),
+        byteLength: entry.byteLength,
+    })));
+}
+function diffManifest(baselineEntries, manifest, baseGeneration) {
+    const baseline = new Map(baselineEntries.map((entry) => [entry.path, entry]));
+    const current = new Map(projectManifest(manifest).map((entry) => [entry.path, entry]));
+    const paths = [...new Set([...baseline.keys(), ...current.keys()])].sort((left, right) => Buffer.from(left).compare(Buffer.from(right)));
+    return Object.freeze(paths.flatMap((path) => {
+        const before = baseline.get(path);
+        const after = current.get(path);
+        if (sameProjection(before, after))
+            return [];
+        const kind = before === undefined ? "create" : after === undefined ? "delete" : "update";
+        const fingerprint = after?.fingerprint ?? ZERO_DIGEST;
+        return [Object.freeze({
+                operationId: randomUUID(),
+                path,
+                kind,
+                baseGeneration,
+                fingerprint,
+                byteLength: after?.byteLength ?? 0,
+            })];
+    }));
+}
+function entryFingerprint(entry) {
+    return createHash("sha256").update(JSON.stringify({
+        path: entry.path,
+        kind: entry.kind,
+        byte_length: entry.kind === "symlink" ? 0 : entry.byteLength,
+        executable: entry.executable,
+        chunks: entry.chunks?.map((chunk) => ({ digest: chunk.digest, byte_length: chunk.byteLength })) ?? [],
+        link_target: entry.linkTarget ?? null,
+    })).digest("hex");
+}
+function sameProjection(left, right) {
+    return left === undefined ? right === undefined : right !== undefined && left.fingerprint === right.fingerprint && left.kind === right.kind;
+}
+function orderRemoteItems(items) {
+    const revisions = items.filter((item) => item.operation === "revision");
+    const directoryCreates = items.filter((item) => item.operation === "upsert" && item.entry?.kind === "directory")
+        .sort((left, right) => depth(left.path) - depth(right.path));
+    const upserts = items.filter((item) => item.operation === "upsert" && item.entry?.kind !== "directory");
+    const deletes = items.filter((item) => item.operation === "delete")
+        .sort((left, right) => depth(right.path) - depth(left.path));
+    return Object.freeze([...revisions, ...directoryCreates, ...upserts, ...deletes]);
+}
+function depth(path) {
+    return path?.split("/").length ?? 0;
+}
+function commonRemoteField(items, field) {
+    const first = items[0]?.[field];
+    if (first === undefined || items.some((item) => item[field] !== first)) {
+        throw syncFailure("remote_generation_inconsistent", EXIT_CODES.remote);
+    }
+    return first;
+}
+async function atomicReplaceFile(root, path, chunks, executable, requireMissing = false) {
+    await ensureSafeDirectory(root, dirname(path));
+    await assertSafeAncestors(root, dirname(path));
+    if (requireMissing && await pathExists(path))
+        throw syncFailure("conflict_retention_collision", EXIT_CODES.conflict);
+    await assertReplaceTarget(path);
+    const temporary = join(dirname(path), `.${basename(path)}.cuna-apply-${randomUUID()}.tmp`);
+    const handle = await open(temporary, fileConstants.O_CREAT | fileConstants.O_EXCL | fileConstants.O_WRONLY | noFollowFlag(), 0o600);
+    try {
+        for (const bytes of chunks)
+            await handle.write(bytes);
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    await handle.close();
+    try {
+        await chmod(temporary, executable ? 0o700 : 0o600);
+        await assertSafeAncestors(root, dirname(path));
+        await assertReplaceTarget(path);
+        await rename(temporary, path);
+        await syncDirectory(dirname(path));
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+async function safeDelete(root, path) {
+    await assertSafeAncestors(root, dirname(path));
+    try {
+        const metadata = await lstat(path);
+        if (metadata.isSymbolicLink() || (!metadata.isFile() && !metadata.isDirectory()) || (metadata.isFile() && metadata.nlink !== 1)) {
+            throw syncFailure("delete_target_untrusted", EXIT_CODES.policy);
+        }
+        if (metadata.isDirectory())
+            await rmdir(path);
+        else
+            await unlink(path);
+        await syncDirectory(dirname(path));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function ensureSafeDirectory(root, requested) {
+    const target = assertLexicallyInsideRoot(root, requested);
+    const difference = relative(root, target);
+    let current = root;
+    for (const component of difference.split(sep).filter(Boolean)) {
+        current = join(current, component);
+        try {
+            const metadata = await lstat(current);
+            if (!metadata.isDirectory() || metadata.isSymbolicLink())
+                throw syncFailure("ancestor_untrusted", EXIT_CODES.policy);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await mkdir(current, { mode: 0o700 });
+            const metadata = await lstat(current);
+            if (!metadata.isDirectory() || metadata.isSymbolicLink())
+                throw syncFailure("ancestor_untrusted", EXIT_CODES.policy);
+        }
+    }
+    await assertSafeAncestors(root, target);
+}
+async function assertSafeAncestors(root, directory) {
+    const target = assertLexicallyInsideRoot(root, directory);
+    const canonical = await realpath(target);
+    const difference = relative(root, canonical);
+    if (difference === ".." || difference.startsWith(`..${sep}`) || isAbsolute(difference)) {
+        throw syncFailure("ancestor_escape", EXIT_CODES.policy);
+    }
+    let current = root;
+    for (const component of relative(root, target).split(sep).filter(Boolean)) {
+        current = join(current, component);
+        const metadata = await lstat(current);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink())
+            throw syncFailure("ancestor_untrusted", EXIT_CODES.policy);
+    }
+}
+async function assertReplaceTarget(path) {
+    try {
+        const metadata = await lstat(path);
+        if (metadata.isSymbolicLink() || !metadata.isFile() || metadata.nlink !== 1) {
+            throw syncFailure("replace_target_untrusted", EXIT_CODES.policy);
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+async function syncDirectory(directory) {
+    try {
+        const handle = await open(directory, fileConstants.O_RDONLY);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (process.platform !== "win32")
+            throw error;
+    }
+}
+async function canonicalPlainDirectory(path) {
+    if (!isAbsolute(path) || path.includes("\0"))
+        throw syncFailure("root_untrusted", EXIT_CODES.policy);
+    const canonical = await realpath(path);
+    const metadata = await lstat(canonical);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw syncFailure("root_untrusted", EXIT_CODES.policy);
+    return canonical;
+}
+async function preparePrivateDirectory(path, workspaceRoot) {
+    if (!isAbsolute(path) || path.includes("\0"))
+        throw syncFailure("state_directory_untrusted", EXIT_CODES.policy);
+    const requested = resolve(path);
+    if (isSameOrInside(workspaceRoot, requested))
+        throw syncFailure("state_inside_workspace", EXIT_CODES.policy);
+    await mkdir(requested, { recursive: true, mode: 0o700 });
+    const canonical = await realpath(requested);
+    const metadata = await lstat(canonical);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink() || isSameOrInside(workspaceRoot, canonical)) {
+        throw syncFailure("state_directory_untrusted", EXIT_CODES.policy);
+    }
+    await chmod(canonical, 0o700).catch((error) => {
+        if (process.platform !== "win32")
+            throw error;
+    });
+    return canonical;
+}
+async function loadState(path) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1 || metadata.size > 64 * 1024 * 1024) {
+            throw syncFailure("state_file_untrusted", EXIT_CODES.policy);
+        }
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function atomicWriteState(path, state) {
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(state)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        // Windows rejects FlushFileBuffers on a read-only handle. Open the private
+        // temporary read/write solely for durability; no bytes are changed here.
+        const handle = await open(temporary, fileConstants.O_RDWR | noFollowFlag());
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, path);
+        await chmod(path, 0o600).catch((error) => { if (process.platform !== "win32")
+            throw error; });
+        await syncDirectory(dirname(path));
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+function admitState(value, input) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw syncFailure("state_invalid", EXIT_CODES.conflict);
+    const source = value;
+    const keys = [
+        "baseline", "binding_generation", "binding_id", "cursor", "dirty", "generation",
+        "manifest_root", "pending_local", "pending_remote", "policy_digest", "reason",
+        "schema_version", "status", "sync_id", "updated_at",
+    ];
+    if (Object.keys(source).sort().join("\0") !== keys.sort().join("\0") || source.schema_version !== STATE_SCHEMA) {
+        throw syncFailure("state_schema_incompatible", EXIT_CODES.conflict);
+    }
+    if (source.binding_id !== input.bindingId ||
+        source.binding_generation !== input.bindingGeneration ||
+        source.policy_digest !== input.policy.digest)
+        throw syncFailure("state_identity_mismatch", EXIT_CODES.policy);
+    const statusValues = new Set(["recovering", "reconciling", "catching_up", "live_unverified", "converged", "conflicted", "paused", "recovery_required", "unknown"]);
+    if (!isUuid(source.sync_id) ||
+        !Number.isSafeInteger(source.generation) || source.generation < 0 ||
+        !isDigest(source.manifest_root) ||
+        (source.cursor !== null && (typeof source.cursor !== "string" || source.cursor.length < 1 || source.cursor.length > 1_024)) ||
+        typeof source.dirty !== "boolean" ||
+        typeof source.status !== "string" || !statusValues.has(source.status) ||
+        (source.reason !== null && (typeof source.reason !== "string" || source.reason.length < 1 || source.reason.length > 128)) ||
+        typeof source.updated_at !== "string" || !Number.isFinite(Date.parse(source.updated_at)) ||
+        !Array.isArray(source.baseline) || !Array.isArray(source.pending_local))
+        throw syncFailure("state_invalid", EXIT_CODES.conflict);
+    const baseline = Object.freeze(source.baseline.map(decodeEntryProjection));
+    const pendingLocal = Object.freeze(source.pending_local.map(decodePendingLocal));
+    const pendingRemote = source.pending_remote === null ? null : decodePendingRemote(source.pending_remote);
+    return Object.freeze({
+        schema_version: 1,
+        binding_id: input.bindingId,
+        binding_generation: input.bindingGeneration,
+        policy_digest: input.policy.digest,
+        sync_id: source.sync_id,
+        generation: source.generation,
+        manifest_root: source.manifest_root,
+        cursor: source.cursor,
+        dirty: source.dirty,
+        status: source.status,
+        reason: source.reason,
+        baseline,
+        pending_local: pendingLocal,
+        pending_remote: pendingRemote,
+        updated_at: source.updated_at,
+    });
+}
+function decodeEntryProjection(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw syncFailure("state_invalid", EXIT_CODES.conflict);
+    const source = value;
+    if (Object.keys(source).sort().join("\0") !== ["byteLength", "fingerprint", "kind", "path"].join("\0") ||
+        typeof source.path !== "string" || !isDigest(source.fingerprint) ||
+        !["directory", "file", "symlink"].includes(source.kind) ||
+        !Number.isSafeInteger(source.byteLength) || source.byteLength < 0)
+        throw syncFailure("state_invalid", EXIT_CODES.conflict);
+    return Object.freeze(source);
+}
+function decodePendingLocal(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw syncFailure("state_invalid", EXIT_CODES.conflict);
+    const source = value;
+    const expected = ["baseGeneration", "byteLength", "fingerprint", "kind", "operationId", "path"];
+    if (Object.keys(source).sort().join("\0") !== expected.join("\0") || !isUuid(source.operationId) ||
+        typeof source.path !== "string" || !["create", "update", "delete"].includes(source.kind) ||
+        !Number.isSafeInteger(source.baseGeneration) || source.baseGeneration < 0 ||
+        !Number.isSafeInteger(source.byteLength) || source.byteLength < 0 || !isDigest(source.fingerprint))
+        throw syncFailure("state_invalid", EXIT_CODES.conflict);
+    return Object.freeze(source);
+}
+function decodePendingRemote(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw syncFailure("state_invalid", EXIT_CODES.conflict);
+    const source = value;
+    const expected = ["cursor", "generation", "items", "manifestRoot", "nextIndex"];
+    if (Object.keys(source).sort().join("\0") !== expected.join("\0") ||
+        !Number.isSafeInteger(source.generation) || source.generation < 1 || !isDigest(source.manifestRoot) ||
+        (source.cursor !== null && (typeof source.cursor !== "string" || source.cursor.length < 1 || source.cursor.length > 1_024)) ||
+        !Array.isArray(source.items) || !Number.isSafeInteger(source.nextIndex) || source.nextIndex < 0 ||
+        source.nextIndex > source.items.length)
+        throw syncFailure("state_invalid", EXIT_CODES.conflict);
+    const decodedItems = decodeChangePage({
+        selected_protocol: 1,
+        items: source.items,
+        next_cursor: null,
+    }).items;
+    return Object.freeze({
+        generation: source.generation,
+        manifestRoot: source.manifestRoot,
+        cursor: source.cursor,
+        items: decodedItems,
+        nextIndex: source.nextIndex,
+    });
+}
+async function createNodeWorkspaceWatcher(input) {
+    let watcher;
+    try {
+        watcher = watch(input.root, { recursive: true, persistent: false }, (_event, filename) => {
+            if (filename === null)
+                input.onEvent({ kind: "overflow" });
+            else
+                input.onEvent({ kind: "change", path: filename.toString() });
+        });
+    }
+    catch (error) {
+        throw syncFailure("watcher_unavailable", EXIT_CODES.unsupported, error);
+    }
+    watcher.on("error", input.onError);
+    return Object.freeze({ close: () => watcher.close() });
+}
+function validateInput(input) {
+    if (!isUuid(input.bindingId) || !isUuid(input.syncId) ||
+        !Number.isSafeInteger(input.bindingGeneration) || input.bindingGeneration < 1 ||
+        !Number.isSafeInteger(input.initialGeneration) || input.initialGeneration < 1 ||
+        !isDigest(input.initialManifestRoot) || !isDigest(input.policy.digest))
+        throw syncFailure("input_invalid", EXIT_CODES.usage);
+    for (const value of [
+        input.debounceMs ?? DEFAULT_DEBOUNCE_MS,
+        input.reconciliationIntervalMs ?? DEFAULT_RECONCILE_MS,
+        input.remotePollIntervalMs ?? DEFAULT_REMOTE_POLL_MS,
+        input.maximumPendingOperations ?? DEFAULT_OPERATION_LIMIT,
+        input.maximumPendingBytes ?? DEFAULT_BYTE_LIMIT,
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw syncFailure("limit_invalid", EXIT_CODES.usage);
+    }
+}
+function latestJournalStates(records) {
+    const result = new Map();
+    for (const record of records)
+        result.set(record.operationId, record.state);
+    return result;
+}
+function samePendingIntent(durable, observed) {
+    if (durable.length !== observed.length)
+        return false;
+    return durable.every((operation, index) => {
+        const candidate = observed[index];
+        return candidate !== undefined &&
+            operation.path === candidate.path &&
+            operation.kind === candidate.kind &&
+            operation.baseGeneration === candidate.baseGeneration &&
+            operation.fingerprint === candidate.fingerprint &&
+            operation.byteLength === candidate.byteLength;
+    });
+}
+async function transitionIfQueued(journal, operationId) {
+    const latest = [...(journal?.records ?? [])].reverse().find((record) => record.operationId === operationId);
+    if (latest?.state === "queued")
+        await journal?.transition(operationId, "sending");
+    else if (latest?.state !== "sending" && latest?.state !== "uncertain") {
+        throw syncFailure("journal_operation_state_invalid", EXIT_CODES.conflict);
+    }
+}
+async function transitionToApplied(journal, operationId) {
+    let latest = [...(journal?.records ?? [])].reverse().find((record) => record.operationId === operationId)?.state;
+    if (latest === "queued") {
+        await journal?.transition(operationId, "sending");
+        latest = "sending";
+    }
+    if (latest === "sending") {
+        await journal?.transition(operationId, "uncertain");
+        latest = "uncertain";
+    }
+    if (latest === "uncertain") {
+        await journal?.transition(operationId, "acknowledged");
+        latest = "acknowledged";
+    }
+    if (latest === "acknowledged")
+        await journal?.transition(operationId, "applied");
+}
+async function transitionIfPossible(journal, operationId, state) {
+    try {
+        await journal?.transition(operationId, state);
+    }
+    catch { /* preserve the original ambiguous failure */ }
+}
+function classifyFailure(error) {
+    if (error instanceof CunaError) {
+        const reason = typeof error.details?.reason === "string" ? error.details.reason : error.code;
+        if (error.code === "cuna.workspace_sync.contract_mismatch" ||
+            error.code === "cuna.workspace.path_invalid" ||
+            error.code === "cuna.workspace.path_escape")
+            return { status: "recovery_required", reason };
+        if (error.exitCode === EXIT_CODES.conflict)
+            return { status: "conflicted", reason };
+        if (error.exitCode === EXIT_CODES.policy || error.exitCode === EXIT_CODES.usage || error.exitCode === EXIT_CODES.unsupported) {
+            return { status: "recovery_required", reason };
+        }
+        return { status: "paused", reason };
+    }
+    const code = error.code;
+    if (code === "ENOSPC" || code === "EDQUOT")
+        return { status: "paused", reason: "disk_exhausted" };
+    return { status: "paused", reason: "dependency_unavailable" };
+}
+function isAbort(error) {
+    return error instanceof CunaError && error.details?.reason === "cancelled";
+}
+function isSameOrInside(root, candidate) {
+    const difference = relative(resolve(root), resolve(candidate));
+    return difference === "" || (!difference.startsWith(`..${sep}`) && difference !== ".." && !isAbsolute(difference));
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function noFollowFlag() {
+    return typeof fileConstants.O_NOFOLLOW === "number" ? fileConstants.O_NOFOLLOW : 0;
+}
+function isUuid(value) {
+    return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value);
+}
+function isDigest(value) {
+    return typeof value === "string" && /^[0-9a-f]{64}$/u.test(value);
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function syncFailure(reason, exitCode, cause) {
+    return new CunaError({
+        code: "cuna.workspace_sync.continuous_failed",
+        message: "Continuous workspace synchronization could not preserve its safety contract.",
+        exitCode: exitCode,
+        details: { reason },
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+async function abortableSleep(milliseconds, signal) {
+    if (signal.aborted)
+        throw signal.reason;
+    await new Promise((resolveSleep, rejectSleep) => {
+        let timer;
+        const abort = () => finish(signal.reason);
+        const finish = (error) => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", abort);
+            if (error === undefined)
+                resolveSleep();
+            else
+                rejectSleep(error);
+        };
+        timer = setTimeout(finish, milliseconds);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
+//# sourceMappingURL=continuous-sync-supervisor.js.map