@sema-agent/core 7.30.1 → 7.31.1

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;

package/dist/core/memory-engine/layer-observations.js

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { relative, sep } from "node:path";
+import { inlineUntrusted } from "../untrusted-text.js";
+import { scanEntryFiles } from "./entry-scan.js";
+import { entryFromFile, parseEntryFile } from "./frontmatter.js";
+import { ControlPlaneCorruptError, canonicalize, lockedStrictUpdate, readStrictSidecar, scopeDirFor } from "./layout.js";
+export const LAYER_OBSERVATIONS_FILE = "layer-observations.json";
+const WHAT = "memory layer-observation table";
+const str = (v) => typeof v === "string" && v.length > 0;
+function coerce(raw) {
+    if (raw === undefined)
+        return { version: 1, rows: [] };
+    const rec = raw;
+    if (typeof rec !== "object" || rec === null || rec.version !== 1 || !Array.isArray(rec.rows))
+        throw new ControlPlaneCorruptError(`${WHAT} has the wrong shape or an unrecognized version — refusing (fail-closed)`);
+    const rows = rec.rows;
+    for (const r of rows) {
+        const row = r;
+        if (typeof row !== "object" || row === null || !str(row.scope) || !str(row.rel) || (row.entryId !== undefined && !str(row.entryId)) || !str(row.observedRev) || (row.rev !== undefined && (row.entryId === undefined || !str(row.rev))) || (row.sessionId !== undefined && !str(row.sessionId)) || typeof row.observedAt !== "number" || !Number.isFinite(row.observedAt) || (row.undecided !== undefined && (row.undecided !== true || row.entryId === undefined || row.rev !== undefined)) || (row.observationId !== undefined && (!str(row.observationId) || row.undecided !== true))) {
+            throw new ControlPlaneCorruptError(`${WHAT}: a row is malformed — refusing (fail-closed; an unevaluable row must not read as "no unexpected write")`);
+        }
+    }
+    return rec;
+}
+const keyOf = (o) => o.entryId === undefined
+    ? JSON.stringify([null, o.scope, o.rel, o.observedRev])
+    : o.undecided === true
+        ? JSON.stringify([o.entryId, { undecided: true }, o.observedRev, o.scope, o.rel, o.sessionId ?? null, o.observedAt, o.observationId ?? null])
+        : JSON.stringify([o.entryId, o.rev ?? null, o.observedRev]);
+const contentKey = (entryId, observedRev) => JSON.stringify([entryId, observedRev]);
+export function recordLayerObservations(controlDir, rows) {
+    if (rows.length === 0)
+        return;
+    lockedStrictUpdate(controlDir, LAYER_OBSERVATIONS_FILE, WHAT, coerce, (rec) => {
+        const byKey = new Map(rec.rows.map((r) => [keyOf(r), r]));
+        for (const r of rows)
+            if (!byKey.has(keyOf(r)))
+                byKey.set(keyOf(r), { ...r });
+        return { next: { version: 1, rows: [...byKey.values()] }, result: undefined };
+    });
+}
+export function layerObservationLookup(controlDir) {
+    const rows = coerce(readStrictSidecar(controlDir, LAYER_OBSERVATIONS_FILE, WHAT)).rows;
+    const ids = new Set(rows.flatMap((r) => (r.entryId !== undefined ? [r.entryId] : [])));
+    const byKey = new Map(rows.map((r) => [keyOf(r), r]));
+    const undecidedByContent = new Map(rows.flatMap((r) => (r.undecided === true && r.entryId !== undefined ? [[contentKey(r.entryId, r.observedRev), r]] : [])));
+    return {
+        covers: (entryId) => ids.has(entryId),
+        find: (entryId, rev, observedRev) => ids.has(entryId) ? (byKey.get(keyOf({ scope: "", rel: "", entryId, rev, observedRev })) ?? undecidedByContent.get(contentKey(entryId, observedRev))) : undefined,
+        findNote: (scope, rel, digest) => byKey.get(keyOf({ scope, rel, observedRev: digest })),
+    };
+}
+export function observedDivergenceNotice(rel, served, undecided = false) {
+    const file = JSON.stringify(inlineUntrusted(rel));
+    if (undecided)
+        return `change NOT adopted yet: ${file} changed while a session held its layer read-only, and whether a commit backs it could not be established — re-judged once a writing session can read the committed account`;
+    return served
+        ? `change NOT adopted: ${file} was written while a session held its layer read-only — memory serves the committed version, not these bytes`
+        : `file NOT adopted: ${file} appeared while a session held its layer read-only — it is not memory; left on disk for review`;
+}
+export function undecidedLayerObservations(controlDir) {
+    return coerce(readStrictSidecar(controlDir, LAYER_OBSERVATIONS_FILE, WHAT)).rows.filter((r) => r.undecided === true);
+}
+function ordinaryRow(r, rev) {
+    return {
+        scope: r.scope,
+        rel: r.rel,
+        ...(r.entryId !== undefined ? { entryId: r.entryId } : {}),
+        ...(rev !== undefined ? { rev } : {}),
+        observedRev: r.observedRev,
+        ...(r.sessionId !== undefined ? { sessionId: r.sessionId } : {}),
+        observedAt: r.observedAt,
+    };
+}
+export function settleUndecidedLayerObservations(controlDir, verdicts) {
+    if (verdicts.size === 0)
+        return;
+    const byKey = new Map([...verdicts].map(([row, v]) => [keyOf(row), v]));
+    lockedStrictUpdate(controlDir, LAYER_OBSERVATIONS_FILE, WHAT, coerce, (rec) => {
+        const next = new Map();
+        for (const r of rec.rows) {
+            const v = r.undecided === true ? byKey.get(keyOf(r)) : undefined;
+            if (v === "backed")
+                continue;
+            const settled = v === undefined ? r : ordinaryRow(r, v.rev);
+            if (!next.has(keyOf(settled)))
+                next.set(keyOf(settled), settled);
+        }
+        return { next: { version: 1, rows: [...next.values()] }, result: undefined };
+    });
+}
+export function layerDigest(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readOnlyLayerCensus(homes) {
+    const files = new Map();
+    for (const home of homes) {
+        for (const f of scanEntryFiles(home)) {
+            const path = canonicalize(f.path);
+            const text = readText(path);
+            if (text !== undefined)
+                files.set(path, layerDigest(text));
+        }
+    }
+    return files;
+}
+export function readOnlyLayerCandidates(memoryDir, controlDir, handle) {
+    const census = handle.layerBaseline;
+    if (census === undefined)
+        return [];
+    const out = [];
+    for (const scope of new Set(handle.scopes)) {
+        if (scope === handle.writeScope)
+            continue;
+        const home = canonicalize(scopeDirFor(memoryDir, controlDir, scope));
+        for (const f of scanEntryFiles(home)) {
+            const path = canonicalize(f.path);
+            const text = readText(path);
+            if (text === undefined || (path !== home && !path.startsWith(`${home}${sep}`)))
+                continue;
+            const digest = layerDigest(text);
+            if (census.get(path) === digest)
+                continue;
+            const id = parseEntryFile(text).id;
+            const rel = relative(home, path).split(sep).join("/");
+            out.push({ path, scope, rel, slug: f.slug, digest, ...(id !== undefined ? { id, observedRev: entryFromFile(text, id, f.slug, scope).rev } : { observedRev: digest }) });
+        }
+    }
+    return out;
+}
+export function landedUndecided(batch) {
+    return batch?.landed === true ? batch.undecided : [];
+}
+export function sameObservation(a, b) {
+    return keyOf(a) === keyOf(b);
+}
+export function observationBacked(row, committed) {
+    return committed !== undefined && committed.scope === row.scope && committed.slug === row.rel.replace(/\.md$/, "") && committed.rev === row.observedRev;
+}

package/dist/core/memory-engine/layout.d.ts

@@ -259,8 +259,41 @@ export declare function adoptRootScopeLayout(rootPath: string, controlDir: strin
 export declare const canonicalize: typeof physicalPathOfExisting;
 /** True iff `child` (canonicalized) is `root` or inside it. */
 export declare function isContainedIn(root: string, child: string): boolean;
+/** The code an act on a store path is refused with when it would land outside the store ({@link storeTargetEscape}). */
+export declare const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+/** Where an act at `p` lands: the physical path of its normalized spelling (the spelling a child path
+ *  joined under it carries), a MISSING tail rejoined under the deepest existing directory (what the act
+ *  creates). Any other resolution fault (EACCES, ELOOP, ENOTDIR) is THROWN as itself: an act that
+ *  cannot be placed is not performed — a failed resolution never implies the act would fail too
+ *  (a link whose own mode refuses `realpath` is still followed by `unlink` and `rename`). */
+export declare function landingPathOf(p: string): string;
+/**
+ * Where a write, rename or delete at `target` would physically LAND, judged against the store's
+ * `physicalRoot`: `undefined` = inside, otherwise the reason. The target's directory, resolved through
+ * every link on its existing prefix (a missing tail is what the act creates, under the deepest existing
+ * directory), must be the root or inside it. `physicalRoot` is the root's physical form as the store
+ * was opened and is not re-resolved here: a store mounted through a link is judged by what the link
+ * resolved to, and a root spelling re-pointed after opening moves the acts, not the store. The final
+ * component is not judged: `rename` and `unlink` act on it and never through it, and the engine's
+ * writes open it no-follow — a link there is replaced, removed or refused, and what it points at is
+ * untouched. A lexical spelling under the root proves nothing: a directory under it replaced by a link
+ * keeps the spelling while the act follows the link out. A directory that cannot be resolved throws its
+ * fault ({@link landingPathOf}).
+ */
+export declare function storeTargetEscape(physicalRoot: string, target: string): string | undefined;
 /** mkdir -p convenience used by the engine/backend (0o700 like the file stores). */
 export declare function ensureDirExists(dir: string): void;
+/** The one remedy every surfaced permission refusal carries — `undefined` unless `err` is a write
+ *  the file system refused on PERMISSIONS (`EACCES` / `EPERM`) at a path INSIDE `memoryDir` (a
+ *  refusal elsewhere — a control plane kept outside the store — is not this store's to fix). The
+ *  engine never changes permission bits on a store — a session's read-only layers are its policy,
+ *  not file-system state — so bits that refuse a write were set by someone else, and nothing here
+ *  clears them (an engine from 7.30.x or earlier left inherited layers read-only on disk). */
+export declare function permissionRemedyOf(err: unknown, memoryDir: string): string | undefined;
+/** Attach {@link permissionRemedyOf} to a permission refusal inside `memoryDir` — in place, so the
+ *  error keeps its class and `code` (callers branch on both), and once (an inner seat that already
+ *  named its store wins over an outer one). Any other value is returned untouched. */
+export declare function withPermissionRemedy<T>(err: T, memoryDir: string): T;
 /** B2/L4 — the control-plane subdir holding gate-rejected originals. ONE name for all three writers
  *  (engine harvest, engine derived-index rung, backend inbound gate): they write the same directory,
  *  so its name and its permissions must not depend on which of them ran first. */
@@ -313,10 +346,13 @@ export interface QuarantineOutcome {
  * without native bindings. What this buys is the leaf variant, which is the cheap one; the ancestor
  * variant stays open and is recorded with the rest of the family rather than papered over.
  *
- * Throws like `writeFileSync`, including ELOOP when the final component IS a symlink. The write
- * itself goes through `writeFileSync` on the open descriptor, which writes every byte or throws —
- * a bare `writeSync` may short-write, and reporting a truncated restore as contained (after
- * `O_TRUNC` already destroyed the destination) is the failure this guard exists to prevent.
+ * Throws like `writeFileSync`, including ELOOP when the final component IS a symlink. A HARD link is the
+ * same tamper by other means — the file's bytes live under a second name, possibly outside the store, and
+ * an in-place write would change them there too — so an opened file with more than one name is refused
+ * the same way, before anything is truncated (the check reads the opened descriptor: no window). The
+ * write itself goes through `writeFileSync` on the open descriptor, which writes every byte or throws —
+ * a bare `writeSync` may short-write, and reporting a truncated restore as contained (after the
+ * truncation already destroyed the destination) is the failure this guard exists to prevent.
  */
 export declare function writeFileNoFollow(path: string, content: string): void;
 /** {@link writeFileNoFollow}'s NO-REPLACE twin: write `content` only if nothing is at `path`. `"written"`

package/dist/core/memory-engine/layout.js

@@ -1,10 +1,10 @@
-import { chmodSync, closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
-const { O_WRONLY, O_RDONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_NONBLOCK, O_EXCL } = fsConstants;
+import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
+const { O_WRONLY, O_RDONLY, O_CREAT, O_NOFOLLOW, O_NONBLOCK, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { MEMORY_ORIGIN_CAUSES } from "./types.js";
-import { physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
+import { physicalPathOf, physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
 import { thrownLabel, thrownText } from "../thrown-value.js";
 const SCOPES_FILE = "scopes.json";
 export const CURSORS_FILE = "cursors.json";
@@ -687,10 +687,8 @@ function moveLooseContent(root, controlDir, rec, owner, label, renew, sink, resu
     const labels = new Set(Object.values(rec.scopes));
     const { names, probes } = looseRootContent(root, labels, controlDir);
     const home = join(root, label);
-    if (names.length > 0) {
+    if (names.length > 0)
         ensureScopeHome(home);
-        chmodSync(home, 0o755);
-    }
     let moved = 0;
     for (const name of names) {
         renew();
@@ -726,15 +724,53 @@ export function isContainedIn(root, child) {
     const c = canonicalize(child);
     return c === r || c.startsWith(`${r}${sep}`);
 }
+export const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+export function landingPathOf(p) {
+    const normalized = resolve(p);
+    try {
+        return physicalPathOf(normalized);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        return canonicalize(normalized);
+    }
+}
+export function storeTargetEscape(physicalRoot, target) {
+    const dir = landingPathOf(dirname(target));
+    return dir === physicalRoot || dir.startsWith(`${physicalRoot}${sep}`) ? undefined : `its directory resolves to ${dir}, outside the store root ${physicalRoot}`;
+}
 export function ensureDirExists(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
+export function permissionRemedyOf(err, memoryDir) {
+    const e = typeof err === "object" && err !== null ? err : undefined;
+    if (e === undefined || (e.code !== "EACCES" && e.code !== "EPERM") || typeof e.path !== "string" || !isContainedIn(memoryDir, e.path))
+        return undefined;
+    return `file permissions refused this memory write (the engine never changes permission bits) — if an engine from 7.30.x or earlier left read-only bits on this store, run \`chmod -R u+w ${shellQuoted(memoryDir)}\` once no such engine still runs on it (an older engine sets the bits again whenever it mounts a layer read-only)`;
+}
+function shellQuoted(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+const remedied = new WeakSet();
+export function withPermissionRemedy(err, memoryDir) {
+    const remedy = permissionRemedyOf(err, memoryDir);
+    if (remedy === undefined || !(err instanceof Error) || remedied.has(err))
+        return err;
+    err.message = `${err.message} — ${remedy}`;
+    remedied.add(err);
+    return err;
+}
 export const QUARANTINE_DIR = "quarantine";
 const DELETED_TOMBSTONE = "---\ndeleted: true\n---\n";
 export function writeFileNoFollow(path, content) {
-    const fd = openSync(path, O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW, 0o644);
+    const fd = openSync(path, O_WRONLY | O_CREAT | O_NOFOLLOW, 0o644);
     try {
+        const links = fstatSync(fd).nlink;
+        if (links > 1)
+            throw Object.assign(new Error(`${path} has ${links} names (a hard link) — a write through one name changes the file under the others; not written`), { path });
+        ftruncateSync(fd, 0);
         writeFileSync(fd, content, "utf8");
     }
     finally {

package/dist/core/memory-engine/types.d.ts

@@ -391,7 +391,9 @@ export interface MaterializedFile {
     rev: string;
     /** True when this file is a budget stub (frontmatter+description only, body archived — §2.3). */
     stub: boolean;
-    /** True when the file belongs to a read-only inherited layer (chmod-protected, never harvested as a write). */
+    /** True when the file belongs to a read-only inherited layer (read-only by this session's policy —
+     *  its file mode is left as found; never harvested as a write, a change to it is a `readonly_layer`
+     *  rejection and the committed copy is restored). */
     readonly: boolean;
 }
 /** The write face's home, for a call site that has established a write face exists (`writeScope !==
@@ -500,6 +502,28 @@ export interface MemorySessionHandle {
         files: Map<string, string>;
         index?: string;
     };
+    /**
+     * The read-only layers' census: every entry file of every layer this session holds read-only,
+     * canonical path → digest of its bytes, taken at materialize BEFORE the adopting read — what stood
+     * when this session's window opened. The harvest's observation half records, in the store's
+     * session-observation table, every id-bearing file of those layers whose bytes changed since and
+     * that no commit backs (the read side never adopts a recorded divergence); the detection half
+     * words a divergence that already stood as not this session's write. Absent ⇔ not a zero-copy
+     * mount (the observed plane is not the store the read side adopts from), or a handle minted
+     * before the field — nothing is recorded then.
+     */
+    layerBaseline?: Map<string, string>;
+    /**
+     * The session-account LEG this mount opened (minted at materialize, stored on the account row).
+     * The harvest closes the account, and a terminal harvest (or a failed prepare's release) ends the
+     * leg, only while the row still carries this leg — a resume that re-opened the row makes this
+     * mount's close / end stale, and they are not written over the later leg. Absent ⇔ this mount
+     * opened no account (no session id, provenance "off", an adoption-restricted mount, an open that
+     * failed and is known not to have landed) — nothing of an account is written for it then. An open
+     * that failed after it landed, or whose landing could not be read back, keeps its leg (every write
+     * made with it is leg-checked).
+     */
+    accountLeg?: string;
 }
 /** Stable rejection codes a harvest gate can produce (model-visible gate events — 镜头 I). */
 export type HarvestRejectionCode = "outside_root" | "symlink" | "secret" | "injection" | "filename" | "too_large" | "file_cap" | "readonly_layer" | "stub_modified" | "nested_too_deep" | "quarantine_failed" | "unreadable" | "deferred" | "polluted" | "restricted_divergence" | "invalid";
@@ -539,7 +563,7 @@ export interface MemoryAnnouncement {
      *  #479's seat is that every face of one harvest names the same id, and a throat that minted its
      *  own would hand the same occurrence two values). Present on the harvest-tail enqueues (the gate
      *  items and the inbound-reject items); absent on every announcement with no report behind it
-     *  (backend adoption notices, mode-sweep notes, index-heal notes) and on a hand-built report that
+     *  (backend adoption notices, layer-census notes, index-heal and index-write notes) and on a hand-built report that
      *  carries no id — omitted, never fabricated.
      *
      *  STRUCTURE-ONLY, deliberately: {@link import("./engine.js").renderAnnouncements} does not read

package/dist/core/parent-spec-seat.d.ts

@@ -13,7 +13,7 @@ import type { Hooks } from "./hooks.js";
 import type { ToolExecuteContext } from "./tool-spec.js";
 import type { TaskSpec } from "./types.js";
 /** The fields of a spec the seat carries — one `Pick`, shared by the mint's input and the apply's target. */
-export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "hooks" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "memory" | "compaction" | "skillListingBudgetFraction" | "skillListingMaxDescChars">;
+export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "hooks" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "memory" | "compaction" | "skillListingBudgetFraction" | "skillListingMaxDescChars" | "fileHistory">;
 /**
  * The seat a run hands its children. Every member is the parent's own value, frozen at mint (arrays copied and
  * frozen; the facts object copied). Members present iff the parent carries them — an absent member is "nothing to
@@ -43,6 +43,8 @@ export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "cli
  *  · `skillListingBudgetFraction` / `skillListingMaxDescChars` — the listing-budget knobs, the same shape for the
  *    same reason: a fraction the parent tuned is a fraction OF EACH LEG'S OWN window, so it travels as a number
  *    and every leg multiplies it by its own.
+ *  · `fileHistory` — the request's file-history off switch (`"disabled"`, its only word), for the edits its delegates
+ *    make on its behalf too. An ORDINARY member (fill law); with one word no child can author it back on.
  */
 export interface ParentSpecSeat {
     readonly principal?: string;
@@ -58,6 +60,7 @@ export interface ParentSpecSeat {
     readonly compaction?: TaskSpec["compaction"];
     readonly skillListingBudgetFraction?: number;
     readonly skillListingMaxDescChars?: number;
+    readonly fileHistory?: "disabled";
 }
 /** Mint the seat off the parent's REBOUND spec and its frozen question face (spec over deps — the caller resolves it once,
  *  the same value the parent's own question routing reads). Absent fields stay absent; `oneShot` only when `true`. */

package/dist/core/parent-spec-seat.js

@@ -12,6 +12,7 @@ export function parentSpecSeatOf(spec, frozenOnQuestion) {
         ...(spec.compaction !== undefined ? { compaction: Object.freeze({ ...spec.compaction }) } : {}),
         ...(spec.skillListingBudgetFraction !== undefined ? { skillListingBudgetFraction: spec.skillListingBudgetFraction } : {}),
         ...(spec.skillListingMaxDescChars !== undefined ? { skillListingMaxDescChars: spec.skillListingMaxDescChars } : {}),
+        ...(spec.fileHistory !== undefined ? { fileHistory: spec.fileHistory } : {}),
         ...(spec.memory?.enabled === false ? { memoryOff: true } : {}),
     });
 }
@@ -31,6 +32,7 @@ export function applyParentSpecSeat(child, seat) {
         ...fill("compaction", (seat.compaction !== undefined ? { ...seat.compaction } : undefined)),
         ...fill("skillListingBudgetFraction", seat.skillListingBudgetFraction),
         ...fill("skillListingMaxDescChars", seat.skillListingMaxDescChars),
+        ...fill("fileHistory", seat.fileHistory),
         ...(seat.oneShot === true ? { oneShot: true } : {}),
         ...(seat.memoryPersistenceCapable === false ? { memoryPersistenceCapable: false } : fill("memoryPersistenceCapable", seat.memoryPersistenceCapable)),
         ...(seat.memoryOff === true ? { memory: memoryTurnedOff(child.memory) } : {}),

package/dist/core/park-selfcheck.js

@@ -74,6 +74,7 @@ function syntheticCheckpoint(scope) {
             preview: { probe: true, note: "park wiring self-check display stub" },
             previewWithheld: "oversize",
             requiresRealApproval: true,
+            mandated: true,
             denialLimitFallback: { consecutive: 3, total: 3, limit: "consecutive", autoDenyAfterMs: 0 },
             origin: "denial_limit_fallback",
             batchToolCallIds: [`${scope}:call`],

package/dist/core/runner/announce-once-ledger.d.ts

@@ -1,4 +1,6 @@
 import type { AnnouncedListingSnapshot, AnnouncedListingSnapshotInput, AnnouncedMcpFailure } from "../../internal/harness.js";
+import type { SessionTreeEntry } from "../../internal/harness-types.js";
+import type { DateAnchorRead } from "./contracts.js";
 import type { McpDroppedTool, McpServerStatus } from "../mcp.js";
 import type { RunnerDeps } from "../types.js";
 /** Upper bound on the advisory-digest arm kept in the record (oldest dropped past it). A digest is
@@ -96,3 +98,27 @@ export declare function loadAnnounceOnceLedger(session: AnnounceOnceSession, che
  *  present-only arms, copied; `undefined` when nothing was announced on any face (the resume seed
  *  then falls to the lower rungs — unchanged contract). */
 export declare function serializeAnnouncedListings(ref: AnnouncedListingSnapshotInput): AnnouncedListingSnapshot | undefined;
+/** The custom-entry kind that carries the session's date anchor (engine-owned; never model-visible). */
+export declare const DATE_ANCHOR_CUSTOM_TYPE = "engine:date-anchor";
+/**
+ * Read the session's date anchor off the active branch: the nearest anchor entry NEWER than the nearest
+ * compaction, honored only when it was written for that same segment. An anchor written by a leg whose
+ * prefix predates a compaction that landed in between therefore reads as absent — the one rule that makes a
+ * compaction re-anchor the date. An unreadable branch returns undefined (the leg renders today, writes nothing).
+ */
+export declare function readDateAnchor(session: {
+    getBranch(): Promise<ReadonlyArray<SessionTreeEntry>>;
+}): Promise<DateAnchorRead | undefined>;
+/**
+ * The anchor write a leg owes when it settles, or undefined: owed when prepare found no anchor for the segment
+ * (the leg rendered today) or the model has since been told a newer date; never after an unreadable branch.
+ * Best-effort — a lost write costs one re-rendered prefix or one repeated reminder next leg, never a wrong date.
+ */
+export declare function owedDateAnchor(session: {
+    appendCustomEntry(customType: string, data?: unknown): Promise<string>;
+}, seat: {
+    legDate: string;
+    anchor: DateAnchorRead | undefined;
+} | undefined, state: {
+    announcedDate: string;
+} | undefined): (() => Promise<void>) | undefined;

package/dist/core/runner/announce-once-ledger.js

@@ -112,3 +112,40 @@ export function serializeAnnouncedListings(ref) {
     };
     return Object.keys(out).length > 0 ? out : undefined;
 }
+export const DATE_ANCHOR_CUSTOM_TYPE = "engine:date-anchor";
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function normalizeDateAnchor(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const { prefixDate, announcedDate, segment } = v;
+    if (typeof prefixDate !== "string" || !ISO_DATE.test(prefixDate) || typeof announcedDate !== "string" || !ISO_DATE.test(announcedDate))
+        return undefined;
+    if (segment !== null && (typeof segment !== "string" || segment.length > 200))
+        return undefined;
+    return { prefixDate, announcedDate, segment };
+}
+export async function readDateAnchor(session) {
+    let branch;
+    try {
+        branch = await session.getBranch();
+    }
+    catch {
+        return undefined;
+    }
+    let found;
+    let i = branch.length - 1;
+    for (; i >= 0 && branch[i].type !== "compaction"; i--) {
+        const e = branch[i];
+        if (found === undefined && e.type === "custom" && e.customType === DATE_ANCHOR_CUSTOM_TYPE)
+            found = normalizeDateAnchor(e.data);
+    }
+    const segment = i >= 0 ? branch[i].id : null;
+    return { current: found !== undefined && found.segment === segment ? { prefixDate: found.prefixDate, announcedDate: found.announcedDate } : undefined, segment };
+}
+export function owedDateAnchor(session, seat, state) {
+    const read = seat?.anchor;
+    if (read === undefined || state === undefined || read.current?.announcedDate === state.announcedDate)
+        return undefined;
+    const data = { prefixDate: seat.legDate, announcedDate: state.announcedDate, segment: read.segment };
+    return () => session.appendCustomEntry(DATE_ANCHOR_CUSTOM_TYPE, data).then(() => undefined, () => undefined);
+}