@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/src/role-runtime.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { readPageSync, RUN_STATE_FILE } from "./run-dossier.ts";
 import { readFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import {
@@ -12,12 +13,14 @@ import {
 
 import { Value } from "typebox/value";
 import { sitianReport } from "./sitian-facade.ts";
+import { sitianReportSafe } from "./host-session-record.ts";
 import { createSubmissionLedgerHost, sealAcceptedSubmission } from "./submission-ledger.ts";
 import { registerFiledSubmissionTool, type FiledSubmissionBeforeAccept } from "./filed-submission.ts";
 import type { RoleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 import { activationTraceRecordSchema, namedActivationCause, type ActivationTraceRecord, type ActivationTraceWriter } from "./activation-trace.ts";
 import { homeFromRunDirectory } from "./activation-ledger-topology.ts";
+import { isSafePositiveTicketNumber, parseTicketNumber } from "./run-ticket-number.ts";
 import {
   durableSessionPointer,
   resolveBookKeyFromGit,
@@ -87,7 +90,6 @@ import {
 } from "./diarist-contracts.ts";
 import { commitDiaristProjection } from "./diarist.ts";
 import { TicketProvenanceInputError } from "./ticket-provenance.ts";
-import { bindTicketNumberOnRunDirectory } from "./public-cli/invocation.ts";
 import {
   GATEKEEPER_TOOL_SPEC,
   type GatekeeperRuntimeDependencies,
@@ -207,12 +209,9 @@ function decodeReviewerAdmittedInputs(getFlag: (name: string) => unknown): Revie
     authorityRefs = Object.freeze(parsed as string[]);
   }
 
-  let ticketNumber: number | undefined;
   const rawTicketNumber = getFlag("ak-review-ticket-number");
   // Shape-invalid flag values do not abort: omit typed candidate; branch→commit→degrade continues.
-  if (typeof rawTicketNumber === "string" && /^[1-9]\d*$/.test(rawTicketNumber)) {
-    ticketNumber = Number(rawTicketNumber);
-  }
+  const ticketNumber = parseTicketNumber(rawTicketNumber);
 
   const baseRevision = getFlag("ak-review-base");
   if (typeof baseRevision !== "string" || !baseRevision.trim()) {
@@ -760,15 +759,8 @@ function readDiaristTicketAssertion(
   }
   const raw = submitted.ticketNumber;
   if (raw === null) return { kind: "true-unbound" };
-  if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1) {
-    return { kind: "ticket", ticketNumber: raw };
-  }
-  if (typeof raw === "string" && /^[1-9]\d*$/.test(raw)) {
-    const n = Number(raw);
-    if (Number.isSafeInteger(n) && n >= 1) {
-      return { kind: "ticket", ticketNumber: n };
-    }
-  }
+  const ticketNumber = parseTicketNumber(raw);
+  if (ticketNumber !== undefined) return { kind: "ticket", ticketNumber };
   return { kind: "invalid" };
 }
 
@@ -781,10 +773,9 @@ function readRoleRunCoordinates(ctx: HostContext, label: string): {
 } {
   const runDirectory = runDirectoryFromHostContext(ctx);
   if (runDirectory === undefined) throw new Error(`${label} requires AK_ROLE_RUN_DIR`);
-  const admittedPath = join(runDirectory, "admitted-request.json");
-  const admitted = JSON.parse(readFileSync(admittedPath, "utf8")) as Record<string, unknown>;
-  if (typeof admitted.projectRoot !== "string" || admitted.projectRoot.trim() === "") {
-    throw new Error(`${label} admitted-request missing projectRoot (${admittedPath})`);
+  const admitted = readPageSync(runDirectory, "admitted");
+  if (typeof admitted?.projectRoot !== "string" || admitted.projectRoot.trim() === "") {
+    throw new Error(`${label} state.jsonl admitted-request row missing projectRoot (${join(runDirectory, RUN_STATE_FILE)})`);
   }
   return {
     runDirectory,
@@ -802,12 +793,9 @@ function readDiaristRunCoordinates(ctx: HostContext): {
   readonly boundTicketNumber?: number;
 } {
   const coordinates = readRoleRunCoordinates(ctx, "diarist accept");
-  const bound =
-    typeof coordinates.admitted.ticketNumber === "number" &&
-    Number.isSafeInteger(coordinates.admitted.ticketNumber) &&
-    coordinates.admitted.ticketNumber >= 1
-      ? coordinates.admitted.ticketNumber
-      : undefined;
+  const bound = isSafePositiveTicketNumber(coordinates.admitted.ticketNumber)
+    ? coordinates.admitted.ticketNumber
+    : undefined;
   return {
     runDirectory: coordinates.runDirectory,
     projectRoot: coordinates.projectRoot,
@@ -849,11 +837,8 @@ export function createDiaristRoleRuntime(
         const coords = readDiaristRunCoordinates(ctx);
         // #836 7.3: pre-bound ticket is material for the LLM, not an override.
         const ticketNumber = assertion.kind === "ticket" ? assertion.ticketNumber : undefined;
-        if (ticketNumber !== undefined) {
-          if (coords.boundTicketNumber === undefined) {
-            await bindTicketNumberOnRunDirectory(coords.runDirectory, ticketNumber);
-          }
-        }
+        // The ticket binds in the public call's own process after the turn, from the sealed
+        // ticketNumber (settlement seam); this leg never writes the run's current.json.
         // Strict-schema hosts emit ticketSessions: null for a single ticket.
         const multiTicket = submitted?.ticketSessions != null;
         const singleSessions = submitted && !multiTicket
@@ -1344,16 +1329,14 @@ export function createRoleRuntimeExtension(
               attemptPointer: receiptAttemptPointer(runPointer, ctx.invocationScopeId),
             });
             envelopeHost.appendEntry(NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, facts);
-            try {
-              sitianReport({
-                level: "event",
-                kind: "no-receipt-lifecycle",
-                cwd: ctx.cwd,
-                sessionParent: ctx.sessionManager.getSessionFile(),
-                payload: facts,
-                source: "role-runtime",
-              });
-            } catch {}
+            sitianReportSafe({
+              level: "event",
+              kind: "no-receipt-lifecycle",
+              cwd: ctx.cwd,
+              sessionParent: ctx.sessionManager.getSessionFile(),
+              payload: facts,
+              source: "role-runtime",
+            });
           }
         }
         return;
@@ -1367,16 +1350,14 @@ export function createRoleRuntimeExtension(
           RECEIPT_DELIVERY_REQUEST_ENTRY,
           scopeId.length > 0 ? { invocationScopeId: scopeId } : undefined,
         );
-        try {
-          sitianReport({
-            level: "event",
-            kind: "receipt-delivery",
-            cwd: ctx.cwd,
-            sessionParent: ctx.sessionManager.getSessionFile(),
-            payload: { type: "ak-receipt-delivery-request" },
-            source: "role-runtime",
-          });
-        } catch {}
+        sitianReportSafe({
+          level: "event",
+          kind: "receipt-delivery",
+          cwd: ctx.cwd,
+          sessionParent: ctx.sessionManager.getSessionFile(),
+          payload: { type: "ak-receipt-delivery-request" },
+          source: "role-runtime",
+        });
         envelopeHost.sendMessage({
           customType: "ak-receipt-delivery-prompt",
           content: JSON.stringify(receiptDelivery.deliveryState()),
@@ -1391,16 +1372,14 @@ export function createRoleRuntimeExtension(
             attemptPointer: receiptAttemptPointer(runPointer, ctx.invocationScopeId),
           });
           envelopeHost.appendEntry(NO_RECEIPT_LIFECYCLE_ENTRY_TYPE, facts);
-          try {
-            sitianReport({
-              level: "event",
-              kind: "no-receipt-lifecycle",
-              cwd: ctx.cwd,
-              sessionParent: ctx.sessionManager.getSessionFile(),
-              payload: facts,
-              source: "role-runtime",
-            });
-          } catch {}
+          sitianReportSafe({
+            level: "event",
+            kind: "no-receipt-lifecycle",
+            cwd: ctx.cwd,
+            sessionParent: ctx.sessionManager.getSessionFile(),
+            payload: facts,
+            source: "role-runtime",
+          });
         }
       }
     });
@@ -1765,16 +1744,14 @@ export function createRoleRuntimeExtension(
               subjectKey: work.subjectKey,
             };
             envelopeHost.appendEntry(NAVIGATOR_INVOCATION_ENTRY, data);
-            try {
-              sitianReport({
-                level: "event",
-                kind: "attendance",
-                cwd: ctx.cwd,
-                sessionParent: ctx.sessionManager.getSessionFile(),
-                payload: { type: NAVIGATOR_INVOCATION_ENTRY, ...data },
-                source: "role-runtime",
-              });
-            } catch {}
+            sitianReportSafe({
+              level: "event",
+              kind: "attendance",
+              cwd: ctx.cwd,
+              sessionParent: ctx.sessionManager.getSessionFile(),
+              payload: { type: NAVIGATOR_INVOCATION_ENTRY, ...data },
+              source: "role-runtime",
+            });
           }
           const activation = navigatorActivation;
           navigatorAttendance = await dependencies.createNavigatorAttendance({

package/src/run-dossier-files.ts

@@ -0,0 +1,33 @@
+/**
+ * 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" as const;
+export const RUN_HISTORY_FILE = "history.jsonl" as const;
+export const RUN_LOG_FILE = "log.jsonl" as const;
+export const RUN_STATE_FILE = "state.jsonl" as const;
+
+/**
+ * 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: ReadonlySet<string> = 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" as const;
+
+/**
+ * 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: ReadonlySet<string> = new Set([
+  "invocation", "admitted-request", "run-state", "terminal", "host-session-id",
+]);

package/src/run-dossier.ts

@@ -0,0 +1,357 @@
+/**
+ * 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.ts";
+import { RUN_CURRENT_FILE, RUN_HISTORY_FILE, RUN_LOG_FILE, RUN_STATE_FILE, OFFICER_POINTER_RECORD_KIND } from "./run-dossier-files.ts";
+import { appendSitianRecord } from "./sitian-appender.ts";
+import { parseSitianRecordText } from "./sitian-reader.ts";
+import { isMissingPathError, isRecord } from "./unknown-value.ts";
+
+export { RUN_CURRENT_FILE, RUN_HISTORY_FILE, RUN_LOG_FILE, RUN_STATE_FILE };
+
+/** Sections of `current.json` that are a whole page appended as one row. */
+export type CurrentSection = "invocation" | "admitted" | "runState" | "terminal";
+/** Sections rendered from rows other seams append. */
+export type DerivedSection = "host" | "submission" | "officers";
+
+/** The row kind of each whole-page section: the name of the file it replaced. */
+const PAGE_ROW_KIND: Readonly<Record<CurrentSection, string>> = {
+  invocation: "invocation",
+  admitted: "admitted-request",
+  runState: "run-state",
+  terminal: "terminal",
+};
+
+export function runCurrentPath(runDirectory: string): string {
+  return join(runDirectory, RUN_CURRENT_FILE);
+}
+
+/** The whole `current.json`, or undefined when absent (ENOENT only). */
+export function readCurrentSync(runDirectory: string): Record<string, unknown> | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(runCurrentPath(runDirectory), "utf8");
+  } catch (error) {
+    if (isMissingPathError(error)) return undefined;
+    throw error;
+  }
+  const parsed: unknown = 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: string,
+  section: CurrentSection | DerivedSection,
+): Record<string, unknown> | undefined {
+  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;
+}
+
+type RowFile = {
+  readonly rows: Record<string, unknown>[];
+  /** Physical on-disk byte length of this read — never a re-encoded string length. */
+  readonly bytes: number;
+  /** The error code of a read that failed for a reason other than the file being absent. */
+  readonly fault?: string;
+  /** Canonical malformed-line diagnostics from the sole Sitian decoder. */
+  readonly diagnostics?: readonly { readonly line: number; readonly error: string }[];
+};
+
+/**
+ * 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: string): RowFile {
+  let buffer: Buffer;
+  try {
+    buffer = readFileSync(path);
+  } catch (error) {
+    if (isMissingPathError(error)) return { rows: [], bytes: 0 };
+    return { rows: [], bytes: 0, fault: String((error as NodeJS.ErrnoException).code ?? (error as Error).name) };
+  }
+  const { records, diagnostics } = parseSitianRecordText(buffer.toString("utf8"));
+  return {
+    rows: [...records] as Record<string, unknown>[],
+    bytes: buffer.length,
+    ...(diagnostics.length > 0
+      ? { diagnostics: diagnostics.map((d) => ({ line: d.line, error: d.error })) }
+      : {}),
+  };
+}
+
+function fileBytes(path: string): number | undefined {
+  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: readonly Record<string, unknown>[], kind: string): unknown {
+  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: readonly Record<string, unknown>[],
+  kind: string,
+  runDirectory: string,
+): Record<string, unknown> | undefined {
+  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: readonly { readonly kind?: unknown; readonly payload?: unknown }[],
+): Readonly<Record<string, unknown>> {
+  const latest: Record<string, unknown> = {};
+  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: string,
+  history: readonly Record<string, unknown>[],
+  state: readonly Record<string, unknown>[],
+  log: readonly Record<string, unknown>[],
+  unreadable: Record<string, string>,
+): Record<string, unknown> {
+  const whole: Record<string, unknown> = {};
+  for (const section of ["invocation", "admitted", "runState", "terminal"] as const) {
+    const page = lastPayloadOfKind(state, PAGE_ROW_KIND[section]);
+    if (page !== undefined) whole[section] = page;
+  }
+  let latest: Record<string, unknown> | undefined;
+  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: Readonly<Record<string, unknown>> = {};
+  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: Record<string, unknown> = {};
+  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: unknown;
+  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: string, whole: Record<string, unknown>): void {
+  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 as NodeJS.ErrnoException).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<string, string>();
+
+/**
+ * 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: string): void {
+  const paths = [RUN_HISTORY_FILE, RUN_STATE_FILE, RUN_LOG_FILE].map((name) => join(runDirectory, name));
+  for (;;) {
+    const [history, state, log] = paths.map(readRowFile) as [RowFile, RowFile, RowFile];
+    const unreadable: Record<string, string> = {};
+    for (const [name, file] of [[RUN_HISTORY_FILE, history], [RUN_STATE_FILE, state], [RUN_LOG_FILE, log]] as const) {
+      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: string, section: CurrentSection, page: Record<string, unknown>): void {
+  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: string, section: CurrentSection): Record<string, unknown> | undefined {
+  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: string): readonly Record<string, unknown>[] {
+  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: string): readonly Record<string, unknown>[] {
+  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: string,
+  section: CurrentSection,
+  value: Record<string, unknown>,
+): void {
+  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: string,
+  section: CurrentSection,
+  update: (current: Record<string, unknown>) => Record<string, unknown> | undefined,
+): void {
+  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);
+}