@sema-agent/core 7.29.0 → 7.30.0

package/dist/stores/cc/mailbox-store.js

@@ -202,9 +202,9 @@ export function createCcFileMailboxStore(opts) {
             const path = inboxPath(handle);
             const held = leases.get(leaseKey(handle));
             if (held === undefined || held.owner !== owner)
-                return Promise.resolve();
+                return Promise.resolve({ acked: false });
             if (!existsSync(path))
-                return Promise.resolve();
+                return Promise.resolve({ acked: false });
             const notes = deferredNotes();
             return withCcLock(path, () => {
                 const box = loadBox(path, notes.note);
@@ -219,6 +219,7 @@ export function createCcFileMailboxStore(opts) {
                     saveBox(path, box);
                 if (held.maxSeq <= upToSeq)
                     leases.delete(leaseKey(handle));
+                return { acked: true };
             }).finally(() => {
                 notes.flush();
             });

package/dist/stores/file/corrupt-read-sink.d.ts

@@ -4,8 +4,34 @@
  * hand-written four times. Three copies contained an async sink's rejection; the mailbox's caught only a
  * synchronous throw, so an `async` sink there became an unhandled rejection.
  */
-/** Coordinates of one durable read a store answered as absent because the bytes were corrupt. */
-export interface CorruptReadInfo {
+import type { CorruptBodyForm } from "../../core/store-contracts/read-back-shape-contract.js";
+/** One disclosure. Every level carries `path` + `reason`; `kind` names the level. */
+export type CorruptReadInfo = CorruptRecordRead | CorruptReplayTally | CorruptFileRead;
+/** One JSONL record a replay skipped: fired per skipped record, in file order, before its read's tally. */
+export interface CorruptRecordRead {
+    kind: "record";
+    path: string;
+    reason: string;
+    /** 1-based line of the skipped record. */
+    line: number;
+    form: CorruptBodyForm;
+}
+/**
+ * The count of one replay that skipped at least one record, fired once after its record disclosures; a
+ * read that skipped nothing fires none. `total` = `kept` + `dropped` (an unterminated crash tail is not a
+ * record); `kept === 0` = nothing in the file was readable.
+ */
+export interface CorruptReplayTally {
+    kind: "replay";
+    path: string;
+    reason: string;
+    kept: number;
+    dropped: number;
+    total: number;
+}
+/** A disclosure about a file or directory as a whole, outside any JSONL replay. */
+export interface CorruptFileRead {
+    kind: "file";
     path: string;
     reason: string;
 }

package/dist/stores/file/file-history-store.d.ts

@@ -1,6 +1,7 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
 import { type FileHistoryDiffStats, type FileHistoryExport, type FileHistoryResult, type FileHistoryRestoreResult, type FileHistoryStore, type FileHistoryTrackResult } from "../../core/file-history-store.js";
 import { type FileHistoryRetentionPolicy } from "../../core/file-history-retention.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 /**
  * design/381 slice 2 — the DURABLE file-backed {@link FileHistoryStore}: the per-edited-file rewind
  * history that survives a process restart (slice 1 shipped the contract + the in-memory reference,
@@ -75,10 +76,7 @@ export interface FileFileHistoryStoreOptions {
      * are then kept — leaked, never lost). Never fires on plain ENOENT: a scope with no history yet
      * really is empty. Swallow-guarded.
      */
-    onCorruptRead?: (info: {
-        path: string;
-        reason: string;
-    }) => void;
+    onCorruptRead?: (info: CorruptReadInfo) => void;
     /**
      * design/381 §片2 — the built-in boundary bound and its override. Omitted ⇒ the engine default
      * ({@link import("../../core/file-history-retention.js").DEFAULT_FILE_HISTORY_BOUNDARY_KEEP}

package/dist/stores/file/file-history-store.js

@@ -195,7 +195,7 @@ export class FileFileHistoryStore {
         }
     }
     disclose(path, reason) {
-        this.onCorruptRead?.({ path, reason });
+        this.onCorruptRead?.({ kind: "file", path, reason });
     }
     scopeDir(scope) {
         return join(this.scopesDir, sanitizeScope(scope));

package/dist/stores/file/fs-atomic.d.ts

@@ -1,3 +1,4 @@
+import type { CorruptRecordRead, CorruptReplayTally } from "./corrupt-read-sink.js";
 /**
  * Validate an engine-minted id (sessionId / tool-result ref) before using it as a path component. These are
  * `uuidv7` / an encoded tool-result ref — already filename-safe — but a strict guard is cheap
@@ -42,19 +43,23 @@ export declare function atomicWriteFile(tmpDir: string, target: string, bytes: s
  *
  * SHAPE (`@contract store.read_back_shape_judged`): parseability is not the judgement. Every store on this
  * format writes ONE JSON OBJECT per line, so a line parsing to a number, string, boolean, `null` or array
- * takes the road a torn line takes — disclosed, skipped, the replay intact — because it is the same fact:
- * these bytes are not what this store wrote. Without it `null` made a `line.kind` test throw.
+ * takes the road a torn line takes — disclosed and skipped — because it is the same fact: these bytes are
+ * not what this store wrote. `judge` (optional) is the consuming store's own floor on an object ("does it
+ * carry my members at all?"); a record it rejects is skipped as `missing-required` on the same road, so
+ * the count below covers every skip.
  *
- * `onCorrupt` (optional, review-510 disclosure-seat family): fired once per skipped INTERIOR record so a
- * caller-side seat can observe real corruption — a silently-skipped record is otherwise indistinguishable
- * from "less data"; its `reason` opens with the {@link CorruptBodyForm} word, so a sink classifies without
- * reading prose. The torn TAIL stays out by design: dying mid-write is the crash shape this format exists
- * to absorb. The callback is invoked as given — a seat that must not throw swallow-guards on ITS side.
+ * `onCorrupt` (optional): one `record` disclosure per skipped INTERIOR record, then — iff any was skipped —
+ * one `replay` tally. The torn TAIL stays out of both by design: dying mid-write is the crash shape this
+ * format exists to absorb. The callback is invoked as given — a seat that must not throw swallow-guards on
+ * ITS side.
  */
-export declare function readJsonlRecords<T>(path: string, onCorrupt?: (info: {
-    path: string;
-    reason: string;
-}) => void): T[];
+export declare function readJsonlRecords<T>(path: string, onCorrupt?: (info: CorruptRecordRead | CorruptReplayTally) => void, judge?: JsonlRecordJudge): T[];
+/** A consuming store's floor on a parsed JSONL object: `accepts` = one of its records; `what` names a
+ *  rejected one in the disclosure's words. */
+export interface JsonlRecordJudge {
+    accepts(record: object): boolean;
+    what: string;
+}
 /**
  * An append-only JSONL log opened once with `O_APPEND` and held for the file's lifetime. One record =
  * one `JSON.stringify(...) + "\n"` written in a SINGLE `writeSync` call (never split across writes → the

package/dist/stores/file/fs-atomic.js

@@ -105,7 +105,7 @@ function basenameOf(p) {
 function dirnameOf(p) {
     return dirname(p);
 }
-export function readJsonlRecords(path, onCorrupt) {
+export function readJsonlRecords(path, onCorrupt, judge) {
     let raw;
     try {
         raw = readFileSync(path, "utf8");
@@ -120,6 +120,11 @@ export function readJsonlRecords(path, onCorrupt) {
     const parts = raw.split("\n");
     const endedClean = parts[parts.length - 1] === "";
     const out = [];
+    let dropped = 0;
+    const discloseSkip = (form, line, what) => {
+        dropped++;
+        onCorrupt?.({ kind: "record", path, reason: `${form}: ${what} at line ${line} (skipped)`, line, form });
+    };
     for (let i = 0; i < parts.length; i++) {
         if (i === parts.length - 1 && !endedClean)
             break;
@@ -131,20 +136,26 @@ export function readJsonlRecords(path, onCorrupt) {
             record = JSON.parse(line);
         }
         catch {
-            onCorrupt?.({ path, reason: corruptRecordReason("torn-json", i + 1, "unparseable jsonl record") });
+            discloseSkip("torn-json", i + 1, "unparseable jsonl record");
             continue;
         }
         if (record === null || typeof record !== "object" || Array.isArray(record)) {
-            onCorrupt?.({ path, reason: corruptRecordReason("not-an-object", i + 1, `jsonl record is ${jsonTypeName(record)}, not an object`) });
+            discloseSkip("not-an-object", i + 1, `jsonl record is ${jsonTypeName(record)}, not an object`);
+            continue;
+        }
+        if (judge !== undefined && !judge.accepts(record)) {
+            discloseSkip("missing-required", i + 1, judge.what);
             continue;
         }
         out.push(record);
     }
+    if (dropped > 0) {
+        const total = out.length + dropped;
+        const reason = out.length === 0 ? `replay: none of ${total} records readable (all skipped)` : `replay: ${dropped} of ${total} records skipped, ${out.length} kept`;
+        onCorrupt?.({ kind: "replay", path, reason, kept: out.length, dropped, total });
+    }
     return out;
 }
-function corruptRecordReason(form, lineNo, what) {
-    return `${form}: ${what} at line ${lineNo} (skipped; the rest of the replay is intact)`;
-}
 function jsonTypeName(value) {
     if (value === null)
         return "null";

package/dist/stores/file/index.d.ts

@@ -5,6 +5,7 @@ import { type EvictPolicy } from "../../core/session-store.js";
 import type { SessionStore } from "../../core/session.js";
 import { type FileCheckpointStoreOptions } from "./checkpoint-store.js";
 import { type FileFileHistoryStoreOptions } from "./file-history-store.js";
+import type { CorruptReadInfo } from "./corrupt-read-sink.js";
 import type { FileHistoryStore } from "../../core/file-history-store.js";
 import type { StrategyStore } from "../../core/strategy-store.js";
 import type { BackgroundAgentStore } from "../../core/background-agent-store.js";
@@ -105,17 +106,15 @@ export interface FileStorageBackendOptions {
  * backend constructs can deliver, so ONE sink reaches all of them (a per-store payload type would make
  * the backend's forwarding contravariance-illegal, which is what kept the seat single-store).
  * `SessionPolicyCorruptReadInfo` is assignable to it; the two-field store seats are satisfied by it.
+ * `path` (absolute) and `reason` ride every level; `kind` tells a skipped JSONL record (`"record"`) and
+ * that replay's count (`"replay"`) from a disclosure about a file or directory as a whole (`"file"`).
  */
-export interface FileStorageCorruptReadInfo {
-    /** Absolute path of the offending file/directory. */
-    path: string;
-    /** What was observed and what the read degraded to. */
-    reason: string;
+export type FileStorageCorruptReadInfo = CorruptReadInfo & {
     /** Present only when the reading store keys by session (the session-policy face). */
     sessionId?: string;
     /** Present only when the read was keyed by a principal. */
     principal?: string;
-}
+};
 export declare class FileStorageBackend {
     /** The resolved, canonical data root all four stores live under. */
     readonly root: string;

package/dist/stores/file/index.js

@@ -89,7 +89,7 @@ export class FileStorageBackend {
                 root: strategiesRoot,
                 ...(opts.onCorruptRead !== undefined
                     ? {
-                        onIncident: (i) => opts.onCorruptRead?.({ path: i.path ?? strategiesRoot, reason: `strategy ${i.op}: ${i.error}` }),
+                        onIncident: (i) => opts.onCorruptRead?.({ kind: "file", path: i.path ?? strategiesRoot, reason: `strategy ${i.op}: ${i.error}` }),
                     }
                     : {}),
             });

package/dist/stores/file/mailbox-store.d.ts

@@ -1,4 +1,5 @@
-import { type MailboxAppendMessage, type MailboxLease, type MailboxStore } from "../../core/mailbox-store.js";
+import { type MailboxAckResult, type MailboxAppendMessage, type MailboxLease, type MailboxStore } from "../../core/mailbox-store.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 /** The waiter's refusal when a box lock stays held by a LIVE process past `lockWaitMs`. Carried as
  *  `.code` on a plain Error (consumers branch on the string); the message names the lock and the holder. */
 export declare const MAILBOX_BOX_LOCK_TIMEOUT_CODE = "mailbox.box_lock_timeout";
@@ -45,10 +46,7 @@ export interface FileMailboxStoreOptions {
      *  INTERIOR record dropped by the JSONL replay is disclosed here instead of silently reading as
      *  "less mail". The torn tail stays silent by design — that is the append-log's documented
      *  crash-recovery shape, not corruption. Swallow-guarded; absent = the old silent tolerance. */
-    onCorruptRead?: (info: {
-        path: string;
-        reason: string;
-    }) => void;
+    onCorruptRead?: (info: CorruptReadInfo) => void;
 }
 export declare class FileMailboxStore implements MailboxStore {
     /** design/385 — the whole cross-process set (box lock + fresh re-read + descriptor reopen +
@@ -105,16 +103,13 @@ export declare class FileMailboxStore implements MailboxStore {
      * and the cache is replayed from the file. A moved INODE also swap-closes the descriptor (ring 3):
      * the next write reopens the current file instead of landing on the unlinked one.
      */
-    /** Fold ONE replayed event, disclosing a record that is not one of this box's ({@link applyEvent}
-     *  answers `false`): dropped silently it reads exactly like a shorter mailbox. */
-    private applyReplayed;
     private reconcile;
     private load;
     private commit;
     private compact;
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
-    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
+    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;

package/dist/stores/file/mailbox-store.js

@@ -373,23 +373,18 @@ export class FileMailboxStore {
             return result;
         });
     }
-    applyReplayed(b, ev, path) {
-        if (applyEvent(b, ev))
-            return;
-        this.discloseCorrupt?.({ path, reason: "missing-required: a mailbox record is not one of this box's events — an unknown tag, or a known tag whose payload is missing (skipped; the rest of the replay is intact)" });
-    }
     reconcile(b) {
         const now = diskMarkOf(b.path);
         if (sameDiskMark(now, b.mark))
             return;
         if (now === undefined || b.mark === undefined || now.ino !== b.mark.ino)
             b.log.closeForSwap();
-        const events = readJsonlRecords(b.path, this.discloseCorrupt);
+        const events = readJsonlRecords(b.path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE);
         b.messages = [];
         b.nextSeq = 1;
         delete b.lease;
         for (const ev of events)
-            this.applyReplayed(b, ev, b.path);
+            applyEvent(b, ev);
         b.events = Math.max(0, events.length - (b.messages.length + 1 + (b.lease !== undefined ? 1 : 0)));
         b.mark = now;
     }
@@ -406,10 +401,10 @@ export class FileMailboxStore {
             return b;
         }
         ensureDir(join(this.dir, sanitizeScope(scope)));
-        const events = readJsonlRecords(path, this.discloseCorrupt);
+        const events = readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE);
         const state = { messages: [], nextSeq: 1, log: new AppendLog(path), events: events.length, refs: 1, path, mark: undefined };
         for (const ev of events)
-            this.applyReplayed(state, ev, path);
+            applyEvent(state, ev);
         state.mark = diskMarkOf(path);
         sharedBoxes.set(key, state);
         this.touched.set(key, state);
@@ -417,7 +412,8 @@ export class FileMailboxStore {
     }
     commit(b, path, ev) {
         b.log.append(ev, this.fsyncEnabled);
-        applyEvent(b, ev);
+        if (MAILBOX_EVENT_JUDGE.accepts(ev))
+            applyEvent(b, ev);
         b.events++;
         if (b.events >= this.compactEvery) {
             try {
@@ -475,8 +471,9 @@ export class FileMailboxStore {
         return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
             const b = this.load(scope, handle);
             if (b.lease === undefined || b.lease.owner !== owner)
-                return;
+                return { acked: false };
             this.commit(b, this.boxPath(scope, handle), { t: "ack", upToSeq });
+            return { acked: true };
         });
     }
     async releaseLease(scope, handle, owner) {
@@ -496,8 +493,8 @@ export class FileMailboxStore {
             return 0;
         return withPathLock(this.lockKey(scope, handle), () => {
             const b = { messages: [], nextSeq: 1 };
-            for (const ev of readJsonlRecords(path, this.discloseCorrupt))
-                this.applyReplayed(b, ev, path);
+            for (const ev of readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE))
+                applyEvent(b, ev);
             return b.messages.length;
         });
     }
@@ -556,8 +553,8 @@ export class FileMailboxStore {
                 if (sharedBoxes.has(key))
                     return false;
                 const b = { messages: [], nextSeq: 1 };
-                for (const ev of readJsonlRecords(path, this.discloseCorrupt))
-                    this.applyReplayed(b, ev, path);
+                for (const ev of readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE))
+                    applyEvent(b, ev);
                 const newest = newestSentAt(b.messages);
                 if (newest === undefined || newest >= now - maxAgeMs)
                     return false;
@@ -584,35 +581,37 @@ export class FileMailboxStore {
     }
 }
 const num = (v) => typeof v === "number" && Number.isFinite(v);
+const MAILBOX_EVENT_JUDGE = {
+    accepts: (r) => {
+        const ev = r;
+        if (ev.t === "append")
+            return ev.m !== null && typeof ev.m === "object" && num(ev.m.seq);
+        if (ev.t === "lease")
+            return typeof ev.owner === "string" && num(ev.maxSeq) && num(ev.expiresAt);
+        if (ev.t === "ack")
+            return num(ev.upToSeq);
+        return ev.t === "release" && typeof ev.owner === "string";
+    },
+    what: "a mailbox record is not one of this box's events — an unknown tag, or a known tag whose payload is missing",
+};
 function applyEvent(b, ev) {
     if (ev.t === "append") {
-        if (ev.m === null || typeof ev.m !== "object" || !num(ev.m.seq))
-            return false;
         b.messages.push(ev.m);
         if (ev.m.seq >= b.nextSeq)
             b.nextSeq = ev.m.seq + 1;
-        return true;
     }
-    if (ev.t === "lease") {
-        if (typeof ev.owner !== "string" || !num(ev.maxSeq) || !num(ev.expiresAt))
-            return false;
+    else if (ev.t === "lease") {
         if (ev.maxSeq >= b.nextSeq)
             b.nextSeq = ev.maxSeq + 1;
         if (ev.owner !== "")
             b.lease = { owner: ev.owner, expiresAt: ev.expiresAt, maxSeq: ev.maxSeq };
-        return true;
     }
-    if (ev.t === "ack") {
-        if (!num(ev.upToSeq))
-            return false;
+    else if (ev.t === "ack") {
         b.messages = b.messages.filter((m) => m.seq > ev.upToSeq);
         if (b.lease !== undefined && b.lease.maxSeq <= ev.upToSeq)
             b.lease = undefined;
-        return true;
     }
-    if (ev.t !== "release" || typeof ev.owner !== "string")
-        return false;
-    if (b.lease?.owner === ev.owner)
+    else if (b.lease?.owner === ev.owner) {
         b.lease = undefined;
-    return true;
+    }
 }

package/dist/stores/file/session-policy-store.d.ts

@@ -16,6 +16,8 @@ import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicySt
 /** Coordinates of one corrupt-treated-as-absent policy read (the {@link FileSessionPolicyStoreOptions.onCorruptRead}
  *  payload). Named rather than inline so the backend option that forwards it names the SAME shape. */
 export interface SessionPolicyCorruptReadInfo {
+    /** Always a whole-file disclosure (the {@link import("./corrupt-read-sink.js").CorruptReadInfo} level). */
+    kind: "file";
     /** The session whose read observed the corrupt row. On the enumeration face this is the session being
      *  ENUMERATED — a corrupt row's own `__sid` is by definition unreadable, so it cannot be attributed. */
     sessionId: string;

package/dist/stores/file/session-policy-store.js

@@ -77,7 +77,7 @@ export class FileSessionPolicyStore {
             adoption !== undefined && "adopted" in adoption && adoption.adopted.from.kind === "local-owner" ? adoption.adopted.toPrincipal : undefined;
     }
     disclose(info) {
-        this.onCorruptRead?.(info);
+        this.onCorruptRead?.({ kind: "file", ...info });
     }
     discloseCorrupt(sessionId, principal, reason) {
         this.disclose({ sessionId, ...(principal !== undefined ? { principal } : {}), path: this.pathFor(sessionId, principal), reason });

package/dist/stores/file/session-store.d.ts

@@ -1,5 +1,6 @@
 import type { Session, SessionCreateOptions, SessionForkOptions, SessionMetadata, SessionPlacementRecord, SessionRepo, SessionTreeEntry } from "../../internal/harness.js";
 import type { PlacedSessionRow } from "../../core/session.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export interface FileSessionRepoOptions {
     /**
      * Disclosure sink for a durable read this repo treats as ABSENT (ruled 2026-08-03). Same name and
@@ -7,17 +8,14 @@ export interface FileSessionRepoOptions {
      * "corrupt read as missing" are one failure grammar, so they get one seat name.
      *
      * Fires for: an unreadable sessions DIRECTORY (the listing degrades to "no sessions"), a session log
-     * that could not be replayed during a listing (skipped from the result), and a corrupt interior JSONL
-     * record dropped on replay (turns silently missing from an otherwise healthy session).
+     * that could not be replayed during a listing (skipped from the result), and each corrupt interior JSONL
+     * record dropped on replay plus that replay's tally (turns missing from an otherwise healthy session).
      *
      * Never fires on plain ENOENT / `not_found` — that is honest absence, and the torn TAIL stays silent
      * too (dying mid-write is the append log's documented crash-recovery shape, not corruption).
      * Swallow-guarded: a throwing sink cannot re-introduce the fault the fail-open avoids.
      */
-    onCorruptRead?: (info: {
-        path: string;
-        reason: string;
-    }) => void;
+    onCorruptRead?: (info: CorruptReadInfo) => void;
 }
 export declare class FileSessionRepo implements SessionRepo {
     private readonly dir;
@@ -31,7 +29,13 @@ export declare class FileSessionRepo implements SessionRepo {
     /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}. */
     private disclose;
     private pathFor;
-    /** Read + torn-tail-recover a session file into (meta, entries); a missing file → not_found. */
+    /**
+     * Read + torn-tail-recover a session file into (meta, entries). Three answers: no file → `not_found`; a
+     * file with no meta header → `corrupt_session`, even when every other record is intact (every write path
+     * here lays the header down first and the header alone carries `createdAt` / fork / placement, so the file
+     * is not a session this store wrote, or its header line is damaged); otherwise the session, each skipped
+     * record disclosed.
+     */
     private read;
     private storage;
     /**

package/dist/stores/file/session-store.js

@@ -6,6 +6,13 @@ import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { thrownText } from "../../core/thrown-value.js";
 const SUFFIX = ".jsonl";
+const SESSION_LINE_JUDGE = {
+    accepts: (r) => {
+        const line = r;
+        return line.kind === "meta" || (line.kind === "entry" && line.entry !== null && typeof line.entry === "object");
+    },
+    what: "a session line is neither a meta header nor an entry record",
+};
 const sharedSessionStorages = new Map();
 const sessionStorageFinalizer = new FinalizationRegistry(({ canonical, log }) => {
     log.close();
@@ -68,7 +75,7 @@ export class FileSessionRepo {
         this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
     }
     disclose(path, reason) {
-        this.onCorruptRead?.({ path, reason });
+        this.onCorruptRead?.({ kind: "file", path, reason });
     }
     pathFor(id) {
         return join(this.dir, `${sanitizePathComponent(id)}${SUFFIX}`);
@@ -78,24 +85,24 @@ export class FileSessionRepo {
         if (!existsSync(path)) {
             throw new SessionError("not_found", `Session not found: ${id}`);
         }
-        const lines = readJsonlRecords(path, (info) => this.disclose(info.path, info.reason));
-        let createdAt = "";
-        let forkedFrom;
-        let placement;
+        let tally;
+        const lines = readJsonlRecords(path, (info) => {
+            if (info.kind === "replay")
+                tally = info;
+            this.onCorruptRead?.(info);
+        }, SESSION_LINE_JUDGE);
+        let meta;
         const entries = [];
         for (const line of lines) {
-            if (line.kind === "meta") {
-                createdAt = line.createdAt;
-                forkedFrom = line.forkedFrom;
-                placement = line.placement;
-                continue;
-            }
-            if (line.kind !== "entry" || line.entry === null || typeof line.entry !== "object") {
-                this.disclose(path, "missing-required: a session line is neither a meta header nor an entry record (skipped; the rest of the replay is intact)");
-                continue;
-            }
-            entries.push(line.entry);
+            if (line.kind === "meta")
+                meta = line;
+            else
+                entries.push(line.entry);
+        }
+        if (meta === undefined) {
+            throw new SessionError("corrupt_session", `Session ${id} is unreadable: its log has no meta header (${tally?.dropped ?? 0} of ${tally?.total ?? lines.length} records skipped as corrupt)`);
         }
+        const { createdAt, forkedFrom, placement } = meta;
         return { createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), ...(placement !== undefined ? { placement } : {}), entries };
     }
     storage(id, createdAt, entries, forkedFrom, placement) {

package/dist/stores/file/shared-ledger.js

@@ -21,22 +21,11 @@ export class LedgerCore {
         this.fence = acquireStoreDirLock(this.paths.dir, { label: this.model.label });
         try {
             const disclose = this.paths.onCorruptRead;
-            const mine = (xs, judge, path, what) => {
-                const kept = [];
-                for (const x of xs) {
-                    if (judge(x))
-                        kept.push(x);
-                    else
-                        disclose?.({ path, reason: `missing-required: a ${what} carries none of this ${this.model.label}'s own members (skipped; the rest of the replay is intact)` });
-                }
-                return kept;
-            };
-            const snapPath = this.paths.snapshotPath;
-            const ledgerPath = this.paths.ledgerPath;
-            for (const row of mine(readJsonlRecords(snapPath, disclose), this.model.judgeRow, snapPath, "snapshot row")) {
+            const judge = (accepts, what) => ({ accepts, what: `a ${what} carries none of this ${this.model.label}'s own members` });
+            for (const row of readJsonlRecords(this.paths.snapshotPath, disclose, judge(this.model.judgeRow, "snapshot row"))) {
                 this.rows.set(this.model.keyOf(row), row);
             }
-            const events = mine(readJsonlRecords(ledgerPath, disclose), this.model.judgeEvent, ledgerPath, "ledger event");
+            const events = readJsonlRecords(this.paths.ledgerPath, disclose, judge(this.model.judgeEvent, "ledger event"));
             this.events = events.length;
             for (const ev of events)
                 this.model.apply(this.rows, ev);

package/dist/stores/file/tool-result-store.d.ts

@@ -37,6 +37,8 @@ export declare class FileToolResultStore implements ToolResultStore {
     private readonly dir;
     private readonly discloseCorrupt;
     constructor(root: string, opts?: FileToolResultStoreOptions);
+    /** The one delivery point for {@link FileToolResultStoreOptions.onCorruptRead}. */
+    private disclose;
     /** The directory a ref's files live in, and their shared stem. See {@link encodeRefFilename} for why
      *  a FOLDED name gets its own directory instead of sharing one with identity names. */
     private locate;

package/dist/stores/file/tool-result-store.js

@@ -14,6 +14,9 @@ export class FileToolResultStore {
         this.discloseCorrupt = guardCorruptSink(opts?.onCorruptRead);
         ensureDir(this.dir);
     }
+    disclose(path, reason) {
+        this.discloseCorrupt?.({ kind: "file", path, reason });
+    }
     locate(ref) {
         assertSafeToolResultRef(ref);
         const encoded = encodeRefFilename(ref);
@@ -81,7 +84,7 @@ export class FileToolResultStore {
                 return undefined;
             if (opts.loud)
                 throw err;
-            this.discloseCorrupt?.({ path: ownerPath, reason: `unreadable owner sidecar (${err.code ?? "unknown"}) — read as unowned` });
+            this.disclose(ownerPath, `unreadable owner sidecar (${err.code ?? "unknown"}) — read as unowned`);
             return undefined;
         }
         const parsed = parseOwnerRecord(raw);
@@ -90,7 +93,7 @@ export class FileToolResultStore {
         if (opts.loud) {
             throw new Error(`tool-result store: owner record for ref ${JSON.stringify(ref)} is present but unreadable — refusing to write over it`);
         }
-        this.discloseCorrupt?.({ path: ownerPath, reason: "not-an-object: owner sidecar is present but is not an owner record — read as unowned" });
+        this.disclose(ownerPath, "not-an-object: owner sidecar is present but is not an owner record — read as unowned");
         return undefined;
     }
     writeOwnerFile(ref, provenance) {

package/dist/stores/file/workflow-journal-store.js

@@ -19,6 +19,10 @@ export const RESUME_CLAIM_SWEEP_INTERVAL_MS = 60_000;
 export const RESUME_CLAIM_REAP_GRACE_MS = 5 * 60_000;
 const sharedJournalDirs = new Map();
 const MAX_OPEN_JOURNAL_LOGS = 64;
+function isJournalLine(r) {
+    const rec = r;
+    return typeof rec.callKey === "string" && typeof rec.scope === "string" && Number.isFinite(rec.ordinal);
+}
 export class FileWorkflowJournalStore {
     fsyncEnabled;
     dir;
@@ -75,16 +79,17 @@ export class FileWorkflowJournalStore {
             return undefined;
         let scope;
         const byOrdinal = new Map();
-        for (const rec of readJsonlRecords(path, this.discloseCorrupt)) {
-            if (typeof rec.callKey !== "string" || typeof rec.scope !== "string" || !Number.isFinite(rec.ordinal)) {
-                this.discloseCorrupt?.({ path, reason: "missing-required: a journal line carries no callKey/scope pair (skipped; the rest of the replay is intact)" });
-                continue;
-            }
-            scope = scope ?? rec.scope;
-            if (rec.scope !== scope)
-                continue;
+        const judge = {
+            accepts: (r) => {
+                if (!isJournalLine(r))
+                    return false;
+                scope ??= r.scope;
+                return r.scope === scope;
+            },
+            what: "a journal line carries no callKey/scope pair, or a scope other than its run's first line",
+        };
+        for (const rec of readJsonlRecords(path, this.discloseCorrupt, judge))
             byOrdinal.set(rec.ordinal, entryOf(rec));
-        }
         return scope === undefined ? undefined : { scope, byOrdinal };
     }
     async append(runId, scope, entry) {