@ai-agent-forge/agent-forge 0.85.0

package/dist/durable/durable-service.js

@@ -0,0 +1,710 @@
+/**
+ * Durable service MVP (7.4b) — in-memory persistence for session, operation,
+ * and artifact records with a single-writer lease, crash recovery, and a
+ * readiness gate.
+ *
+ * Scope: this is the durable *contract* slice. Storage is an in-memory Map;
+ * `exportState`/`importState` are the snapshot restart boundary, and a
+ * {@link DurableStoreBackend} is the log restart boundary: when one is passed
+ * to {@link createDurableService}, every committed record is appended to the
+ * backend log (write-ahead) and the log is replayed at construction to
+ * restore state. Without a backend the service stays purely in-memory — the
+ * original MVP behavior. {@link createFileDurableStoreBackend} is the JSONL
+ * append-only file backend (ledger.ts pattern). Rules frozen here:
+ * - Writes require the writer lease: `persist*` with any writerId other than
+ *   the current holder fails with `not_writer` — before the first claim,
+ *   while another writer holds the lease, and after a crash (until
+ *   `recoverWriter` takes it over).
+ * - A writer recorded in an imported snapshot belonged to the process that
+ *   produced the snapshot and cannot be alive in this one: import enters a
+ *   crash-pending state where the lease stays held by the dead writer, reads
+ *   still work, and only `recoverWriter` can take the lease over. Readiness
+ *   stays `false` until it does.
+ * - File writes through {@link createFileDurableStoreBackend} are
+ *   cross-process mutually exclusive: every persist serializes through a
+ *   `.lock` sibling file (same protocol as the memory ledger — exclusive
+ *   create, poll, stale-lock stealing, token-guarded release; wall-clock
+ *   timeout and staleness configurable, defaults 5 s / 60 s). The lock
+ *   guarantees concurrent appends do not interleave.
+ * - Store-level writer lease (D-067 phase 2 S2): backends may expose an
+ *   optional {@link DurableStoreLeaseV1} — a TTL-based, cross-process
+ *   mutually-exclusive lease over the store. The file backend implements it
+ *   with a `.lease` sibling file (write heartbeat on every persist); the
+ *   service's claim/recover/release then resolve against the store, so a
+ *   second process observes a live foreign writer (`held`) and a crashed
+ *   writer's lease becomes recoverable once its TTL lapses. Without a
+ *   backend lease the writer lease stays process-local memory (unchanged).
+ */
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { sleepSync } from "../utils/sync-sleep.js";
+export class DurableServiceErrorV1 extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "DurableServiceErrorV1";
+        this.code = code;
+    }
+}
+/** The standard durable log path: `<agentDir>/durable/<sessionId>.jsonl`. */
+export function durableLogPath(agentDir, sessionId) {
+    return join(agentDir, "durable", `${sessionId}.jsonl`);
+}
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`${label} must be a non-empty string`);
+}
+/**
+ * Writes every byte of `data` to the fd, looping over partial `writeSync`
+ * results (a short write would silently break the fsync durability promise:
+ * the caller fsyncs and closes only after the full payload is handed to the
+ * OS). Same pattern as the memory ledger's write path, implemented here with
+ * plain node:fs primitives so the file backend needs no ledger dependency.
+ */
+const writeAllSync = (fd, data) => {
+    const buffer = Buffer.from(data, "utf8");
+    let written = 0;
+    while (written < buffer.length) {
+        written += writeSync(fd, buffer, written, buffer.length - written);
+    }
+};
+// ---------------------------------------------------------------------------
+// Cross-process persist lock (ledger.ts lock protocol, no ledger import —
+// the two implementations must stay behaviorally identical)
+// ---------------------------------------------------------------------------
+/** Suffix of the persistence lock sibling file (`<logPath>.lock`). */
+const LOCK_FILE_SUFFIX = ".lock";
+/** Suffix of the store-level writer lease sibling file (`<logPath>.lease`). */
+const LEASE_FILE_SUFFIX = ".lease";
+/**
+ * Wall-clock wait between lock acquisition attempts. Kept as a per-file
+ * constant even though the memory ledger currently uses the same 25 ms value:
+ * the two lock protocols stay independent.
+ */
+const LOCK_POLL_INTERVAL_MS = 25;
+/** Default ceiling on waiting for a competing writer's lock. */
+const DEFAULT_LOCK_TIMEOUT_MS = 5000;
+/**
+ * Default age at which a lock counts as abandoned (its writer crashed while
+ * holding it). Deliberately far above any live hold time (milliseconds of a
+ * bounded append) and above the wait timeout, so a waiter fails loudly at the
+ * timeout instead of stealing a lock that might still be held.
+ */
+const DEFAULT_STALE_LOCK_MS = 60_000;
+/**
+ * Default writer-lease TTL. The holder renews on every persist (heartbeat);
+ * an idle-but-alive process that never persists loses the lease after this
+ * window and must `recoverWriter` before writing again. Deliberately far
+ * above any test-relevant hold so production never sees surprise expiries
+ * within a single persist burst; tests pass small values explicitly.
+ */
+const DEFAULT_LEASE_TTL_MS = 30_000;
+/**
+ * Takes the cross-process persist lock shared by every durable store file
+ * write: exclusive create (`wx`) is the mutex; an existing lock is polled
+ * until released, stolen once its mtime exceeds `staleLockMs` (crashed
+ * writer), or turned into a thrown error at the wait deadline. The lock file
+ * carries a per-acquisition token so a stale-steal victim releasing late can
+ * never delete the thief's fresh lock. Same protocol as the memory ledger's
+ * append lock (now the memory plugin package's ledger, plugins/memory), reimplemented here to avoid module
+ * coupling; the wall-clock lock is a real-time mechanism, deliberately not
+ * driven by any injected deterministic `now`.
+ */
+function acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs) {
+    const deadline = Date.now() + lockTimeoutMs;
+    for (;;) {
+        mkdirSync(dirname(lockPath), { recursive: true });
+        const token = `${process.pid}:${Date.now()}`;
+        try {
+            const fd = openSync(lockPath, "wx");
+            try {
+                writeFileSync(fd, token);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return token;
+        }
+        catch (error) {
+            // POSIX maps a lost create race to EEXIST; Windows/libuv maps the
+            // same concurrent-create sharing violation to EPERM. Both mean the
+            // lock file existed when we tried to create it — contend (poll /
+            // stale-steal below). For EPERM the existence check re-stats: a
+            // lock still there is contention, while ENOENT means the holder
+            // released and deleted it between the failed open and this stat
+            // (or Windows briefly left a delete-pending name that has now
+            // gone) — the same vanished-lock window the EEXIST path tolerates,
+            // so retry too. A stat error other than ENOENT means the EPERM was
+            // a genuine permission failure and propagates, and the vanish path
+            // still rethrows the original EPERM at the wait deadline: a
+            // persistent EPERM with no lock file ever appearing is a genuine
+            // permission failure, not a held lock.
+            const code = error.code;
+            if (code === "EPERM") {
+                let vanished = false;
+                try {
+                    statSync(lockPath);
+                }
+                catch (statError) {
+                    if (statError.code !== "ENOENT")
+                        throw error;
+                    vanished = true;
+                }
+                if (vanished) {
+                    if (Date.now() >= deadline)
+                        throw error;
+                    sleepSync(LOCK_POLL_INTERVAL_MS);
+                    continue;
+                }
+            }
+            else if (code !== "EEXIST") {
+                throw error;
+            }
+            let stale = false;
+            try {
+                stale = Date.now() - statSync(lockPath).mtimeMs > staleLockMs;
+            }
+            catch {
+                // The holder released the lock between the failed open and the
+                // stat — retry the exclusive create immediately.
+            }
+            if (stale) {
+                // A crashed writer left the lock behind: steal it. A competing
+                // waiter may steal first — the next exclusive create resolves that.
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    // Already stolen — retry.
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`durable store persist lock timeout after ${lockTimeoutMs} ms: ${lockPath} is held by another writer`);
+            }
+            sleepSync(LOCK_POLL_INTERVAL_MS);
+        }
+    }
+}
+/** Releases the persist lock, but only if our own token still owns it. */
+function releasePersistLock(lockPath, token) {
+    try {
+        if (readFileSync(lockPath, "utf8") === token)
+            unlinkSync(lockPath);
+    }
+    catch {
+        // The lock is already gone (or unreadable) — nothing to release.
+    }
+}
+/**
+ * Creates a JSONL append-only file backend at `path`
+ * (ledger.ts pattern: one committed record per line, trailing newline so a
+ * crash-truncated tail stays well-formed for the loader). Every persist
+ * serializes against other processes through a `<path>.lock` sibling using
+ * the memory ledger's lock protocol (exclusive create + 25 ms poll + mtime
+ * stale-lock stealing + token-guarded release): `lockTimeoutMs` bounds the
+ * wall-clock wait (default 5 s) and `staleLockMs` the abandoned-lock age
+ * (default 60 s) — both exist so tests can exercise the timeout and steal
+ * paths quickly. The lock makes concurrent appends non-interleaving.
+ *
+ * The backend also exposes the store-level writer lease (`<path>.lease`
+ * sibling, D-067 phase 2 S2): a `{ writerId, expiresAt }` JSON file guarded
+ * by the same lock protocol, with a TTL the holder renews on every persist
+ * (`leaseTtlMs`, default 30 s — small values exist for tests). A crashed
+ * writer's lease becomes recoverable once its TTL lapses; a live foreign
+ * holder makes `claim`/`recover` report `held` and the holder's next `renew`
+ * (i.e. its next persist) fail closed with `not_writer`.
+ */
+export function createFileDurableStoreBackend(options) {
+    assertNonEmptyString(options.path, "Durable store path");
+    if (options.lockTimeoutMs !== undefined && (!Number.isFinite(options.lockTimeoutMs) || options.lockTimeoutMs <= 0)) {
+        throw new Error("Durable store lockTimeoutMs must be a positive number");
+    }
+    if (options.staleLockMs !== undefined && (!Number.isFinite(options.staleLockMs) || options.staleLockMs <= 0)) {
+        throw new Error("Durable store staleLockMs must be a positive number");
+    }
+    if (options.leaseTtlMs !== undefined && (!Number.isFinite(options.leaseTtlMs) || options.leaseTtlMs <= 0)) {
+        throw new Error("Durable store leaseTtlMs must be a positive number");
+    }
+    const path = options.path;
+    const lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+    const staleLockMs = options.staleLockMs ?? DEFAULT_STALE_LOCK_MS;
+    const leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+    const lockPath = `${path}${LOCK_FILE_SUFFIX}`;
+    const leasePath = `${path}${LEASE_FILE_SUFFIX}`;
+    /** Reads the lease file; missing, unreadable, or malformed content = no lease. */
+    const readLease = () => {
+        try {
+            const value = JSON.parse(readFileSync(leasePath, "utf8"));
+            if (typeof value !== "object" || value === null || Array.isArray(value))
+                return undefined;
+            const writerId = value.writerId;
+            const expiresAt = value.expiresAt;
+            if (typeof writerId !== "string" || writerId.length === 0)
+                return undefined;
+            if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt))
+                return undefined;
+            return { writerId, expiresAt };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /**
+     * Overwrites the lease file (caller holds the persist lock). Deliberately
+     * NOT fsynced: the lease is a liveness token, not data — the worst case of
+     * a torn post-crash write is a free lease, which the recover path handles.
+     */
+    const writeLease = (writerId, expiresAt) => {
+        const fd = openSync(leasePath, "w");
+        try {
+            writeAllSync(fd, JSON.stringify({ writerId, expiresAt }));
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    /** True when `current` names a different writer whose TTL has not lapsed. */
+    const liveForeign = (current, writerId) => current.writerId !== writerId && Date.now() <= current.expiresAt;
+    const lease = {
+        claim(writerId) {
+            const token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);
+            try {
+                const current = readLease();
+                if (current !== undefined && liveForeign(current, writerId))
+                    return { status: "held", by: current.writerId };
+                writeLease(writerId, Date.now() + leaseTtlMs);
+                return { status: "claimed" };
+            }
+            finally {
+                releasePersistLock(lockPath, token);
+            }
+        },
+        release(writerId) {
+            const token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);
+            try {
+                const current = readLease();
+                if (current === undefined || current.writerId === writerId) {
+                    try {
+                        unlinkSync(leasePath);
+                    }
+                    catch {
+                        // Already gone (or vanished between the read and the unlink).
+                    }
+                    return { status: "released" };
+                }
+                throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} does not hold the store lease (held by ${current.writerId})`);
+            }
+            finally {
+                releasePersistLock(lockPath, token);
+            }
+        },
+        recover(writerId) {
+            const token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);
+            try {
+                const current = readLease();
+                if (current !== undefined && liveForeign(current, writerId))
+                    return { status: "held" };
+                const previousWriter = current !== undefined && current.writerId !== writerId ? current.writerId : undefined;
+                writeLease(writerId, Date.now() + leaseTtlMs);
+                return previousWriter === undefined ? { status: "recovered" } : { status: "recovered", previousWriter };
+            }
+            finally {
+                releasePersistLock(lockPath, token);
+            }
+        },
+        renew(writerId) {
+            const token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);
+            try {
+                const current = readLease();
+                if (current === undefined || current.writerId !== writerId || Date.now() > current.expiresAt) {
+                    throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} lost the store lease (expired or recovered by another writer)`);
+                }
+                writeLease(writerId, Date.now() + leaseTtlMs);
+            }
+            finally {
+                releasePersistLock(lockPath, token);
+            }
+        },
+    };
+    return {
+        persist(operations) {
+            if (operations.length === 0)
+                return;
+            const lines = operations.map((operation) => `${JSON.stringify(storeOperationEnvelope(operation))}\n`);
+            // Competing writers — including another server process — serialize
+            // through the `.lock` sibling before the fsynced append, so lines from
+            // concurrent processes never interleave (ledger.ts lock protocol).
+            // Lock acquisition creates the parent directory, as in the ledger.
+            const token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);
+            try {
+                // Append is fsynced before close: once persist returns, a hard
+                // crash cannot lose the appended lines (open → write → fsync →
+                // close, the same durability pattern as the memory ledger). A
+                // failure inside the lock releases it and propagates; no
+                // in-memory state of the service is touched (write-ahead).
+                const fd = openSync(path, "a");
+                try {
+                    writeAllSync(fd, lines.join(""));
+                    fsyncSync(fd);
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+            finally {
+                releasePersistLock(lockPath, token);
+            }
+        },
+        load() {
+            let raw;
+            try {
+                raw = readFileSync(path, "utf8");
+            }
+            catch (error) {
+                if (error.code === "ENOENT") {
+                    return { operations: [], corruptedLines: 0, unreadable: false };
+                }
+                return { operations: [], corruptedLines: 0, unreadable: true };
+            }
+            const operations = [];
+            let corruptedLines = 0;
+            for (const line of raw.split("\n")) {
+                if (line.trim() === "")
+                    continue;
+                const operation = parseStoreOperationLine(line);
+                if (operation === undefined) {
+                    corruptedLines += 1;
+                    continue;
+                }
+                operations.push(operation);
+            }
+            return { operations, corruptedLines, unreadable: false };
+        },
+        close() {
+            // Files are opened per append; nothing persistent to release. The
+            // hook exists for backends that hold resources (handles, sockets).
+        },
+        lease,
+    };
+}
+/** Flat one-line envelope: the kind discriminator plus the record fields. */
+function storeOperationEnvelope(operation) {
+    return { kind: operation.kind, ...operation.record };
+}
+/** Parses one log line; undefined when it is malformed (skipped and counted). */
+function parseStoreOperationLine(line) {
+    try {
+        const value = JSON.parse(line);
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return undefined;
+        const record = value;
+        switch (record.kind) {
+            case "session": {
+                const base = importRecordBase(record, "sessionId", "Durable store session record");
+                return {
+                    kind: "session",
+                    record: { sessionId: base.id, data: base.data, persistedAt: base.persistedAt },
+                };
+            }
+            case "operation": {
+                const base = importRecordBase(record, "operationId", "Durable store operation record");
+                return {
+                    kind: "operation",
+                    record: {
+                        operationId: base.id,
+                        sessionId: importOwningSessionId(record, "Durable store operation record"),
+                        data: base.data,
+                        persistedAt: base.persistedAt,
+                    },
+                };
+            }
+            case "artifact": {
+                const base = importRecordBase(record, "artifactId", "Durable store artifact record");
+                return {
+                    kind: "artifact",
+                    record: {
+                        artifactId: base.id,
+                        sessionId: importOwningSessionId(record, "Durable store artifact record"),
+                        data: base.data,
+                        persistedAt: base.persistedAt,
+                    },
+                };
+            }
+            default:
+                return undefined;
+        }
+    }
+    catch {
+        // Corruption tolerance: a malformed line is skipped and counted — a
+        // damaged log must never fail the startup replay.
+        return undefined;
+    }
+}
+function assertObject(value, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+}
+function importRecordBase(value, idField, label) {
+    const id = value[idField];
+    if (typeof id !== "string" || id.length === 0)
+        throw new Error(`${label} ${idField} must be a non-empty string`);
+    const persistedAt = value.persistedAt;
+    if (typeof persistedAt !== "number" || !Number.isFinite(persistedAt)) {
+        throw new Error(`${label} persistedAt must be a finite number`);
+    }
+    // Legacy (pre-单机收敛) log lines and snapshots may carry a `tenantId` key
+    // from the removed multi-tenant machinery; it is tolerated as an ignored
+    // extra key (D-068 增补 1), so it is simply never read here.
+    return { id, data: value.data, persistedAt };
+}
+function importOwningSessionId(value, label) {
+    const sessionId = value.sessionId;
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        throw new Error(`${label} sessionId must be a non-empty string`);
+    }
+    return sessionId;
+}
+export function createDurableService(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const sessions = new Map();
+    const operations = new Map();
+    const artifacts = new Map();
+    /** Current lease holder; `null` when unclaimed or crash-pending. */
+    let holder = null;
+    /** Writer found dead in a restored snapshot; blocks claims and writes until recovered. */
+    let crashPending = null;
+    // Startup replay (durable 落盘): with a backend, the log is the source of
+    // truth for records — replay restores the maps with last-write-wins, the
+    // same semantics as live persists. With a backend lease (D-067 phase 2
+    // S2) the writer lease resolves against the store (cross-process mutual
+    // exclusion, TTL crash recovery); without one it stays process-local.
+    const backend = options.backend;
+    const backendLease = backend?.lease;
+    let replay = { corruptedLines: 0, unreadable: false };
+    if (backend) {
+        const loaded = backend.load();
+        for (const operation of loaded.operations) {
+            switch (operation.kind) {
+                case "session":
+                    sessions.set(operation.record.sessionId, operation.record);
+                    break;
+                case "operation":
+                    operations.set(operation.record.operationId, operation.record);
+                    break;
+                case "artifact":
+                    artifacts.set(operation.record.artifactId, operation.record);
+                    break;
+            }
+        }
+        replay = { corruptedLines: loaded.corruptedLines, unreadable: loaded.unreadable };
+    }
+    /** Write-ahead log append; an append failure leaves the maps untouched. */
+    const logOperation = (operation) => {
+        if (backend)
+            backend.persist([operation]);
+    };
+    function requireWriter(writerId) {
+        if (holder !== writerId) {
+            throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} does not hold the writer lease`);
+        }
+        // Store-level heartbeat + liveness check (D-067 phase 2 S2): another
+        // process recovering our expired lease fail-closes this write instead
+        // of letting a stale writer interleave records.
+        backendLease?.renew(writerId);
+    }
+    return {
+        persistSession(input) {
+            requireWriter(input.writerId);
+            const record = {
+                sessionId: input.sessionId,
+                data: input.data,
+                persistedAt: now(),
+            };
+            logOperation({ kind: "session", record });
+            sessions.set(input.sessionId, record);
+            return record;
+        },
+        loadSession(input) {
+            return sessions.get(input.sessionId);
+        },
+        persistOperation(input) {
+            requireWriter(input.writerId);
+            const record = {
+                operationId: input.operationId,
+                sessionId: input.sessionId,
+                data: input.data,
+                persistedAt: now(),
+            };
+            logOperation({ kind: "operation", record });
+            operations.set(input.operationId, record);
+            return record;
+        },
+        loadOperation(input) {
+            return operations.get(input.operationId);
+        },
+        persistArtifact(input) {
+            requireWriter(input.writerId);
+            const record = {
+                artifactId: input.artifactId,
+                sessionId: input.sessionId,
+                data: input.data,
+                persistedAt: now(),
+            };
+            logOperation({ kind: "artifact", record });
+            artifacts.set(input.artifactId, record);
+            return record;
+        },
+        loadArtifact(input) {
+            return artifacts.get(input.artifactId);
+        },
+        listSessions() {
+            return ([...sessions.values()]
+                // v8 ignore next -- sessionId 是 Map 键恒唯一，相等比较路径不可达
+                .sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0)));
+        },
+        claimWriter(writerId) {
+            if (crashPending !== null)
+                return { status: "held", by: crashPending };
+            if (backendLease === undefined) {
+                if (holder !== null && holder !== writerId)
+                    return { status: "held", by: holder };
+                holder = writerId;
+                return { status: "claimed" };
+            }
+            const result = backendLease.claim(writerId);
+            if (result.status === "claimed") {
+                holder = writerId;
+                return { status: "claimed" };
+            }
+            return { status: "held", by: result.by };
+        },
+        releaseWriter(writerId) {
+            if (crashPending !== null) {
+                throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} cannot release a crashed lease; recover it instead`);
+            }
+            if (backendLease === undefined) {
+                if (holder !== null && holder !== writerId) {
+                    throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} does not hold the writer lease (held by ${holder})`);
+                }
+                holder = null;
+                return { status: "released" };
+            }
+            const result = backendLease.release(writerId);
+            holder = null;
+            return result;
+        },
+        recoverWriter(writerId) {
+            if (crashPending !== null) {
+                const previousWriter = crashPending;
+                crashPending = null;
+                holder = writerId;
+                return { status: "recovered", previousWriter };
+            }
+            if (backendLease === undefined) {
+                if (holder !== null && holder !== writerId)
+                    return { status: "held" };
+                holder = writerId;
+                return { status: "recovered" };
+            }
+            const result = backendLease.recover(writerId);
+            if (result.status === "recovered") {
+                holder = writerId;
+                return result.previousWriter === undefined
+                    ? { status: "recovered" }
+                    : { status: "recovered", previousWriter: result.previousWriter };
+            }
+            return { status: "held" };
+        },
+        readiness() {
+            if (crashPending !== null) {
+                return { ready: false, reason: `writer crash is pending recovery: ${crashPending}` };
+            }
+            if (holder === null) {
+                return { ready: false, reason: "no writer has claimed the lease" };
+            }
+            return { ready: true };
+        },
+        exportState() {
+            return {
+                version: 1,
+                exportedAt: now(),
+                sessions: [...sessions.values()],
+                operations: [...operations.values()],
+                artifacts: [...artifacts.values()],
+                writer: { holder, crashPending },
+            };
+        },
+        importState(snapshot) {
+            assertObject(snapshot, "Durable snapshot");
+            if (snapshot.version !== 1) {
+                throw new Error(`Unsupported durable snapshot version: ${String(snapshot.version)}`);
+            }
+            for (const field of ["sessions", "operations", "artifacts"]) {
+                if (!Array.isArray(snapshot[field]))
+                    throw new Error(`Durable snapshot ${field} must be an array`);
+            }
+            const writer = snapshot.writer;
+            assertObject(writer, "Durable snapshot writer");
+            const snapshotHolder = writer.holder;
+            const snapshotCrashPending = writer.crashPending;
+            if (snapshotHolder !== null && typeof snapshotHolder !== "string") {
+                throw new Error("Durable snapshot writer holder must be a string or null");
+            }
+            if (snapshotCrashPending !== null && typeof snapshotCrashPending !== "string") {
+                throw new Error("Durable snapshot writer crashPending must be a string or null");
+            }
+            const importedSessions = new Map();
+            for (const raw of snapshot.sessions) {
+                assertObject(raw, "Durable snapshot session");
+                const record = importRecordBase(raw, "sessionId", "Durable snapshot session");
+                importedSessions.set(record.id, {
+                    sessionId: record.id,
+                    data: record.data,
+                    persistedAt: record.persistedAt,
+                });
+            }
+            const importedOperations = new Map();
+            for (const raw of snapshot.operations) {
+                assertObject(raw, "Durable snapshot operation");
+                const record = importRecordBase(raw, "operationId", "Durable snapshot operation");
+                importedOperations.set(record.id, {
+                    operationId: record.id,
+                    sessionId: importOwningSessionId(raw, "Durable snapshot operation"),
+                    data: record.data,
+                    persistedAt: record.persistedAt,
+                });
+            }
+            const importedArtifacts = new Map();
+            for (const raw of snapshot.artifacts) {
+                assertObject(raw, "Durable snapshot artifact");
+                const record = importRecordBase(raw, "artifactId", "Durable snapshot artifact");
+                importedArtifacts.set(record.id, {
+                    artifactId: record.id,
+                    sessionId: importOwningSessionId(raw, "Durable snapshot artifact"),
+                    data: record.data,
+                    persistedAt: record.persistedAt,
+                });
+            }
+            sessions.clear();
+            for (const [id, record] of importedSessions)
+                sessions.set(id, record);
+            operations.clear();
+            for (const [id, record] of importedOperations)
+                operations.set(id, record);
+            artifacts.clear();
+            for (const [id, record] of importedArtifacts)
+                artifacts.set(id, record);
+            // A writer recorded in the snapshot belonged to the process that
+            // produced it; it cannot be alive in this one, so its lease needs
+            // recovery before anyone may write again.
+            holder = null;
+            crashPending = snapshotHolder ?? snapshotCrashPending;
+        },
+        replayDiagnostics() {
+            return replay;
+        },
+    };
+}
+//# sourceMappingURL=durable-service.js.map