@sema-agent/core 7.26.3 → 7.28.0

package/dist/stores/file/background-agent-store.d.ts

@@ -1,5 +1,9 @@
 import { type BackgroundAgentReapOptions, type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentStore, type BackgroundAgentUpdateIfExpect } from "../../core/background-agent-store.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export interface FileBackgroundAgentStoreOptions {
+    /** This store's half of {@link import("./shared-ledger.js").LedgerPaths.onCorruptRead} — the same seat,
+     *  over the agent row model. */
+    onCorruptRead?: (info: CorruptReadInfo) => void;
     /** When false, a ledger append is NOT fsync'd. Default true. */
     fsync?: boolean;
     /** Compact the ledger into a snapshot once it exceeds this many events (then truncate). Default 1000. */

package/dist/stores/file/background-agent-store.js

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import { BackgroundAgentStoreError, STALE_RUNNING_REAP_ATTRIBUTION, assertBackgroundAgentReapOptions, queryBackgroundAgents, } from "../../core/background-agent-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
+const isAgentRow = (x) => x !== null && typeof x === "object" && typeof x.handle === "string" && typeof x.scope === "string";
 const agentLedgers = new SharedLedgerTable({
     label: "background-agent ledger",
     keyOf: (r) => FileBackgroundAgentStore.key(r.handle, r.scope),
@@ -12,6 +14,13 @@ const agentLedgers = new SharedLedgerTable({
         }
         rows.set(ev.k, ev.r);
     },
+    judgeRow: isAgentRow,
+    judgeEvent: (x) => {
+        const ev = x;
+        if (typeof ev.k !== "string")
+            return false;
+        return ev.t === "delete" ? true : isAgentRow(ev.r);
+    },
 });
 export class FileBackgroundAgentStore {
     fsyncEnabled;
@@ -29,6 +38,7 @@ export class FileBackgroundAgentStore {
         this.ledger = agentLedgers.acquire({
             dir,
             tmpDir: join(root, "tmp"),
+            ...(opts.onCorruptRead !== undefined ? { onCorruptRead: guardCorruptSink(opts.onCorruptRead) } : {}),
             ledgerPath: join(dir, "agents.jsonl"),
             snapshotPath: join(dir, "agents.snapshot.jsonl"),
         });

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

@@ -1,7 +1,10 @@
 import { type ExecutionOutcomeRecordWord } from "../../core/checkpoint-execution-record.js";
 import { type Checkpoint, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
 import type { GateOutcome } from "../../core/gate-outcome.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export interface FileCheckpointStoreOptions {
+    /** This store's half of {@link import("./shared-ledger.js").LedgerPaths.onCorruptRead}. */
+    onCorruptRead?: (info: CorruptReadInfo) => void;
     /** When false, an `appendLine` for a state transition is NOT fsync'd. The checkpoint COMMIT POINT always
      *  fsyncs regardless (its crash-safety depends on it); this governs the `put` and `setPendingSteer`
      *  (steer-append) commits only — `resolve`/`reopen`/`expire` fsync unconditionally. Default true. */

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

@@ -3,6 +3,7 @@ import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "../../core/checkpoint-execution-record.js";
 import { appendPendingSteer, CheckpointError, checkpointOccMatches, checkpointRowMatches, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 const CHECKPOINT_LEDGER_EVENT_REGISTRY = {
     put: true,
     resolve: true,
@@ -57,10 +58,26 @@ function applyCheckpointEvent(cps, ev) {
         }
     }
 }
+const isCheckpointRow = (x) => x !== null &&
+    typeof x === "object" &&
+    typeof x.token === "string" &&
+    typeof x.scope === "string" &&
+    typeof x.status === "string";
 const checkpointLedgers = new SharedLedgerTable({
     label: "checkpoint ledger",
     keyOf: (cp) => cp.token,
     apply: applyCheckpointEvent,
+    judgeRow: isCheckpointRow,
+    judgeEvent: (x) => {
+        const ev = x;
+        if (typeof ev.t !== "string")
+            return false;
+        if (!KNOWN_CHECKPOINT_LEDGER_EVENTS.has(ev.t))
+            return true;
+        if (typeof ev.token !== "string")
+            return false;
+        return ev.t === "put" ? isCheckpointRow(ev.cp) : true;
+    },
 });
 export class FileCheckpointStore {
     durability = "durable";
@@ -83,6 +100,7 @@ export class FileCheckpointStore {
         this.ledger = checkpointLedgers.acquire({
             dir,
             tmpDir: join(root, "tmp"),
+            ...(opts.onCorruptRead !== undefined ? { onCorruptRead: guardCorruptSink(opts.onCorruptRead) } : {}),
             ledgerPath: join(dir, "checkpoints.jsonl"),
             snapshotPath: join(dir, "checkpoints.snapshot.jsonl"),
         });

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

@@ -0,0 +1,20 @@
+/**
+ * The file backend's ONE disclosure-seat guard: `@contract store.read_back_shape_judged`'s second legal
+ * posture — an absence that DISCLOSES — rides a host's `onCorruptRead`, and the guard around it was
+ * 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 {
+    path: string;
+    reason: string;
+}
+/**
+ * Wrap a host's disclosure seat: neither a synchronous throw nor an async rejection can re-introduce the
+ * fault the fail-open avoids. `undefined` in ⇒ `undefined` out. Generic in the payload because the
+ * session-policy store discloses session coordinates rather than a path.
+ */
+/** The sink is invoked UNBOUND (`this` is undefined): pass a bound function or an arrow, never a bare
+ *  method reference — a method reading `this` throws, and the throw is contained here, so the disclosure
+ *  is silently lost rather than surfaced. */
+export declare function guardCorruptSink<I>(sink: ((info: I) => void) | undefined): ((info: I) => void) | undefined;

package/dist/stores/file/corrupt-read-sink.js

@@ -0,0 +1,15 @@
+export function guardCorruptSink(sink) {
+    if (sink === undefined)
+        return undefined;
+    return (info) => {
+        try {
+            const returned = sink(info);
+            if (typeof returned?.then === "function") {
+                void Promise.resolve(returned).then(undefined, () => {
+                });
+            }
+        }
+        catch {
+        }
+    };
+}

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

@@ -233,8 +233,7 @@ export declare class FileFileHistoryStore implements FileHistoryStore {
      * GC that could not run leaves a graph larger than its bound, the safer of the two directions).
      */
     private applyBoundaryRetention;
-    /** The single delivery point for the disclosure sink; swallow-guarded here so no call site has to
-     *  remember, and so a host's throwing sink cannot break the never-throw seam. */
+    /** The single delivery point for the disclosure sink. */
     private disclose;
     private scopeDir;
     private trackedPath;

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

@@ -5,6 +5,7 @@ import { thrownText } from "../../core/thrown-value.js";
 import { applyFileRestoreViaEnv, boundaryPublishVerdict, worldStillMatchesMint, captureFileBackupViaEnv, modeProvenDifferent, previewFileDelta, describeTrackKey, fileHistoryExportDigest, resolveTrackKey, trackKeyOf, validateFileHistoryExport, } from "../../core/file-history-store.js";
 import { fileHistoryBoundariesToKeep, resolveFileHistoryRetention } from "../../core/file-history-retention.js";
 import { atomicWriteFile, ensureDir, sanitizePathComponent, sanitizeScope, writeThenLink } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { isAbsoluteForFamily } from "../../tools/fs/safety.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 function trackedDigest(rows) {
@@ -156,7 +157,7 @@ export class FileFileHistoryStore {
         this.scopesDir = join(this.base, "scopes");
         ensureDir(this.blobsDir);
         ensureDir(this.scopesDir);
-        this.onCorruptRead = opts?.onCorruptRead;
+        this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
     }
     applyBoundaryRetention(scope, justCommitted) {
         if (this.boundaryKeep === null)
@@ -194,13 +195,7 @@ export class FileFileHistoryStore {
         }
     }
     disclose(path, reason) {
-        try {
-            const r = this.onCorruptRead?.({ path, reason });
-            if (typeof r?.then === "function")
-                r.then(undefined, () => { });
-        }
-        catch {
-        }
+        this.onCorruptRead?.({ path, reason });
     }
     scopeDir(scope) {
         return join(this.scopesDir, sanitizeScope(scope));

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

@@ -40,11 +40,16 @@ export declare function atomicWriteFile(tmpDir: string, target: string, bytes: s
  *    parity), so a single corrupt interior line never poisons the whole replay.
  * A missing file → `[]`. This is why JSONL beats one big JSON blob: a torn tail can never corrupt the store.
  *
+ * 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.
+ *
  * `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". The torn TAIL stays out of it by design: dying mid-write is the documented crash
- * shape this format exists to absorb, not corruption. The callback is invoked as given — a seat that
- * must not throw swallow-guards on ITS side (the stores do).
+ * 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.
  */
 export declare function readJsonlRecords<T>(path: string, onCorrupt?: (info: {
     path: string;

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

@@ -126,15 +126,32 @@ export function readJsonlRecords(path, onCorrupt) {
         const line = parts[i];
         if (line === "")
             continue;
+        let record;
         try {
-            out.push(JSON.parse(line));
+            record = JSON.parse(line);
         }
         catch {
-            onCorrupt?.({ path, reason: `unparseable jsonl record at line ${i + 1} (skipped; the rest of the replay is intact)` });
+            onCorrupt?.({ path, reason: corruptRecordReason("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`) });
+            continue;
         }
+        out.push(record);
     }
     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";
+    if (Array.isArray(value))
+        return "an array";
+    return `a ${typeof value}`;
+}
 export function canonicalStoreKey(p) {
     return physicalPathOfExisting(p).toLowerCase();
 }

package/dist/stores/file/index.js

@@ -65,19 +65,19 @@ export class FileStorageBackend {
             this.fileSessions = repo;
             this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } } });
             this.sessionStore = this.ttl;
-            this.fileCheckpoints = new FileCheckpointStore(this.root, opts.checkpoint);
+            this.fileCheckpoints = new FileCheckpointStore(this.root, { ...opts.checkpoint, ...corruptRead });
             built.push(() => this.fileCheckpoints.close());
             this.checkpointStore = this.fileCheckpoints;
             this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});
             built.push(() => this.fileMemory.close());
             this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
-            this.toolResultStore = new FileToolResultStore(this.root);
+            this.toolResultStore = new FileToolResultStore(this.root, corruptRead);
             this.sessionPolicyStore = new FileSessionPolicyStore(this.root, corruptRead);
-            this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root);
+            this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root, true, corruptRead);
             built.push(() => this.fileWorkflowJournal.dispose());
             this.workflowJournalStore = this.fileWorkflowJournal;
             this.usageWindowStore = new FileUsageWindowStore(this.root);
-            this.fileAgentRows = new FileBackgroundAgentStore(this.root);
+            this.fileAgentRows = new FileBackgroundAgentStore(this.root, corruptRead ?? {});
             built.push(() => this.fileAgentRows.close());
             this.backgroundAgentStore = this.fileAgentRows;
             this.fileMailbox = new FileMailboxStore(this.root, corruptRead ?? {});

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

@@ -105,6 +105,9 @@ 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;

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

@@ -4,6 +4,7 @@ import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { existsSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { detachMailboxMessage, newestSentAt, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { physicalPathOf } from "../../core/physical-path.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 function diskMarkOf(path) {
@@ -339,17 +340,7 @@ export class FileMailboxStore {
             throw new Error(`FileMailboxStore: lockWaitMs must be a finite number > 0, got ${JSON.stringify(opts.lockWaitMs)}`);
         }
         this.lockWaitMs = lockWaitMs;
-        const sink = opts.onCorruptRead;
-        this.discloseCorrupt =
-            sink === undefined
-                ? undefined
-                : (info) => {
-                    try {
-                        sink(info);
-                    }
-                    catch {
-                    }
-                };
+        this.discloseCorrupt = guardCorruptSink(opts.onCorruptRead);
         const lexicalDir = resolve(join(root, "mailboxes"));
         const lexicalTmp = resolve(join(root, "tmp"));
         ensureDir(lexicalDir);
@@ -382,6 +373,11 @@ 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))
@@ -393,7 +389,7 @@ export class FileMailboxStore {
         b.nextSeq = 1;
         delete b.lease;
         for (const ev of events)
-            applyEvent(b, ev);
+            this.applyReplayed(b, ev, b.path);
         b.events = Math.max(0, events.length - (b.messages.length + 1 + (b.lease !== undefined ? 1 : 0)));
         b.mark = now;
     }
@@ -413,7 +409,7 @@ export class FileMailboxStore {
         const events = readJsonlRecords(path, this.discloseCorrupt);
         const state = { messages: [], nextSeq: 1, log: new AppendLog(path), events: events.length, refs: 1, path, mark: undefined };
         for (const ev of events)
-            applyEvent(state, ev);
+            this.applyReplayed(state, ev, path);
         state.mark = diskMarkOf(path);
         sharedBoxes.set(key, state);
         this.touched.set(key, state);
@@ -501,7 +497,7 @@ export class FileMailboxStore {
         return withPathLock(this.lockKey(scope, handle), () => {
             const b = { messages: [], nextSeq: 1 };
             for (const ev of readJsonlRecords(path, this.discloseCorrupt))
-                applyEvent(b, ev);
+                this.applyReplayed(b, ev, path);
             return b.messages.length;
         });
     }
@@ -561,7 +557,7 @@ export class FileMailboxStore {
                     return false;
                 const b = { messages: [], nextSeq: 1 };
                 for (const ev of readJsonlRecords(path, this.discloseCorrupt))
-                    applyEvent(b, ev);
+                    this.applyReplayed(b, ev, path);
                 const newest = newestSentAt(b.messages);
                 if (newest === undefined || newest >= now - maxAgeMs)
                     return false;
@@ -587,26 +583,36 @@ export class FileMailboxStore {
         this.touched.clear();
     }
 }
+const num = (v) => typeof v === "number" && Number.isFinite(v);
 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;
+        return true;
     }
     if (ev.t === "lease") {
+        if (typeof ev.owner !== "string" || !num(ev.maxSeq) || !num(ev.expiresAt))
+            return false;
         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;
+        return true;
     }
     if (ev.t === "ack") {
+        if (!num(ev.upToSeq))
+            return false;
         b.messages = b.messages.filter((m) => m.seq > ev.upToSeq);
         if (b.lease !== undefined && b.lease.maxSeq <= ev.upToSeq)
             b.lease = undefined;
-        return;
+        return true;
     }
+    if (ev.t !== "release" || typeof ev.owner !== "string")
+        return false;
     if (b.lease?.owner === ev.owner)
         b.lease = undefined;
+    return true;
 }

package/dist/stores/file/permission-rule-store.js

@@ -48,8 +48,25 @@ export function readRuleAdoptionFile(dir) {
     }
     return parsed;
 }
+function isRuleOwnerShape(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    const owner = v;
+    return owner.kind === "local-owner" || (owner.kind === "principal" && typeof owner.principal === "string");
+}
 function isRuleAdoptionFileShape(v) {
-    return typeof v === "object" && v !== null && v.schemaVersion === 1 && ("marker" in v || "adopted" in v);
+    if (v === null || typeof v !== "object" || v.schemaVersion !== 1)
+        return false;
+    const hasMarker = "marker" in v;
+    const hasAdopted = "adopted" in v;
+    if (hasMarker === hasAdopted)
+        return false;
+    const rec = (hasMarker ? v.marker : v.adopted);
+    if (rec === null || typeof rec !== "object")
+        return false;
+    if (!isRuleOwnerShape(rec.from) || typeof rec.toPrincipal !== "string" || rec.toPrincipal === "")
+        return false;
+    return hasMarker ? rec.phase === 2 || rec.phase === 3 || rec.phase === 4 || rec.phase === 5 : typeof rec.atMs === "number" && Number.isFinite(rec.atMs);
 }
 export function writeRuleAdoptionFile(dir, content) {
     assertSafeDir(dir);

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

@@ -1,4 +1,20 @@
 import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicyStore, type SessionRulesRecord, type StoredSessionRules } from "../../core/session-policy-store.js";
+/**
+ * design/99 §E6 — file-backed {@link SessionPolicyStore} for the local (TOC) backend: one JSON row file per
+ * `(sessionId, principal)`, plus — once that key has ever been stamped — a second, tiny file beside it holding
+ * the number the erase contract on {@link SessionPolicyStore.deleteBySession} says must outlive the row. Both
+ * names share a stem, and the mark's suffix is what every directory sweep here tests first
+ * ({@link MARK_SUFFIX}). Semantics otherwise **byte-for-byte identical to `InMemorySessionPolicyStore`** (the
+ * cross-backend equivalence contract). CAS-rev OCC + tighten-only reuse the SAME pure helpers
+ * (`loosenReasons`/`normalizeRules`/`stripRev`) as core — no re-implemented rule logic that could drift.
+ *
+ * Atomicity: the file backend is single-process (the `FileStorageBackend` boot lock guarantees ONE writer per
+ * data dir), and `getRules`/`putRules` read-check-write SYNCHRONOUSLY (no await between the rev read and the
+ * atomic write), so the read-modify-write is atomic in the one event loop — exactly the InMemory store's premise.
+ * Cross-process CORRECT concurrency is the Pg/TiDB backend's job (a CAS WHERE clause), by design.
+ */
+/** 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 {
     /** 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. */
@@ -84,7 +100,7 @@ export declare class FileSessionPolicyStore implements SessionPolicyStore {
      *  alike (a window-era anonymous write must not mint a fresh orphan row). */
     private readonly anonymousAlias;
     constructor(root: string, opts?: FileSessionPolicyStoreOptions);
-    /** The one delivery point for {@link onCorruptRead}. Swallow-guarded here so no caller has to remember. */
+    /** The one delivery point for {@link onCorruptRead}. */
     private disclose;
     /** RB-482 top item (baggage class-4 ruling): corrupt-read fail-open is a DOCUMENTED compromise (a throwing
      *  getRules fails the whole task; a throwing putRules self-locks the repair write) — but it must not

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

@@ -2,13 +2,8 @@ import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { loosenReasons, normalizeRules, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate, readRootAdoptionFile } from "./adoption/marker.js";
-function containSinkThenable(r) {
-    if (typeof r?.then === "function") {
-        r.then(undefined, () => {
-        });
-    }
-}
 export const SESSION_POLICY_MARK_SUFFIX = ".hwm.json";
 const MARK_SUFFIX = SESSION_POLICY_MARK_SUFFIX;
 export function readSessionPolicyMark(path) {
@@ -76,17 +71,13 @@ export class FileSessionPolicyStore {
         assertAdoptionBootGate(root, "FileSessionPolicyStore");
         this.dir = join(root, "session-policy");
         ensureDir(this.dir);
-        this.onCorruptRead = opts?.onCorruptRead;
+        this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
         const adoption = readRootAdoptionFile(root);
         this.anonymousAlias =
             adoption !== undefined && "adopted" in adoption && adoption.adopted.from.kind === "local-owner" ? adoption.adopted.toPrincipal : undefined;
     }
     disclose(info) {
-        try {
-            containSinkThenable(this.onCorruptRead?.(info));
-        }
-        catch {
-        }
+        this.onCorruptRead?.(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

@@ -28,11 +28,7 @@ export declare class FileSessionRepo implements SessionRepo {
      *  check on the way out possible without pinning a storage the table itself only holds weakly. */
     private readonly joined;
     constructor(root: string, opts?: FileSessionRepoOptions);
-    /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}; swallow-guarded here so
-     *  no call site has to remember. The sink seat is void-typed but a host may hand it an async
-     *  function — an async sink's rejection is observed off its returned thenable (same containment
-     *  as the strategy store's incident sink), so neither a sync throw nor an async rejection can
-     *  re-introduce the failure mode the fail-open avoids. */
+    /** 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. */

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

@@ -2,14 +2,9 @@ import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { BaseSessionStorage, StoredSession, SessionError, getEntriesToFork, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
+import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { thrownText } from "../../core/thrown-value.js";
-function containSinkThenable(r) {
-    if (typeof r?.then === "function") {
-        r.then(undefined, () => {
-        });
-    }
-}
 const SUFFIX = ".jsonl";
 const sharedSessionStorages = new Map();
 const sessionStorageFinalizer = new FinalizationRegistry(({ canonical, log }) => {
@@ -70,14 +65,10 @@ export class FileSessionRepo {
         this.tmpDir = join(root, "tmp");
         ensureDir(this.dir);
         ensureDir(this.tmpDir);
-        this.onCorruptRead = opts?.onCorruptRead;
+        this.onCorruptRead = guardCorruptSink(opts?.onCorruptRead);
     }
     disclose(path, reason) {
-        try {
-            containSinkThenable(this.onCorruptRead?.({ path, reason }));
-        }
-        catch {
-        }
+        this.onCorruptRead?.({ path, reason });
     }
     pathFor(id) {
         return join(this.dir, `${sanitizePathComponent(id)}${SUFFIX}`);
@@ -97,9 +88,13 @@ export class FileSessionRepo {
                 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;
             }
-            else
-                entries.push(line.entry);
+            entries.push(line.entry);
         }
         return { createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), ...(placement !== undefined ? { placement } : {}), entries };
     }

package/dist/stores/file/shared-ledger.d.ts

@@ -1,3 +1,4 @@
+import type { CorruptReadInfo } from "./corrupt-read-sink.js";
 /**
  * design/157 A9 — the SHARED substrate under the three snapshot+ledger file stores
  * ({@link import("./background-agent-store.js").FileBackgroundAgentStore},
@@ -61,6 +62,11 @@
 /** The paths one ledger authority owns. `dir` is also what the authority is keyed on. */
 export interface LedgerPaths {
     readonly dir: string;
+    /** Disclosure seat for a replay row this authority DROPPED as corrupt — without it the loss is
+     *  indistinguishable from "fewer rows". Already swallow-guarded by the store that wired it. Only the
+     *  FIRST instance over a directory replays, so only its seat can fire: a joiner reads the authority
+     *  that instance built, which is the same fact its refcount records. */
+    readonly onCorruptRead?: (info: CorruptReadInfo) => void;
     /** Scratch dir for {@link atomicWriteFile} (same filesystem as the targets → rename is atomic). */
     readonly tmpDir: string;
     readonly ledgerPath: string;
@@ -73,6 +79,18 @@ export interface LedgerModel<Row, Ev> {
     label: string;
     keyOf(row: Row): string;
     apply(rows: Map<string, Row>, ev: Ev): void;
+    /**
+     * `@contract store.read_back_shape_judged` floor: is this parsed body one of MY rows / MY events at
+     * all? Judged on the DISCRIMINANT only — the key a row is filed under, the tag an event is folded by —
+     * because what to do with a discriminant this binary does not KNOW is the model's own business (the
+     * checkpoint ledger refuses the whole replay for a kind from a newer worker, deliberately). A body
+     * that carries no discriminant carries no such choice: it is damage, and `bootstrap` discloses and
+     * skips it. Required rather than optional, so a fourth ledger store cannot inherit the silence by
+     * omission — before this floor existed, `{"note":"x"}` in an agent ledger filed a row under the key
+     * `undefined` and the next enumeration read members off it.
+     */
+    judgeRow(x: unknown): boolean;
+    judgeEvent(x: unknown): boolean;
 }
 /**
  * One directory's authority: the replayed row map, the per-key async mutex, the append log and the

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

@@ -20,9 +20,23 @@ export class LedgerCore {
     bootstrap() {
         this.fence = acquireStoreDirLock(this.paths.dir, { label: this.model.label });
         try {
-            for (const row of readJsonlRecords(this.paths.snapshotPath))
+            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")) {
                 this.rows.set(this.model.keyOf(row), row);
-            const events = readJsonlRecords(this.paths.ledgerPath);
+            }
+            const events = mine(readJsonlRecords(ledgerPath, disclose), this.model.judgeEvent, ledgerPath, "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

@@ -1,4 +1,5 @@
 import type { ToolResultDeletionReport, ToolResultProvenance, ToolResultSlice, ToolResultStore } from "../../core/tool-result-store.js";
+import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 /**
  * design/80 §2.5 — file {@link ToolResultStore}: write-once-idempotent, ONE file per ref.
  *
@@ -26,9 +27,16 @@ import type { ToolResultDeletionReport, ToolResultProvenance, ToolResultSlice, T
  * is present but unreadable stops the write loudly, where treating it as "no owner" would report
  * success and leave the entry unclaimable forever.
  */
+export interface FileToolResultStoreOptions {
+    /** Disclosure seat for an owner sidecar that is PRESENT but unreadable: {@link
+     *  FileToolResultStore.ownerOf} answers `undefined` — the same word it uses for an entry nobody owns,
+     *  so a host that authorizes on it reads damage as "unowned". Swallow-guarded. */
+    onCorruptRead?: (info: CorruptReadInfo) => void;
+}
 export declare class FileToolResultStore implements ToolResultStore {
     private readonly dir;
-    constructor(root: string);
+    private readonly discloseCorrupt;
+    constructor(root: string, opts?: FileToolResultStoreOptions);
     /** 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;