@ai-agent-forge/agent-forge 0.86.7 → 0.87.0

package/dist/durable/durable-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durable-service.d.ts","sourceRoot":"","sources":["../../src/durable/durable-service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Durable service MVP (7.4b) — in-memory persistence for session, operation,\n * and artifact records with a single-writer lease, crash recovery, and a\n * readiness gate.\n *\n * Scope: this is the durable *contract* slice. Storage is an in-memory Map;\n * `exportState`/`importState` are the snapshot restart boundary, and a\n * {@link DurableStoreBackend} is the log restart boundary: when one is passed\n * to {@link createDurableService}, every committed record is appended to the\n * backend log (write-ahead) and the log is replayed at construction to\n * restore state. Without a backend the service stays purely in-memory — the\n * original MVP behavior. {@link createFileDurableStoreBackend} is the JSONL\n * append-only file backend (ledger.ts pattern). Rules frozen here:\n * - Writes require the writer lease: `persist*` with any writerId other than\n *   the current holder fails with `not_writer` — before the first claim,\n *   while another writer holds the lease, and after a crash (until\n *   `recoverWriter` takes it over).\n * - A writer recorded in an imported snapshot belonged to the process that\n *   produced the snapshot and cannot be alive in this one: import enters a\n *   crash-pending state where the lease stays held by the dead writer, reads\n *   still work, and only `recoverWriter` can take the lease over. Readiness\n *   stays `false` until it does.\n * - File writes through {@link createFileDurableStoreBackend} are\n *   cross-process mutually exclusive: every persist serializes through a\n *   `.lock` sibling file (same protocol as the memory ledger — exclusive\n *   create, poll, stale-lock stealing, token-guarded release; wall-clock\n *   timeout and staleness configurable, defaults 5 s / 60 s). The lock\n *   guarantees concurrent appends do not interleave.\n * - Store-level writer lease (D-067 phase 2 S2): backends may expose an\n *   optional {@link DurableStoreLeaseV1} — a TTL-based, cross-process\n *   mutually-exclusive lease over the store. The file backend implements it\n *   with a `.lease` sibling file (write heartbeat on every persist); the\n *   service's claim/recover/release then resolve against the store, so a\n *   second process observes a live foreign writer (`held`) and a crashed\n *   writer's lease becomes recoverable once its TTL lapses. Without a\n *   backend lease the writer lease stays process-local memory (unchanged).\n */\nimport {\n\tcloseSync,\n\tfsyncSync,\n\tmkdirSync,\n\topenSync,\n\treadFileSync,\n\tstatSync,\n\tunlinkSync,\n\twriteFileSync,\n\twriteSync,\n} from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { sleepSync } from \"../utils/sync-sleep.ts\";\n\n// D-075 S4 third batch: the pure contract types moved to @agent-forge/plugin-sdk\n// (`durable.ts` is the plugin-facing authority); this module re-exports them so\n// the host's historical import paths and public export face keep resolving.\n// The implementation below (writer lease, file backend, store lease) stays here.\nexport type {\n\tDurableArtifactRecordV1,\n\tDurableOperationRecordV1,\n\tDurableReadinessV1,\n\tDurableReplayDiagnosticsV1,\n\tDurableServiceV1,\n\tDurableSessionRecordV1,\n\tDurableSnapshotV1,\n\tDurableWriterClaimV1,\n\tDurableWriterRecoveryV1,\n} from \"@agent-forge/plugin-sdk\";\n\nimport type {\n\tDurableArtifactRecordV1,\n\tDurableOperationRecordV1,\n\tDurableReplayDiagnosticsV1,\n\tDurableServiceV1,\n\tDurableSessionRecordV1,\n} from \"@agent-forge/plugin-sdk\";\n\nexport type DurableServiceErrorCodeV1 = \"not_writer\";\n\nexport class DurableServiceErrorV1 extends Error {\n\treadonly code: DurableServiceErrorCodeV1;\n\n\tconstructor(code: DurableServiceErrorCodeV1, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"DurableServiceErrorV1\";\n\t\tthis.code = code;\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Store backend (durable 落盘): JSONL append-only log contract\n// ---------------------------------------------------------------------------\n\n/** One committed record as carried in a {@link DurableStoreBackend} log. */\nexport type DurableStoreOperationV1 =\n\t| { readonly kind: \"session\"; readonly record: DurableSessionRecordV1 }\n\t| { readonly kind: \"operation\"; readonly record: DurableOperationRecordV1 }\n\t| { readonly kind: \"artifact\"; readonly record: DurableArtifactRecordV1 };\n/** Result of {@link DurableStoreBackend.load}: replayable operations plus skip diagnostics. */\nexport interface DurableStoreLoadResultV1 {\n\t/** Valid operations in log order — replay these into a fresh service. */\n\treadonly operations: readonly DurableStoreOperationV1[];\n\t/** Malformed lines (invalid JSON or invalid records) skipped during load. */\n\treadonly corruptedLines: number;\n\t/** True when the file existed but could not be read (permissions, IO error). */\n\treadonly unreadable: boolean;\n}\n\n/**\n * Durable log backend for {@link createDurableService}. The write path\n * appends every committed record; the read path `load()`s the log at\n * construction and replays it into the fresh in-memory maps (last write per\n * id wins, matching live persist semantics). The default\n * {@link FileDurableStoreBackend} never throws on load — corruption is\n * skipped and counted — and the append path runs under a cross-process\n * `.lock` file mutex and fsyncs, so hard crashes cannot lose the most recent\n * appends and concurrent processes cannot interleave lines (a torn trailing\n * line is still skipped by the loader's corruption tolerance). The lock\n * covers file writes only: the writer lease stays process-local memory.\n */\nexport interface DurableStoreBackend {\n\t/** Appends committed operations to the durable log, in order. */\n\tpersist(operations: readonly DurableStoreOperationV1[]): void;\n\t/**\n\t * Reads the whole log and returns the replayable operations plus skip\n\t * diagnostics. A missing log is an empty backend, not an error; malformed\n\t * lines are skipped and counted — load NEVER throws.\n\t */\n\tload(): DurableStoreLoadResultV1;\n\t/** Releases backend resources. Idempotent; a no-op for the file backend. */\n\tclose(): void;\n\t/**\n\t * Optional store-level writer lease (D-067 phase 2 S2). When present, the\n\t * service resolves its claim/recover/release against it, giving\n\t * cross-process lease mutual exclusion and crash recovery by TTL; when\n\t * absent, the writer lease stays process-local memory.\n\t */\n\treadonly lease?: DurableStoreLeaseV1;\n}\n\n/** Result of {@link DurableStoreLeaseV1.claim}. */\nexport type DurableStoreLeaseClaimV1 =\n\t| { readonly status: \"claimed\" }\n\t| { readonly status: \"held\"; readonly by: string };\n\n/** Result of {@link DurableStoreLeaseV1.recover}. */\nexport type DurableStoreLeaseRecoverV1 =\n\t| { readonly status: \"recovered\"; readonly previousWriter?: string }\n\t| { readonly status: \"held\" };\n\n/**\n * Store-level writer lease: a TTL-based mutual-exclusion token over the whole\n * store, visible across processes. `renew` is the heartbeat — the holder\n * extends its TTL on every persist — and doubles as the liveness check: a\n * writer whose lease expired (or was recovered by another process) fails its\n * next renew with `not_writer`, so stale writes fail closed. All methods may\n * throw `DurableServiceErrorV1` with code `not_writer`.\n */\nexport interface DurableStoreLeaseV1 {\n\t/** Takes the lease; fails while a live foreign holder exists. Re-claim by the live holder refreshes it. */\n\tclaim(writerId: string): DurableStoreLeaseClaimV1;\n\t/** Releases the lease when held by `writerId`; free/expired leases release idempotently; a foreign holder throws. */\n\trelease(writerId: string): { readonly status: \"released\" };\n\t/** Takes over the lease of a holder whose TTL lapsed (dead process); a live foreign holder is reported as `held`. */\n\trecover(writerId: string): DurableStoreLeaseRecoverV1;\n\t/** Heartbeat: extends the holder's TTL; throws `not_writer` when the lease was lost or expired. */\n\trenew(writerId: string): void;\n}\n\n/** The standard durable log path: `<agentDir>/durable/<sessionId>.jsonl`. */\nexport function durableLogPath(agentDir: string, sessionId: string): string {\n\treturn join(agentDir, \"durable\", `${sessionId}.jsonl`);\n}\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);\n}\n\n/**\n * Writes every byte of `data` to the fd, looping over partial `writeSync`\n * results (a short write would silently break the fsync durability promise:\n * the caller fsyncs and closes only after the full payload is handed to the\n * OS). Same pattern as the memory ledger's write path, implemented here with\n * plain node:fs primitives so the file backend needs no ledger dependency.\n */\nconst writeAllSync = (fd: number, data: string): void => {\n\tconst buffer = Buffer.from(data, \"utf8\");\n\tlet written = 0;\n\twhile (written < buffer.length) {\n\t\twritten += writeSync(fd, buffer, written, buffer.length - written);\n\t}\n};\n\n// ---------------------------------------------------------------------------\n// Cross-process persist lock (ledger.ts lock protocol, no ledger import —\n// the two implementations must stay behaviorally identical)\n// ---------------------------------------------------------------------------\n\n/** Suffix of the persistence lock sibling file (`<logPath>.lock`). */\nconst LOCK_FILE_SUFFIX = \".lock\";\n/** Suffix of the store-level writer lease sibling file (`<logPath>.lease`). */\nconst LEASE_FILE_SUFFIX = \".lease\";\n/**\n * Wall-clock wait between lock acquisition attempts. Kept as a per-file\n * constant even though the memory ledger currently uses the same 25 ms value:\n * the two lock protocols stay independent.\n */\nconst LOCK_POLL_INTERVAL_MS = 25;\n/** Default ceiling on waiting for a competing writer's lock. */\nconst DEFAULT_LOCK_TIMEOUT_MS = 5000;\n/**\n * Default age at which a lock counts as abandoned (its writer crashed while\n * holding it). Deliberately far above any live hold time (milliseconds of a\n * bounded append) and above the wait timeout, so a waiter fails loudly at the\n * timeout instead of stealing a lock that might still be held.\n */\nconst DEFAULT_STALE_LOCK_MS = 60_000;\n/**\n * Default writer-lease TTL. The holder renews on every persist (heartbeat);\n * an idle-but-alive process that never persists loses the lease after this\n * window and must `recoverWriter` before writing again. Deliberately far\n * above any test-relevant hold so production never sees surprise expiries\n * within a single persist burst; tests pass small values explicitly.\n */\nconst DEFAULT_LEASE_TTL_MS = 30_000;\n\n/**\n * Takes the cross-process persist lock shared by every durable store file\n * write: exclusive create (`wx`) is the mutex; an existing lock is polled\n * until released, stolen once its mtime exceeds `staleLockMs` (crashed\n * writer), or turned into a thrown error at the wait deadline. The lock file\n * carries a per-acquisition token so a stale-steal victim releasing late can\n * never delete the thief's fresh lock. Same protocol as the memory ledger's\n * append lock (now the memory plugin package's ledger, plugins/memory), reimplemented here to avoid module\n * coupling; the wall-clock lock is a real-time mechanism, deliberately not\n * driven by any injected deterministic `now`.\n */\nfunction acquirePersistLock(lockPath: string, lockTimeoutMs: number, staleLockMs: number): string {\n\tconst deadline = Date.now() + lockTimeoutMs;\n\tfor (;;) {\n\t\tmkdirSync(dirname(lockPath), { recursive: true });\n\t\tconst token = `${process.pid}:${Date.now()}`;\n\t\ttry {\n\t\t\tconst fd = openSync(lockPath, \"wx\");\n\t\t\ttry {\n\t\t\t\twriteFileSync(fd, token);\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t\treturn token;\n\t\t} catch (error) {\n\t\t\t// POSIX maps a lost create race to EEXIST; Windows/libuv maps the\n\t\t\t// same concurrent-create sharing violation to EPERM. Both mean the\n\t\t\t// lock file existed when we tried to create it — contend (poll /\n\t\t\t// stale-steal below). For EPERM the existence check re-stats: a\n\t\t\t// lock still there is contention, while ENOENT means the holder\n\t\t\t// released and deleted it between the failed open and this stat\n\t\t\t// (or Windows briefly left a delete-pending name that has now\n\t\t\t// gone) — the same vanished-lock window the EEXIST path tolerates,\n\t\t\t// so retry too. A stat error other than ENOENT means the EPERM was\n\t\t\t// a genuine permission failure and propagates, and the vanish path\n\t\t\t// still rethrows the original EPERM at the wait deadline: a\n\t\t\t// persistent EPERM with no lock file ever appearing is a genuine\n\t\t\t// permission failure, not a held lock.\n\t\t\tconst code = (error as NodeJS.ErrnoException).code;\n\t\t\tif (code === \"EPERM\") {\n\t\t\t\tlet vanished = false;\n\t\t\t\ttry {\n\t\t\t\t\tstatSync(lockPath);\n\t\t\t\t} catch (statError) {\n\t\t\t\t\tif ((statError as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n\t\t\t\t\tvanished = true;\n\t\t\t\t}\n\t\t\t\tif (vanished) {\n\t\t\t\t\tif (Date.now() >= deadline) throw error;\n\t\t\t\t\tsleepSync(LOCK_POLL_INTERVAL_MS);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t} else if (code !== \"EEXIST\") {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tlet stale = false;\n\t\t\ttry {\n\t\t\t\tstale = Date.now() - statSync(lockPath).mtimeMs > staleLockMs;\n\t\t\t} catch {\n\t\t\t\t// The holder released the lock between the failed open and the\n\t\t\t\t// stat — retry the exclusive create immediately.\n\t\t\t}\n\t\t\tif (stale) {\n\t\t\t\t// A crashed writer left the lock behind: steal it. A competing\n\t\t\t\t// waiter may steal first — the next exclusive create resolves that.\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(lockPath);\n\t\t\t\t} catch {\n\t\t\t\t\t// Already stolen — retry.\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (Date.now() >= deadline) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`durable store persist lock timeout after ${lockTimeoutMs} ms: ${lockPath} is held by another writer`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tsleepSync(LOCK_POLL_INTERVAL_MS);\n\t\t}\n\t}\n}\n\n/** Releases the persist lock, but only if our own token still owns it. */\nfunction releasePersistLock(lockPath: string, token: string): void {\n\ttry {\n\t\tif (readFileSync(lockPath, \"utf8\") === token) unlinkSync(lockPath);\n\t} catch {\n\t\t// The lock is already gone (or unreadable) — nothing to release.\n\t}\n}\n\n/**\n * Creates a JSONL append-only file backend at `path`\n * (ledger.ts pattern: one committed record per line, trailing newline so a\n * crash-truncated tail stays well-formed for the loader). Every persist\n * serializes against other processes through a `<path>.lock` sibling using\n * the memory ledger's lock protocol (exclusive create + 25 ms poll + mtime\n * stale-lock stealing + token-guarded release): `lockTimeoutMs` bounds the\n * wall-clock wait (default 5 s) and `staleLockMs` the abandoned-lock age\n * (default 60 s) — both exist so tests can exercise the timeout and steal\n * paths quickly. The lock makes concurrent appends non-interleaving.\n *\n * The backend also exposes the store-level writer lease (`<path>.lease`\n * sibling, D-067 phase 2 S2): a `{ writerId, expiresAt }` JSON file guarded\n * by the same lock protocol, with a TTL the holder renews on every persist\n * (`leaseTtlMs`, default 30 s — small values exist for tests). A crashed\n * writer's lease becomes recoverable once its TTL lapses; a live foreign\n * holder makes `claim`/`recover` report `held` and the holder's next `renew`\n * (i.e. its next persist) fail closed with `not_writer`.\n */\nexport function createFileDurableStoreBackend(options: {\n\treadonly path: string;\n\t/** Wall-clock ceiling on waiting for a competing writer's lock; default 5 s. */\n\treadonly lockTimeoutMs?: number;\n\t/** Age at which a lock counts as abandoned and is stolen; default 60 s. */\n\treadonly staleLockMs?: number;\n\t/** Writer-lease TTL; the holder renews on every persist. Default 30 s. */\n\treadonly leaseTtlMs?: number;\n}): DurableStoreBackend {\n\tassertNonEmptyString(options.path, \"Durable store path\");\n\tif (options.lockTimeoutMs !== undefined && (!Number.isFinite(options.lockTimeoutMs) || options.lockTimeoutMs <= 0)) {\n\t\tthrow new Error(\"Durable store lockTimeoutMs must be a positive number\");\n\t}\n\tif (options.staleLockMs !== undefined && (!Number.isFinite(options.staleLockMs) || options.staleLockMs <= 0)) {\n\t\tthrow new Error(\"Durable store staleLockMs must be a positive number\");\n\t}\n\tif (options.leaseTtlMs !== undefined && (!Number.isFinite(options.leaseTtlMs) || options.leaseTtlMs <= 0)) {\n\t\tthrow new Error(\"Durable store leaseTtlMs must be a positive number\");\n\t}\n\tconst path = options.path;\n\tconst lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;\n\tconst staleLockMs = options.staleLockMs ?? DEFAULT_STALE_LOCK_MS;\n\tconst leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;\n\tconst lockPath = `${path}${LOCK_FILE_SUFFIX}`;\n\tconst leasePath = `${path}${LEASE_FILE_SUFFIX}`;\n\n\t/** Reads the lease file; missing, unreadable, or malformed content = no lease. */\n\tconst readLease = (): { readonly writerId: string; readonly expiresAt: number } | undefined => {\n\t\ttry {\n\t\t\tconst value: unknown = JSON.parse(readFileSync(leasePath, \"utf8\"));\n\t\t\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return undefined;\n\t\t\tconst writerId = (value as { writerId?: unknown }).writerId;\n\t\t\tconst expiresAt = (value as { expiresAt?: unknown }).expiresAt;\n\t\t\tif (typeof writerId !== \"string\" || writerId.length === 0) return undefined;\n\t\t\tif (typeof expiresAt !== \"number\" || !Number.isFinite(expiresAt)) return undefined;\n\t\t\treturn { writerId, expiresAt };\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t};\n\n\t/**\n\t * Overwrites the lease file (caller holds the persist lock). Deliberately\n\t * NOT fsynced: the lease is a liveness token, not data — the worst case of\n\t * a torn post-crash write is a free lease, which the recover path handles.\n\t */\n\tconst writeLease = (writerId: string, expiresAt: number): void => {\n\t\tconst fd = openSync(leasePath, \"w\");\n\t\ttry {\n\t\t\twriteAllSync(fd, JSON.stringify({ writerId, expiresAt }));\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t};\n\n\t/** True when `current` names a different writer whose TTL has not lapsed. */\n\tconst liveForeign = (\n\t\tcurrent: { readonly writerId: string; readonly expiresAt: number },\n\t\twriterId: string,\n\t): boolean => current.writerId !== writerId && Date.now() <= current.expiresAt;\n\n\tconst lease: DurableStoreLeaseV1 = {\n\t\tclaim(writerId) {\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\tconst current = readLease();\n\t\t\t\tif (current !== undefined && liveForeign(current, writerId))\n\t\t\t\t\treturn { status: \"held\", by: current.writerId };\n\t\t\t\twriteLease(writerId, Date.now() + leaseTtlMs);\n\t\t\t\treturn { status: \"claimed\" };\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t\trelease(writerId) {\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\tconst current = readLease();\n\t\t\t\tif (current === undefined || current.writerId === writerId) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tunlinkSync(leasePath);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Already gone (or vanished between the read and the unlink).\n\t\t\t\t\t}\n\t\t\t\t\treturn { status: \"released\" };\n\t\t\t\t}\n\t\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\t\"not_writer\",\n\t\t\t\t\t`Writer ${writerId} does not hold the store lease (held by ${current.writerId})`,\n\t\t\t\t);\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t\trecover(writerId) {\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\tconst current = readLease();\n\t\t\t\tif (current !== undefined && liveForeign(current, writerId)) return { status: \"held\" };\n\t\t\t\tconst previousWriter =\n\t\t\t\t\tcurrent !== undefined && current.writerId !== writerId ? current.writerId : undefined;\n\t\t\t\twriteLease(writerId, Date.now() + leaseTtlMs);\n\t\t\t\treturn previousWriter === undefined ? { status: \"recovered\" } : { status: \"recovered\", previousWriter };\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t\trenew(writerId) {\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\tconst current = readLease();\n\t\t\t\tif (current === undefined || current.writerId !== writerId || Date.now() > current.expiresAt) {\n\t\t\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\t\t\"not_writer\",\n\t\t\t\t\t\t`Writer ${writerId} lost the store lease (expired or recovered by another writer)`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\twriteLease(writerId, Date.now() + leaseTtlMs);\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t};\n\n\treturn {\n\t\tpersist(operations) {\n\t\t\tif (operations.length === 0) return;\n\t\t\tconst lines = operations.map((operation) => `${JSON.stringify(storeOperationEnvelope(operation))}\\n`);\n\t\t\t// Competing writers — including another server process — serialize\n\t\t\t// through the `.lock` sibling before the fsynced append, so lines from\n\t\t\t// concurrent processes never interleave (ledger.ts lock protocol).\n\t\t\t// Lock acquisition creates the parent directory, as in the ledger.\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\t// Append is fsynced before close: once persist returns, a hard\n\t\t\t\t// crash cannot lose the appended lines (open → write → fsync →\n\t\t\t\t// close, the same durability pattern as the memory ledger). A\n\t\t\t\t// failure inside the lock releases it and propagates; no\n\t\t\t\t// in-memory state of the service is touched (write-ahead).\n\t\t\t\tconst fd = openSync(path, \"a\");\n\t\t\t\ttry {\n\t\t\t\t\twriteAllSync(fd, lines.join(\"\"));\n\t\t\t\t\tfsyncSync(fd);\n\t\t\t\t} finally {\n\t\t\t\t\tcloseSync(fd);\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t\tload() {\n\t\t\tlet raw: string;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(path, \"utf8\");\n\t\t\t} catch (error) {\n\t\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n\t\t\t\t\treturn { operations: [], corruptedLines: 0, unreadable: false };\n\t\t\t\t}\n\t\t\t\treturn { operations: [], corruptedLines: 0, unreadable: true };\n\t\t\t}\n\t\t\tconst operations: DurableStoreOperationV1[] = [];\n\t\t\tlet corruptedLines = 0;\n\t\t\tfor (const line of raw.split(\"\\n\")) {\n\t\t\t\tif (line.trim() === \"\") continue;\n\t\t\t\tconst operation = parseStoreOperationLine(line);\n\t\t\t\tif (operation === undefined) {\n\t\t\t\t\tcorruptedLines += 1;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\toperations.push(operation);\n\t\t\t}\n\t\t\treturn { operations, corruptedLines, unreadable: false };\n\t\t},\n\t\tclose() {\n\t\t\t// Files are opened per append; nothing persistent to release. The\n\t\t\t// hook exists for backends that hold resources (handles, sockets).\n\t\t},\n\t\tlease,\n\t};\n}\n\n/** Flat one-line envelope: the kind discriminator plus the record fields. */\nfunction storeOperationEnvelope(operation: DurableStoreOperationV1): Record<string, unknown> {\n\treturn { kind: operation.kind, ...operation.record };\n}\n\n/** Parses one log line; undefined when it is malformed (skipped and counted). */\nfunction parseStoreOperationLine(line: string): DurableStoreOperationV1 | undefined {\n\ttry {\n\t\tconst value: unknown = JSON.parse(line);\n\t\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return undefined;\n\t\tconst record = value as Record<string, unknown>;\n\t\tswitch (record.kind) {\n\t\t\tcase \"session\": {\n\t\t\t\tconst base = importRecordBase(record, \"sessionId\", \"Durable store session record\");\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"session\",\n\t\t\t\t\trecord: { sessionId: base.id, data: base.data, persistedAt: base.persistedAt },\n\t\t\t\t};\n\t\t\t}\n\t\t\tcase \"operation\": {\n\t\t\t\tconst base = importRecordBase(record, \"operationId\", \"Durable store operation record\");\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"operation\",\n\t\t\t\t\trecord: {\n\t\t\t\t\t\toperationId: base.id,\n\t\t\t\t\t\tsessionId: importOwningSessionId(record, \"Durable store operation record\"),\n\t\t\t\t\t\tdata: base.data,\n\t\t\t\t\t\tpersistedAt: base.persistedAt,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\t\t\tcase \"artifact\": {\n\t\t\t\tconst base = importRecordBase(record, \"artifactId\", \"Durable store artifact record\");\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"artifact\",\n\t\t\t\t\trecord: {\n\t\t\t\t\t\tartifactId: base.id,\n\t\t\t\t\t\tsessionId: importOwningSessionId(record, \"Durable store artifact record\"),\n\t\t\t\t\t\tdata: base.data,\n\t\t\t\t\t\tpersistedAt: base.persistedAt,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\t\t\tdefault:\n\t\t\t\treturn undefined;\n\t\t}\n\t} catch {\n\t\t// Corruption tolerance: a malformed line is skipped and counted — a\n\t\t// damaged log must never fail the startup replay.\n\t\treturn undefined;\n\t}\n}\n\nexport interface DurableServiceOptionsV1 {\n\t/** Deterministic clock for `persistedAt`/`exportedAt`; defaults to `Date.now`. */\n\treadonly now?: () => number;\n\t/**\n\t * Optional durable log backend. Without it the service stays purely\n\t * in-memory (backward-compatible MVP behavior); with it every committed\n\t * record is appended to the backend log before the in-memory maps update\n\t * (write-ahead: an append failure leaves memory untouched) and the log is\n\t * replayed at construction to restore state.\n\t */\n\treadonly backend?: DurableStoreBackend;\n}\n\nfunction assertObject(value: unknown, label: string): asserts value is Record<string, unknown> {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new Error(`${label} must be an object`);\n\t}\n}\n\ninterface ImportedRecordV1 {\n\treadonly id: string;\n\treadonly data: unknown;\n\treadonly persistedAt: number;\n}\n\nfunction importRecordBase(\n\tvalue: Record<string, unknown>,\n\tidField: \"sessionId\" | \"operationId\" | \"artifactId\",\n\tlabel: string,\n): ImportedRecordV1 {\n\tconst id = value[idField];\n\tif (typeof id !== \"string\" || id.length === 0) throw new Error(`${label} ${idField} must be a non-empty string`);\n\tconst persistedAt = value.persistedAt;\n\tif (typeof persistedAt !== \"number\" || !Number.isFinite(persistedAt)) {\n\t\tthrow new Error(`${label} persistedAt must be a finite number`);\n\t}\n\t// Legacy (pre-单机收敛) log lines and snapshots may carry a `tenantId` key\n\t// from the removed multi-tenant machinery; it is tolerated as an ignored\n\t// extra key (D-068 增补 1), so it is simply never read here.\n\treturn { id, data: value.data, persistedAt };\n}\n\nfunction importOwningSessionId(value: Record<string, unknown>, label: string): string {\n\tconst sessionId = value.sessionId;\n\tif (typeof sessionId !== \"string\" || sessionId.length === 0) {\n\t\tthrow new Error(`${label} sessionId must be a non-empty string`);\n\t}\n\treturn sessionId;\n}\n\nexport function createDurableService(options: DurableServiceOptionsV1 = {}): DurableServiceV1 {\n\tconst now = options.now ?? (() => Date.now());\n\tconst sessions = new Map<string, DurableSessionRecordV1>();\n\tconst operations = new Map<string, DurableOperationRecordV1>();\n\tconst artifacts = new Map<string, DurableArtifactRecordV1>();\n\n\t/** Current lease holder; `null` when unclaimed or crash-pending. */\n\tlet holder: string | null = null;\n\t/** Writer found dead in a restored snapshot; blocks claims and writes until recovered. */\n\tlet crashPending: string | null = null;\n\n\t// Startup replay (durable 落盘): with a backend, the log is the source of\n\t// truth for records — replay restores the maps with last-write-wins, the\n\t// same semantics as live persists. With a backend lease (D-067 phase 2\n\t// S2) the writer lease resolves against the store (cross-process mutual\n\t// exclusion, TTL crash recovery); without one it stays process-local.\n\tconst backend = options.backend;\n\tconst backendLease = backend?.lease;\n\tlet replay: DurableReplayDiagnosticsV1 = { corruptedLines: 0, unreadable: false };\n\tif (backend) {\n\t\tconst loaded = backend.load();\n\t\tfor (const operation of loaded.operations) {\n\t\t\tswitch (operation.kind) {\n\t\t\t\tcase \"session\":\n\t\t\t\t\tsessions.set(operation.record.sessionId, operation.record);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"operation\":\n\t\t\t\t\toperations.set(operation.record.operationId, operation.record);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"artifact\":\n\t\t\t\t\tartifacts.set(operation.record.artifactId, operation.record);\n\t\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t\treplay = { corruptedLines: loaded.corruptedLines, unreadable: loaded.unreadable };\n\t}\n\n\t/** Write-ahead log append; an append failure leaves the maps untouched. */\n\tconst logOperation = (operation: DurableStoreOperationV1): void => {\n\t\tif (backend) backend.persist([operation]);\n\t};\n\n\tfunction requireWriter(writerId: string): void {\n\t\tif (holder !== writerId) {\n\t\t\tthrow new DurableServiceErrorV1(\"not_writer\", `Writer ${writerId} does not hold the writer lease`);\n\t\t}\n\t\t// Store-level heartbeat + liveness check (D-067 phase 2 S2): another\n\t\t// process recovering our expired lease fail-closes this write instead\n\t\t// of letting a stale writer interleave records.\n\t\tbackendLease?.renew(writerId);\n\t}\n\n\treturn {\n\t\tpersistSession(input) {\n\t\t\trequireWriter(input.writerId);\n\t\t\tconst record: DurableSessionRecordV1 = {\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tdata: input.data,\n\t\t\t\tpersistedAt: now(),\n\t\t\t};\n\t\t\tlogOperation({ kind: \"session\", record });\n\t\t\tsessions.set(input.sessionId, record);\n\t\t\treturn record;\n\t\t},\n\t\tloadSession(input) {\n\t\t\treturn sessions.get(input.sessionId);\n\t\t},\n\t\tpersistOperation(input) {\n\t\t\trequireWriter(input.writerId);\n\t\t\tconst record: DurableOperationRecordV1 = {\n\t\t\t\toperationId: input.operationId,\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tdata: input.data,\n\t\t\t\tpersistedAt: now(),\n\t\t\t};\n\t\t\tlogOperation({ kind: \"operation\", record });\n\t\t\toperations.set(input.operationId, record);\n\t\t\treturn record;\n\t\t},\n\t\tloadOperation(input) {\n\t\t\treturn operations.get(input.operationId);\n\t\t},\n\t\tpersistArtifact(input) {\n\t\t\trequireWriter(input.writerId);\n\t\t\tconst record: DurableArtifactRecordV1 = {\n\t\t\t\tartifactId: input.artifactId,\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tdata: input.data,\n\t\t\t\tpersistedAt: now(),\n\t\t\t};\n\t\t\tlogOperation({ kind: \"artifact\", record });\n\t\t\tartifacts.set(input.artifactId, record);\n\t\t\treturn record;\n\t\t},\n\t\tloadArtifact(input) {\n\t\t\treturn artifacts.get(input.artifactId);\n\t\t},\n\t\tlistSessions() {\n\t\t\treturn (\n\t\t\t\t[...sessions.values()]\n\t\t\t\t\t// v8 ignore next -- sessionId 是 Map 键恒唯一，相等比较路径不可达\n\t\t\t\t\t.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0))\n\t\t\t);\n\t\t},\n\t\tclaimWriter(writerId) {\n\t\t\tif (crashPending !== null) return { status: \"held\", by: crashPending };\n\t\t\tif (backendLease === undefined) {\n\t\t\t\tif (holder !== null && holder !== writerId) return { status: \"held\", by: holder };\n\t\t\t\tholder = writerId;\n\t\t\t\treturn { status: \"claimed\" };\n\t\t\t}\n\t\t\tconst result = backendLease.claim(writerId);\n\t\t\tif (result.status === \"claimed\") {\n\t\t\t\tholder = writerId;\n\t\t\t\treturn { status: \"claimed\" };\n\t\t\t}\n\t\t\treturn { status: \"held\", by: result.by };\n\t\t},\n\t\treleaseWriter(writerId) {\n\t\t\tif (crashPending !== null) {\n\t\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\t\"not_writer\",\n\t\t\t\t\t`Writer ${writerId} cannot release a crashed lease; recover it instead`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (backendLease === undefined) {\n\t\t\t\tif (holder !== null && holder !== writerId) {\n\t\t\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\t\t\"not_writer\",\n\t\t\t\t\t\t`Writer ${writerId} does not hold the writer lease (held by ${holder})`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tholder = null;\n\t\t\t\treturn { status: \"released\" };\n\t\t\t}\n\t\t\tconst result = backendLease.release(writerId);\n\t\t\tholder = null;\n\t\t\treturn result;\n\t\t},\n\t\trecoverWriter(writerId) {\n\t\t\tif (crashPending !== null) {\n\t\t\t\tconst previousWriter = crashPending;\n\t\t\t\tcrashPending = null;\n\t\t\t\tholder = writerId;\n\t\t\t\treturn { status: \"recovered\", previousWriter };\n\t\t\t}\n\t\t\tif (backendLease === undefined) {\n\t\t\t\tif (holder !== null && holder !== writerId) return { status: \"held\" };\n\t\t\t\tholder = writerId;\n\t\t\t\treturn { status: \"recovered\" };\n\t\t\t}\n\t\t\tconst result = backendLease.recover(writerId);\n\t\t\tif (result.status === \"recovered\") {\n\t\t\t\tholder = writerId;\n\t\t\t\treturn result.previousWriter === undefined\n\t\t\t\t\t? { status: \"recovered\" }\n\t\t\t\t\t: { status: \"recovered\", previousWriter: result.previousWriter };\n\t\t\t}\n\t\t\treturn { status: \"held\" };\n\t\t},\n\t\treadiness() {\n\t\t\tif (crashPending !== null) {\n\t\t\t\treturn { ready: false, reason: `writer crash is pending recovery: ${crashPending}` };\n\t\t\t}\n\t\t\tif (holder === null) {\n\t\t\t\treturn { ready: false, reason: \"no writer has claimed the lease\" };\n\t\t\t}\n\t\t\treturn { ready: true };\n\t\t},\n\t\texportState() {\n\t\t\treturn {\n\t\t\t\tversion: 1 as const,\n\t\t\t\texportedAt: now(),\n\t\t\t\tsessions: [...sessions.values()],\n\t\t\t\toperations: [...operations.values()],\n\t\t\t\tartifacts: [...artifacts.values()],\n\t\t\t\twriter: { holder, crashPending },\n\t\t\t};\n\t\t},\n\t\timportState(snapshot) {\n\t\t\tassertObject(snapshot, \"Durable snapshot\");\n\t\t\tif (snapshot.version !== 1) {\n\t\t\t\tthrow new Error(`Unsupported durable snapshot version: ${String(snapshot.version)}`);\n\t\t\t}\n\t\t\tfor (const field of [\"sessions\", \"operations\", \"artifacts\"] as const) {\n\t\t\t\tif (!Array.isArray(snapshot[field])) throw new Error(`Durable snapshot ${field} must be an array`);\n\t\t\t}\n\t\t\tconst writer = snapshot.writer;\n\t\t\tassertObject(writer, \"Durable snapshot writer\");\n\t\t\tconst snapshotHolder = writer.holder;\n\t\t\tconst snapshotCrashPending = writer.crashPending;\n\t\t\tif (snapshotHolder !== null && typeof snapshotHolder !== \"string\") {\n\t\t\t\tthrow new Error(\"Durable snapshot writer holder must be a string or null\");\n\t\t\t}\n\t\t\tif (snapshotCrashPending !== null && typeof snapshotCrashPending !== \"string\") {\n\t\t\t\tthrow new Error(\"Durable snapshot writer crashPending must be a string or null\");\n\t\t\t}\n\n\t\t\tconst importedSessions = new Map<string, DurableSessionRecordV1>();\n\t\t\tfor (const raw of snapshot.sessions as unknown[]) {\n\t\t\t\tassertObject(raw, \"Durable snapshot session\");\n\t\t\t\tconst record = importRecordBase(raw, \"sessionId\", \"Durable snapshot session\");\n\t\t\t\timportedSessions.set(record.id, {\n\t\t\t\t\tsessionId: record.id,\n\t\t\t\t\tdata: record.data,\n\t\t\t\t\tpersistedAt: record.persistedAt,\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst importedOperations = new Map<string, DurableOperationRecordV1>();\n\t\t\tfor (const raw of snapshot.operations as unknown[]) {\n\t\t\t\tassertObject(raw, \"Durable snapshot operation\");\n\t\t\t\tconst record = importRecordBase(raw, \"operationId\", \"Durable snapshot operation\");\n\t\t\t\timportedOperations.set(record.id, {\n\t\t\t\t\toperationId: record.id,\n\t\t\t\t\tsessionId: importOwningSessionId(raw, \"Durable snapshot operation\"),\n\t\t\t\t\tdata: record.data,\n\t\t\t\t\tpersistedAt: record.persistedAt,\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst importedArtifacts = new Map<string, DurableArtifactRecordV1>();\n\t\t\tfor (const raw of snapshot.artifacts as unknown[]) {\n\t\t\t\tassertObject(raw, \"Durable snapshot artifact\");\n\t\t\t\tconst record = importRecordBase(raw, \"artifactId\", \"Durable snapshot artifact\");\n\t\t\t\timportedArtifacts.set(record.id, {\n\t\t\t\t\tartifactId: record.id,\n\t\t\t\t\tsessionId: importOwningSessionId(raw, \"Durable snapshot artifact\"),\n\t\t\t\t\tdata: record.data,\n\t\t\t\t\tpersistedAt: record.persistedAt,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tsessions.clear();\n\t\t\tfor (const [id, record] of importedSessions) sessions.set(id, record);\n\t\t\toperations.clear();\n\t\t\tfor (const [id, record] of importedOperations) operations.set(id, record);\n\t\t\tartifacts.clear();\n\t\t\tfor (const [id, record] of importedArtifacts) artifacts.set(id, record);\n\n\t\t\t// A writer recorded in the snapshot belonged to the process that\n\t\t\t// produced it; it cannot be alive in this one, so its lease needs\n\t\t\t// recovery before anyone may write again.\n\t\t\tholder = null;\n\t\t\tcrashPending = snapshotHolder ?? snapshotCrashPending;\n\t\t},\n\t\treplayDiagnostics() {\n\t\t\treturn replay;\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"durable-service.d.ts","sourceRoot":"","sources":["../../src/durable/durable-service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Durable service MVP (7.4b) — in-memory persistence for session, operation,\n * and artifact records with a single-writer lease, crash recovery, and a\n * readiness gate.\n *\n * Scope: this is the durable *contract* slice. Storage is an in-memory Map;\n * `exportState`/`importState` are the snapshot restart boundary, and a\n * {@link DurableStoreBackend} is the log restart boundary: when one is passed\n * to {@link createDurableService}, every committed record is appended to the\n * backend log (write-ahead) and the log is replayed at construction to\n * restore state. Without a backend the service stays purely in-memory — the\n * original MVP behavior. {@link createFileDurableStoreBackend} is the JSONL\n * append-only file backend (ledger.ts pattern). Rules frozen here:\n * - Writes require the writer lease: `persist*` with any writerId other than\n *   the current holder fails with `not_writer` — before the first claim,\n *   while another writer holds the lease, and after a crash (until\n *   `recoverWriter` takes it over).\n * - A writer recorded in an imported snapshot belonged to the process that\n *   produced the snapshot and cannot be alive in this one: import enters a\n *   crash-pending state where the lease stays held by the dead writer, reads\n *   still work, and only `recoverWriter` can take the lease over. Readiness\n *   stays `false` until it does.\n * - File writes through {@link createFileDurableStoreBackend} are\n *   cross-process mutually exclusive: every persist serializes through a\n *   `.lock` sibling file (same protocol as the memory ledger — exclusive\n *   create, poll, stale-lock stealing, token-guarded release; wall-clock\n *   timeout and staleness configurable, defaults 5 s / 60 s). The lock\n *   guarantees concurrent appends do not interleave.\n * - Store-level writer lease (D-067 phase 2 S2): backends may expose an\n *   optional {@link DurableStoreLeaseV1} — a TTL-based, cross-process\n *   mutually-exclusive lease over the store. The file backend implements it\n *   with a `.lease` sibling file (write heartbeat on every persist); the\n *   service's claim/recover/release then resolve against the store, so a\n *   second process observes a live foreign writer (`held`) and a crashed\n *   writer's lease becomes recoverable once its TTL lapses. Without a\n *   backend lease the writer lease stays process-local memory (unchanged).\n */\nimport {\n\tcloseSync,\n\tfsyncSync,\n\tmkdirSync,\n\topenSync,\n\treadFileSync,\n\tstatSync,\n\tunlinkSync,\n\twriteFileSync,\n\twriteSync,\n} from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { sleepSync } from \"../utils/sync-sleep.ts\";\n\n// D-075 S4 third batch: the pure contract types moved to @agent-forge/plugin-sdk\n// (`durable.ts` is the plugin-facing authority); this module re-exports them so\n// the host's historical import paths and public export face keep resolving.\n// The implementation below (writer lease, file backend, store lease) stays here.\nexport type {\n\tDurableArtifactRecordV1,\n\tDurableOperationRecordV1,\n\tDurableReadinessV1,\n\tDurableReplayDiagnosticsV1,\n\tDurableServiceV1,\n\tDurableSessionRecordV1,\n\tDurableSnapshotV1,\n\tDurableWriterClaimV1,\n\tDurableWriterRecoveryV1,\n} from \"@agent-forge/plugin-sdk\";\n\nimport type {\n\tDurableArtifactRecordV1,\n\tDurableOperationRecordV1,\n\tDurableReplayDiagnosticsV1,\n\tDurableServiceV1,\n\tDurableSessionRecordV1,\n} from \"@agent-forge/plugin-sdk\";\nimport { t } from \"../core/i18n/index.ts\";\n\nexport type DurableServiceErrorCodeV1 = \"not_writer\";\n\nexport class DurableServiceErrorV1 extends Error {\n\treadonly code: DurableServiceErrorCodeV1;\n\n\tconstructor(code: DurableServiceErrorCodeV1, message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"DurableServiceErrorV1\";\n\t\tthis.code = code;\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Store backend (durable 落盘): JSONL append-only log contract\n// ---------------------------------------------------------------------------\n\n/** One committed record as carried in a {@link DurableStoreBackend} log. */\nexport type DurableStoreOperationV1 =\n\t| { readonly kind: \"session\"; readonly record: DurableSessionRecordV1 }\n\t| { readonly kind: \"operation\"; readonly record: DurableOperationRecordV1 }\n\t| { readonly kind: \"artifact\"; readonly record: DurableArtifactRecordV1 };\n/** Result of {@link DurableStoreBackend.load}: replayable operations plus skip diagnostics. */\nexport interface DurableStoreLoadResultV1 {\n\t/** Valid operations in log order — replay these into a fresh service. */\n\treadonly operations: readonly DurableStoreOperationV1[];\n\t/** Malformed lines (invalid JSON or invalid records) skipped during load. */\n\treadonly corruptedLines: number;\n\t/** True when the file existed but could not be read (permissions, IO error). */\n\treadonly unreadable: boolean;\n}\n\n/**\n * Durable log backend for {@link createDurableService}. The write path\n * appends every committed record; the read path `load()`s the log at\n * construction and replays it into the fresh in-memory maps (last write per\n * id wins, matching live persist semantics). The default\n * {@link FileDurableStoreBackend} never throws on load — corruption is\n * skipped and counted — and the append path runs under a cross-process\n * `.lock` file mutex and fsyncs, so hard crashes cannot lose the most recent\n * appends and concurrent processes cannot interleave lines (a torn trailing\n * line is still skipped by the loader's corruption tolerance). The lock\n * covers file writes only: the writer lease stays process-local memory.\n */\nexport interface DurableStoreBackend {\n\t/** Appends committed operations to the durable log, in order. */\n\tpersist(operations: readonly DurableStoreOperationV1[]): void;\n\t/**\n\t * Reads the whole log and returns the replayable operations plus skip\n\t * diagnostics. A missing log is an empty backend, not an error; malformed\n\t * lines are skipped and counted — load NEVER throws.\n\t */\n\tload(): DurableStoreLoadResultV1;\n\t/** Releases backend resources. Idempotent; a no-op for the file backend. */\n\tclose(): void;\n\t/**\n\t * Optional store-level writer lease (D-067 phase 2 S2). When present, the\n\t * service resolves its claim/recover/release against it, giving\n\t * cross-process lease mutual exclusion and crash recovery by TTL; when\n\t * absent, the writer lease stays process-local memory.\n\t */\n\treadonly lease?: DurableStoreLeaseV1;\n}\n\n/** Result of {@link DurableStoreLeaseV1.claim}. */\nexport type DurableStoreLeaseClaimV1 =\n\t| { readonly status: \"claimed\" }\n\t| { readonly status: \"held\"; readonly by: string };\n\n/** Result of {@link DurableStoreLeaseV1.recover}. */\nexport type DurableStoreLeaseRecoverV1 =\n\t| { readonly status: \"recovered\"; readonly previousWriter?: string }\n\t| { readonly status: \"held\" };\n\n/**\n * Store-level writer lease: a TTL-based mutual-exclusion token over the whole\n * store, visible across processes. `renew` is the heartbeat — the holder\n * extends its TTL on every persist — and doubles as the liveness check: a\n * writer whose lease expired (or was recovered by another process) fails its\n * next renew with `not_writer`, so stale writes fail closed. All methods may\n * throw `DurableServiceErrorV1` with code `not_writer`.\n */\nexport interface DurableStoreLeaseV1 {\n\t/** Takes the lease; fails while a live foreign holder exists. Re-claim by the live holder refreshes it. */\n\tclaim(writerId: string): DurableStoreLeaseClaimV1;\n\t/** Releases the lease when held by `writerId`; free/expired leases release idempotently; a foreign holder throws. */\n\trelease(writerId: string): { readonly status: \"released\" };\n\t/** Takes over the lease of a holder whose TTL lapsed (dead process); a live foreign holder is reported as `held`. */\n\trecover(writerId: string): DurableStoreLeaseRecoverV1;\n\t/** Heartbeat: extends the holder's TTL; throws `not_writer` when the lease was lost or expired. */\n\trenew(writerId: string): void;\n}\n\n/** The standard durable log path: `<agentDir>/durable/<sessionId>.jsonl`. */\nexport function durableLogPath(agentDir: string, sessionId: string): string {\n\treturn join(agentDir, \"durable\", `${sessionId}.jsonl`);\n}\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0)\n\t\tthrow new Error(t(\"{label} must be a non-empty string\", { label }));\n}\n\n/**\n * Writes every byte of `data` to the fd, looping over partial `writeSync`\n * results (a short write would silently break the fsync durability promise:\n * the caller fsyncs and closes only after the full payload is handed to the\n * OS). Same pattern as the memory ledger's write path, implemented here with\n * plain node:fs primitives so the file backend needs no ledger dependency.\n */\nconst writeAllSync = (fd: number, data: string): void => {\n\tconst buffer = Buffer.from(data, \"utf8\");\n\tlet written = 0;\n\twhile (written < buffer.length) {\n\t\twritten += writeSync(fd, buffer, written, buffer.length - written);\n\t}\n};\n\n// ---------------------------------------------------------------------------\n// Cross-process persist lock (ledger.ts lock protocol, no ledger import —\n// the two implementations must stay behaviorally identical)\n// ---------------------------------------------------------------------------\n\n/** Suffix of the persistence lock sibling file (`<logPath>.lock`). */\nconst LOCK_FILE_SUFFIX = \".lock\";\n/** Suffix of the store-level writer lease sibling file (`<logPath>.lease`). */\nconst LEASE_FILE_SUFFIX = \".lease\";\n/**\n * Wall-clock wait between lock acquisition attempts. Kept as a per-file\n * constant even though the memory ledger currently uses the same 25 ms value:\n * the two lock protocols stay independent.\n */\nconst LOCK_POLL_INTERVAL_MS = 25;\n/** Default ceiling on waiting for a competing writer's lock. */\nconst DEFAULT_LOCK_TIMEOUT_MS = 5000;\n/**\n * Default age at which a lock counts as abandoned (its writer crashed while\n * holding it). Deliberately far above any live hold time (milliseconds of a\n * bounded append) and above the wait timeout, so a waiter fails loudly at the\n * timeout instead of stealing a lock that might still be held.\n */\nconst DEFAULT_STALE_LOCK_MS = 60_000;\n/**\n * Default writer-lease TTL. The holder renews on every persist (heartbeat);\n * an idle-but-alive process that never persists loses the lease after this\n * window and must `recoverWriter` before writing again. Deliberately far\n * above any test-relevant hold so production never sees surprise expiries\n * within a single persist burst; tests pass small values explicitly.\n */\nconst DEFAULT_LEASE_TTL_MS = 30_000;\n\n/**\n * Takes the cross-process persist lock shared by every durable store file\n * write: exclusive create (`wx`) is the mutex; an existing lock is polled\n * until released, stolen once its mtime exceeds `staleLockMs` (crashed\n * writer), or turned into a thrown error at the wait deadline. The lock file\n * carries a per-acquisition token so a stale-steal victim releasing late can\n * never delete the thief's fresh lock. Same protocol as the memory ledger's\n * append lock (now the memory plugin package's ledger, plugins/memory), reimplemented here to avoid module\n * coupling; the wall-clock lock is a real-time mechanism, deliberately not\n * driven by any injected deterministic `now`.\n */\nfunction acquirePersistLock(lockPath: string, lockTimeoutMs: number, staleLockMs: number): string {\n\tconst deadline = Date.now() + lockTimeoutMs;\n\tfor (;;) {\n\t\tmkdirSync(dirname(lockPath), { recursive: true });\n\t\tconst token = `${process.pid}:${Date.now()}`;\n\t\ttry {\n\t\t\tconst fd = openSync(lockPath, \"wx\");\n\t\t\ttry {\n\t\t\t\twriteFileSync(fd, token);\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t\treturn token;\n\t\t} catch (error) {\n\t\t\t// POSIX maps a lost create race to EEXIST; Windows/libuv maps the\n\t\t\t// same concurrent-create sharing violation to EPERM. Both mean the\n\t\t\t// lock file existed when we tried to create it — contend (poll /\n\t\t\t// stale-steal below). For EPERM the existence check re-stats: a\n\t\t\t// lock still there is contention, while ENOENT means the holder\n\t\t\t// released and deleted it between the failed open and this stat\n\t\t\t// (or Windows briefly left a delete-pending name that has now\n\t\t\t// gone) — the same vanished-lock window the EEXIST path tolerates,\n\t\t\t// so retry too. A stat error other than ENOENT means the EPERM was\n\t\t\t// a genuine permission failure and propagates, and the vanish path\n\t\t\t// still rethrows the original EPERM at the wait deadline: a\n\t\t\t// persistent EPERM with no lock file ever appearing is a genuine\n\t\t\t// permission failure, not a held lock.\n\t\t\tconst code = (error as NodeJS.ErrnoException).code;\n\t\t\tif (code === \"EPERM\") {\n\t\t\t\tlet vanished = false;\n\t\t\t\ttry {\n\t\t\t\t\tstatSync(lockPath);\n\t\t\t\t} catch (statError) {\n\t\t\t\t\tif ((statError as NodeJS.ErrnoException).code !== \"ENOENT\") throw error;\n\t\t\t\t\tvanished = true;\n\t\t\t\t}\n\t\t\t\tif (vanished) {\n\t\t\t\t\tif (Date.now() >= deadline) throw error;\n\t\t\t\t\tsleepSync(LOCK_POLL_INTERVAL_MS);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t} else if (code !== \"EEXIST\") {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tlet stale = false;\n\t\t\ttry {\n\t\t\t\tstale = Date.now() - statSync(lockPath).mtimeMs > staleLockMs;\n\t\t\t} catch {\n\t\t\t\t// The holder released the lock between the failed open and the\n\t\t\t\t// stat — retry the exclusive create immediately.\n\t\t\t}\n\t\t\tif (stale) {\n\t\t\t\t// A crashed writer left the lock behind: steal it. A competing\n\t\t\t\t// waiter may steal first — the next exclusive create resolves that.\n\t\t\t\ttry {\n\t\t\t\t\tunlinkSync(lockPath);\n\t\t\t\t} catch {\n\t\t\t\t\t// Already stolen — retry.\n\t\t\t\t}\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (Date.now() >= deadline) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\tt(\"durable store persist lock timeout after {timeoutMs} ms: {lockPath} is held by another writer\", {\n\t\t\t\t\t\ttimeoutMs: lockTimeoutMs,\n\t\t\t\t\t\tlockPath,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t\tsleepSync(LOCK_POLL_INTERVAL_MS);\n\t\t}\n\t}\n}\n\n/** Releases the persist lock, but only if our own token still owns it. */\nfunction releasePersistLock(lockPath: string, token: string): void {\n\ttry {\n\t\tif (readFileSync(lockPath, \"utf8\") === token) unlinkSync(lockPath);\n\t} catch {\n\t\t// The lock is already gone (or unreadable) — nothing to release.\n\t}\n}\n\n/**\n * Creates a JSONL append-only file backend at `path`\n * (ledger.ts pattern: one committed record per line, trailing newline so a\n * crash-truncated tail stays well-formed for the loader). Every persist\n * serializes against other processes through a `<path>.lock` sibling using\n * the memory ledger's lock protocol (exclusive create + 25 ms poll + mtime\n * stale-lock stealing + token-guarded release): `lockTimeoutMs` bounds the\n * wall-clock wait (default 5 s) and `staleLockMs` the abandoned-lock age\n * (default 60 s) — both exist so tests can exercise the timeout and steal\n * paths quickly. The lock makes concurrent appends non-interleaving.\n *\n * The backend also exposes the store-level writer lease (`<path>.lease`\n * sibling, D-067 phase 2 S2): a `{ writerId, expiresAt }` JSON file guarded\n * by the same lock protocol, with a TTL the holder renews on every persist\n * (`leaseTtlMs`, default 30 s — small values exist for tests). A crashed\n * writer's lease becomes recoverable once its TTL lapses; a live foreign\n * holder makes `claim`/`recover` report `held` and the holder's next `renew`\n * (i.e. its next persist) fail closed with `not_writer`.\n */\nexport function createFileDurableStoreBackend(options: {\n\treadonly path: string;\n\t/** Wall-clock ceiling on waiting for a competing writer's lock; default 5 s. */\n\treadonly lockTimeoutMs?: number;\n\t/** Age at which a lock counts as abandoned and is stolen; default 60 s. */\n\treadonly staleLockMs?: number;\n\t/** Writer-lease TTL; the holder renews on every persist. Default 30 s. */\n\treadonly leaseTtlMs?: number;\n}): DurableStoreBackend {\n\tassertNonEmptyString(options.path, \"Durable store path\");\n\tif (options.lockTimeoutMs !== undefined && (!Number.isFinite(options.lockTimeoutMs) || options.lockTimeoutMs <= 0)) {\n\t\tthrow new Error(t(\"Durable store lockTimeoutMs must be a positive number\"));\n\t}\n\tif (options.staleLockMs !== undefined && (!Number.isFinite(options.staleLockMs) || options.staleLockMs <= 0)) {\n\t\tthrow new Error(t(\"Durable store staleLockMs must be a positive number\"));\n\t}\n\tif (options.leaseTtlMs !== undefined && (!Number.isFinite(options.leaseTtlMs) || options.leaseTtlMs <= 0)) {\n\t\tthrow new Error(t(\"Durable store leaseTtlMs must be a positive number\"));\n\t}\n\tconst path = options.path;\n\tconst lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;\n\tconst staleLockMs = options.staleLockMs ?? DEFAULT_STALE_LOCK_MS;\n\tconst leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;\n\tconst lockPath = `${path}${LOCK_FILE_SUFFIX}`;\n\tconst leasePath = `${path}${LEASE_FILE_SUFFIX}`;\n\n\t/** Reads the lease file; missing, unreadable, or malformed content = no lease. */\n\tconst readLease = (): { readonly writerId: string; readonly expiresAt: number } | undefined => {\n\t\ttry {\n\t\t\tconst value: unknown = JSON.parse(readFileSync(leasePath, \"utf8\"));\n\t\t\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return undefined;\n\t\t\tconst writerId = (value as { writerId?: unknown }).writerId;\n\t\t\tconst expiresAt = (value as { expiresAt?: unknown }).expiresAt;\n\t\t\tif (typeof writerId !== \"string\" || writerId.length === 0) return undefined;\n\t\t\tif (typeof expiresAt !== \"number\" || !Number.isFinite(expiresAt)) return undefined;\n\t\t\treturn { writerId, expiresAt };\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t};\n\n\t/**\n\t * Overwrites the lease file (caller holds the persist lock). Deliberately\n\t * NOT fsynced: the lease is a liveness token, not data — the worst case of\n\t * a torn post-crash write is a free lease, which the recover path handles.\n\t */\n\tconst writeLease = (writerId: string, expiresAt: number): void => {\n\t\tconst fd = openSync(leasePath, \"w\");\n\t\ttry {\n\t\t\twriteAllSync(fd, JSON.stringify({ writerId, expiresAt }));\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t};\n\n\t/** True when `current` names a different writer whose TTL has not lapsed. */\n\tconst liveForeign = (\n\t\tcurrent: { readonly writerId: string; readonly expiresAt: number },\n\t\twriterId: string,\n\t): boolean => current.writerId !== writerId && Date.now() <= current.expiresAt;\n\n\tconst lease: DurableStoreLeaseV1 = {\n\t\tclaim(writerId) {\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\tconst current = readLease();\n\t\t\t\tif (current !== undefined && liveForeign(current, writerId))\n\t\t\t\t\treturn { status: \"held\", by: current.writerId };\n\t\t\t\twriteLease(writerId, Date.now() + leaseTtlMs);\n\t\t\t\treturn { status: \"claimed\" };\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t\trelease(writerId) {\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\tconst current = readLease();\n\t\t\t\tif (current === undefined || current.writerId === writerId) {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tunlinkSync(leasePath);\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Already gone (or vanished between the read and the unlink).\n\t\t\t\t\t}\n\t\t\t\t\treturn { status: \"released\" };\n\t\t\t\t}\n\t\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\t\"not_writer\",\n\t\t\t\t\tt(\"Writer {writerId} does not hold the store lease (held by {holder})\", {\n\t\t\t\t\t\twriterId,\n\t\t\t\t\t\tholder: current.writerId,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t\trecover(writerId) {\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\tconst current = readLease();\n\t\t\t\tif (current !== undefined && liveForeign(current, writerId)) return { status: \"held\" };\n\t\t\t\tconst previousWriter =\n\t\t\t\t\tcurrent !== undefined && current.writerId !== writerId ? current.writerId : undefined;\n\t\t\t\twriteLease(writerId, Date.now() + leaseTtlMs);\n\t\t\t\treturn previousWriter === undefined ? { status: \"recovered\" } : { status: \"recovered\", previousWriter };\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t\trenew(writerId) {\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\tconst current = readLease();\n\t\t\t\tif (current === undefined || current.writerId !== writerId || Date.now() > current.expiresAt) {\n\t\t\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\t\t\"not_writer\",\n\t\t\t\t\t\tt(\"Writer {writerId} lost the store lease (expired or recovered by another writer)\", { writerId }),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\twriteLease(writerId, Date.now() + leaseTtlMs);\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t};\n\n\treturn {\n\t\tpersist(operations) {\n\t\t\tif (operations.length === 0) return;\n\t\t\tconst lines = operations.map((operation) => `${JSON.stringify(storeOperationEnvelope(operation))}\\n`);\n\t\t\t// Competing writers — including another server process — serialize\n\t\t\t// through the `.lock` sibling before the fsynced append, so lines from\n\t\t\t// concurrent processes never interleave (ledger.ts lock protocol).\n\t\t\t// Lock acquisition creates the parent directory, as in the ledger.\n\t\t\tconst token = acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs);\n\t\t\ttry {\n\t\t\t\t// Append is fsynced before close: once persist returns, a hard\n\t\t\t\t// crash cannot lose the appended lines (open → write → fsync →\n\t\t\t\t// close, the same durability pattern as the memory ledger). A\n\t\t\t\t// failure inside the lock releases it and propagates; no\n\t\t\t\t// in-memory state of the service is touched (write-ahead).\n\t\t\t\tconst fd = openSync(path, \"a\");\n\t\t\t\ttry {\n\t\t\t\t\twriteAllSync(fd, lines.join(\"\"));\n\t\t\t\t\tfsyncSync(fd);\n\t\t\t\t} finally {\n\t\t\t\t\tcloseSync(fd);\n\t\t\t\t}\n\t\t\t} finally {\n\t\t\t\treleasePersistLock(lockPath, token);\n\t\t\t}\n\t\t},\n\t\tload() {\n\t\t\tlet raw: string;\n\t\t\ttry {\n\t\t\t\traw = readFileSync(path, \"utf8\");\n\t\t\t} catch (error) {\n\t\t\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n\t\t\t\t\treturn { operations: [], corruptedLines: 0, unreadable: false };\n\t\t\t\t}\n\t\t\t\treturn { operations: [], corruptedLines: 0, unreadable: true };\n\t\t\t}\n\t\t\tconst operations: DurableStoreOperationV1[] = [];\n\t\t\tlet corruptedLines = 0;\n\t\t\tfor (const line of raw.split(\"\\n\")) {\n\t\t\t\tif (line.trim() === \"\") continue;\n\t\t\t\tconst operation = parseStoreOperationLine(line);\n\t\t\t\tif (operation === undefined) {\n\t\t\t\t\tcorruptedLines += 1;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\toperations.push(operation);\n\t\t\t}\n\t\t\treturn { operations, corruptedLines, unreadable: false };\n\t\t},\n\t\tclose() {\n\t\t\t// Files are opened per append; nothing persistent to release. The\n\t\t\t// hook exists for backends that hold resources (handles, sockets).\n\t\t},\n\t\tlease,\n\t};\n}\n\n/** Flat one-line envelope: the kind discriminator plus the record fields. */\nfunction storeOperationEnvelope(operation: DurableStoreOperationV1): Record<string, unknown> {\n\treturn { kind: operation.kind, ...operation.record };\n}\n\n/** Parses one log line; undefined when it is malformed (skipped and counted). */\nfunction parseStoreOperationLine(line: string): DurableStoreOperationV1 | undefined {\n\ttry {\n\t\tconst value: unknown = JSON.parse(line);\n\t\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return undefined;\n\t\tconst record = value as Record<string, unknown>;\n\t\tswitch (record.kind) {\n\t\t\tcase \"session\": {\n\t\t\t\tconst base = importRecordBase(record, \"sessionId\", \"Durable store session record\");\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"session\",\n\t\t\t\t\trecord: { sessionId: base.id, data: base.data, persistedAt: base.persistedAt },\n\t\t\t\t};\n\t\t\t}\n\t\t\tcase \"operation\": {\n\t\t\t\tconst base = importRecordBase(record, \"operationId\", \"Durable store operation record\");\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"operation\",\n\t\t\t\t\trecord: {\n\t\t\t\t\t\toperationId: base.id,\n\t\t\t\t\t\tsessionId: importOwningSessionId(record, \"Durable store operation record\"),\n\t\t\t\t\t\tdata: base.data,\n\t\t\t\t\t\tpersistedAt: base.persistedAt,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\t\t\tcase \"artifact\": {\n\t\t\t\tconst base = importRecordBase(record, \"artifactId\", \"Durable store artifact record\");\n\t\t\t\treturn {\n\t\t\t\t\tkind: \"artifact\",\n\t\t\t\t\trecord: {\n\t\t\t\t\t\tartifactId: base.id,\n\t\t\t\t\t\tsessionId: importOwningSessionId(record, \"Durable store artifact record\"),\n\t\t\t\t\t\tdata: base.data,\n\t\t\t\t\t\tpersistedAt: base.persistedAt,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t}\n\t\t\tdefault:\n\t\t\t\treturn undefined;\n\t\t}\n\t} catch {\n\t\t// Corruption tolerance: a malformed line is skipped and counted — a\n\t\t// damaged log must never fail the startup replay.\n\t\treturn undefined;\n\t}\n}\n\nexport interface DurableServiceOptionsV1 {\n\t/** Deterministic clock for `persistedAt`/`exportedAt`; defaults to `Date.now`. */\n\treadonly now?: () => number;\n\t/**\n\t * Optional durable log backend. Without it the service stays purely\n\t * in-memory (backward-compatible MVP behavior); with it every committed\n\t * record is appended to the backend log before the in-memory maps update\n\t * (write-ahead: an append failure leaves memory untouched) and the log is\n\t * replayed at construction to restore state.\n\t */\n\treadonly backend?: DurableStoreBackend;\n}\n\nfunction assertObject(value: unknown, label: string): asserts value is Record<string, unknown> {\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new Error(t(\"{label} must be an object\", { label }));\n\t}\n}\n\ninterface ImportedRecordV1 {\n\treadonly id: string;\n\treadonly data: unknown;\n\treadonly persistedAt: number;\n}\n\nfunction importRecordBase(\n\tvalue: Record<string, unknown>,\n\tidField: \"sessionId\" | \"operationId\" | \"artifactId\",\n\tlabel: string,\n): ImportedRecordV1 {\n\tconst id = value[idField];\n\tif (typeof id !== \"string\" || id.length === 0)\n\t\tthrow new Error(t(\"{label} {idField} must be a non-empty string\", { label, idField }));\n\tconst persistedAt = value.persistedAt;\n\tif (typeof persistedAt !== \"number\" || !Number.isFinite(persistedAt)) {\n\t\tthrow new Error(t(\"{label} persistedAt must be a finite number\", { label }));\n\t}\n\t// Legacy (pre-单机收敛) log lines and snapshots may carry a `tenantId` key\n\t// from the removed multi-tenant machinery; it is tolerated as an ignored\n\t// extra key (D-068 增补 1), so it is simply never read here.\n\treturn { id, data: value.data, persistedAt };\n}\n\nfunction importOwningSessionId(value: Record<string, unknown>, label: string): string {\n\tconst sessionId = value.sessionId;\n\tif (typeof sessionId !== \"string\" || sessionId.length === 0) {\n\t\tthrow new Error(t(\"{label} sessionId must be a non-empty string\", { label }));\n\t}\n\treturn sessionId;\n}\n\nexport function createDurableService(options: DurableServiceOptionsV1 = {}): DurableServiceV1 {\n\tconst now = options.now ?? (() => Date.now());\n\tconst sessions = new Map<string, DurableSessionRecordV1>();\n\tconst operations = new Map<string, DurableOperationRecordV1>();\n\tconst artifacts = new Map<string, DurableArtifactRecordV1>();\n\n\t/** Current lease holder; `null` when unclaimed or crash-pending. */\n\tlet holder: string | null = null;\n\t/** Writer found dead in a restored snapshot; blocks claims and writes until recovered. */\n\tlet crashPending: string | null = null;\n\n\t// Startup replay (durable 落盘): with a backend, the log is the source of\n\t// truth for records — replay restores the maps with last-write-wins, the\n\t// same semantics as live persists. With a backend lease (D-067 phase 2\n\t// S2) the writer lease resolves against the store (cross-process mutual\n\t// exclusion, TTL crash recovery); without one it stays process-local.\n\tconst backend = options.backend;\n\tconst backendLease = backend?.lease;\n\tlet replay: DurableReplayDiagnosticsV1 = { corruptedLines: 0, unreadable: false };\n\tif (backend) {\n\t\tconst loaded = backend.load();\n\t\tfor (const operation of loaded.operations) {\n\t\t\tswitch (operation.kind) {\n\t\t\t\tcase \"session\":\n\t\t\t\t\tsessions.set(operation.record.sessionId, operation.record);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"operation\":\n\t\t\t\t\toperations.set(operation.record.operationId, operation.record);\n\t\t\t\t\tbreak;\n\t\t\t\tcase \"artifact\":\n\t\t\t\t\tartifacts.set(operation.record.artifactId, operation.record);\n\t\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t\treplay = { corruptedLines: loaded.corruptedLines, unreadable: loaded.unreadable };\n\t}\n\n\t/** Write-ahead log append; an append failure leaves the maps untouched. */\n\tconst logOperation = (operation: DurableStoreOperationV1): void => {\n\t\tif (backend) backend.persist([operation]);\n\t};\n\n\tfunction requireWriter(writerId: string): void {\n\t\tif (holder !== writerId) {\n\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\"not_writer\",\n\t\t\t\tt(\"Writer {writerId} does not hold the writer lease\", { writerId }),\n\t\t\t);\n\t\t}\n\t\t// Store-level heartbeat + liveness check (D-067 phase 2 S2): another\n\t\t// process recovering our expired lease fail-closes this write instead\n\t\t// of letting a stale writer interleave records.\n\t\tbackendLease?.renew(writerId);\n\t}\n\n\treturn {\n\t\tpersistSession(input) {\n\t\t\trequireWriter(input.writerId);\n\t\t\tconst record: DurableSessionRecordV1 = {\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tdata: input.data,\n\t\t\t\tpersistedAt: now(),\n\t\t\t};\n\t\t\tlogOperation({ kind: \"session\", record });\n\t\t\tsessions.set(input.sessionId, record);\n\t\t\treturn record;\n\t\t},\n\t\tloadSession(input) {\n\t\t\treturn sessions.get(input.sessionId);\n\t\t},\n\t\tpersistOperation(input) {\n\t\t\trequireWriter(input.writerId);\n\t\t\tconst record: DurableOperationRecordV1 = {\n\t\t\t\toperationId: input.operationId,\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tdata: input.data,\n\t\t\t\tpersistedAt: now(),\n\t\t\t};\n\t\t\tlogOperation({ kind: \"operation\", record });\n\t\t\toperations.set(input.operationId, record);\n\t\t\treturn record;\n\t\t},\n\t\tloadOperation(input) {\n\t\t\treturn operations.get(input.operationId);\n\t\t},\n\t\tpersistArtifact(input) {\n\t\t\trequireWriter(input.writerId);\n\t\t\tconst record: DurableArtifactRecordV1 = {\n\t\t\t\tartifactId: input.artifactId,\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tdata: input.data,\n\t\t\t\tpersistedAt: now(),\n\t\t\t};\n\t\t\tlogOperation({ kind: \"artifact\", record });\n\t\t\tartifacts.set(input.artifactId, record);\n\t\t\treturn record;\n\t\t},\n\t\tloadArtifact(input) {\n\t\t\treturn artifacts.get(input.artifactId);\n\t\t},\n\t\tlistSessions() {\n\t\t\treturn (\n\t\t\t\t[...sessions.values()]\n\t\t\t\t\t// v8 ignore next -- sessionId 是 Map 键恒唯一，相等比较路径不可达\n\t\t\t\t\t.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0))\n\t\t\t);\n\t\t},\n\t\tclaimWriter(writerId) {\n\t\t\tif (crashPending !== null) return { status: \"held\", by: crashPending };\n\t\t\tif (backendLease === undefined) {\n\t\t\t\tif (holder !== null && holder !== writerId) return { status: \"held\", by: holder };\n\t\t\t\tholder = writerId;\n\t\t\t\treturn { status: \"claimed\" };\n\t\t\t}\n\t\t\tconst result = backendLease.claim(writerId);\n\t\t\tif (result.status === \"claimed\") {\n\t\t\t\tholder = writerId;\n\t\t\t\treturn { status: \"claimed\" };\n\t\t\t}\n\t\t\treturn { status: \"held\", by: result.by };\n\t\t},\n\t\treleaseWriter(writerId) {\n\t\t\tif (crashPending !== null) {\n\t\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\t\"not_writer\",\n\t\t\t\t\tt(\"Writer {writerId} cannot release a crashed lease; recover it instead\", { writerId }),\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (backendLease === undefined) {\n\t\t\t\tif (holder !== null && holder !== writerId) {\n\t\t\t\t\tthrow new DurableServiceErrorV1(\n\t\t\t\t\t\t\"not_writer\",\n\t\t\t\t\t\tt(\"Writer {writerId} does not hold the writer lease (held by {holder})\", { writerId, holder }),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tholder = null;\n\t\t\t\treturn { status: \"released\" };\n\t\t\t}\n\t\t\tconst result = backendLease.release(writerId);\n\t\t\tholder = null;\n\t\t\treturn result;\n\t\t},\n\t\trecoverWriter(writerId) {\n\t\t\tif (crashPending !== null) {\n\t\t\t\tconst previousWriter = crashPending;\n\t\t\t\tcrashPending = null;\n\t\t\t\tholder = writerId;\n\t\t\t\treturn { status: \"recovered\", previousWriter };\n\t\t\t}\n\t\t\tif (backendLease === undefined) {\n\t\t\t\tif (holder !== null && holder !== writerId) return { status: \"held\" };\n\t\t\t\tholder = writerId;\n\t\t\t\treturn { status: \"recovered\" };\n\t\t\t}\n\t\t\tconst result = backendLease.recover(writerId);\n\t\t\tif (result.status === \"recovered\") {\n\t\t\t\tholder = writerId;\n\t\t\t\treturn result.previousWriter === undefined\n\t\t\t\t\t? { status: \"recovered\" }\n\t\t\t\t\t: { status: \"recovered\", previousWriter: result.previousWriter };\n\t\t\t}\n\t\t\treturn { status: \"held\" };\n\t\t},\n\t\treadiness() {\n\t\t\tif (crashPending !== null) {\n\t\t\t\treturn { ready: false, reason: `writer crash is pending recovery: ${crashPending}` };\n\t\t\t}\n\t\t\tif (holder === null) {\n\t\t\t\treturn { ready: false, reason: \"no writer has claimed the lease\" };\n\t\t\t}\n\t\t\treturn { ready: true };\n\t\t},\n\t\texportState() {\n\t\t\treturn {\n\t\t\t\tversion: 1 as const,\n\t\t\t\texportedAt: now(),\n\t\t\t\tsessions: [...sessions.values()],\n\t\t\t\toperations: [...operations.values()],\n\t\t\t\tartifacts: [...artifacts.values()],\n\t\t\t\twriter: { holder, crashPending },\n\t\t\t};\n\t\t},\n\t\timportState(snapshot) {\n\t\t\tassertObject(snapshot, \"Durable snapshot\");\n\t\t\tif (snapshot.version !== 1) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\tt(\"Unsupported durable snapshot version: {version}\", { version: String(snapshot.version) }),\n\t\t\t\t);\n\t\t\t}\n\t\t\tfor (const field of [\"sessions\", \"operations\", \"artifacts\"] as const) {\n\t\t\t\tif (!Array.isArray(snapshot[field]))\n\t\t\t\t\tthrow new Error(t(\"Durable snapshot {field} must be an array\", { field }));\n\t\t\t}\n\t\t\tconst writer = snapshot.writer;\n\t\t\tassertObject(writer, \"Durable snapshot writer\");\n\t\t\tconst snapshotHolder = writer.holder;\n\t\t\tconst snapshotCrashPending = writer.crashPending;\n\t\t\tif (snapshotHolder !== null && typeof snapshotHolder !== \"string\") {\n\t\t\t\tthrow new Error(t(\"Durable snapshot writer holder must be a string or null\"));\n\t\t\t}\n\t\t\tif (snapshotCrashPending !== null && typeof snapshotCrashPending !== \"string\") {\n\t\t\t\tthrow new Error(t(\"Durable snapshot writer crashPending must be a string or null\"));\n\t\t\t}\n\n\t\t\tconst importedSessions = new Map<string, DurableSessionRecordV1>();\n\t\t\tfor (const raw of snapshot.sessions as unknown[]) {\n\t\t\t\tassertObject(raw, \"Durable snapshot session\");\n\t\t\t\tconst record = importRecordBase(raw, \"sessionId\", \"Durable snapshot session\");\n\t\t\t\timportedSessions.set(record.id, {\n\t\t\t\t\tsessionId: record.id,\n\t\t\t\t\tdata: record.data,\n\t\t\t\t\tpersistedAt: record.persistedAt,\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst importedOperations = new Map<string, DurableOperationRecordV1>();\n\t\t\tfor (const raw of snapshot.operations as unknown[]) {\n\t\t\t\tassertObject(raw, \"Durable snapshot operation\");\n\t\t\t\tconst record = importRecordBase(raw, \"operationId\", \"Durable snapshot operation\");\n\t\t\t\timportedOperations.set(record.id, {\n\t\t\t\t\toperationId: record.id,\n\t\t\t\t\tsessionId: importOwningSessionId(raw, \"Durable snapshot operation\"),\n\t\t\t\t\tdata: record.data,\n\t\t\t\t\tpersistedAt: record.persistedAt,\n\t\t\t\t});\n\t\t\t}\n\t\t\tconst importedArtifacts = new Map<string, DurableArtifactRecordV1>();\n\t\t\tfor (const raw of snapshot.artifacts as unknown[]) {\n\t\t\t\tassertObject(raw, \"Durable snapshot artifact\");\n\t\t\t\tconst record = importRecordBase(raw, \"artifactId\", \"Durable snapshot artifact\");\n\t\t\t\timportedArtifacts.set(record.id, {\n\t\t\t\t\tartifactId: record.id,\n\t\t\t\t\tsessionId: importOwningSessionId(raw, \"Durable snapshot artifact\"),\n\t\t\t\t\tdata: record.data,\n\t\t\t\t\tpersistedAt: record.persistedAt,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tsessions.clear();\n\t\t\tfor (const [id, record] of importedSessions) sessions.set(id, record);\n\t\t\toperations.clear();\n\t\t\tfor (const [id, record] of importedOperations) operations.set(id, record);\n\t\t\tartifacts.clear();\n\t\t\tfor (const [id, record] of importedArtifacts) artifacts.set(id, record);\n\n\t\t\t// A writer recorded in the snapshot belonged to the process that\n\t\t\t// produced it; it cannot be alive in this one, so its lease needs\n\t\t\t// recovery before anyone may write again.\n\t\t\tholder = null;\n\t\t\tcrashPending = snapshotHolder ?? snapshotCrashPending;\n\t\t},\n\t\treplayDiagnostics() {\n\t\t\treturn replay;\n\t\t},\n\t};\n}\n"]}

package/dist/durable/durable-service.js

@@ -38,6 +38,7 @@
 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";
+import { t } from "../core/i18n/index.js";
 export class DurableServiceErrorV1 extends Error {
     code;
     constructor(code, message) {
@@ -52,7 +53,7 @@ export function durableLogPath(agentDir, sessionId) {
 }
 function assertNonEmptyString(value, label) {
     if (typeof value !== "string" || value.trim().length === 0)
-        throw new Error(`${label} must be a non-empty string`);
+        throw new Error(t("{label} must be a non-empty string", { label }));
 }
 /**
  * Writes every byte of `data` to the fd, looping over partial `writeSync`
@@ -180,7 +181,10 @@ function acquirePersistLock(lockPath, lockTimeoutMs, staleLockMs) {
                 continue;
             }
             if (Date.now() >= deadline) {
-                throw new Error(`durable store persist lock timeout after ${lockTimeoutMs} ms: ${lockPath} is held by another writer`);
+                throw new Error(t("durable store persist lock timeout after {timeoutMs} ms: {lockPath} is held by another writer", {
+                    timeoutMs: lockTimeoutMs,
+                    lockPath,
+                }));
             }
             sleepSync(LOCK_POLL_INTERVAL_MS);
         }
@@ -218,13 +222,13 @@ function releasePersistLock(lockPath, token) {
 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");
+        throw new Error(t("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");
+        throw new Error(t("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");
+        throw new Error(t("Durable store leaseTtlMs must be a positive number"));
     }
     const path = options.path;
     const lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
@@ -293,7 +297,10 @@ export function createFileDurableStoreBackend(options) {
                     }
                     return { status: "released" };
                 }
-                throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} does not hold the store lease (held by ${current.writerId})`);
+                throw new DurableServiceErrorV1("not_writer", t("Writer {writerId} does not hold the store lease (held by {holder})", {
+                    writerId,
+                    holder: current.writerId,
+                }));
             }
             finally {
                 releasePersistLock(lockPath, token);
@@ -318,7 +325,7 @@ export function createFileDurableStoreBackend(options) {
             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)`);
+                    throw new DurableServiceErrorV1("not_writer", t("Writer {writerId} lost the store lease (expired or recovered by another writer)", { writerId }));
                 }
                 writeLease(writerId, Date.now() + leaseTtlMs);
             }
@@ -443,16 +450,16 @@ function parseStoreOperationLine(line) {
 }
 function assertObject(value, label) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw new Error(`${label} must be an object`);
+        throw new Error(t("{label} must be an object", { label }));
     }
 }
 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`);
+        throw new Error(t("{label} {idField} must be a non-empty string", { label, idField }));
     const persistedAt = value.persistedAt;
     if (typeof persistedAt !== "number" || !Number.isFinite(persistedAt)) {
-        throw new Error(`${label} persistedAt must be a finite number`);
+        throw new Error(t("{label} persistedAt must be a finite number", { label }));
     }
     // Legacy (pre-单机收敛) log lines and snapshots may carry a `tenantId` key
     // from the removed multi-tenant machinery; it is tolerated as an ignored
@@ -462,7 +469,7 @@ function importRecordBase(value, idField, label) {
 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`);
+        throw new Error(t("{label} sessionId must be a non-empty string", { label }));
     }
     return sessionId;
 }
@@ -507,7 +514,7 @@ export function createDurableService(options = {}) {
     };
     function requireWriter(writerId) {
         if (holder !== writerId) {
-            throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} does not hold the writer lease`);
+            throw new DurableServiceErrorV1("not_writer", t("Writer {writerId} does not hold the writer lease", { writerId }));
         }
         // Store-level heartbeat + liveness check (D-067 phase 2 S2): another
         // process recovering our expired lease fail-closes this write instead
@@ -582,11 +589,11 @@ export function createDurableService(options = {}) {
         },
         releaseWriter(writerId) {
             if (crashPending !== null) {
-                throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} cannot release a crashed lease; recover it instead`);
+                throw new DurableServiceErrorV1("not_writer", t("Writer {writerId} cannot release a crashed lease; recover it instead", { writerId }));
             }
             if (backendLease === undefined) {
                 if (holder !== null && holder !== writerId) {
-                    throw new DurableServiceErrorV1("not_writer", `Writer ${writerId} does not hold the writer lease (held by ${holder})`);
+                    throw new DurableServiceErrorV1("not_writer", t("Writer {writerId} does not hold the writer lease (held by {holder})", { writerId, holder }));
                 }
                 holder = null;
                 return { status: "released" };
@@ -639,21 +646,21 @@ export function createDurableService(options = {}) {
         importState(snapshot) {
             assertObject(snapshot, "Durable snapshot");
             if (snapshot.version !== 1) {
-                throw new Error(`Unsupported durable snapshot version: ${String(snapshot.version)}`);
+                throw new Error(t("Unsupported durable snapshot version: {version}", { 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`);
+                    throw new Error(t("Durable snapshot {field} must be an array", { field }));
             }
             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");
+                throw new Error(t("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");
+                throw new Error(t("Durable snapshot writer crashPending must be a string or null"));
             }
             const importedSessions = new Map();
             for (const raw of snapshot.sessions) {