acp-kernel 0.0.39 → 0.0.41

package/dist/persist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Persistence subpath: crash-safe JSON state storage for downstream hosts.
+ *
+ * The kernel core is pure (no fs). This subpath is the ONLY kernel module
+ * that touches the filesystem, so hosts that never persist stay fs-free by
+ * not importing `acp-kernel/persist`.
+ *
+ * Division of responsibility:
+ * - store owns MECHANISM: atomic writes, rename retries, debounce,
+ *   serialization, discovery, corrupt-file tolerance
+ * - downstream owns POLICY: storage location (dir is a constructor
+ *   argument — the kernel has no default path), schema version, payload
+ *   shape, validation, and lifecycle (when to save, what to load)
+ * - the store never deletes files; cleanup is a downstream decision
+ */
+export { StateStore, flatFileNameFor } from "./store.js";
+export type { PersistedEnvelope, PersistLogger, StateStoreOptions } from "./store.js";
+export { mergeCompressionState } from "./state-merge.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/persist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/persist/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/persist/index.js

@@ -0,0 +1,367 @@
+import {
+  createInitialState
+} from "../chunk-DPH62BGM.js";
+
+// src/persist/store.ts
+import { createHash } from "crypto";
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+var StateStore = class {
+  enabled;
+  dir;
+  version;
+  debounceMs;
+  log;
+  legacyFn;
+  relPathFn;
+  validateFn;
+  timers = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  writeChains = /* @__PURE__ */ new Map();
+  /** id → absolute path, populated by writes and loadAll. */
+  discovered = /* @__PURE__ */ new Map();
+  /** Monotonic counter for unique temp filenames within a process. */
+  tmpSeq = 0;
+  constructor(opts) {
+    this.dir = opts.dir;
+    this.version = opts.version;
+    this.debounceMs = opts.debounceMs ?? 500;
+    this.enabled = opts.enabled ?? true;
+    this.log = opts.log ?? ((_level, _msg) => {
+    });
+    this.relPathFn = opts.relPath;
+    this.legacyFn = opts.legacy;
+    this.validateFn = opts.validate ?? defaultValidate;
+  }
+  /** Debounced save. Coalesces bursts; the builder runs at write time, so
+   *  the freshest state is always persisted. Never throws. */
+  scheduleSave(id, build) {
+    if (!this.enabled) return;
+    this.pending.set(id, build);
+    const existing = this.timers.get(id);
+    if (existing) return;
+    const timer = setTimeout(() => {
+      this.timers.delete(id);
+      const builder = this.pending.get(id);
+      this.pending.delete(id);
+      if (!builder) return;
+      void this.writeNow(id, builder).catch(() => {
+      });
+    }, this.debounceMs);
+    timer.unref?.();
+    this.timers.set(id, timer);
+  }
+  /** Immediate save, serialized per id. Rejects on write failure; a
+   *  failing write never breaks the chain for the next one. */
+  async writeNow(id, build) {
+    if (!this.enabled) return;
+    const prev = this.writeChains.get(id) ?? Promise.resolve();
+    const next = prev.catch(() => {
+    }).then(() => this.writeInner(id, build));
+    this.writeChains.set(id, next);
+    next.finally(() => {
+      if (this.writeChains.get(id) === next) this.writeChains.delete(id);
+    }).catch(() => {
+    });
+    return next;
+  }
+  /** Synchronous flush for one id. Used where the caller cannot await
+   *  (memory eviction, sync shutdown paths). Cancels any pending debounce
+   *  timer. Returns true on success, false on failure — callers that use
+   *  the result to drop in-memory state must NOT drop it on failure. */
+  flushSync(id, build) {
+    if (!this.enabled) return true;
+    const timer = this.timers.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(id);
+      this.pending.delete(id);
+    }
+    let payload;
+    try {
+      payload = build();
+    } catch (e) {
+      this.log("error", `[persist] builder failed for ${id}: ${errText(e)}`);
+      return false;
+    }
+    const file = this.resolvePath(id, payload);
+    const data = JSON.stringify(this.envelope(id, payload));
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+    } catch (e) {
+      this.log("warn", `[persist] could not create dir ${path.dirname(file)}: ${errText(e)}`);
+    }
+    const tmp = this.tempPath(file);
+    try {
+      fs.writeFileSync(tmp, data, "utf8");
+      let lastErr;
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          fs.renameSync(tmp, file);
+          lastErr = void 0;
+          break;
+        } catch (e) {
+          lastErr = e;
+          const code = e.code;
+          if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") break;
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1));
+        }
+      }
+      if (lastErr) throw lastErr;
+      return true;
+    } catch (e) {
+      this.log("error", `[persist] flushSync failed for ${id}: ${errText(e)}`);
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+      }
+      return false;
+    }
+  }
+  /** Load one record. Checks the discovered path (from a prior
+   *  write/loadAll), an optional relative-path hint, and the flat default
+   *  name. Returns null when absent, disabled, corrupt, or rejected by
+   *  validate. The hint covers namespaced records the store has not
+   *  discovered (e.g. an evicted session re-requested with its meta,
+   *  where the path depends on data the store cannot reconstruct from
+   *  the id alone). */
+  loadSync(id, hint) {
+    if (!this.enabled) return null;
+    const candidates = [
+      this.discovered.get(id),
+      hint ? path.join(this.dir, hint) : void 0,
+      path.join(this.dir, flatFileNameFor(id))
+    ];
+    for (const file of candidates) {
+      if (!file) continue;
+      const envelope = this.readEnvelope(file);
+      if (envelope && envelope.id === id) return envelope;
+    }
+    return null;
+  }
+  /** Load every record under dir. Populates the discovery map (enables
+   *  loadSync for namespaced relPaths). Skips corrupt files, `.tmp-*`
+   *  orphans, and records whose filename does not match their id — one
+   *  bad file never blocks boot. Never throws. */
+  async loadAll() {
+    const out = /* @__PURE__ */ new Map();
+    if (!this.enabled) return out;
+    const files = await this.walkJsonFiles(this.dir);
+    for (const file of files) {
+      const envelope = this.readEnvelope(file);
+      if (!envelope) continue;
+      const expected = path.basename(this.relPathOf(envelope.id, envelope.payload)) === path.basename(file) || flatFileNameFor(envelope.id) === path.basename(file);
+      if (!expected) {
+        this.log("warn", `[persist] skipping ${rel(file, this.dir)}: filename does not match record id`);
+        continue;
+      }
+      this.discovered.set(envelope.id, file);
+      out.set(envelope.id, envelope);
+    }
+    return out;
+  }
+  /** Whether a debounced write is pending for an id. */
+  hasPending(id) {
+    return this.timers.has(id);
+  }
+  /** Ids with a pending debounced write. */
+  pendingIds() {
+    return [...this.timers.keys()];
+  }
+  /** Flush every pending debounced write immediately, then drain in-flight
+   *  writes. For graceful shutdown (SIGTERM/SIGINT). Never rejects. */
+  async flushAll() {
+    const ids = this.pendingIds();
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers.clear();
+    const builders = /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      const build = this.pending.get(id);
+      if (build) builders.set(id, build);
+      this.pending.delete(id);
+    }
+    await Promise.all(
+      [...builders.entries()].map(
+        ([id, build]) => this.writeNow(id, build).catch((e) => {
+          this.log("error", `[persist] shutdown flush failed for ${id}: ${errText(e)}`);
+        })
+      )
+    );
+    await Promise.allSettled([...this.writeChains.values()]);
+  }
+  /** Cancel all pending debounced writes without flushing (tests). */
+  cancelAll() {
+    for (const timer of this.timers.values()) clearTimeout(timer);
+    this.timers.clear();
+    this.pending.clear();
+  }
+  async writeInner(id, build) {
+    let payload;
+    try {
+      payload = build();
+    } catch (e) {
+      this.log("error", `[persist] builder failed for ${id}: ${errText(e)}`);
+      throw e;
+    }
+    const file = this.resolvePath(id, payload);
+    try {
+      await fsp.mkdir(path.dirname(file), { recursive: true });
+    } catch (e) {
+      this.log("warn", `[persist] could not create dir ${path.dirname(file)}: ${errText(e)}`);
+    }
+    const tmp = this.tempPath(file);
+    try {
+      await fsp.writeFile(tmp, JSON.stringify(this.envelope(id, payload)), "utf8");
+      await renameWithRetry(tmp, file);
+      this.discovered.set(id, file);
+    } catch (e) {
+      await fsp.unlink(tmp).catch(() => {
+      });
+      this.log("error", `[persist] write failed for ${id}: ${errText(e)}`);
+      throw e;
+    }
+  }
+  envelope(id, payload) {
+    return { version: this.version, savedAt: Date.now(), id, payload };
+  }
+  /** Absolute path for a record: custom relPath (guarded against path
+   *  escape) or the flat hash default. */
+  resolvePath(id, payload) {
+    return path.join(this.dir, this.relPathOf(id, payload));
+  }
+  relPathOf(id, payload) {
+    const custom = this.relPathFn?.(id, payload);
+    if (!custom) return flatFileNameFor(id);
+    const rel2 = path.normalize(custom);
+    if (path.isAbsolute(rel2) || rel2.split(/[\\/]+/).includes("..")) {
+      this.log("warn", `[persist] relPath for ${id} escapes dir; using flat name`);
+      return flatFileNameFor(id);
+    }
+    return rel2;
+  }
+  /** Unique temp file next to the destination (same dir ⇒ same volume ⇒
+   *  rename is atomic). Prefixed `.tmp-` so loadAll skips orphans. */
+  tempPath(dest) {
+    const seq = this.tmpSeq++;
+    return path.join(path.dirname(dest), `.tmp-${path.basename(dest, ".json")}-${process.pid}-${seq}`);
+  }
+  /** Parse + validate one file. Corrupt or invalid records return null
+   *  (logged) instead of throwing — load paths must never block boot. */
+  readEnvelope(file) {
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch (e) {
+      if (e.code !== "ENOENT") {
+        this.log("warn", `[persist] skipping corrupt file ${rel(file, this.dir)}: ${errText(e)}`);
+      }
+      return null;
+    }
+    if (isEnvelopeLike(parsed)) {
+      if (!this.validateFn(parsed)) {
+        this.log("warn", `[persist] skipping invalid record ${rel(file, this.dir)}`);
+        return null;
+      }
+      return parsed;
+    }
+    const adopted = this.adoptLegacy(parsed);
+    if (adopted) return adopted;
+    this.log("warn", `[persist] skipping invalid record ${rel(file, this.dir)}`);
+    return null;
+  }
+  /** Wrap a legacy (pre-envelope) record as an envelope via the `legacy`
+   *  hook, then validate the adopted payload like any other. */
+  adoptLegacy(parsed) {
+    const adoption = this.legacyFn ? this.legacyFn(parsed) : null;
+    if (!adoption || typeof adoption.id !== "string" || adoption.id.length === 0 || adoption.payload == null) {
+      return null;
+    }
+    const source = parsed;
+    const envelope = {
+      version: adoption.version ?? source.version ?? this.version,
+      savedAt: adoption.savedAt ?? source.savedAt ?? 0,
+      id: adoption.id,
+      payload: adoption.payload
+    };
+    if (!this.validateFn(envelope)) return null;
+    return envelope;
+  }
+  /** Iterative recursive walk (no readdir-recursive dependency), skipping
+   *  `.tmp-*` names and non-.json files. */
+  async walkJsonFiles(root) {
+    const out = [];
+    const queue = [root];
+    while (queue.length > 0) {
+      const dir = queue.pop();
+      let dirents;
+      try {
+        dirents = await fsp.readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const d of dirents) {
+        if (d.name.startsWith(".tmp-")) continue;
+        const full = path.join(dir, d.name);
+        if (d.isDirectory()) queue.push(full);
+        else if (d.isFile() && d.name.endsWith(".json")) out.push(full);
+      }
+    }
+    return out;
+  }
+};
+function defaultValidate(envelope) {
+  return typeof envelope.id === "string" && envelope.id.length > 0 && envelope.payload != null;
+}
+function isEnvelopeLike(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.id === "string" && "payload" in v;
+}
+function flatFileNameFor(id) {
+  return createHash("sha256").update(id, "utf8").digest("hex").slice(0, 24) + ".json";
+}
+async function renameWithRetry(src, dest) {
+  let lastErr;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      await fsp.rename(src, dest);
+      return;
+    } catch (e) {
+      lastErr = e;
+      const code = e.code;
+      if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") throw e;
+      const { promise, resolve } = Promise.withResolvers();
+      setTimeout(resolve, 20 * (attempt + 1));
+      await promise;
+    }
+  }
+  throw lastErr;
+}
+function errText(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+function rel(p, base) {
+  const r = path.relative(base, p);
+  return r && !r.startsWith("..") ? r : p;
+}
+
+// src/persist/state-merge.ts
+function mergeCompressionState(parsed) {
+  const fresh = createInitialState();
+  return {
+    blocks: parsed.blocks ?? fresh.blocks,
+    messageRefs: parsed.messageRefs ?? fresh.messageRefs,
+    nudge: { ...fresh.nudge, ...parsed.nudge ?? {} },
+    stats: { ...fresh.stats, ...parsed.stats ?? {} },
+    nextBlockId: parsed.nextBlockId ?? fresh.nextBlockId,
+    nextRunId: parsed.nextRunId ?? fresh.nextRunId,
+    tokenSnapshot: parsed.tokenSnapshot ?? fresh.tokenSnapshot
+  };
+}
+export {
+  StateStore,
+  flatFileNameFor,
+  mergeCompressionState
+};
+//# sourceMappingURL=index.js.map

package/dist/persist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/persist/store.ts","../../src/persist/state-merge.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport fs from \"node:fs\";\nimport fsp from \"node:fs/promises\";\nimport path from \"node:path\";\n\n/** Logger callback. Downstream routes it wherever it wants (file, stderr). */\nexport type PersistLogger = (level: \"info\" | \"warn\" | \"error\", msg: string) => void;\n\n/**\n * On-disk record shape. The store owns the envelope (version stamp, save\n * time, id) so atomicity and discovery can rely on it; the payload schema\n * is entirely downstream-owned. `payload` must be JSON-serializable.\n */\nexport interface PersistedEnvelope<T> {\n    version: number;\n    savedAt: number;\n    id: string;\n    payload: T;\n}\n\n/** A legacy (pre-envelope) record adopted on load. `version`/`savedAt`\n * preserve the source record's own stamps when present. */\nexport interface LegacyAdoption<T> {\n    id: string;\n    payload: T;\n    version?: number;\n    savedAt?: number;\n}\n\nexport interface StateStoreOptions<T> {\n    /**\n     * Storage root. The kernel deliberately has NO default location: the\n     * downstream decides where state lives (CLI dir, XDG data dir, plugin\n     * dir, temp dir in tests). All records live under this directory.\n     */\n    dir: string;\n    /**\n     * Schema version stamped into every envelope. Owned by the downstream;\n     * bump it when the payload shape changes. The store itself never\n     * rejects a record over its version — migration policy belongs to the\n     * reader.\n     */\n    version: number;\n    /** Debounce window for scheduleSave, ms. Default 500. */\n    debounceMs?: number;\n    /** Default true. When false, all writes are silent no-ops and loads\n     *  return empty results. */\n    enabled?: boolean;\n    log?: PersistLogger;\n    /**\n     * Relative path (under `dir`) for a record, possibly namespaced into\n     * subdirectories (e.g. `openai/host-hash.json`). Default: flat\n     * `<sha256(id)[:24]>.json`.\n     *\n     * Because the path may depend on payload fields the store only learns\n     * at write time, single-record loads resolve namespaced files only\n     * after loadAll() has discovered them (or the store itself wrote\n     * them). The flat default name is always checked as a fallback, so\n     * downstreams using a custom relPath should call loadAll() at boot.\n     */\n    relPath?: (id: string, payload: T) => string;\n    /**\n     * Adopt records written by an older, pre-envelope schema. Receives the\n     * parsed JSON of any file that failed the envelope-shape check; return\n     * an adoption to load it as an envelope, or null to skip it. Adopted\n     * records are re-persisted in the current envelope format on the next\n     * dirty write — files migrate organically, and old files keep loading\n     * (same policy billion-context's proxy used for its v1→v3 migration).\n     */\n    legacy?: (parsed: unknown) => LegacyAdoption<T> | null;\n    /**\n     * Payload validation on load. Return false to skip a record (foreign\n     * schema, corrupt content). Default: envelope-shape check only\n     * (string id, non-null payload).\n     */\n    validate?: (envelope: PersistedEnvelope<T>) => boolean;\n}\n\n/**\n * Crash-safe, debounce-coalescing JSON state store. Mechanism only — lifted\n * from billion-context's proxy SessionStore and generalized:\n *\n * - atomic writes: temp file + rename, so a crash mid-write never leaves a\n *   truncated record (readers see either the old or the new file)\n * - rename retries on Windows transient locks (EPERM/EBUSY/EACCES)\n * - per-id serialization so concurrent writeNow calls never interleave\n *   temp-file names or reorders writes\n * - debounced scheduleSave coalesces bursts into one write; the record is\n *   built at WRITE time from a builder, so late mutations are picked up\n * - loadAll skips `.tmp-*` orphans, corrupt JSON, and records whose\n *   filename does not match their id — one bad file never blocks boot\n *\n * The store never deletes files. Session cleanup is a downstream policy\n * decision (kernel position: persisted state should not be deleted\n * opportunistically).\n */\nexport class StateStore<T> {\n    readonly enabled: boolean;\n    private readonly dir: string;\n    private readonly version: number;\n    private readonly debounceMs: number;\n    private readonly log: PersistLogger;\n    private readonly legacyFn?: (parsed: unknown) => LegacyAdoption<T> | null;\n    private readonly relPathFn?: (id: string, payload: T) => string;\n    private readonly validateFn: (envelope: PersistedEnvelope<T>) => boolean;\n    private readonly timers = new Map<string, NodeJS.Timeout>();\n    private readonly pending = new Map<string, () => T>();\n    private readonly writeChains = new Map<string, Promise<void>>();\n    /** id → absolute path, populated by writes and loadAll. */\n    private readonly discovered = new Map<string, string>();\n    /** Monotonic counter for unique temp filenames within a process. */\n    private tmpSeq = 0;\n\n    constructor(opts: StateStoreOptions<T>) {\n        this.dir = opts.dir;\n        this.version = opts.version;\n        this.debounceMs = opts.debounceMs ?? 500;\n        this.enabled = opts.enabled ?? true;\n        this.log = opts.log ?? ((_level, _msg) => {});\n        this.relPathFn = opts.relPath;\n        this.legacyFn = opts.legacy;\n        this.validateFn = opts.validate ?? defaultValidate;\n    }\n\n    /** Debounced save. Coalesces bursts; the builder runs at write time, so\n     *  the freshest state is always persisted. Never throws. */\n    scheduleSave(id: string, build: () => T): void {\n        if (!this.enabled) return;\n        this.pending.set(id, build);\n        const existing = this.timers.get(id);\n        if (existing) return;\n        const timer = setTimeout(() => {\n            this.timers.delete(id);\n            const builder = this.pending.get(id);\n            this.pending.delete(id);\n            if (!builder) return;\n            // Errors are logged inside writeInner; swallowing here keeps a\n            // failed timer write from becoming an unhandledRejection.\n            void this.writeNow(id, builder).catch(() => {});\n        }, this.debounceMs);\n        timer.unref?.();\n        this.timers.set(id, timer);\n    }\n\n    /** Immediate save, serialized per id. Rejects on write failure; a\n     *  failing write never breaks the chain for the next one. */\n    async writeNow(id: string, build: () => T): Promise<void> {\n        if (!this.enabled) return;\n        // The previous promise may reject (disk full, EPERM) — catch so our\n        // chain doesn't break, then run our own write.\n        const prev = this.writeChains.get(id) ?? Promise.resolve();\n        const next = prev.catch(() => {}).then(() => this.writeInner(id, build));\n        this.writeChains.set(id, next);\n        // Clean up the chain entry once settled so the Map doesn't grow. The\n        // .catch() is load-bearing: .finally() returns a derived promise that\n        // nobody else holds — when the chain rejects it would surface as an\n        // unhandledRejection and crash the host on default Node settings.\n        next\n            .finally(() => {\n                if (this.writeChains.get(id) === next) this.writeChains.delete(id);\n            })\n            .catch(() => {});\n        return next;\n    }\n\n    /** Synchronous flush for one id. Used where the caller cannot await\n     *  (memory eviction, sync shutdown paths). Cancels any pending debounce\n     *  timer. Returns true on success, false on failure — callers that use\n     *  the result to drop in-memory state must NOT drop it on failure. */\n    flushSync(id: string, build: () => T): boolean {\n        if (!this.enabled) return true;\n        const timer = this.timers.get(id);\n        if (timer) {\n            clearTimeout(timer);\n            this.timers.delete(id);\n            this.pending.delete(id);\n        }\n        let payload: T;\n        try {\n            payload = build();\n        } catch (e) {\n            this.log(\"error\", `[persist] builder failed for ${id}: ${errText(e)}`);\n            return false;\n        }\n        const file = this.resolvePath(id, payload);\n        const data = JSON.stringify(this.envelope(id, payload));\n        try {\n            fs.mkdirSync(path.dirname(file), { recursive: true });\n        } catch (e) {\n            this.log(\"warn\", `[persist] could not create dir ${path.dirname(file)}: ${errText(e)}`);\n        }\n        const tmp = this.tempPath(file);\n        try {\n            fs.writeFileSync(tmp, data, \"utf8\");\n            // renameSync can throw EPERM/EBUSY on Windows when the dest is\n            // briefly held (AV scanner, indexer, SMB). Retry briefly —\n            // transient locks usually release within ms.\n            let lastErr: unknown;\n            for (let attempt = 0; attempt < 3; attempt++) {\n                try {\n                    fs.renameSync(tmp, file);\n                    lastErr = undefined;\n                    break;\n                } catch (e) {\n                    lastErr = e;\n                    const code = (e as NodeJS.ErrnoException).code;\n                    if (code !== \"EPERM\" && code !== \"EBUSY\" && code !== \"EACCES\") break;\n                    // brief sync backoff (Atomics.wait is the sync sleep)\n                    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1));\n                }\n            }\n            if (lastErr) throw lastErr;\n            return true;\n        } catch (e) {\n            this.log(\"error\", `[persist] flushSync failed for ${id}: ${errText(e)}`);\n            try {\n                fs.unlinkSync(tmp);\n            } catch {\n                // best-effort cleanup of the orphan temp\n            }\n            return false;\n        }\n    }\n\n    /** Load one record. Checks the discovered path (from a prior\n     *  write/loadAll), an optional relative-path hint, and the flat default\n     *  name. Returns null when absent, disabled, corrupt, or rejected by\n     *  validate. The hint covers namespaced records the store has not\n     *  discovered (e.g. an evicted session re-requested with its meta,\n     *  where the path depends on data the store cannot reconstruct from\n     *  the id alone). */\n    loadSync(id: string, hint?: string): PersistedEnvelope<T> | null {\n        if (!this.enabled) return null;\n        const candidates = [\n            this.discovered.get(id),\n            hint ? path.join(this.dir, hint) : undefined,\n            path.join(this.dir, flatFileNameFor(id)),\n        ];\n        for (const file of candidates) {\n            if (!file) continue;\n            const envelope = this.readEnvelope(file);\n            if (envelope && envelope.id === id) return envelope;\n        }\n        return null;\n    }\n\n    /** Load every record under dir. Populates the discovery map (enables\n     *  loadSync for namespaced relPaths). Skips corrupt files, `.tmp-*`\n     *  orphans, and records whose filename does not match their id — one\n     *  bad file never blocks boot. Never throws. */\n    async loadAll(): Promise<Map<string, PersistedEnvelope<T>>> {\n        const out = new Map<string, PersistedEnvelope<T>>();\n        if (!this.enabled) return out;\n        const files = await this.walkJsonFiles(this.dir);\n        for (const file of files) {\n            const envelope = this.readEnvelope(file);\n            if (!envelope) continue;\n            const expected =\n                path.basename(this.relPathOf(envelope.id, envelope.payload)) === path.basename(file) ||\n                flatFileNameFor(envelope.id) === path.basename(file);\n            if (!expected) {\n                this.log(\"warn\", `[persist] skipping ${rel(file, this.dir)}: filename does not match record id`);\n                continue;\n            }\n            this.discovered.set(envelope.id, file);\n            out.set(envelope.id, envelope);\n        }\n        return out;\n    }\n\n    /** Whether a debounced write is pending for an id. */\n    hasPending(id: string): boolean {\n        return this.timers.has(id);\n    }\n\n    /** Ids with a pending debounced write. */\n    pendingIds(): string[] {\n        return [...this.timers.keys()];\n    }\n\n    /** Flush every pending debounced write immediately, then drain in-flight\n     *  writes. For graceful shutdown (SIGTERM/SIGINT). Never rejects. */\n    async flushAll(): Promise<void> {\n        const ids = this.pendingIds();\n        for (const timer of this.timers.values()) clearTimeout(timer);\n        this.timers.clear();\n        const builders = new Map<string, () => T>();\n        for (const id of ids) {\n            const build = this.pending.get(id);\n            if (build) builders.set(id, build);\n            this.pending.delete(id);\n        }\n        await Promise.all(\n            [...builders.entries()].map(([id, build]) =>\n                this.writeNow(id, build).catch((e) => {\n                    this.log(\"error\", `[persist] shutdown flush failed for ${id}: ${errText(e)}`);\n                }),\n            ),\n        );\n        // Drain writes whose timer fired earlier but are still mid-flight.\n        await Promise.allSettled([...this.writeChains.values()]);\n    }\n\n    /** Cancel all pending debounced writes without flushing (tests). */\n    cancelAll(): void {\n        for (const timer of this.timers.values()) clearTimeout(timer);\n        this.timers.clear();\n        this.pending.clear();\n    }\n\n    private async writeInner(id: string, build: () => T): Promise<void> {\n        let payload: T;\n        try {\n            payload = build();\n        } catch (e) {\n            this.log(\"error\", `[persist] builder failed for ${id}: ${errText(e)}`);\n            throw e;\n        }\n        const file = this.resolvePath(id, payload);\n        try {\n            await fsp.mkdir(path.dirname(file), { recursive: true });\n        } catch (e) {\n            this.log(\"warn\", `[persist] could not create dir ${path.dirname(file)}: ${errText(e)}`);\n        }\n        const tmp = this.tempPath(file);\n        try {\n            await fsp.writeFile(tmp, JSON.stringify(this.envelope(id, payload)), \"utf8\");\n            await renameWithRetry(tmp, file);\n            this.discovered.set(id, file);\n        } catch (e) {\n            // Wrap so a failure cleans up the .tmp orphan instead of leaving\n            // it for the next write to collide with.\n            await fsp.unlink(tmp).catch(() => {});\n            this.log(\"error\", `[persist] write failed for ${id}: ${errText(e)}`);\n            throw e;\n        }\n    }\n\n    private envelope(id: string, payload: T): PersistedEnvelope<T> {\n        return { version: this.version, savedAt: Date.now(), id, payload };\n    }\n\n    /** Absolute path for a record: custom relPath (guarded against path\n     *  escape) or the flat hash default. */\n    private resolvePath(id: string, payload: T): string {\n        return path.join(this.dir, this.relPathOf(id, payload));\n    }\n\n    private relPathOf(id: string, payload: T): string {\n        const custom = this.relPathFn?.(id, payload);\n        if (!custom) return flatFileNameFor(id);\n        const rel = path.normalize(custom);\n        if (path.isAbsolute(rel) || rel.split(/[\\\\/]+/).includes(\"..\")) {\n            this.log(\"warn\", `[persist] relPath for ${id} escapes dir; using flat name`);\n            return flatFileNameFor(id);\n        }\n        return rel;\n    }\n\n    /** Unique temp file next to the destination (same dir ⇒ same volume ⇒\n     *  rename is atomic). Prefixed `.tmp-` so loadAll skips orphans. */\n    private tempPath(dest: string): string {\n        const seq = this.tmpSeq++;\n        return path.join(path.dirname(dest), `.tmp-${path.basename(dest, \".json\")}-${process.pid}-${seq}`);\n    }\n\n    /** Parse + validate one file. Corrupt or invalid records return null\n     *  (logged) instead of throwing — load paths must never block boot. */\n    private readEnvelope(file: string): PersistedEnvelope<T> | null {\n        let parsed: unknown;\n        try {\n            parsed = JSON.parse(fs.readFileSync(file, \"utf8\"));\n        } catch (e) {\n            // A missing candidate path is an expected miss (loadSync probes);\n            // only genuinely unreadable/corrupt files get logged.\n            if ((e as NodeJS.ErrnoException).code !== \"ENOENT\") {\n                this.log(\"warn\", `[persist] skipping corrupt file ${rel(file, this.dir)}: ${errText(e)}`);\n            }\n            return null;\n        }\n        if (isEnvelopeLike(parsed)) {\n            if (!this.validateFn(parsed as PersistedEnvelope<T>)) {\n                this.log(\"warn\", `[persist] skipping invalid record ${rel(file, this.dir)}`);\n                return null;\n            }\n            return parsed as PersistedEnvelope<T>;\n        }\n        const adopted = this.adoptLegacy(parsed);\n        if (adopted) return adopted;\n        this.log(\"warn\", `[persist] skipping invalid record ${rel(file, this.dir)}`);\n        return null;\n    }\n\n    /** Wrap a legacy (pre-envelope) record as an envelope via the `legacy`\n     *  hook, then validate the adopted payload like any other. */\n    private adoptLegacy(parsed: unknown): PersistedEnvelope<T> | null {\n        const adoption = this.legacyFn ? this.legacyFn(parsed) : null;\n        if (!adoption || typeof adoption.id !== \"string\" || adoption.id.length === 0 || adoption.payload == null) {\n            return null;\n        }\n        const source = parsed as Partial<PersistedEnvelope<T>>;\n        const envelope: PersistedEnvelope<T> = {\n            version: adoption.version ?? source.version ?? this.version,\n            savedAt: adoption.savedAt ?? source.savedAt ?? 0,\n            id: adoption.id,\n            payload: adoption.payload,\n        };\n        if (!this.validateFn(envelope)) return null;\n        return envelope;\n    }\n\n    /** Iterative recursive walk (no readdir-recursive dependency), skipping\n     *  `.tmp-*` names and non-.json files. */\n    private async walkJsonFiles(root: string): Promise<string[]> {\n        const out: string[] = [];\n        const queue: string[] = [root];\n        while (queue.length > 0) {\n            const dir = queue.pop()!;\n            let dirents: fs.Dirent[];\n            try {\n                dirents = await fsp.readdir(dir, { withFileTypes: true });\n            } catch {\n                continue; // missing dir → no records yet\n            }\n            for (const d of dirents) {\n                if (d.name.startsWith(\".tmp-\")) continue;\n                const full = path.join(dir, d.name);\n                if (d.isDirectory()) queue.push(full);\n                else if (d.isFile() && d.name.endsWith(\".json\")) out.push(full);\n            }\n        }\n        return out;\n    }\n}\n\nfunction defaultValidate<T>(envelope: PersistedEnvelope<T>): boolean {\n    return typeof envelope.id === \"string\" && envelope.id.length > 0 && envelope.payload != null;\n}\n\nfunction isEnvelopeLike(value: unknown): value is PersistedEnvelope<unknown> {\n    if (!value || typeof value !== \"object\") return false;\n    const v = value as Partial<PersistedEnvelope<unknown>>;\n    return typeof v.id === \"string\" && \"payload\" in v;\n}\n\n/** Deterministic flat filename: `<sha256(id)[:24]>.json`. Truncated hash —\n *  96 bits keeps collisions unreachable for realistic id counts, and short\n *  names stay greppable. */\nexport function flatFileNameFor(id: string): string {\n    return createHash(\"sha256\").update(id, \"utf8\").digest(\"hex\").slice(0, 24) + \".json\";\n}\n\n/** fs.rename with brief retries on Windows transient locks (EPERM/EBUSY/\n *  EACCES from AV scan, search indexer, SMB). A short delay + retry almost\n *  always succeeds; other errors are real and rethrown immediately. */\nasync function renameWithRetry(src: string, dest: string): Promise<void> {\n    let lastErr: unknown;\n    for (let attempt = 0; attempt < 3; attempt++) {\n        try {\n            await fsp.rename(src, dest);\n            return;\n        } catch (e) {\n            lastErr = e;\n            const code = (e as NodeJS.ErrnoException).code;\n            if (code !== \"EPERM\" && code !== \"EBUSY\" && code !== \"EACCES\") throw e;\n            const { promise, resolve } = Promise.withResolvers<void>();\n            setTimeout(resolve, 20 * (attempt + 1));\n            await promise;\n        }\n    }\n    throw lastErr;\n}\n\nfunction errText(e: unknown): string {\n    return e instanceof Error ? e.message : String(e);\n}\n\n\nfunction rel(p: string, base: string): string {\n    const r = path.relative(base, p);\n    return r && !r.startsWith(\"..\") ? r : p;\n}\n","import type { CompressionState } from \"../types.js\";\nimport { createInitialState } from \"../state.js\";\n\n/**\n * Forward-compat: merge a parsed state with a fresh one so fields added in\n * later kernel versions get sane defaults instead of `undefined`. Nested\n * groups (nudge, stats) are shallow-merged per field so older snapshots\n * keep their values while newer counters default in.\n *\n * Lifted verbatim in behavior from billion-context's proxy mergeState.\n */\nexport function mergeCompressionState(parsed: CompressionState): CompressionState {\n  const fresh = createInitialState();\n  return {\n    blocks: parsed.blocks ?? fresh.blocks,\n    messageRefs: parsed.messageRefs ?? fresh.messageRefs,\n    nudge: { ...fresh.nudge, ...(parsed.nudge ?? {}) },\n    stats: { ...fresh.stats, ...(parsed.stats ?? {}) },\n    nextBlockId: parsed.nextBlockId ?? fresh.nextBlockId,\n    nextRunId: parsed.nextRunId ?? fresh.nextRunId,\n    tokenSnapshot: parsed.tokenSnapshot ?? fresh.tokenSnapshot,\n  };\n}\n"],"mappings":"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","names":["rel"]}

package/dist/persist/state-merge.d.ts

@@ -0,0 +1,11 @@
+import type { CompressionState } from "../types.js";
+/**
+ * Forward-compat: merge a parsed state with a fresh one so fields added in
+ * later kernel versions get sane defaults instead of `undefined`. Nested
+ * groups (nudge, stats) are shallow-merged per field so older snapshots
+ * keep their values while newer counters default in.
+ *
+ * Lifted verbatim in behavior from billion-context's proxy mergeState.
+ */
+export declare function mergeCompressionState(parsed: CompressionState): CompressionState;
+//# sourceMappingURL=state-merge.d.ts.map

package/dist/persist/state-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-merge.d.ts","sourceRoot":"","sources":["../../src/persist/state-merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAWhF"}

package/dist/persist/store.d.ts

@@ -0,0 +1,161 @@
+/** Logger callback. Downstream routes it wherever it wants (file, stderr). */
+export type PersistLogger = (level: "info" | "warn" | "error", msg: string) => void;
+/**
+ * On-disk record shape. The store owns the envelope (version stamp, save
+ * time, id) so atomicity and discovery can rely on it; the payload schema
+ * is entirely downstream-owned. `payload` must be JSON-serializable.
+ */
+export interface PersistedEnvelope<T> {
+    version: number;
+    savedAt: number;
+    id: string;
+    payload: T;
+}
+/** A legacy (pre-envelope) record adopted on load. `version`/`savedAt`
+ * preserve the source record's own stamps when present. */
+export interface LegacyAdoption<T> {
+    id: string;
+    payload: T;
+    version?: number;
+    savedAt?: number;
+}
+export interface StateStoreOptions<T> {
+    /**
+     * Storage root. The kernel deliberately has NO default location: the
+     * downstream decides where state lives (CLI dir, XDG data dir, plugin
+     * dir, temp dir in tests). All records live under this directory.
+     */
+    dir: string;
+    /**
+     * Schema version stamped into every envelope. Owned by the downstream;
+     * bump it when the payload shape changes. The store itself never
+     * rejects a record over its version — migration policy belongs to the
+     * reader.
+     */
+    version: number;
+    /** Debounce window for scheduleSave, ms. Default 500. */
+    debounceMs?: number;
+    /** Default true. When false, all writes are silent no-ops and loads
+     *  return empty results. */
+    enabled?: boolean;
+    log?: PersistLogger;
+    /**
+     * Relative path (under `dir`) for a record, possibly namespaced into
+     * subdirectories (e.g. `openai/host-hash.json`). Default: flat
+     * `<sha256(id)[:24]>.json`.
+     *
+     * Because the path may depend on payload fields the store only learns
+     * at write time, single-record loads resolve namespaced files only
+     * after loadAll() has discovered them (or the store itself wrote
+     * them). The flat default name is always checked as a fallback, so
+     * downstreams using a custom relPath should call loadAll() at boot.
+     */
+    relPath?: (id: string, payload: T) => string;
+    /**
+     * Adopt records written by an older, pre-envelope schema. Receives the
+     * parsed JSON of any file that failed the envelope-shape check; return
+     * an adoption to load it as an envelope, or null to skip it. Adopted
+     * records are re-persisted in the current envelope format on the next
+     * dirty write — files migrate organically, and old files keep loading
+     * (same policy billion-context's proxy used for its v1→v3 migration).
+     */
+    legacy?: (parsed: unknown) => LegacyAdoption<T> | null;
+    /**
+     * Payload validation on load. Return false to skip a record (foreign
+     * schema, corrupt content). Default: envelope-shape check only
+     * (string id, non-null payload).
+     */
+    validate?: (envelope: PersistedEnvelope<T>) => boolean;
+}
+/**
+ * Crash-safe, debounce-coalescing JSON state store. Mechanism only — lifted
+ * from billion-context's proxy SessionStore and generalized:
+ *
+ * - atomic writes: temp file + rename, so a crash mid-write never leaves a
+ *   truncated record (readers see either the old or the new file)
+ * - rename retries on Windows transient locks (EPERM/EBUSY/EACCES)
+ * - per-id serialization so concurrent writeNow calls never interleave
+ *   temp-file names or reorders writes
+ * - debounced scheduleSave coalesces bursts into one write; the record is
+ *   built at WRITE time from a builder, so late mutations are picked up
+ * - loadAll skips `.tmp-*` orphans, corrupt JSON, and records whose
+ *   filename does not match their id — one bad file never blocks boot
+ *
+ * The store never deletes files. Session cleanup is a downstream policy
+ * decision (kernel position: persisted state should not be deleted
+ * opportunistically).
+ */
+export declare class StateStore<T> {
+    readonly enabled: boolean;
+    private readonly dir;
+    private readonly version;
+    private readonly debounceMs;
+    private readonly log;
+    private readonly legacyFn?;
+    private readonly relPathFn?;
+    private readonly validateFn;
+    private readonly timers;
+    private readonly pending;
+    private readonly writeChains;
+    /** id → absolute path, populated by writes and loadAll. */
+    private readonly discovered;
+    /** Monotonic counter for unique temp filenames within a process. */
+    private tmpSeq;
+    constructor(opts: StateStoreOptions<T>);
+    /** Debounced save. Coalesces bursts; the builder runs at write time, so
+     *  the freshest state is always persisted. Never throws. */
+    scheduleSave(id: string, build: () => T): void;
+    /** Immediate save, serialized per id. Rejects on write failure; a
+     *  failing write never breaks the chain for the next one. */
+    writeNow(id: string, build: () => T): Promise<void>;
+    /** Synchronous flush for one id. Used where the caller cannot await
+     *  (memory eviction, sync shutdown paths). Cancels any pending debounce
+     *  timer. Returns true on success, false on failure — callers that use
+     *  the result to drop in-memory state must NOT drop it on failure. */
+    flushSync(id: string, build: () => T): boolean;
+    /** Load one record. Checks the discovered path (from a prior
+     *  write/loadAll), an optional relative-path hint, and the flat default
+     *  name. Returns null when absent, disabled, corrupt, or rejected by
+     *  validate. The hint covers namespaced records the store has not
+     *  discovered (e.g. an evicted session re-requested with its meta,
+     *  where the path depends on data the store cannot reconstruct from
+     *  the id alone). */
+    loadSync(id: string, hint?: string): PersistedEnvelope<T> | null;
+    /** Load every record under dir. Populates the discovery map (enables
+     *  loadSync for namespaced relPaths). Skips corrupt files, `.tmp-*`
+     *  orphans, and records whose filename does not match their id — one
+     *  bad file never blocks boot. Never throws. */
+    loadAll(): Promise<Map<string, PersistedEnvelope<T>>>;
+    /** Whether a debounced write is pending for an id. */
+    hasPending(id: string): boolean;
+    /** Ids with a pending debounced write. */
+    pendingIds(): string[];
+    /** Flush every pending debounced write immediately, then drain in-flight
+     *  writes. For graceful shutdown (SIGTERM/SIGINT). Never rejects. */
+    flushAll(): Promise<void>;
+    /** Cancel all pending debounced writes without flushing (tests). */
+    cancelAll(): void;
+    private writeInner;
+    private envelope;
+    /** Absolute path for a record: custom relPath (guarded against path
+     *  escape) or the flat hash default. */
+    private resolvePath;
+    private relPathOf;
+    /** Unique temp file next to the destination (same dir ⇒ same volume ⇒
+     *  rename is atomic). Prefixed `.tmp-` so loadAll skips orphans. */
+    private tempPath;
+    /** Parse + validate one file. Corrupt or invalid records return null
+     *  (logged) instead of throwing — load paths must never block boot. */
+    private readEnvelope;
+    /** Wrap a legacy (pre-envelope) record as an envelope via the `legacy`
+     *  hook, then validate the adopted payload like any other. */
+    private adoptLegacy;
+    /** Iterative recursive walk (no readdir-recursive dependency), skipping
+     *  `.tmp-*` names and non-.json files. */
+    private walkJsonFiles;
+}
+/** Deterministic flat filename: `<sha256(id)[:24]>.json`. Truncated hash —
+ *  96 bits keeps collisions unreachable for realistic id counts, and short
+ *  names stay greppable. */
+export declare function flatFileNameFor(id: string): string;
+//# sourceMappingURL=store.d.ts.map

package/dist/persist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/persist/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "acp-kernel",
-    "version": "0.0.39",
+    "version": "0.0.41",
     "description": "Framework-agnostic context-compression engine (model-driven, 3-tier LSM). Pure core: no host dependency.",
     "license": "MIT",
     "author": "ranxianglei",
@@ -37,6 +37,10 @@
         "./panel": {
             "types": "./dist/panel/index.d.ts",
             "import": "./dist/panel/index.js"
+        },
+        "./persist": {
+            "types": "./dist/persist/index.d.ts",
+            "import": "./dist/persist/index.js"
         }
     },
     "files": [