@akagilnc/pi-workflow-roles 0.1.5504 → 0.1.5575

package/src/public-cli/terminal.ts

@@ -18,7 +18,7 @@ export function encodeTerminalField(value: string): string {
 }
 
 export type TerminalArtifactRef = {
-  kind: "report" | "evidence" | "error";
+  kind: "report" | "error";
   /** Openable local reference (path). Layout is private; the ref value is the contract. */
   path: string;
 };

package/src/role-run-placement.ts

@@ -17,7 +17,6 @@ export type RoleRunPlacement = {
   readonly runDirectory: string;
   readonly sessionDirectory: string;
   readonly sessionFile: string;
-  readonly artifactsDirectory: string;
   readonly attachmentsDirectory: string;
 };
 
@@ -150,16 +149,10 @@ export function roleRunPlacement(
     runDirectory,
     sessionDirectory,
     sessionFile: sessionFileIn(sessionDirectory),
-    artifactsDirectory: roleRunArtifactsDirectory(runDirectory),
     attachmentsDirectory: join(runDirectory, "attachments"),
   };
 }
 
-/** The single artifacts subpath definition for new and resumed role runs. */
-export function roleRunArtifactsDirectory(runDirectory: string): string {
-  return join(runDirectory, "artifacts");
-}
-
 /** Canonical unbound placement: a run directory under `<book>/unbound/runs/`. */
 export function isUnboundRunDirectory(runDirectory: string): boolean {
   return runDirectory.replaceAll("\\", "/").includes("/unbound/runs/");
@@ -177,10 +170,6 @@ export function ensureRoleRunPlacement(
   ledgerHome: string,
   placement: RoleRunPlacement,
 ): void {
-  for (const directory of [
-    placement.sessionDirectory,
-    placement.attachmentsDirectory,
-  ]) {
-    ensureRoleRunDirectory(ledgerHome, directory);
-  }
+  // attachments/ appears only when something is frozen into it.
+  ensureRoleRunDirectory(ledgerHome, placement.sessionDirectory);
 }

package/src/role-run-relocation.ts

@@ -6,7 +6,6 @@
  * 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";
 
@@ -16,11 +15,12 @@ import { findRoleRunDirectory, roleRunPlacement } from "./role-run-placement.ts"
 
 import { AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE } from "./compliance-transport.ts";
 
+import { readPageSync, updateSectionSync } from "./run-dossier.ts";
 import { isRecord, isEnoent } from "./unknown-value.ts";
 
 const ADMITTED_PAGE_FIELDS = [
   "runDirectory",
-  "admittedRequestPath",
+  "admittedRequestPath", // pre-#1161 pages only
   "sessionDirectory",
   "sessionFile",
   "taskPath",
@@ -39,7 +39,7 @@ const INVOCATION_PAGE_FIELDS = [
 
 const RUN_STATE_PAGE_FIELDS = [
   "runDirectory",
-  "admittedRequestPath",
+  "admittedRequestPath", // pre-#1161 pages only
   "sessionDirectory",
   "sessionFile",
 ] as const;
@@ -245,32 +245,29 @@ export function rewriteAdmittedRoleRunPage(
   }
 }
 
-async function rewriteOfficerPointerFile(
+/** Pre-#1161 `session/auditor-roles/<officer>.pointer.json` (migrator input only). */
+async function rewriteLegacyOfficerPointerFile(
   path: string,
   rewrites: readonly RunDirectoryPathRewrite[],
 ): Promise<void> {
-  if (!existsSync(path)) return;
   const page = JSON.parse(await readFile(path, "utf8")) as unknown;
-  if (!isRecord(page)) return;
-  // Only the typed direct-officer pointer shape — never arbitrary .pointer.json.
-  if (page.kind !== "direct-officer-run-pointer") return;
+  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) {
-    await writeFile(path, `${JSON.stringify(page)}\n`, "utf8");
-  }
+  rewriteRunDirectoryPathFieldsAgainstRewrites(page, OFFICER_POINTER_FIELDS, rewrites);
+  if (JSON.stringify(page) !== before) await writeFile(path, `${JSON.stringify(page)}\n`, "utf8");
 }
 
 async function rewriteSitianRecordsJsonl(
   path: string,
   rewrites: readonly RunDirectoryPathRewrite[],
 ): Promise<void> {
-  if (!existsSync(path)) return;
-  const raw = await readFile(path, "utf8");
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (isEnoent(error)) return;
+    throw error;
+  }
   if (raw.length === 0) return;
   const endsWithNewline = raw.endsWith("\n");
   const lines = raw.split("\n");
@@ -328,8 +325,13 @@ async function rewriteSessionTranscriptBindings(
   path: string,
   rewrites: readonly RunDirectoryPathRewrite[],
 ): Promise<void> {
-  if (!existsSync(path)) return;
-  const raw = await readFile(path, "utf8");
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if (isEnoent(error)) return;
+    throw error;
+  }
   if (raw.length === 0) return;
   const endsWithNewline = raw.endsWith("\n");
   const lines = raw.split("\n");
@@ -394,8 +396,8 @@ async function rewriteSessionTranscriptBindings(
 
 /**
  * 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: string,
@@ -418,7 +420,7 @@ async function rewriteNestedMachinePathPages(
       }
       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);
       } else if (entry.name.endsWith(".jsonl")) {
@@ -430,7 +432,7 @@ async function rewriteNestedMachinePathPages(
 }
 
 /**
- * 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
@@ -446,54 +448,55 @@ 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")) as Record<
-      string,
-      unknown
-    >;
-    const before = JSON.stringify(page);
-    rewriteAdmittedRoleRunPage(page, rewrites);
-    if (JSON.stringify(page) !== before) {
-      await writeFile(admittedPath, `${JSON.stringify(page, null, 2)}\n`, "utf8");
-    }
+  // One rewriter per page kind; each keeps its own field list.
+  const pageRewriters: Readonly<Record<"admitted" | "invocation" | "runState", (page: Record<string, unknown>) => void>> = {
+    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) as [keyof typeof pageRewriters, (page: Record<string, unknown>) => void][]) {
+    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 invocationPath = join(pagesDirectory, "invocation.json");
-  if (existsSync(invocationPath)) {
-    const page = JSON.parse(await readFile(invocationPath, "utf8")) as Record<string, unknown>;
-    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");
+  // 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],
+  ] as const) {
+    const path = join(pagesDirectory, file);
+    let raw: string;
+    try {
+      raw = await readFile(path, "utf8");
+    } catch (error) {
+      if (isEnoent(error)) continue;
+      throw error;
     }
-  }
-
-  const statePath = join(pagesDirectory, "run-state.json");
-  if (existsSync(statePath)) {
-    const page = JSON.parse(await readFile(statePath, "utf8")) as Record<
-      string,
-      unknown
-    >;
+    const page = JSON.parse(raw) as Record<string, unknown>;
     const before = JSON.stringify(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);
-    }
+    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");
     }
   }
 

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 {
@@ -89,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,
@@ -773,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,
@@ -838,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

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",
+]);