@sema-agent/core 7.40.0 → 7.41.0

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

@@ -4,7 +4,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { isRuleBehavior } from "../../core/permission-rule-model.js";
 import { PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, unknownRuleWriteDeltaError, } from "../../core/permission-rule-store.js";
 import { canonicalize } from "../../core/canonical-json.js";
-import { BootLock } from "./fs-atomic.js";
+import { BootLock, FileStoreLockError } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { thrownText } from "../../core/thrown-value.js";
 function isRuleFile(v) {
@@ -26,27 +26,31 @@ export class OrgRevisionRefusal extends Error {
 }
 const LOCAL_OWNER_FILE = "local-owner.json";
 const ADOPTION_FILE = "PERMISSION-RULES-ADOPTION.json";
-export function readRuleAdoptionFile(dir) {
+function judgeRuleAdoptionFile(dir) {
     let raw;
     try {
         raw = readFileSync(join(dir, ADOPTION_FILE), "utf8");
     }
     catch (err) {
         if (err?.code === "ENOENT")
-            return undefined;
-        throw new Error(`could not read the permission-rule adoption marker in ${dir}: ${err.message}`);
+            return { marker: undefined };
+        return { corrupt: `could not be read (${err?.code ?? err?.name ?? "unknown"})`, detail: thrownText(err) };
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch (err) {
-        throw new Error(`the permission-rule adoption marker in ${dir} is not valid JSON (${err.message}) — refusing to resolve owners until it is repaired`);
+        return { corrupt: `is not valid JSON (${err.message})` };
     }
-    if (!isRuleAdoptionFileShape(parsed)) {
-        throw new Error(`the permission-rule adoption marker in ${dir} does not carry a readable shape — refusing to resolve owners until it is repaired`);
+    return isRuleAdoptionFileShape(parsed) ? { marker: parsed } : { corrupt: "does not carry a readable shape" };
+}
+export function readRuleAdoptionFile(dir) {
+    const judged = judgeRuleAdoptionFile(dir);
+    if ("corrupt" in judged) {
+        throw new Error(`the permission-rule adoption marker in ${dir} ${judged.corrupt}${judged.detail !== undefined ? `: ${judged.detail}` : ""} — refusing to resolve owners until it is repaired`);
     }
-    return parsed;
+    return judged.marker;
 }
 function isRuleOwnerShape(v) {
     if (v === null || typeof v !== "object")
@@ -114,19 +118,53 @@ const EMPTY_READ = { rules: [], tombstones: [], rev: 0 };
 function checksumOf(body) {
     return `sha256:${createHash("sha256").update(canonicalize(body), "utf8").digest("hex")}`;
 }
-function assertSafeDir(dir) {
+function unsafeDirFault(dir) {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const st = lstatSync(dir);
-    if (st.isSymbolicLink() || !st.isDirectory()) {
-        throw new Error(`permission-rule store directory ${dir} is a symlink or not a directory; refusing to use it`);
+    if (st.isSymbolicLink() || !st.isDirectory())
+        return "is a symlink or not a directory";
+    if (typeof process.getuid === "function" && st.uid !== process.getuid())
+        return "is owned by another user";
+    if ((st.mode & 0o022) !== 0)
+        return `is writable by group or others (mode ${(st.mode & 0o777).toString(8)}) — anyone who can write there can grant themselves permissions`;
+    return undefined;
+}
+function assertSafeDir(dir) {
+    const fault = unsafeDirFault(dir);
+    if (fault !== undefined)
+        throw new Error(`permission-rule store directory ${dir} ${fault}; refusing to use it`);
+}
+function refusalText(onError, sentence, location) {
+    try {
+        onError?.(`${sentence} (at ${location})`);
     }
-    if (typeof process.getuid === "function" && st.uid !== process.getuid()) {
-        throw new Error(`permission-rule store directory ${dir} is owned by another user; refusing to use it`);
+    catch {
     }
-    if ((st.mode & 0o022) !== 0) {
-        throw new Error(`permission-rule store directory ${dir} is writable by group or others (mode ${(st.mode & 0o777).toString(8)}); ` +
-            `refusing to use it — anyone who can write here can grant themselves permissions`);
+    return `${sentence}. The location is reported to the store's error disclosure (onError), not in this message.`;
+}
+function assertSafeDirAtRequest(dir, onError, act) {
+    const fault = unsafeDirFault(dir);
+    if (fault !== undefined)
+        throw new Error(refusalText(onError, `the permission-rule store directory ${fault}; refusing to ${act} it`, dir));
+}
+function writerLockRefusal(err, onError) {
+    let sentence;
+    switch (err.code) {
+        case "store.dir_in_use":
+            sentence = `another live process${err.ownerPid !== undefined ? ` (pid ${err.ownerPid})` : ""} holds the permission-rule store's writer lock — refusing to interleave writes with it; write through that process, or stop it`;
+            break;
+        case "store.dir_claiming":
+            sentence = "another process is reclaiming the permission-rule store's writer lock from a crashed owner — retry";
+            break;
+        case "store.lock_unreadable":
+            sentence = "the permission-rule store's writer lock is in a state only a person should resolve — remove it by hand if no process holds it";
+            break;
+        default: {
+            const unhandled = err.code;
+            sentence = `the permission-rule store's writer lock refused (${String(unhandled)})`;
+        }
     }
+    return new FileStoreLockError(err.code, refusalText(onError, sentence, `${err.lockPath}: ${err.message}`), err.lockPath, err.ownerPid);
 }
 class FileDurableRulePartition {
     dir;
@@ -142,48 +180,41 @@ class FileDurableRulePartition {
         this.onError = onError;
     }
     read() {
+        const bucket = "this owner's permission-rule bucket";
+        const whole = "refusing the whole file and loading zero rules — repair the file, or remove it (removing it gives up every rule and tombstone it held)";
+        const unreadable = (sentence, location = this.file) => ({ unreadable: refusalText(this.onError, sentence, location) });
         let raw;
         try {
-            assertSafeDir(this.dir);
+            const dirFault = unsafeDirFault(this.dir);
+            if (dirFault !== undefined)
+                return unreadable(`the permission-rule store directory ${dirFault}; loading zero rules`, this.dir);
             const st = lstatSync(this.file);
-            if (st.isSymbolicLink() || !st.isFile()) {
-                const why = `${this.file} is a symlink or not a regular file; refusing to load any rule from it`;
-                this.disclose(why);
-                return { unreadable: why };
-            }
+            if (st.isSymbolicLink() || !st.isFile())
+                return unreadable(`${bucket} is a symlink or not a regular file; refusing to load any rule from it`);
             raw = readFileSync(this.file, "utf8");
         }
         catch (err) {
             const e = err;
             if (e?.code === "ENOENT")
                 return { absent: true };
-            const why = `could not read ${this.file}: ${thrownText(err)}; loading zero rules`;
-            this.disclose(why);
-            return { unreadable: why };
+            return unreadable(`${bucket} could not be read (${e?.code ?? err?.name ?? "unknown"}); loading zero rules`, `${this.file}: ${thrownText(err)}`);
         }
         let parsed;
         try {
             parsed = JSON.parse(raw);
         }
         catch (err) {
-            const why = `${this.file} is not valid JSON (${err.message}); refusing the whole file and loading zero rules`;
-            this.disclose(why);
-            return { unreadable: why };
+            return unreadable(`${bucket} is not valid JSON (${err.message}); ${whole}`);
         }
         if (!isRuleFile(parsed)) {
             const sv = schemaVersionWord(parsed);
-            const why = typeof sv === "number"
-                ? `${this.file} is a schema ${String(sv)} bucket; this engine reads schema 4 only and does not migrate an older engine's bucket — refusing the whole file and loading zero rules (the bytes are left for a person to look at)`
-                : `${this.file} does not carry a readable rule-file shape; refusing the whole file and loading zero rules`;
-            this.disclose(why);
-            return { unreadable: why };
+            return unreadable(typeof sv === "number"
+                ? `${bucket} is a schema ${String(sv)} bucket; this engine reads schema 4 only and does not migrate an older engine's bucket — refusing the whole file and loading zero rules (the bytes are left for a person to look at)`
+                : `${bucket} does not carry a readable rule-file shape; ${whole}`);
         }
         const { checksum, ...body } = parsed;
-        if (checksum !== checksumOf(body)) {
-            const why = `${this.file} failed its integrity check; refusing the whole file and loading zero rules`;
-            this.disclose(why);
-            return { unreadable: why };
-        }
+        if (checksum !== checksumOf(body))
+            return unreadable(`${bucket} failed its integrity check; ${whole}`);
         const rowKinds = [
             ["rule", parsed.rules],
             ["tombstone", parsed.tombstones],
@@ -191,11 +222,8 @@ class FileDurableRulePartition {
         ];
         for (const [kind, rows] of rowKinds) {
             const bad = rows.findIndex((r) => !isRuleBehavior(r?.behavior));
-            if (bad !== -1) {
-                const why = `${this.file} carries a ${kind} row (#${bad}) whose behavior word is outside deny/ask/allow — a schema 4 row must name its behavior; refusing the whole file and loading zero rules`;
-                this.disclose(why);
-                return { unreadable: why };
-            }
+            if (bad !== -1)
+                return unreadable(`${bucket} carries a ${kind} row (#${bad}) whose behavior word is outside deny/ask/allow — a schema 4 row must name its behavior; ${whole}`);
         }
         return { file: parsed };
     }
@@ -218,7 +246,7 @@ class FileDurableRulePartition {
         return { rules, tombstones, quarantined };
     }
     write(next) {
-        assertSafeDir(this.dir);
+        assertSafeDirAtRequest(this.dir, this.onError, "write through");
         atomicPublish(this.dir, this.file, JSON.stringify({ ...next, checksum: checksumOf(next) }, null, 2));
     }
     async list() {
@@ -370,6 +398,14 @@ export class FileDurableRulePartitionProvider {
         if (opts?.dataRoot !== undefined)
             assertAdoptionBootGate(opts.dataRoot, "FileDurableRulePartitionProvider");
     }
+    adoptionMarker() {
+        const judged = judgeRuleAdoptionFile(this.dir);
+        if ("corrupt" in judged) {
+            const location = `${join(this.dir, ADOPTION_FILE)}${judged.detail !== undefined ? `: ${judged.detail}` : ""}`;
+            throw new Error(refusalText(this.onError, `the permission-rule store's adoption marker ${judged.corrupt}; refusing to resolve whose bucket this is until it is repaired`, location));
+        }
+        return judged.marker;
+    }
     orgStatePersistence() {
         return this.fileOrgPersistence();
     }
@@ -380,16 +416,21 @@ export class FileDurableRulePartitionProvider {
     acquireWriteLock = () => {
         if (this.lock !== undefined)
             return;
-        assertSafeDir(this.dir);
+        assertSafeDirAtRequest(this.dir, this.onError, "write through");
         const lock = new BootLock(join(this.dir, "PERMISSION-RULES-WRITER-LOCK"));
-        lock.acquire();
+        try {
+            lock.acquire();
+        }
+        catch (err) {
+            throw err instanceof FileStoreLockError ? writerLockRefusal(err, this.onError) : err;
+        }
         this.lock = lock;
     };
     forPrincipal(principal) {
         if (typeof principal !== "string" || principal === "") {
             return { list: async () => ({ ...EMPTY_READ }), durability: "process-local" };
         }
-        const adoption = readRuleAdoptionFile(this.dir);
+        const adoption = this.adoptionMarker();
         if (adoption !== undefined) {
             const rec = "adopted" in adoption ? adoption.adopted : adoption.marker;
             if (rec.from.kind === "principal" && rec.from.principal === principal) {
@@ -403,7 +444,7 @@ export class FileDurableRulePartitionProvider {
         return readOnlyRuleStoreView(new FileDurableRulePartition(this.dir, join(this.dir, pick), this.acquireWriteLock, this.onError));
     }
     forLocalOwner() {
-        const adoption = readRuleAdoptionFile(this.dir);
+        const adoption = this.adoptionMarker();
         if (adoption !== undefined) {
             const rec = "adopted" in adoption ? adoption.adopted : adoption.marker;
             if (rec.from.kind === "local-owner") {
@@ -430,25 +471,52 @@ class FileOrgRuleStatePersistence {
         this.file = join(dir, ORG_STATE_FILE);
     }
     readSync() {
-        let raw;
+        const refuse = (sentence, location = this.file) => {
+            throw new Error(refusalText(this.onError, `${sentence}; refusing it whole — repair the file, or remove it (removing it gives up the last-known-good org snapshot and its anti-rollback mark)`, location));
+        };
+        const ioFault = (err) => `could not be read (${err?.code ?? err?.name ?? "unknown"})`;
+        let dirFault;
         try {
-            assertSafeDir(this.dir);
-            const st = lstatSync(this.file);
-            if (st.isSymbolicLink() || !st.isFile())
-                throw new Error(`${this.file} is a symlink or not a regular file; refusing to load the org state from it`);
-            raw = readFileSync(this.file, "utf8");
+            dirFault = unsafeDirFault(this.dir);
         }
         catch (err) {
+            return refuse(`the permission-rule store directory ${ioFault(err)}`, `${this.dir}: ${thrownText(err)}`);
+        }
+        if (dirFault !== undefined)
+            return refuse(`the permission-rule store directory ${dirFault}`, this.dir);
+        const unreadable = (err) => {
             if (err?.code === "ENOENT")
                 return undefined;
-            throw err;
+            return refuse(`the org state file ${ioFault(err)}`, `${this.file}: ${thrownText(err)}`);
+        };
+        let st;
+        try {
+            st = lstatSync(this.file);
+        }
+        catch (err) {
+            return unreadable(err);
+        }
+        if (st.isSymbolicLink() || !st.isFile())
+            return refuse("the org state file is a symlink or not a regular file");
+        let raw;
+        try {
+            raw = readFileSync(this.file, "utf8");
+        }
+        catch (err) {
+            return unreadable(err);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            return refuse(`the org state file is not valid JSON (${err.message})`);
         }
-        const parsed = JSON.parse(raw);
         if (!isOrgStateFile(parsed))
-            throw new Error(`${this.file} does not carry a readable org-state shape; refusing it whole`);
+            return refuse("the org state file does not carry a readable org-state shape");
         const { checksum, ...body } = parsed;
         if (checksum !== checksumOf(body))
-            throw new Error(`${this.file} failed its integrity check; refusing it whole`);
+            return refuse("the org state file failed its integrity check");
         return parsed.state;
     }
     async readOrgState() {
@@ -456,7 +524,7 @@ class FileOrgRuleStatePersistence {
     }
     installOrgStateSync(state) {
         this.acquireWriteLock();
-        assertSafeDir(this.dir);
+        assertSafeDirAtRequest(this.dir, this.onError, "write through");
         state = jsonForm(state);
         const cur = this.readSync();
         if (cur !== undefined && state.revisionHighWater < cur.revisionHighWater) {

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

@@ -1,4 +1,4 @@
-import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicyStore, type SessionRulesRecord, type StoredSessionRules } from "../../core/session-policy-store.js";
+import { type PutRulesOptions, type SessionPolicyStoreOptions, 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
@@ -20,18 +20,23 @@ 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. */
+     *  ENUMERATED: the row it refuses is that session's ({@link attributeSessionPolicyRow}), the row it omits is one
+     *  nothing on disk attributes to anybody. */
     sessionId: string;
     /** Present only when the read was keyed by a principal (the enumeration face has none). */
     principal?: string;
-    /** Absolute path of the offending file. */
+    /** Absolute path of the offending file — a rules row, or a key's high-water mark (`*.hwm.json`). The refusals'
+     *  messages never carry it: this is where a location is reported. */
     path: string;
-    /** What was observed — the same words the refusal's message carries after its grade (unparseable / malformed / unreadable). */
+    /** What was observed — the same words the refusal's message carries after its grade (unparseable / malformed / unreadable);
+     *  for a high-water mark, `high-water mark ` + the reader's fault predicate (is unparseable / is not a JSON object / …). */
     reason: string;
 }
-export interface FileSessionPolicyStoreOptions {
-    /** Disclosure sink for a damaged rules file (see {@link FileSessionPolicyStore.refuseDamaged}): it fires WITH the
-     *  refusal on the keyed read and on its own where the enumeration skips the row. Never fires on plain ENOENT.
+export interface FileSessionPolicyStoreOptions extends SessionPolicyStoreOptions {
+    /** Disclosure sink for a damaged rules file or high-water mark (see {@link FileSessionPolicyStore.refuseDamaged} and
+     *  its mark sibling): it fires WITH the refusal on the keyed read / write and on the enumeration of the session that
+     *  owns the row, and on its own where the enumeration omits a row nothing attributes to anybody or the erase sweep
+     *  leaves a damaged mark. Never fires on plain ENOENT.
      *  Swallow-guarded: a throwing sink cannot change the refusal. */
     onCorruptRead?: (info: SessionPolicyCorruptReadInfo) => void;
 }
@@ -54,15 +59,27 @@ export interface StoredHighWaterMark {
     /** The erase's tombstone (a torn row purged with no mark): writes are refused until an operator deletes this file. */
     __lineage?: "lost";
 }
+/** The ONE reader's answer: the mark (`null` = no file), or the fault that makes the bytes not a mark. `reason` is a
+ *  predicate ("is unparseable"), so every wrapper — the keyed store's refusal, the adoption leg's, the disclosure —
+ *  says the same fault in the same words. */
+export type SessionPolicyMarkRead = {
+    mark: StoredHighWaterMark | null;
+} | {
+    corrupt: {
+        reason: string;
+    };
+};
 /**
- * The ONE reader of a mark file — the number it holds, or `null` when there is no file (the ordinary state of
- * a key nobody erased). Every other outcome is a refusal, and that is the point: for a ROW "unreadable"
- * degrades to "absent" and costs nothing, while for a mark absence reads as ZERO, which is precisely the
- * rollback the erase contract forbids. Bytes that are not a mark raise `SessionPolicyError("corrupt")` naming
- * the file; an IO failure propagates as it already does for a row. Exported because ownership adoption moves
- * these files too, and a second, more tolerant reader over there is how the guarantee goes quietly missing.
+ * The ONE reader of a mark file — the number it holds (`{ mark }`, `null` for no file: the ordinary state of a key
+ * nobody erased), or the fault that makes the bytes not a mark (`{ corrupt }`). Every outcome but those two is a
+ * refusal at the caller: for a ROW "unreadable" degrades to "absent" and costs nothing, while for a mark absence
+ * reads as ZERO, the rollback the erase contract forbids. It only JUDGES, carrying no sentence and no location,
+ * because the wording depends on the audience: a store method answers an end user (session, fault, repair; the
+ * location goes to the disclosure sink), the adoption leg answers an operator (it names the file). An IO failure
+ * propagates raw. Exported because adoption moves these files too; a second, more tolerant reader there is how the
+ * guarantee goes quietly missing.
  */
-export declare function readSessionPolicyMark(path: string): StoredHighWaterMark | null;
+export declare function readSessionPolicyMark(path: string): SessionPolicyMarkRead;
 /** Why one row file's bytes are not a row. `unparseable` is the ONE grade saying they are not JSON at all — the
  *  only evidence the erase sweep's crash-artifact ruling rests on. `reason` is the disclosure text, so two faces
  *  judging the SAME file name the same fault in the same words. */
@@ -91,9 +108,32 @@ export declare function judgeSessionPolicyRowShape(row: Record<string, unknown>)
 } | {
     corrupt: SessionPolicyRowFault;
 };
+/** Whose key one row file is, as the bytes on disk show it. */
+export interface SessionPolicyRowOwner {
+    sessionId: string;
+    /** The principal the SAME evidence names: a string, `null` for the anonymous lane, `undefined` when it names none it can spell. */
+    principal: string | null | undefined;
+}
+/**
+ * The ONE answer to "whose row is this file?" for every face that sweeps the directory — the enumeration, the erase
+ * and the ownership rebind — so a damaged row is one session's fact on all three. The row's own `__sid` when its
+ * bytes are a JSON object carrying one; otherwise the `__sid` of its same-stem high-water mark, which every stamp
+ * writes BEFORE the row, so a torn, non-object or unreadable row still has it. `undefined` = nothing on disk names
+ * an owner (no mark, or one that is not a mark or carries no session): such a row can be judged by nobody's key, and
+ * each face keeps its own answer for it. A mark that cannot be READ is no evidence either way, so it THROWS (raw,
+ * from the reader) and the caller refuses rather than guess: guessing "nobody" would let an erase sweep another
+ * session's restriction, or a rebind strand it, on one transient read fault. When the answer rested on the mark,
+ * the read is handed back (`markRead`) so a caller that then acts on the mark acts on the SAME observation.
+ */
+export declare function attributeSessionPolicyRow(dir: string, file: string, row: Record<string, unknown> | undefined): {
+    owner: SessionPolicyRowOwner | undefined;
+    markRead?: SessionPolicyMarkRead;
+};
 export declare class FileSessionPolicyStore implements SessionPolicyStore {
     private readonly dir;
     private readonly onCorruptRead;
+    /** {@link SessionPolicyStoreOptions.mountedToolNames}, read once at construction. */
+    private readonly mountedToolNames;
     /** #132 — the ADOPTED identity of a local-owner root's anonymous lane, or undefined on an
      *  unadopted (or principal-adopted) root. A local-owner adoption rebinds the anonymous
      *  `[sid,null]` estate rows to `toPrincipal`; until the deployment's principal wiring lands
@@ -116,6 +156,25 @@ export declare class FileSessionPolicyStore implements SessionPolicyStore {
      *  body, so it names no on-disk location. Two ways out, both the operator's: fix the file, or delete it — deleting is an explicit "no rules" and
      *  gives up the rules the file held. */
     private refuseDamaged;
+    /** The sibling of {@link refuseDamaged} for the key's high-water MARK, and its only other voice: one disclosure
+     *  shape, one code, a message naming the session, the fault and the repair but never a location (the path rides
+     *  the sink, as the row's does). It refuses rather than read the mark as absent: that reads as ZERO and restarts
+     *  the key's rev (see {@link readSessionPolicyMark}). Deleting the file gives up the number it held. */
+    private refuseDamagedMark;
+    /** The sweeps' (enumeration / erase) refusal when a file they must READ cannot be — the directory, or a mark that
+     *  decides whose a row is or holds the number an erase must keep. Same voice as the two above: session, fault,
+     *  repair, and the location only on the disclosure. Nothing is guessed and nothing is removed; a retry re-reads. */
+    private refuseUnreadable;
+    /** {@link attributeSessionPolicyRow} for a sweep: an unreadable mark becomes {@link refuseUnreadable}. */
+    private ownerOf;
+    /** A mark the erase must act on, read in the sweep's voice ({@link refuseUnreadable} when it cannot be read). */
+    private sweepMark;
+    /** The directory a sweep enumerates; absent = empty, unreadable = {@link refuseUnreadable}. */
+    private sweepEntries;
+    /** The keyed read of the mark for a write: the number, `null` for a key nobody stamped; a file that is there is a
+     *  mark or a refusal ({@link refuseDamagedMark}), never "no mark". One that cannot be READ refuses in the same
+     *  voice — the raw errno error names the file (EACCES does). */
+    private readMark;
     /** `(sessionId, principal)` → a safe, INJECTIVE filename (sanitizeScope appends the full sha256 of the raw
      *  composite key, so distinct keys never collide on disk). On a local-owner-adopted root the
      *  anonymous lane resolves to the adopted principal's key (#132 — see {@link anonymousAlias}). */
@@ -130,8 +189,21 @@ export declare class FileSessionPolicyStore implements SessionPolicyStore {
     /** The keyed read: `null` is ABSENCE only (no file); a file that is there is served as rules or refused
      *  ({@link refuseDamaged}) — it is never read as "no rules". */
     private read;
+    /** One row file → its JSON object, the fault that makes it not one (the read failure included), or `null` for
+     *  ABSENCE (ENOENT — also a row unlinked under a sweep, an honest absence). Every face reads a row through here. */
+    private readRowFile;
     getRules(sessionId: string, principal?: string): Promise<StoredSessionRules | null>;
     putRules(sessionId: string, principal: string | undefined, rules: SessionPermissionRules, opts?: PutRulesOptions): Promise<StoredSessionRules>;
     listBySession(sessionId: string): Promise<SessionRulesRecord[]>;
     deleteBySession(sessionId: string): Promise<void>;
+    /** Erase ONE row this session owns: the number must outlive it, so it is folded into the key's mark BEFORE the
+     *  unlink, and the erase ends the row's lineage (`__gen` + 1) in that same single mark write — a crash in between
+     *  leaves a mark one erase ahead of a row that still exists, which the next erase counts again (a skipped
+     *  generation, and nothing else). Normally the mark is already ahead (every stamp writes it first); the fold earns
+     *  its keep on rows that predate the mark. A row is released only once its number is provably safe, so exactly ONE
+     *  fault may be absorbed: bytes that are not a mark. Those already block every future write to this key (`putRules`
+     *  refuses on them), so they are left as they are rather than replaced by evidence this sweep cannot check. A mark
+     *  that cannot be READ proves nothing: {@link refuseUnreadable}, and the erase is retried. `observed` = the read the
+     *  owner judgment already took — acted on as observed, so a mark cannot vanish between the judgment and the erase. */
+    private eraseRow;
 }