@zelari/core 2.37.3 → 2.38.0

package/dist/runtime/providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/runtime/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,0EAA0E;AAC1E,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAG/B;IACA;IAHT,IAAI,GAAG,uBAAuB,CAAC;IACxC,YACkB,IAAY,EACZ,SAAiB;QAEjC,KAAK,CAAC,gCAAgC,SAAS,WAAW,IAAI,GAAG,CAAC,CAAC;QAHnD,SAAI,GAAJ,IAAI,CAAQ;QACZ,cAAS,GAAT,SAAS,CAAQ;QAGjC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAYD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAW;IACrD,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,wBAAwB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,6CAA6C;AAC7C,MAAM,OAAO,cAAc;IAGJ;IAFZ,IAAI,GAAG,OAAgB,CAAC;IAEjC,YAAqB,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;IAErC,OAAO,CAAC,GAAW;QACjB,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;CACF;AAkDD,+EAA+E;AAC/E,MAAM,OAAO,oBAAoB;IACtB,SAAS,GAAG,KAAK,CAAC;IAE3B,KAAK,CAAC,OAAO,CAAC,IAAkB;QAC9B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,+DAA+D,IAAI,CAAC,IAAI,IAAI;SACzF,CAAC;IACJ,CAAC;CACF;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAqB,IAAI,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/runtime/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,0EAA0E;AAC1E,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAG/B;IACA;IAHT,IAAI,GAAG,uBAAuB,CAAC;IACxC,YACkB,IAAY,EACZ,SAAiB;QAEjC,KAAK,CAAC,gCAAgC,SAAS,WAAW,IAAI,GAAG,CAAC,CAAC;QAHnD,SAAI,GAAJ,IAAI,CAAQ;QACZ,cAAS,GAAT,SAAS,CAAQ;QAGjC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAYD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAW;IACrD,MAAM,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,wBAAwB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,6CAA6C;AAC7C,MAAM,OAAO,cAAc;IAGJ;IAFZ,IAAI,GAAG,OAAgB,CAAC;IAEjC,YAAqB,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;IAErC,OAAO,CAAC,GAAW;QACjB,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;CACF;AA0DD,+EAA+E;AAC/E,MAAM,OAAO,oBAAoB;IACtB,SAAS,GAAG,KAAK,CAAC;IAE3B,KAAK,CAAC,OAAO,CAAC,IAAkB;QAC9B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE,+DAA+D,IAAI,CAAC,IAAI,IAAI;SACzF,CAAC;IACJ,CAAC;CACF;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAqB,IAAI,oBAAoB,EAAE,CAAC"}

package/dist/session/index.d.ts

@@ -11,6 +11,7 @@ export * from './compaction.js';
 export * from './agentAdapter.js';
 export * from './writer.js';
 export * from './replay.js';
+export * from './replayCache.js';
 export * from './store.js';
 export * from './lineage.js';
 export * from './exportSession.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/session/index.js

@@ -11,6 +11,7 @@ export * from './compaction.js';
 export * from './agentAdapter.js';
 export * from './writer.js';
 export * from './replay.js';
+export * from './replayCache.js';
 export * from './store.js';
 export * from './lineage.js';
 export * from './exportSession.js';

package/dist/session/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}

package/dist/session/replay.d.ts

@@ -24,6 +24,24 @@ export interface ReplayReport {
     ok: boolean;
 }
 export declare function readSessionLog(filePath: string): Promise<ReplayReport>;
+/** Whole-file text → ReplayReport (shared with the incremental reader, Int4a). */
+export declare function parseSessionLogText(filePath: string, content: string): ReplayReport;
+/**
+ * Parse ONE batch of raw JSONL lines (as produced by `split('\n')`), carrying
+ * the running `expected` seq and the 0-based index of the batch's first line.
+ * The full reader above and the incremental byte-append reader (replayCache.ts)
+ * share this, so both report the SAME events/issues for the same log — that
+ * equivalence is the replay-cache contract.
+ */
+export declare function parseSessionLogLines(lines: readonly string[], opts?: {
+    expected?: number;
+    linesConsumed?: number;
+}): {
+    events: SessionEventEnvelope[];
+    issues: ReplayIssue[];
+    expected: number;
+    linesConsumed: number;
+};
 /** Loose summary of a verification.run event (defensive reads). */
 export interface VerificationRunSummary {
     seq: number;

package/dist/session/replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/session/replay.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/E,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,SAAS,GACT,kBAAkB,CAAC;AAEvB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,4DAA4D;IAC5D,EAAE,EAAE,OAAO,CAAC;CACb;AAED,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAoD5E;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,sBAAsB,EAAE,CAAC;IACxC,aAAa,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,0EAA0E;IAC1E,aAAa,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,uEAAuE;IACvE,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACrC;AAmBD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EAAE,MAAM,GAAE,WAAW,EAAO,GAAG,iBAAiB,CA4DtH"}
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/session/replay.ts"],"names":[],"mappings":"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"}

package/dist/session/replay.js

@@ -20,15 +20,30 @@ export async function readSessionLog(filePath) {
         }
         throw err;
     }
+    return parseSessionLogText(filePath, content);
+}
+/** Whole-file text → ReplayReport (shared with the incremental reader, Int4a). */
+export function parseSessionLogText(filePath, content) {
+    const { events, issues } = parseSessionLogLines(content.split('\n'));
+    return { path: filePath, events, issues, ok: issues.length === 0 };
+}
+/**
+ * Parse ONE batch of raw JSONL lines (as produced by `split('\n')`), carrying
+ * the running `expected` seq and the 0-based index of the batch's first line.
+ * The full reader above and the incremental byte-append reader (replayCache.ts)
+ * share this, so both report the SAME events/issues for the same log — that
+ * equivalence is the replay-cache contract.
+ */
+export function parseSessionLogLines(lines, opts = {}) {
     const events = [];
     const issues = [];
-    let expected = 1;
-    const lines = content.split('\n');
+    const base = opts.linesConsumed ?? 0;
+    let expected = opts.expected ?? 1;
     for (let i = 0; i < lines.length; i++) {
         const trimmed = lines[i].trim();
         if (!trimmed)
             continue;
-        const lineNo = i + 1;
+        const lineNo = base + i + 1;
         let parsed;
         try {
             parsed = JSON.parse(trimmed);
@@ -65,7 +80,7 @@ export async function readSessionLog(filePath) {
             expected = envelope.seq + 1;
         }
     }
-    return { path: filePath, events, issues, ok: issues.length === 0 };
+    return { events, issues, expected, linesConsumed: base + lines.length };
 }
 function parseVerification(e) {
     const raw = Array.isArray(e.data.results) ? e.data.results : [];

package/dist/session/replay.js.map

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

package/dist/session/replayCache.d.ts

@@ -0,0 +1,76 @@
+/**
+ * session/replayCache.ts — Int4a incremental replay cache for long sessions.
+ *
+ * `readSessionLog()` re-reads the WHOLE JSONL and Zod-parses every line on
+ * every call, and the spine does it 2–8 times per turn: O(n²) in session
+ * length. This cache keeps the parsed events per file and, on a later call,
+ * reads only the bytes appended since the last read (COMPLETE lines only).
+ *
+ * Invariants:
+ *   - `byteSize` is what the entry OWNS: every complete line consumed plus the
+ *     bytes held in `partial`. It always sits on a UTF-8 character boundary, so
+ *     the next read starts exactly there and no byte is ever parsed twice.
+ *   - A tail without its final '\n' stays in `partial` and is NOT an event yet:
+ *     it appears exactly once, when the writer completes the line. A tail
+ *     ending INSIDE a multi-byte character is not consumed at all (re-read from
+ *     a boundary) — a torn write can never poison the cache with U+FFFD.
+ *   - Shrink (`size < byteSize`) or a backwards mtime (rotation / in-place
+ *     rewrite) ⇒ full re-read through the SAME parse path as `readSessionLog`,
+ *     so a replaced log is never served from stale entries.
+ *   - The returned ReplayReport is fresh (caller-owned arrays); the envelopes
+ *     inside are shared and treat-as-immutable — the spine contract.
+ *   - Known deviation: a COLD read (empty cache / rotation) consumes a
+ *     non-terminated last line exactly as `readSessionLog` does today; only
+ *     appends observed while warm are deferred into `partial`. The writer
+ *     always terminates lines with '\n', so this needs external truncation.
+ *
+ * Kill switch `ZELARI_SPINE_REPLAY_CACHE`: DEFAULT OFF in this merge (dogfood
+ * first) — set `1`/`true`/`yes`/`on` to enable. When unset/0/false/off,
+ * `readSessionLogCached` calls the existing `readSessionLog` verbatim.
+ */
+import { type ReplayIssue, type ReplayReport } from './replay.js';
+import type { SessionEventEnvelope } from './types.js';
+/** `ZELARI_SPINE_REPLAY_CACHE` (default OFF): truthy spelling = 1/true/yes/on. */
+export declare function isReplayCacheEnabled(env?: NodeJS.ProcessEnv): boolean;
+export interface ReplayCacheEntry {
+    /** Bytes owned by this entry: complete lines + the bytes held in `partial`. */
+    byteSize: number;
+    mtimeMs: number;
+    events: SessionEventEnvelope[];
+    issues: ReplayIssue[];
+    /** Seq the next event must carry to be accepted gap-free. */
+    expectedSeq: number;
+    /** Tail without a final '\n' (writer crash mid-line) — not yet an event. */
+    partial: string;
+    /**
+     * Lines consumed so far, blank/corrupt ones included, so a new issue keeps
+     * its ORIGINAL 1-based file line number (`linesConsumed + index + 1`).
+     * Additive to the planned entry shape: without it an incremental read would
+     * renumber issues and stop being equivalent to `readSessionLog`.
+     */
+    linesConsumed: number;
+}
+/**
+ * Incremental replay cache. Own ONE instance per session (the spine mirror owns
+ * its own); entries are keyed by file path, so concurrent sessions never share
+ * decoded state.
+ */
+export declare class SessionLogCache {
+    private readonly entries;
+    /** Files currently cached (diagnostics). */
+    get size(): number;
+    /** The cached entry for `filePath` (copy; tests + diagnostics), if any. */
+    peek(filePath: string): ReplayCacheEntry | undefined;
+    /** Read the log, incrementally when a usable entry exists. */
+    read(filePath: string): Promise<ReplayReport>;
+    /** Append-path read: only the bytes written since the last read are parsed. */
+    private extend;
+    /** Cold / rotated read: same parse as `readSessionLog`, then seed the entry. */
+    private full;
+}
+/**
+ * Cached read of a session log. Without a cache — or with the kill switch off
+ * (the default in this merge) — this is `readSessionLog` verbatim.
+ */
+export declare function readSessionLogCached(filePath: string, cache?: SessionLogCache, env?: NodeJS.ProcessEnv): Promise<ReplayReport>;
+//# sourceMappingURL=replayCache.d.ts.map

package/dist/session/replayCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replayCache.d.ts","sourceRoot":"","sources":["../../src/session/replayCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAMvD,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAGlF;AAED,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAuCD;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAE/D,4CAA4C;IAC5C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,2EAA2E;IAC3E,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAKpD,8DAA8D;IACxD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAmBnD,+EAA+E;YACjE,MAAM;IAwCpB,gFAAgF;YAClE,IAAI;CA6BnB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,eAAe,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAAC,YAAY,CAAC,CAGvB"}

package/dist/session/replayCache.js

@@ -0,0 +1,188 @@
+/**
+ * session/replayCache.ts — Int4a incremental replay cache for long sessions.
+ *
+ * `readSessionLog()` re-reads the WHOLE JSONL and Zod-parses every line on
+ * every call, and the spine does it 2–8 times per turn: O(n²) in session
+ * length. This cache keeps the parsed events per file and, on a later call,
+ * reads only the bytes appended since the last read (COMPLETE lines only).
+ *
+ * Invariants:
+ *   - `byteSize` is what the entry OWNS: every complete line consumed plus the
+ *     bytes held in `partial`. It always sits on a UTF-8 character boundary, so
+ *     the next read starts exactly there and no byte is ever parsed twice.
+ *   - A tail without its final '\n' stays in `partial` and is NOT an event yet:
+ *     it appears exactly once, when the writer completes the line. A tail
+ *     ending INSIDE a multi-byte character is not consumed at all (re-read from
+ *     a boundary) — a torn write can never poison the cache with U+FFFD.
+ *   - Shrink (`size < byteSize`) or a backwards mtime (rotation / in-place
+ *     rewrite) ⇒ full re-read through the SAME parse path as `readSessionLog`,
+ *     so a replaced log is never served from stale entries.
+ *   - The returned ReplayReport is fresh (caller-owned arrays); the envelopes
+ *     inside are shared and treat-as-immutable — the spine contract.
+ *   - Known deviation: a COLD read (empty cache / rotation) consumes a
+ *     non-terminated last line exactly as `readSessionLog` does today; only
+ *     appends observed while warm are deferred into `partial`. The writer
+ *     always terminates lines with '\n', so this needs external truncation.
+ *
+ * Kill switch `ZELARI_SPINE_REPLAY_CACHE`: DEFAULT OFF in this merge (dogfood
+ * first) — set `1`/`true`/`yes`/`on` to enable. When unset/0/false/off,
+ * `readSessionLogCached` calls the existing `readSessionLog` verbatim.
+ */
+import { promises as fs } from 'node:fs';
+import { readSessionLog, parseSessionLogLines, } from './replay.js';
+/** `ZELARI_SPINE_REPLAY_CACHE` (default OFF): truthy spelling = 1/true/yes/on. */
+export function isReplayCacheEnabled(env = process.env) {
+    const v = (env.ZELARI_SPINE_REPLAY_CACHE ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+const NL = 0x0a;
+/** >0 when `buf` ends inside a multi-byte UTF-8 sequence (bytes to leave unread). */
+function utf8IncompleteTailBytes(buf) {
+    const max = Math.min(4, buf.length);
+    for (let back = 1; back <= max; back++) {
+        const b = buf[buf.length - back];
+        if (b < 0x80)
+            return 0; // ASCII tail — complete
+        if (b >= 0xc0) {
+            // Lead byte: it must be followed by (need - 1) continuation bytes.
+            const need = b >= 0xf0 ? 4 : b >= 0xe0 ? 3 : 2;
+            return back >= need ? 0 : need - back;
+        }
+        // 0x80..0xbf = continuation byte — walk back to its lead byte.
+    }
+    return 0; // no lead byte within 4 bytes: malformed anyway, let JSON.parse judge
+}
+/** Read exactly `length` bytes at `position` (a live writer may shorten reads). */
+async function readAt(fh, position, length) {
+    const buf = Buffer.allocUnsafe(length);
+    let done = 0;
+    while (done < length) {
+        const { bytesRead } = await fh.read(buf, done, length - done, position + done);
+        if (bytesRead === 0)
+            break; // truncated under us — parse what we got
+        done += bytesRead;
+    }
+    return done === length ? buf : buf.subarray(0, done);
+}
+/** Fresh report over the cached arrays — a consumer may mutate them freely. */
+function toReport(filePath, entry) {
+    const events = entry.events.slice();
+    const issues = entry.issues.slice();
+    return { path: filePath, events, issues, ok: issues.length === 0 };
+}
+/**
+ * Incremental replay cache. Own ONE instance per session (the spine mirror owns
+ * its own); entries are keyed by file path, so concurrent sessions never share
+ * decoded state.
+ */
+export class SessionLogCache {
+    entries = new Map();
+    /** Files currently cached (diagnostics). */
+    get size() {
+        return this.entries.size;
+    }
+    /** The cached entry for `filePath` (copy; tests + diagnostics), if any. */
+    peek(filePath) {
+        const entry = this.entries.get(filePath);
+        return entry ? { ...entry } : undefined;
+    }
+    /** Read the log, incrementally when a usable entry exists. */
+    async read(filePath) {
+        const cached = this.entries.get(filePath);
+        let stat;
+        try {
+            stat = await fs.stat(filePath);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                this.entries.delete(filePath);
+                return { path: filePath, events: [], issues: [], ok: true };
+            }
+            throw err;
+        }
+        if (cached && stat.size >= cached.byteSize && stat.mtimeMs >= cached.mtimeMs) {
+            if (stat.size > cached.byteSize)
+                return this.extend(filePath, cached, stat);
+            return toReport(filePath, cached); // nothing new — no I/O at all
+        }
+        return this.full(filePath, stat);
+    }
+    /** Append-path read: only the bytes written since the last read are parsed. */
+    async extend(filePath, cached, stat) {
+        const fh = await fs.open(filePath, 'r');
+        let chunk;
+        try {
+            chunk = await readAt(fh, cached.byteSize, stat.size - cached.byteSize);
+        }
+        finally {
+            await fh.close();
+        }
+        const nl = chunk.lastIndexOf(NL);
+        const headEnd = nl === -1 ? 0 : nl + 1; // end of the last COMPLETE line
+        const tail = chunk.subarray(headEnd);
+        // PERF-4a: bytes of the tail that decode cleanly. A tail ending INSIDE a
+        // multi-byte char stays unconsumed and is re-read from a boundary, so
+        // `partial` is never a U+FFFD-mangled fragment.
+        const keep = tail.subarray(0, tail.length - utf8IncompleteTailBytes(tail));
+        // The old `partial` is folded into `head` only once a newline arrives; while
+        // no line completes it stays in front of the unconsumed tail.
+        const head = cached.partial + chunk.subarray(0, headEnd).toString('utf8');
+        const lines = headEnd > 0 ? head.split('\n').slice(0, -1) : [];
+        const parsed = parseSessionLogLines(lines, {
+            expected: cached.expectedSeq,
+            linesConsumed: cached.linesConsumed,
+        });
+        const entry = {
+            byteSize: cached.byteSize + headEnd + keep.length,
+            mtimeMs: stat.mtimeMs,
+            events: parsed.events.length > 0 ? cached.events.concat(parsed.events) : cached.events,
+            issues: parsed.issues.length > 0 ? cached.issues.concat(parsed.issues) : cached.issues,
+            expectedSeq: parsed.expected,
+            partial: (headEnd > 0 ? '' : cached.partial) + keep.toString('utf8'),
+            linesConsumed: parsed.linesConsumed,
+        };
+        this.entries.set(filePath, entry);
+        return toReport(filePath, entry);
+    }
+    /** Cold / rotated read: same parse as `readSessionLog`, then seed the entry. */
+    async full(filePath, stat) {
+        let content;
+        try {
+            content = await fs.readFile(filePath, 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                this.entries.delete(filePath);
+                return { path: filePath, events: [], issues: [], ok: true };
+            }
+            throw err;
+        }
+        const lines = content.split('\n');
+        const parsed = parseSessionLogLines(lines);
+        // Count the lines this read consumed: the split's trailing '' is the
+        // artificial piece after the final '\n'; a torn tail is already parsed.
+        const linesConsumed = content.length === 0 ? 0 : content.endsWith('\n') ? lines.length - 1 : lines.length;
+        const entry = {
+            // Bytes actually read (never the pre-read stat: the log may have grown).
+            byteSize: Buffer.byteLength(content, 'utf8'),
+            mtimeMs: stat.mtimeMs,
+            events: parsed.events,
+            issues: parsed.issues,
+            expectedSeq: parsed.expected,
+            partial: '',
+            linesConsumed,
+        };
+        this.entries.set(filePath, entry);
+        return { path: filePath, events: entry.events.slice(), issues: entry.issues.slice(), ok: entry.issues.length === 0 };
+    }
+}
+/**
+ * Cached read of a session log. Without a cache — or with the kill switch off
+ * (the default in this merge) — this is `readSessionLog` verbatim.
+ */
+export async function readSessionLogCached(filePath, cache, env = process.env) {
+    if (!cache || !isReplayCacheEnabled(env))
+        return readSessionLog(filePath);
+    return cache.read(filePath);
+}
+//# sourceMappingURL=replayCache.js.map

package/dist/session/replayCache.js.map

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

package/dist/verification/commandConcurrency.d.ts

@@ -0,0 +1,34 @@
+/**
+ * verification/commandConcurrency.ts — Int2a gate fan-out policy (ADR-0023).
+ *
+ * A criteria pack runs independent PROCESSES (typecheck / test / build) that
+ * are not independent WRITES: on this repo `test` rebuilds `@zelari/core` into
+ * `packages/core/dist` while `build` cleans the very same path, so a parallel
+ * run can read a partial `dist` and produce flaky FAILs. Fail-closed is not
+ * good enough — a flaky gate destroys trust in strict-done exactly like a
+ * false PASS does, so fan-out is OPT-IN per repo and OFF by default.
+ *
+ *   ZELARI_VERIFY_PARALLEL     1|true|yes|on → bounded parallel evaluation of
+ *                              command criteria (anything else → sequential)
+ *   ZELARI_VERIFY_CONCURRENCY  max commands in flight, default 3
+ *
+ * Kill-switch: unset, `0` or any unrecognized value → 1, i.e. the sequential
+ * `for...of` path this engine has always used (same order, same events).
+ *
+ * @since v2.38.x
+ */
+/** Only used when parallelism is explicitly enabled and no limit is given. */
+export declare const DEFAULT_COMMAND_CONCURRENCY = 3;
+/**
+ * Parallel evaluation is opt-in: `1|true|yes|on` (case/space insensitive)
+ * enables it, everything else — including unset — keeps the gate sequential.
+ */
+export declare function isVerifyParallelEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * Effective max number of command criteria in flight: `1` unless parallelism
+ * is enabled. `ZELARI_VERIFY_CONCURRENCY` is only consulted when enabled and
+ * is clamped to >= 1 (a bad value can never deadlock or fan out unbounded —
+ * the runner additionally clamps to the number of criteria).
+ */
+export declare function resolveCommandConcurrency(env?: Record<string, string | undefined>): number;
+//# sourceMappingURL=commandConcurrency.d.ts.map

package/dist/verification/commandConcurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandConcurrency.d.ts","sourceRoot":"","sources":["../../src/verification/commandConcurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAI7C;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAGT;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,CAKR"}

package/dist/verification/commandConcurrency.js

@@ -0,0 +1,45 @@
+/**
+ * verification/commandConcurrency.ts — Int2a gate fan-out policy (ADR-0023).
+ *
+ * A criteria pack runs independent PROCESSES (typecheck / test / build) that
+ * are not independent WRITES: on this repo `test` rebuilds `@zelari/core` into
+ * `packages/core/dist` while `build` cleans the very same path, so a parallel
+ * run can read a partial `dist` and produce flaky FAILs. Fail-closed is not
+ * good enough — a flaky gate destroys trust in strict-done exactly like a
+ * false PASS does, so fan-out is OPT-IN per repo and OFF by default.
+ *
+ *   ZELARI_VERIFY_PARALLEL     1|true|yes|on → bounded parallel evaluation of
+ *                              command criteria (anything else → sequential)
+ *   ZELARI_VERIFY_CONCURRENCY  max commands in flight, default 3
+ *
+ * Kill-switch: unset, `0` or any unrecognized value → 1, i.e. the sequential
+ * `for...of` path this engine has always used (same order, same events).
+ *
+ * @since v2.38.x
+ */
+/** Only used when parallelism is explicitly enabled and no limit is given. */
+export const DEFAULT_COMMAND_CONCURRENCY = 3;
+const PARALLEL_TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+/**
+ * Parallel evaluation is opt-in: `1|true|yes|on` (case/space insensitive)
+ * enables it, everything else — including unset — keeps the gate sequential.
+ */
+export function isVerifyParallelEnabled(env = process.env) {
+    const raw = env.ZELARI_VERIFY_PARALLEL?.trim().toLowerCase();
+    return raw !== undefined && PARALLEL_TRUTHY.has(raw);
+}
+/**
+ * Effective max number of command criteria in flight: `1` unless parallelism
+ * is enabled. `ZELARI_VERIFY_CONCURRENCY` is only consulted when enabled and
+ * is clamped to >= 1 (a bad value can never deadlock or fan out unbounded —
+ * the runner additionally clamps to the number of criteria).
+ */
+export function resolveCommandConcurrency(env = process.env) {
+    if (!isVerifyParallelEnabled(env))
+        return 1;
+    const raw = Number(env.ZELARI_VERIFY_CONCURRENCY);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_COMMAND_CONCURRENCY;
+    return Math.floor(raw);
+}
+//# sourceMappingURL=commandConcurrency.js.map

package/dist/verification/commandConcurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandConcurrency.js","sourceRoot":"","sources":["../../src/verification/commandConcurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAA0C,OAAO,CAAC,GAAG;IAErD,MAAM,GAAG,GAAG,GAAG,CAAC,sBAAsB,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7D,OAAO,GAAG,KAAK,SAAS,IAAI,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAA0C,OAAO,CAAC,GAAG;IAErD,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,2BAA2B,CAAC;IAC1E,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}

package/dist/verification/engine.d.ts

@@ -12,6 +12,23 @@
  * output tails) and, when the emitter resolves to the appended envelope, the
  * assigned seq anchors the EvidenceRef — evidence is traceable to the
  * session event that captured it, not to a narrated summary.
+ *
+ * Int2b: when the injected shell is decorated with a result cache (see
+ * `src/cli/kraken/cachedShell.ts`), a served-from-cache observation is
+ * ANNOTATED, never reinterpreted — `detail` gains a " (cached — tree unchanged
+ * since last run)" suffix and the evidence event carries an optional
+ * `cached: true`. Status, digest and evidence payload shape are untouched, so
+ * caching can change the latency of a verdict but never the verdict.
+ *
+ * Int2a: command criteria MAY be evaluated concurrently with a bounded
+ * fan-out (`commandConcurrency`, default OFF — see `./commandConcurrency.ts`).
+ * Parallelism is about `evaluateOne` concurrency, the cache is about shell
+ * exec reuse; they compose. Only the LATENCY changes: results keep the
+ * criteria order of `verification.run`, and `verification.evidence` events may
+ * interleave because each ref is anchored to its OWN event seq (a seq anchors
+ * an observation, it never depends on the position of the event in the log).
+ * When the fan-out is 1 (default, or the kill-switch) the loop below is the
+ * untouched sequential path.
  */
 import type { FsProvider, ShellProvider } from '../runtime/providers.js';
 import type { SessionEventInput } from '../session/types.js';
@@ -30,6 +47,14 @@ export interface VerificationEngineOptions {
     emit?: (input: SessionEventInput) => Promise<unknown>;
     now?: () => number;
     sha256?: (input: string) => string;
+    /**
+     * Max command criteria evaluated concurrently. `undefined` (the default)
+     * resolves through `resolveCommandConcurrency()` — i.e. 1 unless the
+     * environment opts in via `ZELARI_VERIFY_PARALLEL=1`. `<= 1` always means
+     * the plain sequential loop; a host that wires the flag explicitly should
+     * keep passing a value here.
+     */
+    commandConcurrency?: number;
 }
 export declare class VerificationEngine {
     private readonly services;

package/dist/verification/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/verification/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAe,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACpC;AAUD,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,QAAQ,GAAE,oBAAyB,EACnC,OAAO,GAAE,yBAA8B;IAG1D,4EAA4E;IACtE,QAAQ,CACZ,QAAQ,EAAE,SAAS,SAAS,EAAE,EAC9B,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,kBAAkB,CAAA;KAAO,GAC5D,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAkChC;;;;;OAKG;YACW,YAAY;YAiBZ,WAAW;YAmDX,WAAW;IAmDzB;;;;OAIG;YACW,UAAU;YAkBV,cAAc;YAmBd,cAAc;YAiBd,gBAAgB;CAyB/B"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/verification/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAe,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAI7E,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAkBD,qBAAa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,QAAQ,GAAE,oBAAyB,EACnC,OAAO,GAAE,yBAA8B;IAG1D,4EAA4E;IACtE,QAAQ,CACZ,QAAQ,EAAE,SAAS,SAAS,EAAE,EAC9B,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,kBAAkB,CAAA;KAAO,GAC5D,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA4ChC;;;;;OAKG;YACW,YAAY;YAiBZ,WAAW;YAmDX,WAAW;IAqEzB;;;;OAIG;YACW,UAAU;YAkBV,cAAc;YAmBd,cAAc;YAiBd,gBAAgB;CAyB/B"}