@ai-agent-forge/agent-forge 0.85.0

package/dist/core/trace-retention.js

@@ -0,0 +1,91 @@
+import { readdirSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Trace-file retention sweep (设计 docs/design/会话轨迹与日志设计.md §6 轨迹保留).
+ *
+ * Deletes expired `*.trace.jsonl` files from a sessions root — the root itself
+ * plus its direct subdirectories, one level deep, matching where trace files
+ * are written next to their sessions (per-project session directories and the
+ * `_agents` subagent directory).
+ *
+ * Safety invariants:
+ * - Only the exact `.trace.jsonl` suffix is ever deleted; session `.jsonl`
+ *   files (and any other suffix) are never touched.
+ * - Scope is the caller's choice. main.ts sweeps only the default sessions
+ *   root (`getSessionsDir()`); a custom `--session-dir` is NOT swept.
+ * - Retention is opt-in: with `maxAgeDays <= 0` the sweep short-circuits with
+ *   no filesystem access at all (the default is permanent retention).
+ *
+ * Failure contract: the sweep never throws. Unreadable directories and
+ * unreadable file stats contribute nothing (treated as 0); delete failures
+ * are counted per file without interrupting the rest. The caller surfaces the
+ * summary through the host logger (deleted > 0 → info, failed > 0 → warn).
+ */
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Exact trace-file suffix; a session `.jsonl` file can never match it. */
+const TRACE_FILE_SUFFIX = ".trace.jsonl";
+export function sweepTraceFiles(sessionsRoot, options) {
+    if (options.maxAgeDays <= 0) {
+        return { scanned: 0, deleted: 0, failed: 0 };
+    }
+    const now = options.now ?? Date.now;
+    const unlink = options.unlink ?? ((path) => unlinkSync(path));
+    const cutoff = now() - options.maxAgeDays * DAY_MS;
+    let scanned = 0;
+    let deleted = 0;
+    let failed = 0;
+    const readEntries = (dir) => {
+        try {
+            return readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            // Unreadable location contributes nothing and never throws.
+            return undefined;
+        }
+    };
+    const sweepFilesIn = (dir, entries) => {
+        for (const entry of entries) {
+            if (!entry.name.endsWith(TRACE_FILE_SUFFIX))
+                continue;
+            const fullPath = join(dir, entry.name);
+            let isFile = false;
+            let isExpired = false;
+            try {
+                const stats = statSync(fullPath);
+                isFile = stats.isFile();
+                isExpired = isFile && stats.mtimeMs < cutoff;
+            }
+            catch {
+                continue; // Unreadable stat contributes nothing and never throws.
+            }
+            if (!isFile)
+                continue; // A directory named *.trace.jsonl is never swept.
+            scanned += 1;
+            if (!isExpired)
+                continue;
+            try {
+                unlink(fullPath);
+                deleted += 1;
+            }
+            catch {
+                failed += 1;
+            }
+        }
+    };
+    const rootEntries = readEntries(sessionsRoot);
+    if (rootEntries === undefined) {
+        return { scanned: 0, deleted: 0, failed: 0 };
+    }
+    sweepFilesIn(sessionsRoot, rootEntries);
+    for (const entry of rootEntries) {
+        if (!entry.isDirectory())
+            continue;
+        const subdirectory = join(sessionsRoot, entry.name);
+        const subEntries = readEntries(subdirectory);
+        if (subEntries !== undefined) {
+            sweepFilesIn(subdirectory, subEntries);
+        }
+    }
+    return { scanned, deleted, failed };
+}
+//# sourceMappingURL=trace-retention.js.map

package/dist/core/trace-retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-retention.js","sourceRoot":"","sources":["../../src/core/trace-retention.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Dirent, readdirSync, statSync, unlinkSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\n/**\n * Trace-file retention sweep (设计 docs/design/会话轨迹与日志设计.md §6 轨迹保留).\n *\n * Deletes expired `*.trace.jsonl` files from a sessions root — the root itself\n * plus its direct subdirectories, one level deep, matching where trace files\n * are written next to their sessions (per-project session directories and the\n * `_agents` subagent directory).\n *\n * Safety invariants:\n * - Only the exact `.trace.jsonl` suffix is ever deleted; session `.jsonl`\n *   files (and any other suffix) are never touched.\n * - Scope is the caller's choice. main.ts sweeps only the default sessions\n *   root (`getSessionsDir()`); a custom `--session-dir` is NOT swept.\n * - Retention is opt-in: with `maxAgeDays <= 0` the sweep short-circuits with\n *   no filesystem access at all (the default is permanent retention).\n *\n * Failure contract: the sweep never throws. Unreadable directories and\n * unreadable file stats contribute nothing (treated as 0); delete failures\n * are counted per file without interrupting the rest. The caller surfaces the\n * summary through the host logger (deleted > 0 → info, failed > 0 → warn).\n */\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\n\n/** Exact trace-file suffix; a session `.jsonl` file can never match it. */\nconst TRACE_FILE_SUFFIX = \".trace.jsonl\";\n\n/** Structured sweep summary returned to the caller for logging. */\nexport interface TraceSweepSummary {\n\t/** Trace files evaluated against the cutoff (expired and kept alike). */\n\treadonly scanned: number;\n\t/** Files successfully removed. */\n\treadonly deleted: number;\n\t/** Files whose removal failed; each failure is counted, none interrupt the sweep. */\n\treadonly failed: number;\n}\n\nexport interface SweepTraceFilesOptions {\n\t/** Retention window in days; files older than this are removed. `<= 0` disables sweeping. */\n\treadonly maxAgeDays: number;\n\t/** Injectable clock for deterministic tests. Default `Date.now`. */\n\treadonly now?: () => number;\n\t/** Injectable delete for failure-counting tests. Default `node:fs.unlinkSync`. */\n\treadonly unlink?: (path: string) => void;\n}\n\nexport function sweepTraceFiles(sessionsRoot: string, options: SweepTraceFilesOptions): TraceSweepSummary {\n\tif (options.maxAgeDays <= 0) {\n\t\treturn { scanned: 0, deleted: 0, failed: 0 };\n\t}\n\tconst now = options.now ?? Date.now;\n\tconst unlink = options.unlink ?? ((path: string): void => unlinkSync(path));\n\tconst cutoff = now() - options.maxAgeDays * DAY_MS;\n\n\tlet scanned = 0;\n\tlet deleted = 0;\n\tlet failed = 0;\n\n\tconst readEntries = (dir: string): readonly Dirent[] | undefined => {\n\t\ttry {\n\t\t\treturn readdirSync(dir, { withFileTypes: true });\n\t\t} catch {\n\t\t\t// Unreadable location contributes nothing and never throws.\n\t\t\treturn undefined;\n\t\t}\n\t};\n\n\tconst sweepFilesIn = (dir: string, entries: readonly Dirent[]): void => {\n\t\tfor (const entry of entries) {\n\t\t\tif (!entry.name.endsWith(TRACE_FILE_SUFFIX)) continue;\n\t\t\tconst fullPath = join(dir, entry.name);\n\t\t\tlet isFile = false;\n\t\t\tlet isExpired = false;\n\t\t\ttry {\n\t\t\t\tconst stats = statSync(fullPath);\n\t\t\t\tisFile = stats.isFile();\n\t\t\t\tisExpired = isFile && stats.mtimeMs < cutoff;\n\t\t\t} catch {\n\t\t\t\tcontinue; // Unreadable stat contributes nothing and never throws.\n\t\t\t}\n\t\t\tif (!isFile) continue; // A directory named *.trace.jsonl is never swept.\n\t\t\tscanned += 1;\n\t\t\tif (!isExpired) continue;\n\t\t\ttry {\n\t\t\t\tunlink(fullPath);\n\t\t\t\tdeleted += 1;\n\t\t\t} catch {\n\t\t\t\tfailed += 1;\n\t\t\t}\n\t\t}\n\t};\n\n\tconst rootEntries = readEntries(sessionsRoot);\n\tif (rootEntries === undefined) {\n\t\treturn { scanned: 0, deleted: 0, failed: 0 };\n\t}\n\tsweepFilesIn(sessionsRoot, rootEntries);\n\tfor (const entry of rootEntries) {\n\t\tif (!entry.isDirectory()) continue;\n\t\tconst subdirectory = join(sessionsRoot, entry.name);\n\t\tconst subEntries = readEntries(subdirectory);\n\t\tif (subEntries !== undefined) {\n\t\t\tsweepFilesIn(subdirectory, subEntries);\n\t\t}\n\t}\n\n\treturn { scanned, deleted, failed };\n}\n"]}

package/dist/core/usage-totals.d.ts

@@ -0,0 +1,21 @@
+import type { Usage } from "@agent-forge/ai/compat";
+import type { SessionEntry } from "./session-manager.ts";
+export interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}
+export declare function createUsageTotals(): UsageTotals;
+export declare function addUsageToTotals(totals: UsageTotals, usage: Usage): void;
+export interface UsageCostBreakdownEntry {
+    key: string;
+    cost: number;
+    tokens: number;
+    /** 该桶的完整用量拆分（含缓存读/写），供 TUI 双维度展示（总计 + 按供应商/模型）。 */
+    totals: UsageTotals;
+}
+/** Group attributable assistant usage by model and all other usage into a separate bucket. */
+export declare function getUsageCostBreakdown(entries: SessionEntry[]): UsageCostBreakdownEntry[];
+//# sourceMappingURL=usage-totals.d.ts.map

package/dist/core/usage-totals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-totals.d.ts","sourceRoot":"","sources":["../../src/core/usage-totals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAQ/C;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAMxE;AAED,MAAM,WAAW,uBAAuB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,uHAAmD;IACnD,MAAM,EAAE,WAAW,CAAC;CACpB;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,uBAAuB,EAAE,CAkCxF","sourcesContent":["import type { Usage } from \"@agent-forge/ai/compat\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\nexport interface UsageTotals {\n\tinput: number;\n\toutput: number;\n\tcacheRead: number;\n\tcacheWrite: number;\n\tcost: number;\n}\n\nexport function createUsageTotals(): UsageTotals {\n\treturn {\n\t\tinput: 0,\n\t\toutput: 0,\n\t\tcacheRead: 0,\n\t\tcacheWrite: 0,\n\t\tcost: 0,\n\t};\n}\n\nexport function addUsageToTotals(totals: UsageTotals, usage: Usage): void {\n\ttotals.input += usage.input;\n\ttotals.output += usage.output;\n\ttotals.cacheRead += usage.cacheRead;\n\ttotals.cacheWrite += usage.cacheWrite;\n\ttotals.cost += usage.cost.total;\n}\n\nexport interface UsageCostBreakdownEntry {\n\tkey: string;\n\tcost: number;\n\ttokens: number;\n\t/** 该桶的完整用量拆分（含缓存读/写），供 TUI 双维度展示（总计 + 按供应商/模型）。 */\n\ttotals: UsageTotals;\n}\n\n/** Group attributable assistant usage by model and all other usage into a separate bucket. */\nexport function getUsageCostBreakdown(entries: SessionEntry[]): UsageCostBreakdownEntry[] {\n\tconst totalsByKey = new Map<string, UsageTotals>();\n\n\tfor (const entry of entries) {\n\t\tlet key: string | undefined;\n\t\tlet usage: Usage | undefined;\n\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tkey = `${entry.message.provider}/${entry.message.responseModel ?? entry.message.model}`;\n\t\t\tusage = entry.message.usage;\n\t\t} else if (entry.type === \"message\" && entry.message.role === \"toolResult\" && entry.message.usage) {\n\t\t\tkey = \"Tools/summaries\";\n\t\t\tusage = entry.message.usage;\n\t\t} else if ((entry.type === \"branch_summary\" || entry.type === \"compaction\") && entry.usage) {\n\t\t\tkey = \"Tools/summaries\";\n\t\t\tusage = entry.usage;\n\t\t}\n\t\tif (!key || !usage) continue;\n\n\t\tlet totals = totalsByKey.get(key);\n\t\tif (!totals) {\n\t\t\ttotals = createUsageTotals();\n\t\t\ttotalsByKey.set(key, totals);\n\t\t}\n\t\taddUsageToTotals(totals, usage);\n\t}\n\n\treturn Array.from(totalsByKey, ([key, totals]) => ({\n\t\tkey,\n\t\tcost: totals.cost,\n\t\ttokens: totals.input + totals.output + totals.cacheRead + totals.cacheWrite,\n\t\ttotals,\n\t}))\n\t\t.filter((entry) => entry.cost > 0 || entry.tokens > 0)\n\t\t.sort((a, b) => b.cost - a.cost);\n}\n"]}

package/dist/core/usage-totals.js

@@ -0,0 +1,53 @@
+export function createUsageTotals() {
+    return {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        cost: 0,
+    };
+}
+export function addUsageToTotals(totals, usage) {
+    totals.input += usage.input;
+    totals.output += usage.output;
+    totals.cacheRead += usage.cacheRead;
+    totals.cacheWrite += usage.cacheWrite;
+    totals.cost += usage.cost.total;
+}
+/** Group attributable assistant usage by model and all other usage into a separate bucket. */
+export function getUsageCostBreakdown(entries) {
+    const totalsByKey = new Map();
+    for (const entry of entries) {
+        let key;
+        let usage;
+        if (entry.type === "message" && entry.message.role === "assistant") {
+            key = `${entry.message.provider}/${entry.message.responseModel ?? entry.message.model}`;
+            usage = entry.message.usage;
+        }
+        else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage) {
+            key = "Tools/summaries";
+            usage = entry.message.usage;
+        }
+        else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage) {
+            key = "Tools/summaries";
+            usage = entry.usage;
+        }
+        if (!key || !usage)
+            continue;
+        let totals = totalsByKey.get(key);
+        if (!totals) {
+            totals = createUsageTotals();
+            totalsByKey.set(key, totals);
+        }
+        addUsageToTotals(totals, usage);
+    }
+    return Array.from(totalsByKey, ([key, totals]) => ({
+        key,
+        cost: totals.cost,
+        tokens: totals.input + totals.output + totals.cacheRead + totals.cacheWrite,
+        totals,
+    }))
+        .filter((entry) => entry.cost > 0 || entry.tokens > 0)
+        .sort((a, b) => b.cost - a.cost);
+}
+//# sourceMappingURL=usage-totals.js.map

package/dist/core/usage-totals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-totals.js","sourceRoot":"","sources":["../../src/core/usage-totals.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Usage } from \"@agent-forge/ai/compat\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\nexport interface UsageTotals {\n\tinput: number;\n\toutput: number;\n\tcacheRead: number;\n\tcacheWrite: number;\n\tcost: number;\n}\n\nexport function createUsageTotals(): UsageTotals {\n\treturn {\n\t\tinput: 0,\n\t\toutput: 0,\n\t\tcacheRead: 0,\n\t\tcacheWrite: 0,\n\t\tcost: 0,\n\t};\n}\n\nexport function addUsageToTotals(totals: UsageTotals, usage: Usage): void {\n\ttotals.input += usage.input;\n\ttotals.output += usage.output;\n\ttotals.cacheRead += usage.cacheRead;\n\ttotals.cacheWrite += usage.cacheWrite;\n\ttotals.cost += usage.cost.total;\n}\n\nexport interface UsageCostBreakdownEntry {\n\tkey: string;\n\tcost: number;\n\ttokens: number;\n\t/** 该桶的完整用量拆分（含缓存读/写），供 TUI 双维度展示（总计 + 按供应商/模型）。 */\n\ttotals: UsageTotals;\n}\n\n/** Group attributable assistant usage by model and all other usage into a separate bucket. */\nexport function getUsageCostBreakdown(entries: SessionEntry[]): UsageCostBreakdownEntry[] {\n\tconst totalsByKey = new Map<string, UsageTotals>();\n\n\tfor (const entry of entries) {\n\t\tlet key: string | undefined;\n\t\tlet usage: Usage | undefined;\n\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tkey = `${entry.message.provider}/${entry.message.responseModel ?? entry.message.model}`;\n\t\t\tusage = entry.message.usage;\n\t\t} else if (entry.type === \"message\" && entry.message.role === \"toolResult\" && entry.message.usage) {\n\t\t\tkey = \"Tools/summaries\";\n\t\t\tusage = entry.message.usage;\n\t\t} else if ((entry.type === \"branch_summary\" || entry.type === \"compaction\") && entry.usage) {\n\t\t\tkey = \"Tools/summaries\";\n\t\t\tusage = entry.usage;\n\t\t}\n\t\tif (!key || !usage) continue;\n\n\t\tlet totals = totalsByKey.get(key);\n\t\tif (!totals) {\n\t\t\ttotals = createUsageTotals();\n\t\t\ttotalsByKey.set(key, totals);\n\t\t}\n\t\taddUsageToTotals(totals, usage);\n\t}\n\n\treturn Array.from(totalsByKey, ([key, totals]) => ({\n\t\tkey,\n\t\tcost: totals.cost,\n\t\ttokens: totals.input + totals.output + totals.cacheRead + totals.cacheWrite,\n\t\ttotals,\n\t}))\n\t\t.filter((entry) => entry.cost > 0 || entry.tokens > 0)\n\t\t.sort((a, b) => b.cost - a.cost);\n}\n"]}

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

@@ -0,0 +1,136 @@
+export type { DurableArtifactRecordV1, DurableOperationRecordV1, DurableReadinessV1, DurableReplayDiagnosticsV1, DurableServiceV1, DurableSessionRecordV1, DurableSnapshotV1, DurableWriterClaimV1, DurableWriterRecoveryV1, } from "@agent-forge/plugin-sdk";
+import type { DurableArtifactRecordV1, DurableOperationRecordV1, DurableServiceV1, DurableSessionRecordV1 } from "@agent-forge/plugin-sdk";
+export type DurableServiceErrorCodeV1 = "not_writer";
+export declare class DurableServiceErrorV1 extends Error {
+    readonly code: DurableServiceErrorCodeV1;
+    constructor(code: DurableServiceErrorCodeV1, message: string);
+}
+/** One committed record as carried in a {@link DurableStoreBackend} log. */
+export type DurableStoreOperationV1 = {
+    readonly kind: "session";
+    readonly record: DurableSessionRecordV1;
+} | {
+    readonly kind: "operation";
+    readonly record: DurableOperationRecordV1;
+} | {
+    readonly kind: "artifact";
+    readonly record: DurableArtifactRecordV1;
+};
+/** Result of {@link DurableStoreBackend.load}: replayable operations plus skip diagnostics. */
+export interface DurableStoreLoadResultV1 {
+    /** Valid operations in log order — replay these into a fresh service. */
+    readonly operations: readonly DurableStoreOperationV1[];
+    /** Malformed lines (invalid JSON or invalid records) skipped during load. */
+    readonly corruptedLines: number;
+    /** True when the file existed but could not be read (permissions, IO error). */
+    readonly unreadable: boolean;
+}
+/**
+ * Durable log backend for {@link createDurableService}. The write path
+ * appends every committed record; the read path `load()`s the log at
+ * construction and replays it into the fresh in-memory maps (last write per
+ * id wins, matching live persist semantics). The default
+ * {@link FileDurableStoreBackend} never throws on load — corruption is
+ * skipped and counted — and the append path runs under a cross-process
+ * `.lock` file mutex and fsyncs, so hard crashes cannot lose the most recent
+ * appends and concurrent processes cannot interleave lines (a torn trailing
+ * line is still skipped by the loader's corruption tolerance). The lock
+ * covers file writes only: the writer lease stays process-local memory.
+ */
+export interface DurableStoreBackend {
+    /** Appends committed operations to the durable log, in order. */
+    persist(operations: readonly DurableStoreOperationV1[]): void;
+    /**
+     * Reads the whole log and returns the replayable operations plus skip
+     * diagnostics. A missing log is an empty backend, not an error; malformed
+     * lines are skipped and counted — load NEVER throws.
+     */
+    load(): DurableStoreLoadResultV1;
+    /** Releases backend resources. Idempotent; a no-op for the file backend. */
+    close(): void;
+    /**
+     * Optional store-level writer lease (D-067 phase 2 S2). When present, the
+     * service resolves its claim/recover/release against it, giving
+     * cross-process lease mutual exclusion and crash recovery by TTL; when
+     * absent, the writer lease stays process-local memory.
+     */
+    readonly lease?: DurableStoreLeaseV1;
+}
+/** Result of {@link DurableStoreLeaseV1.claim}. */
+export type DurableStoreLeaseClaimV1 = {
+    readonly status: "claimed";
+} | {
+    readonly status: "held";
+    readonly by: string;
+};
+/** Result of {@link DurableStoreLeaseV1.recover}. */
+export type DurableStoreLeaseRecoverV1 = {
+    readonly status: "recovered";
+    readonly previousWriter?: string;
+} | {
+    readonly status: "held";
+};
+/**
+ * Store-level writer lease: a TTL-based mutual-exclusion token over the whole
+ * store, visible across processes. `renew` is the heartbeat — the holder
+ * extends its TTL on every persist — and doubles as the liveness check: a
+ * writer whose lease expired (or was recovered by another process) fails its
+ * next renew with `not_writer`, so stale writes fail closed. All methods may
+ * throw `DurableServiceErrorV1` with code `not_writer`.
+ */
+export interface DurableStoreLeaseV1 {
+    /** Takes the lease; fails while a live foreign holder exists. Re-claim by the live holder refreshes it. */
+    claim(writerId: string): DurableStoreLeaseClaimV1;
+    /** Releases the lease when held by `writerId`; free/expired leases release idempotently; a foreign holder throws. */
+    release(writerId: string): {
+        readonly status: "released";
+    };
+    /** Takes over the lease of a holder whose TTL lapsed (dead process); a live foreign holder is reported as `held`. */
+    recover(writerId: string): DurableStoreLeaseRecoverV1;
+    /** Heartbeat: extends the holder's TTL; throws `not_writer` when the lease was lost or expired. */
+    renew(writerId: string): void;
+}
+/** The standard durable log path: `<agentDir>/durable/<sessionId>.jsonl`. */
+export declare function durableLogPath(agentDir: string, sessionId: string): string;
+/**
+ * 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 declare function createFileDurableStoreBackend(options: {
+    readonly path: string;
+    /** Wall-clock ceiling on waiting for a competing writer's lock; default 5 s. */
+    readonly lockTimeoutMs?: number;
+    /** Age at which a lock counts as abandoned and is stolen; default 60 s. */
+    readonly staleLockMs?: number;
+    /** Writer-lease TTL; the holder renews on every persist. Default 30 s. */
+    readonly leaseTtlMs?: number;
+}): DurableStoreBackend;
+export interface DurableServiceOptionsV1 {
+    /** Deterministic clock for `persistedAt`/`exportedAt`; defaults to `Date.now`. */
+    readonly now?: () => number;
+    /**
+     * Optional durable log backend. Without it the service stays purely
+     * in-memory (backward-compatible MVP behavior); with it every committed
+     * record is appended to the backend log before the in-memory maps update
+     * (write-ahead: an append failure leaves memory untouched) and the log is
+     * replayed at construction to restore state.
+     */
+    readonly backend?: DurableStoreBackend;
+}
+export declare function createDurableService(options?: DurableServiceOptionsV1): DurableServiceV1;
+//# sourceMappingURL=durable-service.d.ts.map

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

@@ -0,0 +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"]}