@akagilnc/pi-workflow-roles 0.1.5504 → 0.1.5575

package/dist/role-run-relocation.js

@@ -6,17 +6,17 @@
  * frozen attachment/artifact bytes. Nested walk is confined to package-owned
  * `session/` seams.
  */
-import { existsSync } from "node:fs";
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, sep } from "node:path";
 import { activationBookDirectory, physicalPathIdentity } from "./activation-ledger-topology.js";
 import { readRoleRunIdentity } from "./public-cli/run-lifecycle.js";
 import { findRoleRunDirectory, roleRunPlacement } from "./role-run-placement.js";
 import { AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE } from "./compliance-transport.js";
+import { readPageSync, updateSectionSync } from "./run-dossier.js";
 import { isRecord, isEnoent } from "./unknown-value.js";
 const ADMITTED_PAGE_FIELDS = [
     "runDirectory",
-    "admittedRequestPath",
+    "admittedRequestPath", // pre-#1161 pages only
     "sessionDirectory",
     "sessionFile",
     "taskPath",
@@ -33,7 +33,7 @@ const INVOCATION_PAGE_FIELDS = [
 ];
 const RUN_STATE_PAGE_FIELDS = [
     "runDirectory",
-    "admittedRequestPath",
+    "admittedRequestPath", // pre-#1161 pages only
     "sessionDirectory",
     "sessionFile",
 ];
@@ -176,25 +176,26 @@ export function rewriteAdmittedRoleRunPage(page, rewrites) {
         rewriteRunDirectoryPathFieldsAgainstRewrites(page.principal, ["sessionDirectory", "sessionFile"], rewrites);
     }
 }
-async function rewriteOfficerPointerFile(path, rewrites) {
-    if (!existsSync(path))
-        return;
+/** Pre-#1161 `session/auditor-roles/<officer>.pointer.json` (migrator input only). */
+async function rewriteLegacyOfficerPointerFile(path, rewrites) {
     const page = JSON.parse(await readFile(path, "utf8"));
-    if (!isRecord(page))
-        return;
-    // Only the typed direct-officer pointer shape — never arbitrary .pointer.json.
-    if (page.kind !== "direct-officer-run-pointer")
+    if (!isRecord(page) || page.kind !== "direct-officer-run-pointer")
         return;
     const before = JSON.stringify(page);
     rewriteRunDirectoryPathFieldsAgainstRewrites(page, OFFICER_POINTER_FIELDS, rewrites);
-    if (JSON.stringify(page) !== before) {
+    if (JSON.stringify(page) !== before)
         await writeFile(path, `${JSON.stringify(page)}\n`, "utf8");
-    }
 }
 async function rewriteSitianRecordsJsonl(path, rewrites) {
-    if (!existsSync(path))
-        return;
-    const raw = await readFile(path, "utf8");
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return;
+        throw error;
+    }
     if (raw.length === 0)
         return;
     const endsWithNewline = raw.endsWith("\n");
@@ -244,9 +245,15 @@ async function rewriteSitianRecordsJsonl(path, rewrites) {
  * ak_auditor_parent_attempt_binding data.parent.sessionFile. Never message text.
  */
 async function rewriteSessionTranscriptBindings(path, rewrites) {
-    if (!existsSync(path))
-        return;
-    const raw = await readFile(path, "utf8");
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return;
+        throw error;
+    }
     if (raw.length === 0)
         return;
     const endsWithNewline = raw.endsWith("\n");
@@ -303,8 +310,8 @@ async function rewriteSessionTranscriptBindings(path, rewrites) {
 }
 /**
  * Package-owned nested seams under session/ only:
- * direct-officer *.pointer.json, sitian records.jsonl,
- * session transcript typed parent bindings. Never walks attachments/ or artifacts/.
+ * sitian records.jsonl,
+ * session transcript typed parent bindings. Never walks attachments/.
  */
 async function rewriteNestedMachinePathPages(pagesDirectory, rewrites) {
     const sessionRoot = join(pagesDirectory, "session");
@@ -327,7 +334,7 @@ async function rewriteNestedMachinePathPages(pagesDirectory, rewrites) {
             if (!entry.isFile())
                 continue;
             if (entry.name.endsWith(".pointer.json")) {
-                await rewriteOfficerPointerFile(path, rewrites);
+                await rewriteLegacyOfficerPointerFile(path, rewrites);
             }
             else if (entry.name === "records.jsonl") {
                 await rewriteSitianRecordsJsonl(path, rewrites);
@@ -340,7 +347,7 @@ async function rewriteNestedMachinePathPages(pagesDirectory, rewrites) {
     await walk(sessionRoot);
 }
 /**
- * Rewrite admitted-request / invocation / run-state path fields (attachment
+ * Rewrite the admitted / invocation / runState fact rows (path fields: attachment
  * frozenPath / summons.attachmentPaths pointers only), then nested package-owned
  * session seams. Callers may rewrite before or after the filesystem move/copy:
  * `pagesDirectory` is where the pages currently live on disk; path strings that
@@ -350,38 +357,53 @@ async function rewriteNestedMachinePathPages(pagesDirectory, rewrites) {
 export async function rewriteRoleRunDurablePages(input) {
     const { pagesDirectory } = input;
     const rewrites = collectRewrites(input);
-    const admittedPath = join(pagesDirectory, "admitted-request.json");
-    if (existsSync(admittedPath)) {
-        const page = JSON.parse(await readFile(admittedPath, "utf8"));
-        const before = JSON.stringify(page);
-        rewriteAdmittedRoleRunPage(page, rewrites);
-        if (JSON.stringify(page) !== before) {
-            await writeFile(admittedPath, `${JSON.stringify(page, null, 2)}\n`, "utf8");
-        }
-    }
-    const invocationPath = join(pagesDirectory, "invocation.json");
-    if (existsSync(invocationPath)) {
-        const page = JSON.parse(await readFile(invocationPath, "utf8"));
-        const before = JSON.stringify(page);
-        rewriteRunDirectoryPathFieldsAgainstRewrites(page, INVOCATION_PAGE_FIELDS, rewrites);
-        if (JSON.stringify(page) !== before) {
-            await writeFile(invocationPath, `${JSON.stringify(page, null, 2)}\n`, "utf8");
-        }
+    // One rewriter per page kind; each keeps its own field list.
+    const pageRewriters = {
+        admitted: (page) => rewriteAdmittedRoleRunPage(page, rewrites),
+        invocation: (page) => rewriteRunDirectoryPathFieldsAgainstRewrites(page, INVOCATION_PAGE_FIELDS, rewrites),
+        runState: (page) => {
+            rewriteRunDirectoryPathFieldsAgainstRewrites(page, RUN_STATE_PAGE_FIELDS, rewrites);
+            if (isRecord(page.principal)) {
+                rewriteRunDirectoryPathFieldsAgainstRewrites(page.principal, ["sessionDirectory", "sessionFile"], rewrites);
+            }
+            // Open court summons: source-run locators + frozen attachment path pointers.
+            if (isRecord(page.currentCourt)) {
+                rewriteSummonsMaterials(page.currentCourt.summons, rewrites);
+            }
+        },
+    };
+    // A page is rewritten only when its fact row exists — never gate on the rendering.
+    for (const [section, rewrite] of Object.entries(pageRewriters)) {
+        if (readPageSync(pagesDirectory, section) === undefined)
+            continue;
+        updateSectionSync(pagesDirectory, section, (current) => {
+            const page = structuredClone(current);
+            rewrite(page);
+            return JSON.stringify(page) === JSON.stringify(current) ? undefined : page;
+        });
     }
-    const statePath = join(pagesDirectory, "run-state.json");
-    if (existsSync(statePath)) {
-        const page = JSON.parse(await readFile(statePath, "utf8"));
-        const before = JSON.stringify(page);
-        rewriteRunDirectoryPathFieldsAgainstRewrites(page, RUN_STATE_PAGE_FIELDS, rewrites);
-        if (isRecord(page.principal)) {
-            rewriteRunDirectoryPathFieldsAgainstRewrites(page.principal, ["sessionDirectory", "sessionFile"], rewrites);
+    // Runs from before #1161 (the one-shot book-topology migrator's input) keep these
+    // as separate page files; the same rewriters apply. Nothing live writes them.
+    for (const [file, rewrite] of [
+        ["admitted-request.json", pageRewriters.admitted],
+        ["invocation.json", pageRewriters.invocation],
+        ["run-state.json", pageRewriters.runState],
+    ]) {
+        const path = join(pagesDirectory, file);
+        let raw;
+        try {
+            raw = await readFile(path, "utf8");
         }
-        // Open court summons: source-run locators + frozen attachment path pointers.
-        if (isRecord(page.currentCourt)) {
-            rewriteSummonsMaterials(page.currentCourt.summons, rewrites);
+        catch (error) {
+            if (isEnoent(error))
+                continue;
+            throw error;
         }
+        const page = JSON.parse(raw);
+        const before = JSON.stringify(page);
+        rewrite(page);
         if (JSON.stringify(page) !== before) {
-            await writeFile(statePath, `${JSON.stringify(page, null, 2)}\n`, "utf8");
+            await writeFile(path, `${JSON.stringify(page, null, 2)}\n`, "utf8");
         }
     }
     await rewriteNestedMachinePathPages(pagesDirectory, rewrites);

package/dist/run-dossier-files.js

@@ -0,0 +1,30 @@
+/**
+ * Names in a run directory (docs/dossier-topology.md, #1161). Constants only, so
+ * the appender and the `current.json` renderer can both import them.
+ */
+export const RUN_CURRENT_FILE = "current.json";
+export const RUN_HISTORY_FILE = "history.jsonl";
+export const RUN_LOG_FILE = "log.jsonl";
+export const RUN_STATE_FILE = "state.jsonl";
+/**
+ * Record kinds that make a leg's history: they land in `history.jsonl`. The
+ * original submission ledger and attempt history, the prompt/schema each turn was
+ * started with, and officer pointers.
+ */
+export const RUN_HISTORY_KINDS = new Set([
+    "candidate", "roundContext", "outcome", "sealed", "post-seal-anomaly",
+    "attempt-history", "turn-delivery", "officer-pointer",
+]);
+/** History record kind of a booked officer pointer (appender routes it to history.jsonl). */
+export const OFFICER_POINTER_RECORD_KIND = "officer-pointer";
+/**
+ * The facts a run cannot go on without land in `state.jsonl`: the four whole pages only the
+ * public call knows, and the native session id a host binds (a resume needs it). A
+ * different volume than the submission ledger and than the auxiliary stream, as the
+ * files they replaced were (a page write failure throws; a ledger volume that cannot
+ * be written does not stop a resume; a stream line that cannot be written is noted).
+ * Every other kind lands in `log.jsonl`.
+ */
+export const RUN_STATE_KINDS = new Set([
+    "invocation", "admitted-request", "run-state", "terminal", "host-session-id",
+]);

package/dist/run-dossier.js

@@ -0,0 +1,322 @@
+/**
+ * The per-leg dossier files (docs/dossier-topology.md, #1161): `current.json`,
+ * `history.jsonl` (the submission ledger and attempt history), `state.jsonl` (the four
+ * whole pages) and `log.jsonl` (the rest), all append-only and written through the sitian appender, and the one host original.
+ *
+ * Facts are rows first. The four pages only the public call knows — identity
+ * (`invocation`), admission (`admitted-request`), lifecycle (`run-state`) and the
+ * terminal — are each rewritten whole by appending one `state.jsonl` row whose
+ * payload is that page. `current.json` is a rendering: the last row of each kind
+ * in the three row files, read at the moment of writing, never a value
+ * carried from an earlier snapshot or from the previous `current.json`.
+ *
+ * Two public calls may exist on one leg (the live leg and a manual resume) and
+ * both write `current.json`; there is no lock. After writing, a writer checks that
+ * the row files are still the size it rendered from and, if rows were appended
+ * meanwhile, renders again — so whichever writer finishes last has rendered from
+ * every row, and the file ends equal to a fresh rendering.
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { sessionFileOf } from "./role-run-placement.js";
+import { RUN_CURRENT_FILE, RUN_HISTORY_FILE, RUN_LOG_FILE, RUN_STATE_FILE, OFFICER_POINTER_RECORD_KIND } from "./run-dossier-files.js";
+import { appendSitianRecord } from "./sitian-appender.js";
+import { parseSitianRecordText } from "./sitian-reader.js";
+import { isMissingPathError, isRecord } from "./unknown-value.js";
+export { RUN_CURRENT_FILE, RUN_HISTORY_FILE, RUN_LOG_FILE, RUN_STATE_FILE };
+/** The row kind of each whole-page section: the name of the file it replaced. */
+const PAGE_ROW_KIND = {
+    invocation: "invocation",
+    admitted: "admitted-request",
+    runState: "run-state",
+    terminal: "terminal",
+};
+export function runCurrentPath(runDirectory) {
+    return join(runDirectory, RUN_CURRENT_FILE);
+}
+/** The whole `current.json`, or undefined when absent (ENOENT only). */
+export function readCurrentSync(runDirectory) {
+    let raw;
+    try {
+        raw = readFileSync(runCurrentPath(runDirectory), "utf8");
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return undefined;
+        throw error;
+    }
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed))
+        throw new TypeError(`${RUN_CURRENT_FILE} is not an object: ${runCurrentPath(runDirectory)}`);
+    return parsed;
+}
+/** One section of `current.json` (the rendering); undefined when the file or the section is absent. */
+export function readSectionSync(runDirectory, section) {
+    const value = readCurrentSync(runDirectory)?.[section];
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value)) {
+        throw new TypeError(`${RUN_CURRENT_FILE} ${section} section is not an object: ${runCurrentPath(runDirectory)}`);
+    }
+    return value;
+}
+/**
+ * The rows of one run file as of this read, with the physical byte length they came from.
+ * Missing file → empty. IO fault → no rows + fault code. Damaged lines keep the sole
+ * Sitian decoder's diagnostics and do not invent a second skip parser.
+ */
+function readRowFile(path) {
+    let buffer;
+    try {
+        buffer = readFileSync(path);
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return { rows: [], bytes: 0 };
+        return { rows: [], bytes: 0, fault: String(error.code ?? error.name) };
+    }
+    const { records, diagnostics } = parseSitianRecordText(buffer.toString("utf8"));
+    return {
+        rows: [...records],
+        bytes: buffer.length,
+        ...(diagnostics.length > 0
+            ? { diagnostics: diagnostics.map((d) => ({ line: d.line, error: d.error })) }
+            : {}),
+    };
+}
+function fileBytes(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch (error) {
+        return isMissingPathError(error) ? 0 : undefined;
+    }
+}
+/**
+ * Payload of the last row of `kind`, or undefined when no such row exists.
+ * Non-object payloads are returned as-is: a later illegal whole page must not
+ * be washed into an older valid page or into absence.
+ */
+function lastPayloadOfKind(rows, kind) {
+    for (let index = rows.length - 1; index >= 0; index -= 1) {
+        const row = rows[index];
+        if (row.kind === kind)
+            return row.payload;
+    }
+    return undefined;
+}
+/** Last whole-page payload as an object, or undefined when absent; illegal values throw. */
+function lastPagePayload(rows, kind, runDirectory) {
+    const payload = lastPayloadOfKind(rows, kind);
+    if (payload === undefined)
+        return undefined;
+    if (!isRecord(payload)) {
+        throw new TypeError(`${RUN_STATE_FILE} ${kind} payload is not an object: ${runDirectory}`);
+    }
+    return payload;
+}
+/**
+ * Latest officer-pointer payload per officer from already-decoded history rows.
+ * Sole reducer for the "last booking wins per officer" rule (#753 / #1161 officers).
+ * A booked officer-pointer row with a non-object payload or non-string officer is
+ * damaged topology — never silently omitted into lawful zero rounds (#1161 O1).
+ * Absence of any officer-pointer row remains lawful empty.
+ * Invalid input is a TypeError (same class as other dossier illegal payloads).
+ * Control readers (`readBookedOfficerPointers`) let this throw into the existing
+ * auditor-roles unreadable seam; `render` catches only that TypeError and marks
+ * `history.jsonl` unreadable so other reachable facts stay in current.json.
+ */
+export function latestOfficerPointersFromRecords(records) {
+    const latest = {};
+    for (const record of records) {
+        if (record.kind !== OFFICER_POINTER_RECORD_KIND)
+            continue;
+        if (!isRecord(record.payload) || typeof record.payload.officer !== "string") {
+            throw new TypeError("officer-pointer payload is not a record with string officer");
+        }
+        latest[record.payload.officer] = record.payload;
+    }
+    return latest;
+}
+/** `current.json` as the rows say right now. */
+function render(runDirectory, history, state, log, unreadable) {
+    const whole = {};
+    for (const section of ["invocation", "admitted", "runState", "terminal"]) {
+        const page = lastPayloadOfKind(state, PAGE_ROW_KIND[section]);
+        if (page !== undefined)
+            whole[section] = page;
+    }
+    let latest;
+    for (const row of history) {
+        const payload = isRecord(row.payload) ? row.payload : undefined;
+        if (row.kind === "sealed" && payload !== undefined) {
+            latest = { toolCallId: payload.toolCallId, role: payload.role, accepted: payload.accepted, at: row.timestamp };
+        }
+    }
+    // Control readers still fail closed via latestOfficerPointersFromRecords.
+    // Render must keep other reachable facts and surface damage on the existing
+    // file unreadable seam — never abort the whole current.json (#1161 O1).
+    // Catch only the reducer's known TypeError; unknown throws stay unknown
+    // (never wash into malformed by free-text message).
+    let officers = {};
+    try {
+        officers = latestOfficerPointersFromRecords(history);
+    }
+    catch (error) {
+        if (!(error instanceof TypeError))
+            throw error;
+        if (unreadable[RUN_HISTORY_FILE] === undefined)
+            unreadable[RUN_HISTORY_FILE] = "malformed";
+    }
+    const sessions = {};
+    for (const row of state) {
+        const payload = isRecord(row.payload) ? row.payload : undefined;
+        if (row.kind === "host-session-id" && payload !== undefined && typeof payload.host === "string") {
+            sessions[payload.host] = payload.sessionId;
+        }
+    }
+    let original;
+    for (const row of log) {
+        const payload = isRecord(row.payload) ? row.payload : undefined;
+        if (row.kind === "host-session" && payload?.type === "native-session-copy" && typeof payload.landingPath === "string") {
+            original = payload.landingPath;
+        }
+    }
+    // The copy row keeps the absolute path it was written to; a run that was filed under its ticket
+    // since lives elsewhere. The original is projected from where this run directory is now.
+    if (typeof original === "string")
+        original = join(runDirectory, "session", basename(original));
+    whole.host = { sessions, ...(original === undefined ? {} : { original }) };
+    whole.submission = latest === undefined ? {} : { latest };
+    whole.officers = officers;
+    if (Object.keys(unreadable).length > 0)
+        whole.unreadable = unreadable;
+    return whole;
+}
+function writeWhole(runDirectory, whole) {
+    const destination = runCurrentPath(runDirectory);
+    const body = `${JSON.stringify(whole, null, 2)}\n`;
+    // Same-directory temp + rename: a concurrent reader (the analyst scans live
+    // runs) never sees a torn file. A run directory that cannot take a new entry
+    // (settlement after a chmod) still accepts an in-place overwrite of the
+    // writable file, so that case degrades instead of failing.
+    const temporary = join(runDirectory, `.${RUN_CURRENT_FILE}-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, body, "utf8");
+        renameSync(temporary, destination);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        const code = error.code;
+        if (code !== "EACCES" && code !== "EPERM" && code !== "EROFS")
+            throw error;
+        writeFileSync(destination, body, "utf8");
+    }
+}
+/**
+ * Process-local once-declare for unreadable row files (Node.js emitWarning
+ * "Avoiding duplicate warnings": once per process, not keyed off the durable
+ * rendering). Key = runDirectory + file name; value = last declared code.
+ */
+const declaredUnreadable = new Map();
+/**
+ * Write `current.json` from the rows as read now; then, if a row file grew since that read,
+ * render again. The last appender renders after its own append, so the loop ends when the
+ * appends stop. A row file that cannot be read is rendered as having no rows and named in
+ * the rendering's `unreadable` marker (file to error code), so a stale or partial rendering
+ * is never silent. Declaration does not read the previous rendering: a damaged
+ * `current.json` must not block fact append, re-render, or public resume.
+ */
+export function renderCurrentSync(runDirectory) {
+    const paths = [RUN_HISTORY_FILE, RUN_STATE_FILE, RUN_LOG_FILE].map((name) => join(runDirectory, name));
+    for (;;) {
+        const [history, state, log] = paths.map(readRowFile);
+        const unreadable = {};
+        for (const [name, file] of [[RUN_HISTORY_FILE, history], [RUN_STATE_FILE, state], [RUN_LOG_FILE, log]]) {
+            if (file.fault !== undefined)
+                unreadable[name] = file.fault;
+            else if (file.diagnostics !== undefined && file.diagnostics.length > 0)
+                unreadable[name] = "malformed";
+        }
+        // Render may add officer-pointer TypeError damage onto the same unreadable map;
+        // declare after render so that cause enters the existing diagnostics/unreadable seam.
+        const whole = render(runDirectory, history.rows, state.rows, log.rows, unreadable);
+        for (const [name, code] of Object.entries(unreadable)) {
+            const key = `${runDirectory}\0${name}`;
+            if (declaredUnreadable.get(key) === code)
+                continue;
+            const detail = code === "malformed"
+                ? `${name} has malformed row(s); current.json keeps reachable rows and retains the diagnostic`
+                : `${name} cannot be read (${code}); current.json is rendered without it`;
+            process.stderr.write(`[run-dossier] ${detail}: ${runDirectory}\n`);
+            declaredUnreadable.set(key, code);
+        }
+        writeWhole(runDirectory, whole);
+        // Growth uses physical bytes; a malformed diagnostic must not skip the check.
+        const grew = [history, state, log].some((file, index) => file.fault === undefined && fileBytes(paths[index]) !== file.bytes);
+        if (!grew)
+            return;
+    }
+}
+function appendPageRow(runDirectory, section, page) {
+    appendSitianRecord({
+        level: "event",
+        kind: PAGE_ROW_KIND[section],
+        sessionParent: sessionFileOf(runDirectory),
+        source: "run-dossier",
+        payload: page,
+    });
+}
+/**
+ * The fact itself: a whole-page section as its last row says. The public call
+ * reads its own facts here, not from the rendering, so a rendering that is stale
+ * or refused changes nothing. Absence of a row is absence — never a `current.json`
+ * fallback. A row file that cannot be read fails closed. An illegal (non-object)
+ * latest payload keeps its failure identity; it is not filtered into absence.
+ */
+export function readPageSync(runDirectory, section) {
+    const state = readRowFile(join(runDirectory, RUN_STATE_FILE));
+    if (state.fault !== undefined)
+        throw new Error(`${RUN_STATE_FILE} is unreadable (${state.fault}): ${runDirectory}`);
+    // Control plane fails closed on damaged rows: reachable older pages must not
+    // silently drive lifecycle (#1161 C3). Rendering still keeps reachable facts.
+    if (state.diagnostics !== undefined && state.diagnostics.length > 0) {
+        throw new Error(`${RUN_STATE_FILE} has malformed row(s); refusing stale control-plane page: ${runDirectory}`);
+    }
+    return lastPagePayload(state.rows, PAGE_ROW_KIND[section], runDirectory);
+}
+/** Every row of history.jsonl, in order; a file that cannot be read throws. */
+export function readHistoryRowsSync(runDirectory) {
+    const history = readRowFile(join(runDirectory, RUN_HISTORY_FILE));
+    if (history.fault !== undefined)
+        throw new Error(`${RUN_HISTORY_FILE} is unreadable (${history.fault}): ${runDirectory}`);
+    return history.rows;
+}
+/** Every row of state.jsonl, in order; a file that cannot be read throws. */
+export function readStateRowsSync(runDirectory) {
+    const state = readRowFile(join(runDirectory, RUN_STATE_FILE));
+    if (state.fault !== undefined)
+        throw new Error(`${RUN_STATE_FILE} is unreadable (${state.fault}): ${runDirectory}`);
+    return state.rows;
+}
+/** Rewrite one section whole: append its row, then render `current.json`. */
+export function writeSectionSync(runDirectory, section, value) {
+    appendPageRow(runDirectory, section, value);
+    renderCurrentSync(runDirectory);
+}
+/**
+ * Let the caller keep its field rules for one existing section: the update
+ * receives the last row's page. `undefined` means no change. A missing section
+ * is an error: admission writes it first.
+ */
+export function updateSectionSync(runDirectory, section, update) {
+    const current = readPageSync(runDirectory, section);
+    if (current === undefined) {
+        throw new Error(`${RUN_STATE_FILE} has no ${PAGE_ROW_KIND[section]} row: ${runDirectory}`);
+    }
+    const next = update(current);
+    if (next === undefined)
+        return;
+    writeSectionSync(runDirectory, section, next);
+}