acp-kernel 0.0.46 → 0.0.47-pr.174.27
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +21 -13
- package/dist/index.js.map +1 -1
- package/dist/parse-compress-input.d.ts +2 -0
- package/dist/parse-compress-input.d.ts.map +1 -1
- package/dist/persist/index.js +132 -45
- package/dist/persist/index.js.map +1 -1
- package/dist/persist/store.d.ts +46 -5
- package/dist/persist/store.d.ts.map +1 -1
- package/package.json +1 -1
|
@@ -13,6 +13,8 @@ export interface CompressParseDiagnostics {
|
|
|
13
13
|
keys?: string[];
|
|
14
14
|
/** Entries dropped because they were not valid ranges. */
|
|
15
15
|
invalidItems: number;
|
|
16
|
+
/** One human-readable reason per dropped entry (index-prefixed). */
|
|
17
|
+
invalidReasons?: string[];
|
|
16
18
|
}
|
|
17
19
|
export interface ParsedCompressInput {
|
|
18
20
|
ranges: CompressRangeSpec[];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"parse-compress-input.d.ts","sourceRoot":"","sources":["../src/parse-compress-input.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,MAAM,iBAAiB,GACvB,IAAI,GACJ,aAAa,GACb,YAAY,GACZ,iBAAiB,GACjB,mBAAmB,GACnB,gBAAgB,GAChB,WAAW,GACX,iBAAiB,CAAC;AAExB,MAAM,WAAW,wBAAwB;IACrC,uDAAuD;IACvD,EAAE,EAAE,OAAO,CAAC;IACZ,2CAA2C;IAC3C,IAAI,EAAE,iBAAiB,CAAC;IACxB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"parse-compress-input.d.ts","sourceRoot":"","sources":["../src/parse-compress-input.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,MAAM,iBAAiB,GACvB,IAAI,GACJ,aAAa,GACb,YAAY,GACZ,iBAAiB,GACjB,mBAAmB,GACnB,gBAAgB,GAChB,WAAW,GACX,iBAAiB,CAAC;AAExB,MAAM,WAAW,wBAAwB;IACrC,uDAAuD;IACvD,EAAE,EAAE,OAAO,CAAC;IACZ,2CAA2C;IAC3C,IAAI,EAAE,iBAAiB,CAAC;IACxB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAChC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,WAAW,EAAE,wBAAwB,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,mBAAmB,CAmBjG"}
|
package/dist/persist/index.js
CHANGED
|
@@ -16,11 +16,16 @@ var StateStore = class {
|
|
|
16
16
|
legacyFn;
|
|
17
17
|
relPathFn;
|
|
18
18
|
validateFn;
|
|
19
|
+
retryAttempts;
|
|
20
|
+
retryBaseMs;
|
|
21
|
+
retryMaxMs;
|
|
19
22
|
timers = /* @__PURE__ */ new Map();
|
|
20
23
|
pending = /* @__PURE__ */ new Map();
|
|
21
24
|
writeChains = /* @__PURE__ */ new Map();
|
|
22
25
|
/** id → absolute path, populated by writes and loadAll. */
|
|
23
26
|
discovered = /* @__PURE__ */ new Map();
|
|
27
|
+
/** id → cumulative write-failure count, for rate-limited alerting. */
|
|
28
|
+
failCounts = /* @__PURE__ */ new Map();
|
|
24
29
|
/** Monotonic counter for unique temp filenames within a process. */
|
|
25
30
|
tmpSeq = 0;
|
|
26
31
|
constructor(opts) {
|
|
@@ -33,6 +38,9 @@ var StateStore = class {
|
|
|
33
38
|
this.relPathFn = opts.relPath;
|
|
34
39
|
this.legacyFn = opts.legacy;
|
|
35
40
|
this.validateFn = opts.validate ?? defaultValidate;
|
|
41
|
+
this.retryAttempts = Math.max(1, opts.retryAttempts ?? 6);
|
|
42
|
+
this.retryBaseMs = Math.max(1, opts.retryBaseMs ?? 50);
|
|
43
|
+
this.retryMaxMs = Math.max(this.retryBaseMs, opts.retryMaxMs ?? 1600);
|
|
36
44
|
}
|
|
37
45
|
/** Debounced save. Coalesces bursts; the builder runs at write time, so
|
|
38
46
|
* the freshest state is always persisted. Never throws. */
|
|
@@ -92,32 +100,42 @@ var StateStore = class {
|
|
|
92
100
|
} catch (e) {
|
|
93
101
|
this.log("warn", `[persist] could not create dir ${path.dirname(file)}: ${errText(e)}`);
|
|
94
102
|
}
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
103
|
+
let lastErr;
|
|
104
|
+
for (let attempt = 0; attempt < this.retryAttempts; attempt++) {
|
|
105
|
+
const tmp = this.tempPath(file);
|
|
106
|
+
try {
|
|
107
|
+
fs.writeFileSync(tmp, data, "utf8");
|
|
108
|
+
fs.renameSync(tmp, file);
|
|
109
|
+
lastErr = void 0;
|
|
110
|
+
break;
|
|
111
|
+
} catch (e) {
|
|
112
|
+
lastErr = e;
|
|
100
113
|
try {
|
|
101
|
-
fs.
|
|
102
|
-
|
|
103
|
-
break;
|
|
104
|
-
} catch (e) {
|
|
105
|
-
lastErr = e;
|
|
106
|
-
const code = e.code;
|
|
107
|
-
if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") break;
|
|
108
|
-
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1));
|
|
114
|
+
fs.unlinkSync(tmp);
|
|
115
|
+
} catch {
|
|
109
116
|
}
|
|
117
|
+
const code = e.code;
|
|
118
|
+
if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") break;
|
|
119
|
+
if (attempt === this.retryAttempts - 1) break;
|
|
120
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, this.backoffMs(attempt));
|
|
110
121
|
}
|
|
111
|
-
|
|
122
|
+
}
|
|
123
|
+
if (!lastErr) {
|
|
124
|
+
this.discovered.set(id, file);
|
|
125
|
+
this.clearFailure(id);
|
|
126
|
+
this.removeSpillSync(file);
|
|
112
127
|
return true;
|
|
113
|
-
} catch (e) {
|
|
114
|
-
this.log("error", `[persist] flushSync failed for ${id}: ${errText(e)}`);
|
|
115
|
-
try {
|
|
116
|
-
fs.unlinkSync(tmp);
|
|
117
|
-
} catch {
|
|
118
|
-
}
|
|
119
|
-
return false;
|
|
120
128
|
}
|
|
129
|
+
let spillPath = null;
|
|
130
|
+
try {
|
|
131
|
+
const spill = this.spillPathFor(file);
|
|
132
|
+
fs.writeFileSync(spill, data, "utf8");
|
|
133
|
+
spillPath = spill;
|
|
134
|
+
this.discovered.set(id, spill);
|
|
135
|
+
} catch {
|
|
136
|
+
}
|
|
137
|
+
this.recordFailure(id, lastErr, spillPath);
|
|
138
|
+
return spillPath !== null;
|
|
121
139
|
}
|
|
122
140
|
/** Load one record. Checks the discovered path (from a prior
|
|
123
141
|
* write/loadAll), an optional relative-path hint, and the flat default
|
|
@@ -151,13 +169,27 @@ var StateStore = class {
|
|
|
151
169
|
for (const file of files) {
|
|
152
170
|
const envelope = this.readEnvelope(file);
|
|
153
171
|
if (!envelope) continue;
|
|
154
|
-
const
|
|
155
|
-
|
|
172
|
+
const base = path.basename(file);
|
|
173
|
+
const relBase = path.basename(this.relPathOf(envelope.id, envelope.payload));
|
|
174
|
+
const flatBase = flatFileNameFor(envelope.id);
|
|
175
|
+
let owner = null;
|
|
176
|
+
if (base === relBase || base === flatBase) {
|
|
177
|
+
owner = envelope.id;
|
|
178
|
+
} else if (base.endsWith(".fb.json")) {
|
|
179
|
+
const canonicalBase = `${base.slice(0, -".fb.json".length)}.json`;
|
|
180
|
+
if (canonicalBase === relBase || canonicalBase === flatBase) {
|
|
181
|
+
owner = envelope.id;
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
if (owner === null) {
|
|
156
185
|
this.log("warn", `[persist] skipping ${rel(file, this.dir)}: filename does not match record id`);
|
|
157
186
|
continue;
|
|
158
187
|
}
|
|
159
|
-
|
|
160
|
-
|
|
188
|
+
const existing = out.get(owner);
|
|
189
|
+
if (!existing || envelope.savedAt >= existing.savedAt) {
|
|
190
|
+
out.set(owner, envelope);
|
|
191
|
+
this.discovered.set(owner, file);
|
|
192
|
+
}
|
|
161
193
|
}
|
|
162
194
|
return out;
|
|
163
195
|
}
|
|
@@ -211,14 +243,25 @@ var StateStore = class {
|
|
|
211
243
|
this.log("warn", `[persist] could not create dir ${path.dirname(file)}: ${errText(e)}`);
|
|
212
244
|
}
|
|
213
245
|
const tmp = this.tempPath(file);
|
|
246
|
+
const env = this.envelope(id, payload);
|
|
214
247
|
try {
|
|
215
|
-
await fsp.writeFile(tmp, JSON.stringify(
|
|
216
|
-
await renameWithRetry(tmp, file);
|
|
248
|
+
await fsp.writeFile(tmp, JSON.stringify(env), "utf8");
|
|
249
|
+
await this.renameWithRetry(tmp, file);
|
|
217
250
|
this.discovered.set(id, file);
|
|
251
|
+
this.clearFailure(id);
|
|
252
|
+
await this.removeSpill(file);
|
|
218
253
|
} catch (e) {
|
|
219
254
|
await fsp.unlink(tmp).catch(() => {
|
|
220
255
|
});
|
|
221
|
-
|
|
256
|
+
let spillPath = null;
|
|
257
|
+
try {
|
|
258
|
+
const spill = this.spillPathFor(file);
|
|
259
|
+
await fsp.writeFile(spill, JSON.stringify(env), "utf8");
|
|
260
|
+
spillPath = spill;
|
|
261
|
+
this.discovered.set(id, spill);
|
|
262
|
+
} catch {
|
|
263
|
+
}
|
|
264
|
+
this.recordFailure(id, e, spillPath);
|
|
222
265
|
throw e;
|
|
223
266
|
}
|
|
224
267
|
}
|
|
@@ -246,6 +289,67 @@ var StateStore = class {
|
|
|
246
289
|
const seq = this.tmpSeq++;
|
|
247
290
|
return path.join(path.dirname(dest), `.tmp-${path.basename(dest, ".json")}-${process.pid}-${seq}`);
|
|
248
291
|
}
|
|
292
|
+
backoffMs(attempt) {
|
|
293
|
+
return Math.min(this.retryBaseMs * 2 ** attempt, this.retryMaxMs);
|
|
294
|
+
}
|
|
295
|
+
/** Side file for a record whose canonical write keeps failing: the
|
|
296
|
+
* canonical name with a `.fb` (fallback) infix, e.g. `a.json` →
|
|
297
|
+
* `a.fb.json`. One slot per id, overwritten on each spill, so a stuck
|
|
298
|
+
* lock never accumulates files. Ends in `.json` so loadAll discovers it. */
|
|
299
|
+
spillPathFor(file) {
|
|
300
|
+
const base = path.basename(file);
|
|
301
|
+
const dot = base.lastIndexOf(".");
|
|
302
|
+
const stem = dot > 0 ? base.slice(0, dot) : base;
|
|
303
|
+
const ext = dot > 0 ? base.slice(dot) : ".json";
|
|
304
|
+
return path.join(path.dirname(file), `${stem}.fb${ext}`);
|
|
305
|
+
}
|
|
306
|
+
/** Remove a stale spill after a successful canonical write (best-effort). */
|
|
307
|
+
async removeSpill(file) {
|
|
308
|
+
await fsp.unlink(this.spillPathFor(file)).catch(() => {
|
|
309
|
+
});
|
|
310
|
+
}
|
|
311
|
+
removeSpillSync(file) {
|
|
312
|
+
try {
|
|
313
|
+
fs.unlinkSync(this.spillPathFor(file));
|
|
314
|
+
} catch {
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
/** Rate-limited failure alerting: log on the first failure and at each
|
|
318
|
+
* power-of-two count (1,2,4,8,…), so a long lock yields ~log2(N) lines
|
|
319
|
+
* instead of one per write. Includes the spill path so the operator can
|
|
320
|
+
* see where the data landed. */
|
|
321
|
+
recordFailure(id, err, spillPath) {
|
|
322
|
+
const count = (this.failCounts.get(id) ?? 0) + 1;
|
|
323
|
+
this.failCounts.set(id, count);
|
|
324
|
+
const alertAt = count === 1 || count >= 2 && (count & count - 1) === 0;
|
|
325
|
+
if (!alertAt) return;
|
|
326
|
+
const where = spillPath ? `; data spilled to ${rel(spillPath, this.dir)}` : "; SPILLOVER ALSO FAILED \u2014 data at risk";
|
|
327
|
+
this.log(count === 1 ? "error" : "warn", `[persist] write failed for ${id} (total ${count}x): ${errText(err)}${where}`);
|
|
328
|
+
}
|
|
329
|
+
clearFailure(id) {
|
|
330
|
+
this.failCounts.delete(id);
|
|
331
|
+
}
|
|
332
|
+
/** fs.rename with exponential-backoff retries on Windows transient locks
|
|
333
|
+
* (EPERM/EBUSY/EACCES from AV scan, search indexer, SMB). Other errors
|
|
334
|
+
* are real and rethrown immediately. */
|
|
335
|
+
async renameWithRetry(src, dest) {
|
|
336
|
+
let lastErr;
|
|
337
|
+
for (let attempt = 0; attempt < this.retryAttempts; attempt++) {
|
|
338
|
+
try {
|
|
339
|
+
await fsp.rename(src, dest);
|
|
340
|
+
return;
|
|
341
|
+
} catch (e) {
|
|
342
|
+
lastErr = e;
|
|
343
|
+
const code = e.code;
|
|
344
|
+
if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") throw e;
|
|
345
|
+
if (attempt === this.retryAttempts - 1) throw e;
|
|
346
|
+
const { promise, resolve } = Promise.withResolvers();
|
|
347
|
+
setTimeout(resolve, this.backoffMs(attempt));
|
|
348
|
+
await promise;
|
|
349
|
+
}
|
|
350
|
+
}
|
|
351
|
+
throw lastErr;
|
|
352
|
+
}
|
|
249
353
|
/** Parse + validate one file. Corrupt or invalid records return null
|
|
250
354
|
* (logged) instead of throwing — load paths must never block boot. */
|
|
251
355
|
readEnvelope(file) {
|
|
@@ -321,23 +425,6 @@ function isEnvelopeLike(value) {
|
|
|
321
425
|
function flatFileNameFor(id) {
|
|
322
426
|
return createHash("sha256").update(id, "utf8").digest("hex").slice(0, 24) + ".json";
|
|
323
427
|
}
|
|
324
|
-
async function renameWithRetry(src, dest) {
|
|
325
|
-
let lastErr;
|
|
326
|
-
for (let attempt = 0; attempt < 3; attempt++) {
|
|
327
|
-
try {
|
|
328
|
-
await fsp.rename(src, dest);
|
|
329
|
-
return;
|
|
330
|
-
} catch (e) {
|
|
331
|
-
lastErr = e;
|
|
332
|
-
const code = e.code;
|
|
333
|
-
if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") throw e;
|
|
334
|
-
const { promise, resolve } = Promise.withResolvers();
|
|
335
|
-
setTimeout(resolve, 20 * (attempt + 1));
|
|
336
|
-
await promise;
|
|
337
|
-
}
|
|
338
|
-
}
|
|
339
|
-
throw lastErr;
|
|
340
|
-
}
|
|
341
428
|
function errText(e) {
|
|
342
429
|
return e instanceof Error ? e.message : String(e);
|
|
343
430
|
}
|
|
@@ -1 +1 @@
|
|
|
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 absorbed: parsed.absorbed ?? fresh.absorbed,\n };\n}\n"],"mappings":"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","names":["rel"]}
|
|
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 * Rename-retry policy for Windows transient locks (EPERM/EBUSY/EACCES\n * from AV scan, search indexer, SMB). Exponential backoff: the delay\n * after attempt i is min(retryBaseMs * 2^i, retryMaxMs). Defaults\n * (6 attempts, 50ms base, 1600ms cap) give a ~1.5s window — long enough\n * for most AV locks to release, short enough not to stall a sync flush.\n * When the window is exhausted the write spills to a side file (see\n * spillPath) instead of dropping the data.\n */\n retryAttempts?: number;\n retryBaseMs?: number;\n retryMaxMs?: number;\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 with exponential backoff on Windows transient locks\n * (EPERM/EBUSY/EACCES); when the window is exhausted the record spills to\n * a side file (`<name>.fb.json`) instead of being dropped, so a lock held\n * by AV/indexer/SMB never silently loses session data\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; it\n * reconciles a canonical record against its spill by savedAt (freshest wins)\n *\n * The store never deletes a record's data. On a successful canonical write it\n * removes a now-stale spill of the SAME id (a duplicate, not distinct data).\n * Session cleanup is a downstream policy decision (kernel position: persisted\n * state should not be deleted 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 retryAttempts: number;\n private readonly retryBaseMs: number;\n private readonly retryMaxMs: number;\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 /** id → cumulative write-failure count, for rate-limited alerting. */\n private readonly failCounts = new Map<string, number>();\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 this.retryAttempts = Math.max(1, opts.retryAttempts ?? 6);\n this.retryBaseMs = Math.max(1, opts.retryBaseMs ?? 50);\n this.retryMaxMs = Math.max(this.retryBaseMs, opts.retryMaxMs ?? 1600);\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 let lastErr: unknown;\n for (let attempt = 0; attempt < this.retryAttempts; attempt++) {\n // Fresh temp name per attempt: on Windows a failed cleanup can\n // leave the previous name delete-pending, and creating over a\n // tombstoned name fails immediately — reusing it would burn every\n // remaining attempt before the write even happens.\n const tmp = this.tempPath(file);\n try {\n fs.writeFileSync(tmp, data, \"utf8\");\n fs.renameSync(tmp, file);\n lastErr = undefined;\n break;\n } catch (e) {\n lastErr = e;\n try {\n fs.unlinkSync(tmp);\n } catch {\n // temp never created or already gone\n }\n const code = (e as NodeJS.ErrnoException).code;\n if (code !== \"EPERM\" && code !== \"EBUSY\" && code !== \"EACCES\") break;\n if (attempt === this.retryAttempts - 1) break;\n // sync sleep (Atomics.wait) — backoff grows per attempt\n Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, this.backoffMs(attempt));\n }\n }\n if (!lastErr) {\n this.discovered.set(id, file);\n this.clearFailure(id);\n this.removeSpillSync(file);\n return true;\n }\n // The canonical rename outlived the retry window (Windows lock held by\n // AV/indexer/SMB). Spill to a side file so the data still lands on\n // disk instead of being dropped — loadAll picks the freshest of the\n // canonical and the spill.\n let spillPath: string | null = null;\n try {\n const spill = this.spillPathFor(file);\n fs.writeFileSync(spill, data, \"utf8\");\n spillPath = spill;\n this.discovered.set(id, spill);\n } catch {\n // spillover also failed (dir read-only / disk full) — data at risk\n }\n this.recordFailure(id, lastErr, spillPath);\n return spillPath !== null;\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 base = path.basename(file);\n const relBase = path.basename(this.relPathOf(envelope.id, envelope.payload));\n const flatBase = flatFileNameFor(envelope.id);\n // A file is a valid record for its envelope id when its name is the\n // canonical name OR a spill (`.fb`) of the canonical name. This lets\n // a spilled record (written while the canonical was locked) be\n // discovered and reconciled against the canonical by savedAt.\n let owner: string | null = null;\n if (base === relBase || base === flatBase) {\n owner = envelope.id;\n } else if (base.endsWith(\".fb.json\")) {\n const canonicalBase = `${base.slice(0, -\".fb.json\".length)}.json`;\n if (canonicalBase === relBase || canonicalBase === flatBase) {\n owner = envelope.id;\n }\n }\n if (owner === null) {\n this.log(\"warn\", `[persist] skipping ${rel(file, this.dir)}: filename does not match record id`);\n continue;\n }\n const existing = out.get(owner);\n if (!existing || envelope.savedAt >= existing.savedAt) {\n out.set(owner, envelope);\n this.discovered.set(owner, file);\n }\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 const env = this.envelope(id, payload);\n try {\n await fsp.writeFile(tmp, JSON.stringify(env), \"utf8\");\n await this.renameWithRetry(tmp, file);\n this.discovered.set(id, file);\n this.clearFailure(id);\n await this.removeSpill(file);\n } catch (e) {\n // Clean up the .tmp orphan so the next write doesn't collide with it.\n await fsp.unlink(tmp).catch(() => {});\n // The canonical rename outlived the retry window (Windows lock held\n // by AV/indexer/SMB). Spill to a side file so the data still lands\n // on disk instead of being dropped — loadAll picks the freshest of\n // the canonical and the spill.\n let spillPath: string | null = null;\n try {\n const spill = this.spillPathFor(file);\n await fsp.writeFile(spill, JSON.stringify(env), \"utf8\");\n spillPath = spill;\n this.discovered.set(id, spill);\n } catch {\n // spillover also failed (dir read-only / disk full) — data at risk\n }\n this.recordFailure(id, e, spillPath);\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 private backoffMs(attempt: number): number {\n return Math.min(this.retryBaseMs * 2 ** attempt, this.retryMaxMs);\n }\n\n /** Side file for a record whose canonical write keeps failing: the\n * canonical name with a `.fb` (fallback) infix, e.g. `a.json` →\n * `a.fb.json`. One slot per id, overwritten on each spill, so a stuck\n * lock never accumulates files. Ends in `.json` so loadAll discovers it. */\n private spillPathFor(file: string): string {\n const base = path.basename(file);\n const dot = base.lastIndexOf(\".\");\n const stem = dot > 0 ? base.slice(0, dot) : base;\n const ext = dot > 0 ? base.slice(dot) : \".json\";\n return path.join(path.dirname(file), `${stem}.fb${ext}`);\n }\n\n /** Remove a stale spill after a successful canonical write (best-effort). */\n private async removeSpill(file: string): Promise<void> {\n await fsp.unlink(this.spillPathFor(file)).catch(() => {});\n }\n\n private removeSpillSync(file: string): void {\n try {\n fs.unlinkSync(this.spillPathFor(file));\n } catch {\n // no spill or still locked — loadAll reconciles by savedAt\n }\n }\n\n /** Rate-limited failure alerting: log on the first failure and at each\n * power-of-two count (1,2,4,8,…), so a long lock yields ~log2(N) lines\n * instead of one per write. Includes the spill path so the operator can\n * see where the data landed. */\n private recordFailure(id: string, err: unknown, spillPath: string | null): void {\n const count = (this.failCounts.get(id) ?? 0) + 1;\n this.failCounts.set(id, count);\n const alertAt = count === 1 || (count >= 2 && (count & (count - 1)) === 0);\n if (!alertAt) return;\n const where = spillPath\n ? `; data spilled to ${rel(spillPath, this.dir)}`\n : \"; SPILLOVER ALSO FAILED — data at risk\";\n this.log(count === 1 ? \"error\" : \"warn\", `[persist] write failed for ${id} (total ${count}x): ${errText(err)}${where}`);\n }\n\n private clearFailure(id: string): void {\n this.failCounts.delete(id);\n }\n\n /** fs.rename with exponential-backoff retries on Windows transient locks\n * (EPERM/EBUSY/EACCES from AV scan, search indexer, SMB). Other errors\n * are real and rethrown immediately. */\n private async renameWithRetry(src: string, dest: string): Promise<void> {\n let lastErr: unknown;\n for (let attempt = 0; attempt < this.retryAttempts; 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 if (attempt === this.retryAttempts - 1) throw e;\n const { promise, resolve } = Promise.withResolvers<void>();\n setTimeout(resolve, this.backoffMs(attempt));\n await promise;\n }\n }\n throw lastErr;\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\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 absorbed: parsed.absorbed ?? fresh.absorbed,\n };\n}\n"],"mappings":"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","names":["rel"]}
|
package/dist/persist/store.d.ts
CHANGED
|
@@ -66,6 +66,18 @@ export interface StateStoreOptions<T> {
|
|
|
66
66
|
* (string id, non-null payload).
|
|
67
67
|
*/
|
|
68
68
|
validate?: (envelope: PersistedEnvelope<T>) => boolean;
|
|
69
|
+
/**
|
|
70
|
+
* Rename-retry policy for Windows transient locks (EPERM/EBUSY/EACCES
|
|
71
|
+
* from AV scan, search indexer, SMB). Exponential backoff: the delay
|
|
72
|
+
* after attempt i is min(retryBaseMs * 2^i, retryMaxMs). Defaults
|
|
73
|
+
* (6 attempts, 50ms base, 1600ms cap) give a ~1.5s window — long enough
|
|
74
|
+
* for most AV locks to release, short enough not to stall a sync flush.
|
|
75
|
+
* When the window is exhausted the write spills to a side file (see
|
|
76
|
+
* spillPath) instead of dropping the data.
|
|
77
|
+
*/
|
|
78
|
+
retryAttempts?: number;
|
|
79
|
+
retryBaseMs?: number;
|
|
80
|
+
retryMaxMs?: number;
|
|
69
81
|
}
|
|
70
82
|
/**
|
|
71
83
|
* Crash-safe, debounce-coalescing JSON state store. Mechanism only — lifted
|
|
@@ -73,17 +85,22 @@ export interface StateStoreOptions<T> {
|
|
|
73
85
|
*
|
|
74
86
|
* - atomic writes: temp file + rename, so a crash mid-write never leaves a
|
|
75
87
|
* truncated record (readers see either the old or the new file)
|
|
76
|
-
* - rename retries on Windows transient locks
|
|
88
|
+
* - rename retries with exponential backoff on Windows transient locks
|
|
89
|
+
* (EPERM/EBUSY/EACCES); when the window is exhausted the record spills to
|
|
90
|
+
* a side file (`<name>.fb.json`) instead of being dropped, so a lock held
|
|
91
|
+
* by AV/indexer/SMB never silently loses session data
|
|
77
92
|
* - per-id serialization so concurrent writeNow calls never interleave
|
|
78
93
|
* temp-file names or reorders writes
|
|
79
94
|
* - debounced scheduleSave coalesces bursts into one write; the record is
|
|
80
95
|
* built at WRITE time from a builder, so late mutations are picked up
|
|
81
96
|
* - loadAll skips `.tmp-*` orphans, corrupt JSON, and records whose
|
|
82
|
-
* filename does not match their id — one bad file never blocks boot
|
|
97
|
+
* filename does not match their id — one bad file never blocks boot; it
|
|
98
|
+
* reconciles a canonical record against its spill by savedAt (freshest wins)
|
|
83
99
|
*
|
|
84
|
-
* The store never deletes
|
|
85
|
-
*
|
|
86
|
-
*
|
|
100
|
+
* The store never deletes a record's data. On a successful canonical write it
|
|
101
|
+
* removes a now-stale spill of the SAME id (a duplicate, not distinct data).
|
|
102
|
+
* Session cleanup is a downstream policy decision (kernel position: persisted
|
|
103
|
+
* state should not be deleted opportunistically).
|
|
87
104
|
*/
|
|
88
105
|
export declare class StateStore<T> {
|
|
89
106
|
readonly enabled: boolean;
|
|
@@ -94,11 +111,16 @@ export declare class StateStore<T> {
|
|
|
94
111
|
private readonly legacyFn?;
|
|
95
112
|
private readonly relPathFn?;
|
|
96
113
|
private readonly validateFn;
|
|
114
|
+
private readonly retryAttempts;
|
|
115
|
+
private readonly retryBaseMs;
|
|
116
|
+
private readonly retryMaxMs;
|
|
97
117
|
private readonly timers;
|
|
98
118
|
private readonly pending;
|
|
99
119
|
private readonly writeChains;
|
|
100
120
|
/** id → absolute path, populated by writes and loadAll. */
|
|
101
121
|
private readonly discovered;
|
|
122
|
+
/** id → cumulative write-failure count, for rate-limited alerting. */
|
|
123
|
+
private readonly failCounts;
|
|
102
124
|
/** Monotonic counter for unique temp filenames within a process. */
|
|
103
125
|
private tmpSeq;
|
|
104
126
|
constructor(opts: StateStoreOptions<T>);
|
|
@@ -144,6 +166,25 @@ export declare class StateStore<T> {
|
|
|
144
166
|
/** Unique temp file next to the destination (same dir ⇒ same volume ⇒
|
|
145
167
|
* rename is atomic). Prefixed `.tmp-` so loadAll skips orphans. */
|
|
146
168
|
private tempPath;
|
|
169
|
+
private backoffMs;
|
|
170
|
+
/** Side file for a record whose canonical write keeps failing: the
|
|
171
|
+
* canonical name with a `.fb` (fallback) infix, e.g. `a.json` →
|
|
172
|
+
* `a.fb.json`. One slot per id, overwritten on each spill, so a stuck
|
|
173
|
+
* lock never accumulates files. Ends in `.json` so loadAll discovers it. */
|
|
174
|
+
private spillPathFor;
|
|
175
|
+
/** Remove a stale spill after a successful canonical write (best-effort). */
|
|
176
|
+
private removeSpill;
|
|
177
|
+
private removeSpillSync;
|
|
178
|
+
/** Rate-limited failure alerting: log on the first failure and at each
|
|
179
|
+
* power-of-two count (1,2,4,8,…), so a long lock yields ~log2(N) lines
|
|
180
|
+
* instead of one per write. Includes the spill path so the operator can
|
|
181
|
+
* see where the data landed. */
|
|
182
|
+
private recordFailure;
|
|
183
|
+
private clearFailure;
|
|
184
|
+
/** fs.rename with exponential-backoff retries on Windows transient locks
|
|
185
|
+
* (EPERM/EBUSY/EACCES from AV scan, search indexer, SMB). Other errors
|
|
186
|
+
* are real and rethrown immediately. */
|
|
187
|
+
private renameWithRetry;
|
|
147
188
|
/** Parse + validate one file. Corrupt or invalid records return null
|
|
148
189
|
* (logged) instead of throwing — load paths must never block boot. */
|
|
149
190
|
private readEnvelope;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/persist/store.ts"],"names":[],"mappings":"AAKA,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAEpF;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,CAAC,CAAC;CACd;AAED;2DAC2D;AAC3D,MAAM,WAAW,cAAc,CAAC,CAAC;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAChC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;gCAC4B;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,MAAM,CAAC;IAC7C;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;
|
|
1
|
+
{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/persist/store.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED