@sema-agent/core 7.54.1 → 7.56.0

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

@@ -62,6 +62,18 @@ export interface JsonlRecordJudge {
     accepts(record: object): boolean;
     what: string;
 }
+/**
+ * The FIRST record of an open JSONL file of `size` bytes — the record {@link readJsonlRecords} would return first — read forward one
+ * block at a time and stopping there: a read bounded by the lines before it, never by the file. Skipped lines are not disclosed (the
+ * whole-file read discloses them); `undefined` = the file holds no record.
+ */
+export declare function firstJsonlRecord(fd: number, size: number, judge?: JsonlRecordJudge): object | undefined;
+/**
+ * The LAST record of an open JSONL file of `size` bytes that `pick` accepts — the last such record {@link readJsonlRecords} would
+ * return — found by walking back from the end one block at a time: a read bounded by the lines after it, never by the file. The
+ * unterminated last segment is judged as the whole-file read judges it. Skipped lines are not disclosed; `undefined` = none.
+ */
+export declare function lastJsonlRecord(fd: number, size: number, pick: (record: object) => boolean, judge?: JsonlRecordJudge): object | undefined;
 /**
  * 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
@@ -162,6 +174,9 @@ export declare class AppendLog {
      */
     private rollBackFailedWrite;
     close(): void;
+    /** Whether this log's open descriptor is the file its path names now (same device and inode). A file removed or replaced under it
+     *  is not — its writes land on an inode no reader of the path sees — and neither is a log with no open descriptor. */
+    isFileAtPath(): boolean;
     /**
      * RB-167 — release the descriptor for a compaction SWAP. The next write reopens it lazily.
      *

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

@@ -1,4 +1,4 @@
-import { appendFileSync, closeSync, constants as FS, existsSync, fstatSync, ftruncateSync, linkSync, mkdirSync, openSync, readFileSync, readSync, renameSync, truncateSync, unlinkSync, writeFileSync, writeSync, fsyncSync, } from "node:fs";
+import { appendFileSync, closeSync, constants as FS, existsSync, fstatSync, ftruncateSync, linkSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync, truncateSync, unlinkSync, writeFileSync, writeSync, fsyncSync, } from "node:fs";
 import { constants as bufferConstants } from "node:buffer";
 import { homedir, hostname, uptime } from "node:os";
 import { hrtime } from "node:process";
@@ -142,19 +142,11 @@ export function readJsonlRecords(path, onCorrupt, judge) {
         const line = parts[i];
         if (line === "")
             continue;
-        const read = jsonlTextFormOf(line);
-        if (read.form === "unparseable") {
-            if (i === parts.length - 1)
-                break;
-            discloseSkip("torn-json", i + 1, "unparseable jsonl record");
-            continue;
-        }
-        if (read.form === "not-an-object") {
-            discloseSkip("not-an-object", i + 1, `jsonl record is ${jsonTypeName(read.value)}, not an object`);
-            continue;
-        }
-        if (judge !== undefined && !judge.accepts(read.record)) {
-            discloseSkip("missing-required", i + 1, judge.what);
+        const read = readJsonlLine(line, i === parts.length - 1, judge);
+        if (read.verdict === "partial-tail")
+            break;
+        if (read.verdict === "skip") {
+            discloseSkip(read.form, i + 1, read.what);
             continue;
         }
         out.push(read.record);
@@ -166,6 +158,77 @@ export function readJsonlRecords(path, onCorrupt, judge) {
     }
     return out;
 }
+function readJsonlLine(line, unterminated, judge) {
+    const read = jsonlTextFormOf(line);
+    if (read.form === "unparseable")
+        return unterminated ? { verdict: "partial-tail" } : { verdict: "skip", form: "torn-json", what: "unparseable jsonl record" };
+    if (read.form === "not-an-object")
+        return { verdict: "skip", form: "not-an-object", what: `jsonl record is ${jsonTypeName(read.value)}, not an object` };
+    if (judge !== undefined && !judge.accepts(read.record))
+        return { verdict: "skip", form: "missing-required", what: judge.what };
+    return { verdict: "record", record: read.record };
+}
+function assertJudgeableLine(length) {
+    if (length > JSONL_TAIL_SEGMENT_LIMIT)
+        throw new Error(`jsonl record cursor: a line of ${length} bytes is past the judgeable bound (${JSONL_TAIL_SEGMENT_LIMIT})`);
+}
+function jsonlLineText(bytes) {
+    assertJudgeableLine(bytes.length);
+    return bytes.toString("utf8");
+}
+export function firstJsonlRecord(fd, size, judge) {
+    let carry = Buffer.alloc(0);
+    for (let from = 0; from < size;) {
+        const block = Buffer.allocUnsafe(Math.min(JSONL_TAIL_READ_BLOCK, size - from));
+        readExactly(fd, block, block.length, from);
+        from += block.length;
+        let data = carry.length > 0 ? Buffer.concat([carry, block]) : block;
+        for (let nl = data.indexOf(0x0a); nl >= 0; nl = data.indexOf(0x0a)) {
+            const text = jsonlLineText(data.subarray(0, nl));
+            data = data.subarray(nl + 1);
+            if (text === "")
+                continue;
+            const read = readJsonlLine(text, false, judge);
+            if (read.verdict === "record")
+                return read.record;
+        }
+        carry = Buffer.from(data);
+        assertJudgeableLine(carry.length);
+    }
+    if (carry.length === 0)
+        return undefined;
+    const read = readJsonlLine(jsonlLineText(carry), true, judge);
+    return read.verdict === "record" ? read.record : undefined;
+}
+export function lastJsonlRecord(fd, size, pick, judge) {
+    let carry = Buffer.alloc(0);
+    let segmentEndsFile = true;
+    const visit = (bytes) => {
+        const unterminated = segmentEndsFile;
+        segmentEndsFile = false;
+        if (bytes.length === 0)
+            return undefined;
+        const read = readJsonlLine(jsonlLineText(bytes), unterminated, judge);
+        return read.verdict === "record" && pick(read.record) ? read.record : undefined;
+    };
+    for (let end = size; end > 0;) {
+        const from = Math.max(0, end - JSONL_TAIL_READ_BLOCK);
+        const block = Buffer.allocUnsafe(end - from);
+        readExactly(fd, block, block.length, from);
+        end = from;
+        const data = carry.length > 0 ? Buffer.concat([block, carry]) : block;
+        let segEnd = data.length;
+        for (let nl = segEnd > 0 ? data.lastIndexOf(0x0a, segEnd - 1) : -1; nl >= 0; nl = segEnd > 0 ? data.lastIndexOf(0x0a, segEnd - 1) : -1) {
+            const hit = visit(data.subarray(nl + 1, segEnd));
+            if (hit !== undefined)
+                return hit;
+            segEnd = nl;
+        }
+        carry = Buffer.from(data.subarray(0, segEnd));
+        assertJudgeableLine(carry.length);
+    }
+    return visit(carry);
+}
 function jsonTypeName(value) {
     if (value === null)
         return "null";
@@ -271,6 +334,18 @@ export class AppendLog {
         this.disposed = true;
         this.releaseFd();
     }
+    isFileAtPath() {
+        if (this.fd < 0)
+            return false;
+        try {
+            const open = fstatSync(this.fd, { bigint: true });
+            const named = statSync(this.path, { bigint: true });
+            return open.dev === named.dev && open.ino === named.ino;
+        }
+        catch {
+            return false;
+        }
+    }
     closeForSwap() {
         this.releaseFd();
     }

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

@@ -27,7 +27,7 @@ export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsol
 export { FileStoreLockError, type FileStoreLockErrorCode } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
 export { processFingerprint, isProcessLive, type ProcessFingerprint } from "./fs-atomic.js";
-export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./adoption/marker.js";
+export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./adoption/marker.js";
 export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, type AdoptionStatus, type AdoptLocalDataRootOptions, type AdoptLocalDataRootResult, type AdoptionCarriageLeg, type AdoptionCarriageLegContext, type AdoptionConfigWitnessReceipt, } from "./adoption/adopt.js";
 /**
  * design/80 — the file-backed {@link EngineStorageBackend} for the local (TOC) single-user binary, selected

package/dist/stores/file/index.js

@@ -62,7 +62,8 @@ 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, ...corruptRead });
+            const sessionHeadOf = this.ttl.headOf;
+            this.fileCheckpoints = new FileCheckpointStore(this.root, { ...opts.checkpoint, ...corruptRead, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
             built.push(() => this.fileCheckpoints.close());
             this.checkpointStore = this.fileCheckpoints;
             this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});

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

@@ -52,6 +52,9 @@ export declare class FileMailboxStore implements MailboxStore {
     /** design/385 — the whole cross-process set (box lock + fresh re-read + descriptor reopen +
      *  compaction under the lock) is in place and accepted by `mailboxCrossProcessContract`. */
     readonly crossProcessSafe = true;
+    /** The sha-256 of the PHYSICAL path of the boxes directory: every instance over one directory — whatever
+     *  spelling of the root it was built from, in any process — answers the same identity. */
+    readonly identity: string;
     private readonly dir;
     private readonly tmpDir;
     private readonly fsyncEnabled;

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

@@ -1,5 +1,5 @@
 import { join, resolve, sep } from "node:path";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 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";
@@ -324,6 +324,7 @@ function sweepLockResidue(dir, lockName) {
 }
 export class FileMailboxStore {
     crossProcessSafe = true;
+    identity;
     dir;
     tmpDir;
     fsyncEnabled;
@@ -347,6 +348,7 @@ export class FileMailboxStore {
         ensureDir(lexicalTmp);
         this.dir = physicalPathOf(lexicalDir);
         this.tmpDir = physicalPathOf(lexicalTmp);
+        this.identity = createHash("sha256").update(this.dir).digest("hex");
     }
     boxPath(scope, handle) {
         return join(this.dir, sanitizeScope(scope), `${sanitizePathComponent(handle).toLowerCase()}.jsonl`);

package/dist/stores/file/permission-rule-adopt.d.ts

@@ -24,7 +24,7 @@
  * join, deliberately not a rename. Rows the far side refuses during ⑤ move to the local quarantine
  * area — preserved and disclosed, never deleted (the F-011 "nothing is lost" floor).
  */
-import type { RuleOwner } from "../../core/permission-rule-store.js";
+import { type RuleOwner } from "../../core/rule-owner.js";
 import { type PermissionRuleSyncResult, type PermissionRuleSyncTransport } from "../../core/permission-rule-sync.js";
 export type AdoptFileRuleStoreResult = 
 /** The full arc completed (this call, or an earlier one — the terminal marker makes it idempotent). */

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

@@ -1,28 +1,34 @@
 import { existsSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { writerOf } from "../../core/permission-rule-store.js";
+import { readRuleOwner, ruleOwnerText, sameRuleOwner } from "../../core/rule-owner.js";
+import { principalNameOf } from "../../core/principal-name.js";
 import { createPermissionRuleStoreProvider } from "../../core/permission-rule-provider.js";
 import { syncPermissionRules } from "../../core/permission-rule-sync.js";
 import { thrownText } from "../../core/thrown-value.js";
 import { FileStoreLockError } from "./fs-atomic.js";
 import { FileDurableRulePartitionProvider, LOCAL_OWNER_FILE, principalRuleFileName, readRuleAdoptionFile, writeRuleAdoptionFile, } from "./permission-rule-store.js";
 export async function adoptFilePermissionRuleStore(opts) {
-    if (typeof opts.toPrincipal !== "string" || opts.toPrincipal === "") {
-        throw new Error("adoptFilePermissionRuleStore requires the adopting principal — adoption is the act of giving this bucket an identity");
+    if (principalNameOf(opts.toPrincipal) === undefined) {
+        throw new Error("adoptFilePermissionRuleStore requires the adopting principal, a principal name — adoption is the act of giving this bucket an identity");
     }
-    if (opts.from.kind === "principal" && opts.from.principal === opts.toPrincipal) {
+    const from = readRuleOwner(opts.from);
+    if (from === undefined) {
+        throw new Error("adoptFilePermissionRuleStore requires a source owner — a principal owner whose principal is a principal name, or the local owner");
+    }
+    if (from.kind === "principal" && from.principal === opts.toPrincipal) {
         throw new Error(`the bucket already belongs to "${opts.toPrincipal}" — there is nothing to adopt`);
     }
-    const sourceFile = join(opts.dir, opts.from.kind === "local-owner" ? LOCAL_OWNER_FILE : principalRuleFileName(opts.from.principal));
+    const sourceFile = join(opts.dir, from.kind === "local-owner" ? LOCAL_OWNER_FILE : principalRuleFileName(from.principal));
     const targetFile = join(opts.dir, principalRuleFileName(opts.toPrincipal));
     const existing = readRuleAdoptionFile(opts.dir);
     if (existing !== undefined) {
         if ("adopted" in existing) {
-            if (existing.adopted.toPrincipal === opts.toPrincipal && sameOwner(existing.adopted.from, opts.from))
+            if (existing.adopted.toPrincipal === opts.toPrincipal && sameRuleOwner(existing.adopted.from, from))
                 return { status: "adopted" };
-            throw new Error(`this directory already carries a completed adoption (${ownerText(existing.adopted.from)} → "${existing.adopted.toPrincipal}") — a second adoption of the same directory is not a shape this helper supports`);
+            throw new Error(`this directory already carries a completed adoption (${ruleOwnerText(existing.adopted.from)} → "${existing.adopted.toPrincipal}") — a second adoption of the same directory is not a shape this helper supports`);
         }
-        if (existing.marker.toPrincipal !== opts.toPrincipal || !sameOwner(existing.marker.from, opts.from)) {
+        if (existing.marker.toPrincipal !== opts.toPrincipal || !sameRuleOwner(existing.marker.from, from)) {
             throw new Error(`an adoption toward "${existing.marker.toPrincipal}" is already in flight in this directory — refusing to start a different one (resume the original, or repair the marker by hand)`);
         }
     }
@@ -44,7 +50,7 @@ export async function adoptFilePermissionRuleStore(opts) {
             throw new Error("the target store refused a write face");
         let phase = existing !== undefined && "marker" in existing ? existing.marker.phase : 2;
         if (existing === undefined) {
-            writeRuleAdoptionFile(opts.dir, marker(opts.from, opts.toPrincipal, 2));
+            writeRuleAdoptionFile(opts.dir, marker(from, opts.toPrincipal, 2));
             phase = 2;
         }
         if (phase < 3) {
@@ -55,11 +61,11 @@ export async function adoptFilePermissionRuleStore(opts) {
             }
             if (sourcePresent)
                 renameSync(sourceFile, targetFile);
-            writeRuleAdoptionFile(opts.dir, marker(opts.from, opts.toPrincipal, 3));
+            writeRuleAdoptionFile(opts.dir, marker(from, opts.toPrincipal, 3));
             phase = 3;
         }
         if (phase < 4) {
-            writeRuleAdoptionFile(opts.dir, marker(opts.from, opts.toPrincipal, 4));
+            writeRuleAdoptionFile(opts.dir, marker(from, opts.toPrincipal, 4));
             phase = 4;
         }
         let syncResult;
@@ -82,12 +88,12 @@ export async function adoptFilePermissionRuleStore(opts) {
                     error: `the first sync round did not land clean (${(syncResult.warnings ?? []).join("; ") || `${syncResult.dropped.length} drop(s)`}) — resume when the endpoint is healthy`,
                 };
             }
-            writeRuleAdoptionFile(opts.dir, marker(opts.from, opts.toPrincipal, 5));
+            writeRuleAdoptionFile(opts.dir, marker(from, opts.toPrincipal, 5));
             phase = 5;
         }
         writeRuleAdoptionFile(opts.dir, {
             schemaVersion: 1,
-            adopted: { from: opts.from, toPrincipal: opts.toPrincipal, atMs: (opts.now ?? Date.now)() },
+            adopted: { from, toPrincipal: opts.toPrincipal, atMs: (opts.now ?? Date.now)() },
         });
         return { status: "adopted", ...(syncResult !== undefined ? { syncResult } : {}) };
     }
@@ -98,9 +104,3 @@ export async function adoptFilePermissionRuleStore(opts) {
 function marker(from, toPrincipal, phase) {
     return { schemaVersion: 1, marker: { from, toPrincipal, phase } };
 }
-function sameOwner(a, b) {
-    return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
-}
-function ownerText(o) {
-    return o.kind === "principal" ? `principal "${o.principal}"` : "the local owner";
-}

package/dist/stores/file/permission-rule-store.d.ts

@@ -8,6 +8,16 @@
  * reader accepts schema 4 ONLY: any other schema word is refused whole, loudly, bytes left untouched —
  * this engine performs no migration of an older engine's buckets.
  *
+ * ## A bucket carries its rule grammar
+ *
+ * Every write stamps the bucket with this engine's rule grammar (`grammar`, the number the session rules
+ * store stamps too); every read judges it through the one stamp judge (`readRuleGrammarStamp`). A bucket
+ * stamped with a later grammar was written by a newer engine whose rows this one may read as nothing — a
+ * deny it cannot parse refuses nothing — so it is refused WHOLE, like any bucket this engine cannot read,
+ * with its own code (`PERMISSION_RULES_LATER_GRAMMAR_CODE`): reads answer zero rules and say so, writes
+ * refuse, the bytes stay as they are. A bucket without the member was written before the stamp and reads
+ * in this engine's grammar; the next write stamps it.
+ *
  * ## Why this store builds its own symlink refusal
  *
  * The other file stores canonicalize with `realpath`, which RESOLVES a symlink rather than refusing one —
@@ -50,7 +60,8 @@
  * For this backend the trust is host = user, exactly as for the settings file it mirrors.
  */
 import type { PersistedRule, RuleTombstone } from "../../core/permission-rule-model.js";
-import type { DurableRulePartition, DurableRulePartitionProvider, PermissionRuleWriter, QuarantinedRuleAdd, RuleOwner, RuleSyncFrontier, StoredRules, WritableDurableRulePartition } from "../../core/permission-rule-store.js";
+import type { DurableRulePartition, DurableRulePartitionProvider, PermissionRuleWriter, QuarantinedRuleAdd, RuleSyncFrontier, StoredRules, WritableDurableRulePartition } from "../../core/permission-rule-store.js";
+import { type RuleOwner } from "../../core/rule-owner.js";
 import { PERMISSION_RULE_WRITER } from "../../core/permission-rule-store.js";
 import { type OrgRuleStatePersistence, type PersistedOrgRuleState } from "../../core/permission-rule-org.js";
 import type { StoreDurability, StoreFidelity } from "../../core/checkpoint-store.js";
@@ -72,6 +83,9 @@ interface RuleFile {
         lastRoundAtMs?: number;
     };
     quarantined?: QuarantinedRuleAdd[];
+    /** The rule grammar the rows were written in: stamped by every write, judged by every read (see the module note).
+     *  Absent on a bucket written before the stamp. */
+    grammar?: number;
     checksum: string;
 }
 /** The deployment-wide org state file: last-known-good snapshot + anti-rollback high-water, one blob. */
@@ -145,6 +159,7 @@ declare class FileDurableRulePartition implements WritableDurableRulePartition {
      * sync wire (`readRaw`) or adjudication.
      */
     private screenDurableRows;
+    /** Publish `next` stamped with this engine's rule grammar — the stamp's one mint — and answer the checksum written. */
     private write;
     list(): Promise<StoredRules>;
     /** The quarantine area (design/182 §5.2/§8.3): introspection only — never part of `list()`. Its posture
@@ -162,7 +177,8 @@ declare class FileDurableRulePartition implements WritableDurableRulePartition {
      * unrecoverable one: the next redemption would write a fresh file over the damaged one, discarding every
      * standing rule, every tombstone, the revision and the replica identity, along with the evidence of what
      * went wrong. Reads already answer zero rules for the same condition, so the lane stays fail-closed
-     * while a person looks at the file.
+     * while a person looks at the file. A bucket a newer engine wrote is one of these: writing it in this
+     * engine's grammar would stamp rows this engine cannot read with a grammar that claims it can.
      */
     private current;
     /**

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

@@ -3,8 +3,11 @@ import { join } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { isRuleBehavior } from "../../core/permission-rule-model.js";
 import { posixModeBitsMeaningful } from "../../core/posix-mode-face.js";
-import { PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, unknownRuleWriteDeltaError, } from "../../core/permission-rule-store.js";
+import { readRuleOwner } from "../../core/rule-owner.js";
+import { principalNameOf, readPrincipal } from "../../core/principal-name.js";
+import { PERMISSION_RULES_LATER_GRAMMAR_CODE, PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, unknownRuleWriteDeltaError, } from "../../core/permission-rule-store.js";
 import { sameOrgPolicyContent } from "../../core/permission-rule-org.js";
+import { SESSION_RULES_GRAMMAR, readRuleGrammarStamp } from "../../core/session-policy-store.js";
 import { canonicalize } from "../../core/canonical-json.js";
 import { BootLock, FileStoreLockError } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
@@ -54,12 +57,6 @@ export function readRuleAdoptionFile(dir) {
     }
     return judged.marker;
 }
-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) {
     if (v === null || typeof v !== "object" || v.schemaVersion !== 1)
         return false;
@@ -70,7 +67,7 @@ function isRuleAdoptionFileShape(v) {
     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 === "")
+    if (readRuleOwner(rec.from) === undefined || principalNameOf(rec.toPrincipal) === undefined)
         return false;
     return hasMarker ? rec.phase === 2 || rec.phase === 3 || rec.phase === 4 || rec.phase === 5 : typeof rec.atMs === "number" && Number.isFinite(rec.atMs);
 }
@@ -144,6 +141,9 @@ function refusalText(onError, sentence, location) {
     discloseTo(onError, `${sentence} (at ${location})`);
     return `${sentence}. The location is reported to the store's error disclosure (onError), not in this message.`;
 }
+function unreadableError(r, sentence = r.unreadable) {
+    return r.code !== undefined ? Object.assign(new Error(sentence), { code: r.code }) : new Error(sentence);
+}
 function discloseTo(onError, message) {
     try {
         onError?.(message);
@@ -226,6 +226,12 @@ class FileDurableRulePartition {
         const { checksum, ...body } = parsed;
         if (checksum !== checksumOf(body))
             return unreadable(`${bucket} failed its integrity check; ${whole}`);
+        const grammar = readRuleGrammarStamp(parsed.grammar, SESSION_RULES_GRAMMAR, { rules: `the rules in ${bucket}`, held: "rows" });
+        if ("got" in grammar) {
+            return grammar.later === true
+                ? { ...unreadable(`${grammar.sentence} — loading zero rules and refusing every write until then; the file is left as it is`), code: PERMISSION_RULES_LATER_GRAMMAR_CODE }
+                : unreadable(`${grammar.sentence}; ${whole}`);
+        }
         const rowKinds = [
             ["rule", parsed.rules],
             ["tombstone", parsed.tombstones],
@@ -254,12 +260,15 @@ class FileDurableRulePartition {
     }
     write(next) {
         assertSafeDirAtRequest(this.dir, this.onError, "write through", this.vetting);
-        atomicPublish(this.dir, this.file, JSON.stringify({ ...next, checksum: checksumOf(next) }, null, 2));
+        const body = { ...next, grammar: SESSION_RULES_GRAMMAR };
+        const checksum = checksumOf(body);
+        atomicPublish(this.dir, this.file, JSON.stringify({ ...body, checksum }, null, 2));
+        return checksum;
     }
     async list() {
         const r = this.read();
         if ("unreadable" in r)
-            throw new Error(r.unreadable);
+            throw unreadableError(r);
         if (!("file" in r))
             return { ...EMPTY_READ };
         const screened = this.screenDurableRows(r.file);
@@ -273,13 +282,13 @@ class FileDurableRulePartition {
     async quarantined() {
         const r = this.read();
         if ("unreadable" in r)
-            throw new Error(r.unreadable);
+            throw unreadableError(r);
         return "file" in r ? this.screenDurableRows(r.file).quarantined : [];
     }
     current() {
         const r = this.read();
         if ("unreadable" in r) {
-            throw new Error(`refusing to write the permission-rule store while it cannot be read: ${r.unreadable}`);
+            throw unreadableError(r, `refusing to write the permission-rule store while it cannot be read: ${r.unreadable}`);
         }
         if ("absent" in r) {
             return { schemaVersion: 4, actor: `file-${randomBytes(6).toString("hex")}`, counter: 0, rev: 0, rules: [], tombstones: [] };
@@ -296,8 +305,7 @@ class FileDurableRulePartition {
         };
     }
     writeAndVerify(next) {
-        const expected = checksumOf(next);
-        this.write(next);
+        const expected = this.write(next);
         const after = this.read();
         return "file" in after && after.file.checksum === expected;
     }
@@ -445,17 +453,22 @@ export class FileDurableRulePartitionProvider {
         this.lock = lock;
     };
     forPrincipal(principal) {
-        if (typeof principal !== "string" || principal === "") {
+        const reading = readPrincipal(principal);
+        if (reading.kind === "invalid") {
+            throw new Error(`the principal given is not a principal name (got ${reading.fault}) — refusing to resolve a bucket for it; a provided value that names nobody is not "no principal"`);
+        }
+        if (reading.kind === "absent") {
             return { list: async () => ({ ...EMPTY_READ }), durability: "process-local" };
         }
+        const name = reading.name;
         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) {
-                return this.readOnlySourceView(principalRuleFileName(principal), principalRuleFileName(rec.toPrincipal), "adopted" in adoption || adoption.marker.phase >= 4);
+            if (rec.from.kind === "principal" && rec.from.principal === name) {
+                return this.readOnlySourceView(principalRuleFileName(name), principalRuleFileName(rec.toPrincipal), "adopted" in adoption || adoption.marker.phase >= 4);
             }
         }
-        return new FileDurableRulePartition(this.dir, join(this.dir, principalRuleFileName(principal)), this.acquireWriteLock, this.onError, this.vetting);
+        return new FileDurableRulePartition(this.dir, join(this.dir, principalRuleFileName(name)), this.acquireWriteLock, this.onError, this.vetting);
     }
     readOnlySourceView(sourceName, targetName, flipped) {
         const pick = flipped ? targetName : existsSync(join(this.dir, sourceName)) ? sourceName : targetName;

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

@@ -151,9 +151,9 @@ export declare class FileSessionPolicyStore implements SessionPolicyStore {
     private disclose;
     /** The ONE refusal for a rules file that is PRESENT but cannot be served as rules — every damage grade lands
      *  here (`unreadable` bytes, `unparseable` JSON, a `malformed` row), so the keyed read and the write that reads
-     *  before it answer with one voice. Session rules only TIGHTEN: a row is the restriction an operator put on the
-     *  session, so reading a damaged one as "no rules" would drop the restriction itself — the wrong direction for a
-     *  store whose every other face refuses a loosening. ABSENCE (ENOENT) is the only "no rules"; it never reaches
+     *  before it answer with one voice. Session rules only TIGHTEN: a row is a restriction on the session's calls, so
+     *  reading a damaged one as "no rules" would drop the restriction itself — a loosening no write made, which the
+     *  write judge would refuse below the row's operator part. ABSENCE (ENOENT) is the only "no rules"; it never reaches
      *  here. The disclosure sink fires with the refusal (swallow-guarded: a throwing sink cannot turn it back into an
      *  answer) and is the ONLY carrier of the file's path: the thrown message reaches end users through a host's error
      *  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

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

@@ -1,4 +1,4 @@
-import type { Session, SessionCreateOptions, SessionForkOptions, SessionMetadata, SessionPlacementRecord, SessionRepo, SessionTreeEntry } from "../../internal/harness.js";
+import type { Session, SessionCreateOptions, SessionForkOptions, SessionHead, SessionMetadata, SessionPlacementRecord, SessionRepo, SessionRow, SessionTreeEntry } from "../../internal/harness.js";
 import type { PlacedSessionRow } from "../../core/session.js";
 import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export interface FileSessionRepoOptions {
@@ -8,8 +8,9 @@ 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 each corrupt interior JSONL
-     * record dropped on replay plus that replay's tally (turns missing from an otherwise healthy session).
+     * whose header could not be read during a listing (skipped from the result — a listing reads headers,
+     * it never replays a log), 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).
@@ -37,12 +38,37 @@ export declare class FileSessionRepo implements SessionRepo {
     private pathFor;
     /**
      * 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.
+     * file whose first record is not a 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 / owner, 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;
+    /**
+     * The row's cells from its FIRST record — the one header every write path lays down before any entry; a later meta record is
+     * never read as the header. Each occupant cell goes through the one incarnation decoding (an unknown occupant, said here when the
+     * cell is there but names nobody) and the owner cell through its decoding (a cell that is neither an owner nor anonymous refuses
+     * the row). `skipped` words the corrupt-header refusal's reading of the records around it, where the caller has one.
+     */
+    private headerOf;
+    /**
+     * The row's head in one read, without replaying the log: ONE descriptor on the session file, its first record for the owner and
+     * occupant cells, and walking back from its end to the last entry record for the leaf. The three come from one inode — a file
+     * replaced (fork / import) or removed (delete) while this reads is still the inode this descriptor opened — so they answer for one
+     * row generation. The leaf is what a replay computes (the leaf after the last entry the whole-file read keeps, judged by the same
+     * per-line rule, a torn tail dropped alike): the log is the only carrier, so no state exists in which the log holds an entry the
+     * head does not see. A leaf entry naming an id the log does not hold is not checked here (a replay refuses that log on open).
+     */
+    headOf(sessionId: string): Promise<SessionHead | undefined>;
+    /**
+     * The row's {@link SessionRow} — its header cells and the newest write it holds, the log's modification time (every write to a row
+     * is an append to its log; the placed listing's age reads the same time) — in one read of the header, never a replay of the log.
+     * `undefined` = no row; a row whose header cannot be read rejects (`corrupt_session`).
+     */
+    private rowOf;
+    /** The one descriptor a by-id read of the row takes: its size and modification time and its header, from one inode (a file replaced
+     *  or removed while this reads is still the inode this descriptor opened); `undefined` = no file. */
+    private atRow;
     private storage;
     /**
      * RB-437 — release every shared authority this repo joined (LAST holder ⇒ evict + close the append fd).
@@ -59,12 +85,25 @@ export declare class FileSessionRepo implements SessionRepo {
     dispose(): Promise<void>;
     create(options?: SessionCreateOptions): Promise<Session>;
     open(metadata: SessionMetadata): Promise<Session>;
-    list(): Promise<SessionMetadata[]>;
+    /** Record activity on the row now: its log's modification time — the one time a listing reads, which every append moves too — is
+     *  set to now, the log's bytes untouched. A missing file is nothing to record; any other fault rejects. */
+    touch(sessionId: string): Promise<void>;
+    /** Every ordinary row with the newest write its log holds ({@link rowOf}): one header read per session file, no replay — what a
+     *  listing costs grows with the number of sessions, never with their history. Placed rows are the placed listing's. */
+    list(): Promise<SessionRow[]>;
+    /**
+     * Every row of the sessions directory, each read by {@link rowOf}. The listing degrades to "no sessions" so a
+     * browse face never throws — but "I could not read the directory" and "there are none" are different facts, and only the sink can
+     * tell them apart (ENOENT is honest absence: the constructor creates the directory, so it was removed underneath us). A session
+     * whose header cannot be read is skipped and disclosed — it exists and is missing from the listing — while a file that vanished
+     * between the directory read and its own is honest absence.
+     */
+    private rows;
     /**
      * Subagent transcript persistence — the PLACED partition's own enumeration (the joint reap's
      * partition-leg input; `TtlSessionStore` re-exposes it verbatim). Age (`olderThanMs`) is judged on
-     * the session FILE's mtime — the transcript's last append — falling back to `placedAt` when the
-     * stat fails (mtime is also the CC orphan-adoption window's basis, so the two age reads agree).
+     * the session FILE's mtime — the transcript's last append, the time the host listing reads too
+     * (mtime is also the CC orphan-adoption window's basis, so the age reads agree).
      * Rows missing either `(scope, handle)` join half return the honest `tupleIncomplete` variant
      * (consumers fail closed on it — never age-reaped, see the SessionStore contract).
      */
@@ -73,21 +112,20 @@ export declare class FileSessionRepo implements SessionRepo {
         scope?: string;
     }): Promise<PlacedSessionRow[]>;
     /** The row as it stands before a file-replacing write: `undefined` ⇔ there is no row (no file); a row
-     *  whose header cannot be read answers an empty header (it exists, its cells are unknown). */
+     *  whose header cannot be read rejects (it exists, and nobody can name its cells). */
     private priorHeader;
     /** Cheap placement probe for one id (the TtlSessionStore's cold-cache release consults it so the
-     *  placed real-deletion obligation holds after a restart). `undefined` = missing file OR unplaced. */
+     *  placed real-deletion obligation holds after a restart). `undefined` = missing file OR unplaced; a row that cannot be read rejects. */
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
     delete(metadata: SessionMetadata): Promise<void>;
-    fork(sourceMetadata: SessionMetadata, options?: SessionForkOptions): Promise<Session>;
+    fork(sourceMetadata: SessionMetadata, options?: SessionForkOptions & SessionCreateOptions): Promise<Session>;
     /** 2c session-sync (the FILE half): the FULL oldest-first log for export. The file backend
      *  has NO F3 floor — `read` returns EVERY persisted entry (`id`/`parentId` verbatim) — so this is the complete
      *  log, BYPASSing any bounded tail (matches `InMemorySessionRepo.exportEntries`). Missing file → not_found. */
     exportEntries(sessionId: string): Promise<SessionTreeEntry[]>;
     /** 2c session-sync: import a verbatim log into `sessionId`. The single fail-closed invariant gate runs
-     *  FIRST ({@link validateEntriesForImport}); `owner` is a durable multi-tenant concept the local file backend
-     *  has no field for (accepted, unused — same as `InMemorySessionRepo`). Writes the WHOLE file (meta + entries)
-     *  atomically via tmp→fsync→rename — the rename is the commit point, so a crash leaves either nothing or an
+     *  FIRST ({@link validateEntriesForImport}); a new row's header records `owner`, an existing row's is laid down again whole. Writes the WHOLE file
+     *  (meta + entries) atomically via tmp→fsync→rename — the rename is the commit point, so a crash leaves either nothing or an
      *  orphan temp, never a partially-imported session (mirrors `fork`). An existing session is REPLACED (the
      *  orchestrator's importSession owns the already-exists policy, same as InMemory's overwrite). */
     importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options?: {