@sema-agent/core 7.30.0 → 7.31.0

package/dist/core/memory-engine/entry-scan.d.ts

@@ -0,0 +1,23 @@
+/** Files/dirs the entry scan never treats as entries: the derived index, dotfiles (`.hydrate`,
+ *  transaction staging files), and anything not `.md`. */
+export declare const MEMORY_INDEX_FILENAME = "MEMORY.md";
+/** Default nesting depth cap under a scope dir (CC memory is flat; a small allowance for topic dirs). */
+export declare const DEFAULT_MAX_ENTRY_DEPTH = 3;
+/** One on-disk entry file the scan found. */
+export interface ScannedEntryFile {
+    /** Absolute path. */
+    path: string;
+    /** Slug = path relative to the scope dir, without `.md` (may contain `/` for nested topics). */
+    slug: string;
+}
+/**
+ * Enumerate a scope dir's entry files (depth-capped, symlinks skipped, dotfiles/index/non-`.md`
+ * ignored). Shared by the backend and the engine's harvest scan so the two can never disagree on
+ * what counts as an entry file. A scope dir is that scope's home and nothing else — no other
+ * scope's directory can lie under it, so there is nothing to exclude.
+ */
+export declare function scanEntryFiles(dir: string, opts?: {
+    maxDepth?: number;
+    /** Harvest gate hook: called for every path the scan SKIPS, with why (backend scans ignore it). */
+    onSkip?: (path: string, kind: "symlink" | "depth" | "nonmd" | "dotfile" | "unreadable") => void;
+}): ScannedEntryFile[];

package/dist/core/memory-engine/entry-scan.js

@@ -0,0 +1,55 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+export const MEMORY_INDEX_FILENAME = "MEMORY.md";
+export const DEFAULT_MAX_ENTRY_DEPTH = 3;
+export function scanEntryFiles(dir, opts = {}) {
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_ENTRY_DEPTH;
+    const out = [];
+    const walk = (d, depth) => {
+        let names;
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            if (d !== dir)
+                opts.onSkip?.(d, "unreadable");
+            return;
+        }
+        for (const name of names.sort()) {
+            if (name.startsWith(".") || name === MEMORY_INDEX_FILENAME) {
+                if (name.startsWith("."))
+                    opts.onSkip?.(join(d, name), "dotfile");
+                continue;
+            }
+            const p = join(d, name);
+            let st;
+            try {
+                st = lstatSync(p);
+            }
+            catch {
+                opts.onSkip?.(p, "unreadable");
+                continue;
+            }
+            if (st.isSymbolicLink()) {
+                opts.onSkip?.(p, "symlink");
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (depth + 1 <= maxDepth)
+                    walk(p, depth + 1);
+                else
+                    opts.onSkip?.(p, "depth");
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!name.endsWith(".md")) {
+                opts.onSkip?.(p, "nonmd");
+                continue;
+            }
+            out.push({ path: p, slug: relative(dir, p).replace(/\.md$/, "") });
+        }
+    };
+    walk(dir, 0);
+    return out;
+}

package/dist/core/memory-engine/file-backend.d.ts

@@ -1,29 +1,7 @@
 import { scopeDirName, type ChallengeEvent, type MemoryPartitionIncidentSink } from "./layout.js";
 import type { MemoryBundleImportPlan, MemoryImportReport } from "./export-bundle.js";
 import type { HarvestRejection, MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryScopeEnumeration, NotePatch, PatchReport, ScoredMemoryEntry } from "./types.js";
-/** Files/dirs the entry scan never treats as entries: the derived index, dotfiles (`.hydrate`,
- *  transaction staging files), and anything not `.md`. */
-export declare const MEMORY_INDEX_FILENAME = "MEMORY.md";
-/** Default nesting depth cap under a scope dir (CC memory is flat; a small allowance for topic dirs). */
-export declare const DEFAULT_MAX_ENTRY_DEPTH = 3;
-/** One on-disk entry file the scan found. */
-export interface ScannedEntryFile {
-    /** Absolute path. */
-    path: string;
-    /** Slug = path relative to the scope dir, without `.md` (may contain `/` for nested topics). */
-    slug: string;
-}
-/**
- * Enumerate a scope dir's entry files (depth-capped, symlinks skipped, dotfiles/index/non-`.md`
- * ignored). Shared by the backend and the engine's harvest scan so the two can never disagree on
- * what counts as an entry file. A scope dir is that scope's home and nothing else — no other
- * scope's directory can lie under it, so there is nothing to exclude.
- */
-export declare function scanEntryFiles(dir: string, opts?: {
-    maxDepth?: number;
-    /** Harvest gate hook: called for every path the scan SKIPS, with why (backend scans ignore it). */
-    onSkip?: (path: string, kind: "symlink" | "depth" | "nonmd" | "dotfile" | "unreadable") => void;
-}): ScannedEntryFile[];
+export { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles, type ScannedEntryFile } from "./entry-scan.js";
 /** design/178 v2-b §3.3(b) — the explicit erasure selector (each form resolves to an explicit id
  *  list before anything is deleted; there is no whole-store selector). */
 export type ErasureSelect = {
@@ -737,6 +715,14 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  the probe classifies those inline and keeps going — a store with a lingering copy never
      *  contends for the writer lock on every read. */
     private readScope;
+    /** #1076b — the observation-table door of the adopting read: bytes a session recorded appearing
+     *  while it held this layer read-only are never adopted. Gate-failing bytes are not taken here —
+     *  the inbound gate's containment keeps its door. A hit is announced, the committed copy stands in
+     *  when this path is the entry's bound projection, and the disk is left as found (the account it
+     *  is judged against is current — the scan sees to that). The notice is deduplicated against what
+     *  is still queued, so every session that meets the file is told once. Returns whether the file
+     *  was settled (the caller moves on). */
+    private settledAsObserved;
     /**
      * design-A RB-5 ([A3]) — the read-side whitewash gate, shared by the bound-here divergence lane
      * and the move+edit lane so the two can never drift: an out-of-session disk change (git pull /
@@ -846,6 +832,13 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * WRITES ARE REFUSED, loudly — a view handed to a write path is a defect, not a fallback.
      */
     retrievalView(): MemoryBackend;
+    /** #1076b — the lock-free retrieval face serves no recorded divergence either (side-effect-free, so
+     *  no notice): the committed copy stands in at the entry's bound projection, anything else is
+     *  withheld. The table is read per call; the account only when it names one of these ids. */
+    private withoutObserved;
+    /** The committed rows read afresh from disk (no cache install), or undefined when the account
+     *  cannot be read — a fault, never folded into "no rows". */
+    private committedRowsOrFault;
     /** Dedup keys for divergence findings the restricted view already recorded: one materialize reads
      *  a scope several times (listHeaders, then getByIds per scope), and a checkpoint-cadence harvest
      *  re-audits the same still-pending state — without the key, one untouched divergence would mint

package/dist/core/memory-engine/file-backend.js

@@ -6,63 +6,13 @@ import { MAX_MEMORY_BYTES } from "../memory.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { ambiguousOriginRepresentation, committedDistilledOf, committedOriginOf, computeEntryRev, distilledEquals, entryFromFile, isValidEntryId, originEquals, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
 import { convertV1SidecarKeys } from "./delegation-settlement.js";
-import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, adoptRootScopeLayout, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, layoutNeedsAdoption, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, scopeRegistryShape, stageImportLatch, writeAllSync, } from "./layout.js";
+import { layerObservationLookup, observedDivergenceNotice } from "./layer-observations.js";
+import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./entry-scan.js";
+import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, adoptRootScopeLayout, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, permissionRemedyOf, withPermissionRemedy, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, layoutNeedsAdoption, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, scopeRegistryShape, stageImportLatch, writeAllSync, } from "./layout.js";
 import { screenInboundEntries } from "./data-plane.js";
 import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
 import { thrownText } from "../thrown-value.js";
-export const MEMORY_INDEX_FILENAME = "MEMORY.md";
-export const DEFAULT_MAX_ENTRY_DEPTH = 3;
-export function scanEntryFiles(dir, opts = {}) {
-    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_ENTRY_DEPTH;
-    const out = [];
-    const walk = (d, depth) => {
-        let names;
-        try {
-            names = readdirSync(d);
-        }
-        catch {
-            if (d !== dir)
-                opts.onSkip?.(d, "unreadable");
-            return;
-        }
-        for (const name of names.sort()) {
-            if (name.startsWith(".") || name === MEMORY_INDEX_FILENAME) {
-                if (name.startsWith("."))
-                    opts.onSkip?.(join(d, name), "dotfile");
-                continue;
-            }
-            const p = join(d, name);
-            let st;
-            try {
-                st = lstatSync(p);
-            }
-            catch {
-                opts.onSkip?.(p, "unreadable");
-                continue;
-            }
-            if (st.isSymbolicLink()) {
-                opts.onSkip?.(p, "symlink");
-                continue;
-            }
-            if (st.isDirectory()) {
-                if (depth + 1 <= maxDepth)
-                    walk(p, depth + 1);
-                else
-                    opts.onSkip?.(p, "depth");
-                continue;
-            }
-            if (!st.isFile())
-                continue;
-            if (!name.endsWith(".md")) {
-                opts.onSkip?.(p, "nonmd");
-                continue;
-            }
-            out.push({ path: p, slug: relative(dir, p).replace(/\.md$/, "") });
-        }
-    };
-    walk(dir, 0);
-    return out;
-}
+export { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./entry-scan.js";
 export function canonicalJsonStringify(value) {
     if (Array.isArray(value))
         return `[${value.map((v) => (v === undefined || typeof v === "function" || typeof v === "symbol" ? "null" : canonicalJsonStringify(v))).join(",")}]`;
@@ -257,6 +207,45 @@ function validateLedgerRowsV2(rowsRaw, path) {
     }
     return out;
 }
+function parseJournal(raw, jp) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.ops))
+            throw new Error("wrong shape");
+        return parsed;
+    }
+    catch {
+        throw new ControlPlaneCorruptError(`transaction journal is unparseable: ${jp}`);
+    }
+}
+function journalLedgerSnapshot(journal, jp) {
+    const hasV2 = journal.ledger2 !== undefined;
+    const hasV1 = journal.ledger !== undefined;
+    if (hasV2 === hasV1) {
+        throw new ControlPlaneCorruptError(`transaction journal has ${hasV2 ? "both ledger snapshots" : "no ledger snapshot"} (wrong shape): ${jp}`);
+    }
+    if (hasV2) {
+        const env = journal.ledger2;
+        if (!env || typeof env !== "object" || Array.isArray(env) || env.v !== LEDGER_SCHEMA_VERSION) {
+            throw new ControlPlaneCorruptError(`transaction journal ledger2 snapshot has the wrong shape: ${jp}`);
+        }
+        const extras = {};
+        for (const [k, val] of Object.entries(env))
+            if (k !== "v" && k !== "rows")
+                extras[k] = val;
+        return { form: "v2", rows: validateLedgerRowsV2(env.rows, jp), extras };
+    }
+    const map = journal.ledger;
+    if (!map || typeof map !== "object" || Array.isArray(map))
+        throw new ControlPlaneCorruptError(`transaction journal ledger snapshot has the wrong shape: ${jp}`);
+    const rows = Object.create(null);
+    for (const [id, rev] of Object.entries(map)) {
+        if (typeof rev !== "string")
+            throw new ControlPlaneCorruptError(`transaction journal v1 ledger snapshot entry ${JSON.stringify(id)} is not a string: ${jp}`);
+        rows[id] = { rev };
+    }
+    return { form: "v1", rows };
+}
 function parseLedgerText(raw, path) {
     let parsed;
     try {
@@ -1240,44 +1229,9 @@ export class FileMemoryEngineBackend {
         const jp = join(this.controlPlaneRoot, JOURNAL_FILE);
         const raw = readControlFileOrAbsent(jp, "transaction journal");
         if (raw !== undefined) {
-            let journal;
-            try {
-                const parsed = JSON.parse(raw);
-                if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.ops))
-                    throw new Error("wrong shape");
-                journal = parsed;
-            }
-            catch {
-                throw new ControlPlaneCorruptError(`transaction journal is unparseable: ${jp}`);
-            }
-            const hasV2 = journal.ledger2 !== undefined;
-            const hasV1 = journal.ledger !== undefined;
-            if (hasV2 === hasV1) {
-                throw new ControlPlaneCorruptError(`transaction journal has ${hasV2 ? "both ledger snapshots" : "no ledger snapshot"} (wrong shape): ${jp}`);
-            }
-            let snapshotRows;
-            let snapshotExtras;
-            if (hasV2) {
-                const env = journal.ledger2;
-                if (!env || typeof env !== "object" || Array.isArray(env) || env.v !== LEDGER_SCHEMA_VERSION) {
-                    throw new ControlPlaneCorruptError(`transaction journal ledger2 snapshot has the wrong shape: ${jp}`);
-                }
-                snapshotRows = validateLedgerRowsV2(env.rows, jp);
-                snapshotExtras = {};
-                for (const [k, val] of Object.entries(env))
-                    if (k !== "v" && k !== "rows")
-                        snapshotExtras[k] = val;
-            }
-            else {
-                const map = journal.ledger;
-                if (!map || typeof map !== "object" || Array.isArray(map))
-                    throw new ControlPlaneCorruptError(`transaction journal ledger snapshot has the wrong shape: ${jp}`);
-                snapshotRows = Object.create(null);
-                for (const [id, rev] of Object.entries(map)) {
-                    if (typeof rev !== "string")
-                        throw new ControlPlaneCorruptError(`transaction journal v1 ledger snapshot entry ${JSON.stringify(id)} is not a string: ${jp}`);
-                    snapshotRows[id] = { rev };
-                }
+            const journal = parseJournal(raw, jp);
+            const { rows: snapshotRows, extras: snapshotExtras, form: snapshotForm } = journalLedgerSnapshot(journal, jp);
+            if (snapshotForm === "v1") {
                 try {
                     const diskRaw = readControlFileOrAbsent(join(this.controlPlaneRoot, LEDGER_FILE), "committed-rev ledger");
                     const diskParsed = diskRaw !== undefined ? JSON.parse(diskRaw) : undefined;
@@ -1314,7 +1268,7 @@ export class FileMemoryEngineBackend {
                     }
                     journalEvs.set(e.ev, canonical);
                 }
-                if (hasV1)
+                if (snapshotForm === "v1")
                     throw new ControlPlaneCorruptError(`transaction journal carries transfers with a v1 snapshot (impossible form): ${jp}`);
                 if (journalEvs.size > 0) {
                     for (const row of this.readTransferChain(fenceToken)) {
@@ -1464,12 +1418,12 @@ export class FileMemoryEngineBackend {
                 }
                 catch (err) {
                     const code = err.code;
-                    throw new ControlPlaneCorruptError(`transaction journal replay failed on op kind=${op.kind} target=${JSON.stringify(op.target)} (${code ?? (thrownText(err))}) — the journal is kept at ${jp}; an I/O failure retries at the next construction, a persistent fault needs the explicit control-plane rebuild path`);
+                    throw new ControlPlaneCorruptError(`transaction journal replay failed on op kind=${op.kind} target=${JSON.stringify(op.target)} (${code ?? (thrownText(err))}) — the journal is kept at ${jp}; ${permissionRemedyOf(err, this.directoryRoot) ?? "an I/O failure retries at the next construction, a persistent fault needs the explicit control-plane rebuild path"}`);
                 }
             }
             this.recoveryCommitProbe?.();
             this.assertTxnLockOwnership(fenceToken);
-            if (hasV2) {
+            if (snapshotForm === "v2") {
                 this.ledger = snapshotRows;
                 this.envelopeExtras = snapshotExtras;
                 this.persistedSchemaVersion = "v2";
@@ -1589,6 +1543,9 @@ export class FileMemoryEngineBackend {
         const moveEvents = [];
         const moveAnnouncements = [];
         const skippedUnreadable = [];
+        let table;
+        const observed = () => (table ??= layerObservationLookup(this.controlPlaneRoot));
+        let freshAccount;
         for (const f of files) {
             let text;
             try {
@@ -1608,6 +1565,12 @@ export class FileMemoryEngineBackend {
                 const committed = rowsRev(rows, entry.id);
                 const binding = rowsBinding(rows, entry.id);
                 const relPath = relative(this.directoryRoot, f.path);
+                if (probeOnly === true && observed().covers(entry.id)) {
+                    const fresh = (freshAccount ??= this.committedRowsOrFault() ?? null);
+                    const freshBinding = fresh !== null ? rowsBinding(fresh, entry.id) : undefined;
+                    if (fresh === null || rowsRev(fresh, entry.id) !== committed || freshBinding?.scope !== binding?.scope || freshBinding?.slug !== binding?.slug)
+                        return undefined;
+                }
                 if (committed !== undefined && binding !== undefined && !(binding.scope === scope && binding.slug === f.slug)) {
                     const probe = probeProjection(this.bindingAbsPath(binding), entry.id);
                     if (probe === "present") {
@@ -1618,6 +1581,8 @@ export class FileMemoryEngineBackend {
                         this.announceAdoptionNotice(`bindprobe|${relPath}`, `committed entry ${entry.id} appears at ${JSON.stringify(inlineUntrusted(relPath))} but is bound to ${JSON.stringify(inlineUntrusted(this.bindingRelPath(binding)))}, and the bound projection could not be probed conclusively (a read failure, or a foreign file at that address — not ENOENT) — nothing is served or adopted this pass`);
                         continue;
                     }
+                    if (this.settledAsObserved(observed(), entries, entry, relPath, f.slug, scope, committed, binding, text, "quarantined-only"))
+                        continue;
                     if (probeOnly)
                         return undefined;
                     if (lockToken !== undefined)
@@ -1630,6 +1595,8 @@ export class FileMemoryEngineBackend {
                     continue;
                 }
                 if (committed !== entry.rev) {
+                    if (committed !== undefined && this.settledAsObserved(observed(), entries, entry, relPath, f.slug, scope, committed, binding, text, "restored"))
+                        continue;
                     if (probeOnly)
                         return undefined;
                     if (lockToken !== undefined)
@@ -1664,6 +1631,8 @@ export class FileMemoryEngineBackend {
                         entry = entryFromFile(shadowText, entry.id, f.slug, scope);
                     }
                     else {
+                        if (committed === undefined && this.settledAsObserved(observed(), entries, entry, relPath, f.slug, scope, committed, binding, text, "restored"))
+                            continue;
                         if (committed !== undefined)
                             adoptedExternal.push(relPath);
                         bindRowTracked(rows, entry.id, { rev: entry.rev, scope, slug: f.slug, at: this.now() }, moveEvents, "adopted-move");
@@ -1740,6 +1709,25 @@ export class FileMemoryEngineBackend {
             this.batchScan.set(scope, entries);
         return entries;
     }
+    settledAsObserved(table, out, entry, relPath, slug, scope, committed, binding, text, containment) {
+        if (!table.covers(entry.id) || this.inboundGate(relPath, text) !== undefined)
+            return false;
+        if (committed !== undefined && committed !== entry.rev && this.whitewashInboundFinding(relPath, entry, containment) !== undefined)
+            return false;
+        const hit = table.find(entry.id, committed, entry.rev);
+        if (hit === undefined)
+            return false;
+        const standIn = committed !== undefined && binding !== undefined && binding.scope === scope && binding.slug === slug ? this.readCommittedShadow(entry.id) : undefined;
+        const notice = observedDivergenceNotice(relPath, standIn !== undefined, hit.undecided === true);
+        try {
+            enqueueMemoryAnnouncement(this.controlPlaneRoot, { kind: "external", at: this.now(), items: [notice] }, { supersedesPrefix: notice });
+        }
+        catch {
+        }
+        if (standIn !== undefined)
+            out.push(entryFromFile(standIn, entry.id, slug, scope));
+        return true;
+    }
     whitewashInboundFinding(relPath, entry, containment) {
         const committedShadow = this.readCommittedShadow(entry.id);
         const committedFm = committedShadow !== undefined ? parseEntryFile(committedShadow).frontmatter : undefined;
@@ -1862,14 +1850,46 @@ export class FileMemoryEngineBackend {
             throw new Error(`memory retrieval view is read-only — ${op} must go through the backend itself`);
         };
         return {
-            listHeaders: async (scopes) => (this.ensureLayout(), this.listHeadersFrom(scopes, (s) => this.readScope(s, false))),
-            getByIds: async (ids) => (this.ensureLayout(), this.getByIdsFrom(ids, (s) => this.readScope(s, false))),
-            search: async (query, scopes, opts) => (this.ensureLayout(), this.searchFrom(query, scopes, opts, (s) => this.readScope(s, false))),
+            listHeaders: async (scopes) => (this.ensureLayout(), this.listHeadersFrom(scopes, (s) => this.withoutObserved(this.readScope(s, false), s))),
+            getByIds: async (ids) => (this.ensureLayout(), this.getByIdsFrom(ids, (s) => this.withoutObserved(this.readScope(s, false), s))),
+            search: async (query, scopes, opts) => (this.ensureLayout(), this.searchFrom(query, scopes, opts, (s) => this.withoutObserved(this.readScope(s, false), s))),
             applyPatches: async () => refuse("applyPatches"),
             getConsolidationCursor: async (scope) => this.getConsolidationCursor(scope),
             setConsolidationCursor: async () => refuse("setConsolidationCursor"),
         };
     }
+    withoutObserved(entries, scope) {
+        const table = layerObservationLookup(this.controlPlaneRoot);
+        if (!entries.some((e) => table.covers(e.id)))
+            return entries;
+        const account = this.committedRowsOrFault();
+        if (account === undefined)
+            return entries.filter((e) => !table.covers(e.id));
+        const out = [];
+        for (const e of entries) {
+            const committed = rowsRev(account, e.id);
+            const binding = rowsBinding(account, e.id);
+            const boundHere = binding !== undefined && binding.scope === scope && binding.slug === e.slug;
+            if ((committed === e.rev && boundHere) || table.find(e.id, committed, e.rev) === undefined) {
+                out.push(e);
+                continue;
+            }
+            const standIn = committed !== undefined && boundHere ? this.readCommittedShadow(e.id) : undefined;
+            if (standIn !== undefined)
+                out.push(entryFromFile(standIn, e.id, e.slug, scope));
+        }
+        return out;
+    }
+    committedRowsOrFault() {
+        const path = join(this.controlPlaneRoot, LEDGER_FILE);
+        try {
+            const raw = readControlFileOrAbsent(path, "committed-rev ledger");
+            return raw === undefined ? Object.create(null) : parseLedgerText(raw, path).rows;
+        }
+        catch {
+            return undefined;
+        }
+    }
     restrictedFindingKeys = new Set();
     recordRestrictedFinding(key, finding) {
         if (this.restrictedFindingKeys.has(key))
@@ -2187,6 +2207,9 @@ export class FileMemoryEngineBackend {
         try {
             return await this.applyPatchesLocked(patches, lock.token);
         }
+        catch (err) {
+            throw withPermissionRemedy(err, this.directoryRoot);
+        }
         finally {
             lock.release();
         }
@@ -2865,7 +2888,7 @@ export class FileMemoryEngineBackend {
         }
         catch (err) {
             this.ledger = undefined;
-            throw err;
+            throw withPermissionRemedy(err, this.directoryRoot);
         }
         finally {
             lock.release();

package/dist/core/memory-engine/layer-observations.d.ts

@@ -0,0 +1,109 @@
+import type { HarvestRejection, MemorySessionHandle } from "./types.js";
+export declare const LAYER_OBSERVATIONS_FILE = "layer-observations.json";
+/** One recorded unexpected write into a read-only layer. */
+export interface LayerObservation {
+    /** The layer (scope) the bytes were observed in. */
+    scope: string;
+    /** Scope-home-relative, `/`-separated path the bytes were observed at (disclosure only). */
+    rel: string;
+    /** The entry id the observed file carries; absent ⇔ an id-less note. */
+    entryId?: string;
+    /** The entry's committed rev when observed; absent ⇔ the id had no committed row. */
+    rev?: string;
+    /** The observed content's identity: its entry rev (what the read side computes from the file), or
+     *  for an id-less note the sha256 of its bytes. */
+    observedRev: string;
+    /** The observing session, when the harvest was given one. */
+    sessionId?: string;
+    observedAt: number;
+    /** Whether a commit backs these bytes could not be established when they were observed (a
+     *  transaction journal was pending — the committed account could not be read whole). The row — one
+     *  per observation — then stands against ANY committed rev (never adopted) until the first session
+     *  that may write settles it, once its preflight has recovered the journal
+     *  ({@link settleUndecidedLayerObservations}): the committed account backs its bytes at its seat ⇒
+     *  this observation is removed (the bytes are committed content); it does not ⇒ pinned to the
+     *  committed rev read, an ordinary row from then on, retired when that rev moves (superseded, as
+     *  every ordinary row is); the account still cannot be read ⇒ it stays undecided. Only id-bearing
+     *  rows (a note has no commit question) and never with `rev`. */
+    undecided?: true;
+    /** An undecided row's own identity (random, minted with the row): two observations alike in every
+     *  other field — the same session in the same millisecond — stay two rows. Undecided rows only. */
+    observationId?: string;
+}
+/** Record observations (locked, journaled; an existing key keeps its first row). Nothing is pruned
+ *  here: the rev a harvest read before this lock need not be current any more, so it cannot decide
+ *  which other rows are stale — and a row against a rev the entry has left can never match anyway. */
+export declare function recordLayerObservations(controlDir: string, rows: readonly LayerObservation[]): void;
+/** The table as a read-side lookup. */
+export interface LayerObservationLookup {
+    /** Whether any row names `entryId` (a cheap pre-test before the committed rev is fetched). */
+    covers(entryId: string): boolean;
+    /** The row naming exactly this content (`observedRev`) of `entryId` against its committed rev
+     *  `rev` (absent ⇔ the id has no committed row) — or an undecided row for that content, which stands
+     *  against any rev until it is settled — else undefined. */
+    find(entryId: string, rev: string | undefined, observedRev: string): LayerObservation | undefined;
+    /** The row naming exactly these bytes (`digest`) of an id-less note at (`scope`, `rel`), or undefined. */
+    findNote(scope: string, rel: string, digest: string): LayerObservation | undefined;
+}
+/** Read the table (throws the strict family's refusal on a corrupt table). */
+export declare function layerObservationLookup(controlDir: string): LayerObservationLookup;
+/** The disclosure line for a recorded divergence met on the adopting read (one spelling, every
+ *  door). The verdict leads: the render boundary caps an item at a label's length. */
+export declare function observedDivergenceNotice(rel: string, served: boolean, undecided?: boolean): string;
+/** The undecided rows ({@link LayerObservation.undecided}) awaiting settlement. */
+export declare function undecidedLayerObservations(controlDir: string): LayerObservation[];
+/** Settle undecided rows (locked, journaled), each by its own key (one observation — never another
+ *  observation of the same entry): `"backed"` removes the row (the committed account backs its bytes
+ *  at its seat: those bytes are committed content, so no unexpected write is lost), `{ rev }` pins
+ *  it to the committed rev the settlement read (`rev` absent ⇔ no committed row) — an ordinary row,
+ *  retired like any other when that rev moves. A row without a verdict stays undecided. */
+export declare function settleUndecidedLayerObservations(controlDir: string, verdicts: ReadonlyMap<LayerObservation, "backed" | {
+    rev?: string;
+}>): void;
+/** The census digest: whole-file bytes (sha256), so "the bytes that stood when the window opened"
+ *  means the bytes. */
+export declare function layerDigest(text: string): string;
+/** The read-only layers' census (materialize, zero-copy): canonical path → {@link layerDigest} of
+ *  every entry file under `homes`, scanned at the read side's depth (what the adopting read sees). */
+export declare function readOnlyLayerCensus(homes: readonly string[]): Map<string, string>;
+/** A file of a read-only layer whose bytes changed since the materialize-time census. */
+export interface ReadOnlyObservationCandidate {
+    path: string;
+    scope: string;
+    rel: string;
+    slug: string;
+    digest: string;
+    id?: string;
+    /** The entry rev of the bytes, or their digest for an id-less note. */
+    observedRev: string;
+}
+/** The observation half's candidates: files of the layers `handle` holds read-only whose bytes differ
+ *  from its materialize-time census (none without a census). Throws when the scope registry cannot
+ *  be read (the homes are resolved through it). */
+export declare function readOnlyLayerCandidates(memoryDir: string, controlDir: string, handle: Pick<MemorySessionHandle, "layerBaseline" | "scopes" | "writeScope">): ReadOnlyObservationCandidate[];
+/** What a harvest's observation half judged at detection: the rows (written AS JUDGED — a retry writes
+ *  the same rows, never a re-judgment against a later account), the rejections and undecided
+ *  candidates they carry, whether they landed, and the failure of the last attempt that did not. */
+export interface ObservationBatch {
+    rows: LayerObservation[];
+    rejections: HarvestRejection[];
+    /** Each undecided candidate with the row it was recorded as (its observation identity). */
+    undecided: Array<{
+        candidate: ReadOnlyObservationCandidate;
+        row: LayerObservation;
+    }>;
+    landed: boolean;
+    failure?: string;
+}
+/** The undecided candidates a LANDED batch recorded (an unlanded one claims none). */
+export declare function landedUndecided(batch: ObservationBatch | undefined): ObservationBatch["undecided"];
+/** Whether two rows are the same observation (the table's key — for an undecided row, one
+ *  observation: session and time included). */
+export declare function sameObservation(a: LayerObservation, b: LayerObservation): boolean;
+/** Whether the committed row backs an observation's bytes at its seat (same rev, bound there) — the
+ *  observation was a commit, not an unexpected write. */
+export declare function observationBacked(row: Pick<LayerObservation, "scope" | "rel" | "observedRev">, committed: {
+    rev: string;
+    scope?: string;
+    slug?: string;
+} | undefined): boolean;