@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/dist/public-cli/terminal.js

@@ -85,18 +85,6 @@ export function formatTerminalResult(result) {
     for (const artifact of result.artifacts) {
         lines.push(`artifact\t${artifact.kind}\t${encodeTerminalField(artifact.path)}`);
     }
-    // Gate region is unfrozen presentation of typed facts (ADR 0052) — machines
-    // read result.gate, never these row labels.
-    if (result.gate !== undefined) {
-        lines.push(`gate\t${encodeTerminalField(result.gate.actualSeats.join(","))}\t${result.gate.rounds.length}`);
-        for (const round of result.gate.rounds) {
-            const reason = round.dispatch.kind === "historical_dispatch"
-                && round.dispatch.reason !== undefined
-                ? encodeTerminalField(round.dispatch.reason)
-                : "";
-            lines.push(`gate-round\t${round.roundIndex}\t${round.dispatch.kind}\t${round.dispatch.officer}\t${reason}\t${round.officer.seat}\t${encodeTerminalField(round.officer.status)}\t${encodeTerminalField(JSON.stringify(round.officer.findings))}`);
-        }
-    }
     if (result.reviewerChildOutcomes !== undefined) {
         for (const axis of ["completeness", "correctness"]) {
             const child = result.reviewerChildOutcomes[axis];

package/dist/role-run-placement.js

@@ -1,11 +1,35 @@
 import { readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import {
   activationBookDirectory,
   ensureRealDirectoryTree
 } from "./activation-ledger-topology.js";
 import { requireSafePositiveTicketNumber } from "./run-ticket-number.js";
 import { isEnoent } from "./unknown-value.js";
+function formatRunLeaf(runId, role) {
+  return `${runId}@${role}`;
+}
+function parseRunLeaf(name) {
+  const at = name.lastIndexOf("@");
+  if (at <= 0 || at === name.length - 1) return void 0;
+  return { runId: name.slice(0, at), role: name.slice(at + 1) };
+}
+function sessionDirectoryOf(runDirectory) {
+  return join(runDirectory, "session");
+}
+const ROLE_RUN_SESSION_FILENAME = "session.jsonl";
+function sessionFileIn(sessionDirectory) {
+  return join(sessionDirectory, ROLE_RUN_SESSION_FILENAME);
+}
+function sessionFileOf(runDirectory) {
+  return sessionFileIn(sessionDirectoryOf(runDirectory));
+}
+function runDirectoryOfSessionFile(sessionFile) {
+  return dirname(dirname(sessionFile));
+}
+function runDirectoryFromSessionDirectory(sessionDirectory) {
+  return dirname(sessionDirectory);
+}
 async function listBookRunDirectories(bookDir) {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
@@ -39,6 +63,20 @@ async function listBookRunDirectories(bookDir) {
   }
   return out.sort();
 }
+async function findRoleRunDirectory(bookDirectories, runId, onlyRole) {
+  const matches = [];
+  for (const bookDirectory of bookDirectories) {
+    for (const runDirectory of await listBookRunDirectories(bookDirectory)) {
+      const parsed = parseRunLeaf(basename(runDirectory));
+      if (parsed === void 0 || parsed.runId !== runId) continue;
+      if (onlyRole !== void 0 && parsed.role !== onlyRole) continue;
+      matches.push(runDirectory);
+    }
+  }
+  if (matches.length === 0) return void 0;
+  if (matches.length === 1) return matches[0];
+  throw new Error(`ambiguous role run id ${runId}: ${matches.join(", ")}`);
+}
 function roleRunPlacement(ledgerHome, input) {
   const subjectDirectory = "ticketNumber" in input.subject ? String(requireSafePositiveTicketNumber(
     input.subject.ticketNumber,
@@ -48,20 +86,16 @@ function roleRunPlacement(ledgerHome, input) {
     activationBookDirectory(ledgerHome, input.bookKey),
     subjectDirectory,
     "runs",
-    `${input.runId}@${input.role}`
+    formatRunLeaf(input.runId, input.role)
   );
-  const sessionDirectory = join(runDirectory, "session");
+  const sessionDirectory = sessionDirectoryOf(runDirectory);
   return {
     runDirectory,
     sessionDirectory,
-    sessionFile: join(sessionDirectory, "session.jsonl"),
-    artifactsDirectory: roleRunArtifactsDirectory(runDirectory),
+    sessionFile: sessionFileIn(sessionDirectory),
     attachmentsDirectory: join(runDirectory, "attachments")
   };
 }
-function roleRunArtifactsDirectory(runDirectory) {
-  return join(runDirectory, "artifacts");
-}
 function isUnboundRunDirectory(runDirectory) {
   return runDirectory.replaceAll("\\", "/").includes("/unbound/runs/");
 }
@@ -69,18 +103,21 @@ function ensureRoleRunDirectory(ledgerHome, directory) {
   return ensureRealDirectoryTree(ledgerHome, directory);
 }
 function ensureRoleRunPlacement(ledgerHome, placement) {
-  for (const directory of [
-    placement.sessionDirectory,
-    placement.attachmentsDirectory
-  ]) {
-    ensureRoleRunDirectory(ledgerHome, directory);
-  }
+  ensureRoleRunDirectory(ledgerHome, placement.sessionDirectory);
 }
 export {
+  ROLE_RUN_SESSION_FILENAME,
   ensureRoleRunDirectory,
   ensureRoleRunPlacement,
+  findRoleRunDirectory,
+  formatRunLeaf,
   isUnboundRunDirectory,
   listBookRunDirectories,
-  roleRunArtifactsDirectory,
-  roleRunPlacement
+  parseRunLeaf,
+  roleRunPlacement,
+  runDirectoryFromSessionDirectory,
+  runDirectoryOfSessionFile,
+  sessionDirectoryOf,
+  sessionFileIn,
+  sessionFileOf
 };

package/dist/role-run-relocation.js

@@ -1,19 +1,22 @@
 /**
  * Single authority for rewriting durable run pages after a run directory moves.
- * Live unbound→ticket relocate and book-topology migration both call this.
+ * Live callers project typed fields; only historical migrators walk durable pages.
  *
  * Scope is typed machine-consumed path fields only — never free text, never
  * 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 { join, sep } from "node:path";
+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",
@@ -30,7 +33,7 @@ const INVOCATION_PAGE_FIELDS = [
 ];
 const RUN_STATE_PAGE_FIELDS = [
     "runDirectory",
-    "admittedRequestPath",
+    "admittedRequestPath", // pre-#1161 pages only
     "sessionDirectory",
     "sessionFile",
 ];
@@ -52,6 +55,40 @@ export function rewriteRunDirectoryPathValue(value, oldRunDirectory, newRunDirec
     }
     return value;
 }
+/** Match physical aliases or a normal unbound→ticket bind, never historical migration layouts. */
+export async function retainedRunPathsMatch(recordedPath, currentPath, currentRunDirectory) {
+    if (recordedPath === currentPath)
+        return true;
+    if (typeof recordedPath !== "string")
+        return false;
+    const recordedPathIdentity = physicalPathIdentity(recordedPath);
+    const currentPathIdentity = physicalPathIdentity(currentPath);
+    if (recordedPathIdentity === currentPathIdentity)
+        return true;
+    if (currentRunDirectory === undefined)
+        return false;
+    const runDirectory = physicalPathIdentity(currentRunDirectory);
+    const identity = await readRoleRunIdentity(runDirectory);
+    if (identity === undefined)
+        return false;
+    for (let directory = runDirectory; dirname(directory) !== directory; directory = dirname(directory)) {
+        const ledgerHome = dirname(dirname(directory));
+        if (directory !== activationBookDirectory(ledgerHome, identity.bookKey))
+            continue;
+        const unbound = roleRunPlacement(ledgerHome, {
+            bookKey: identity.bookKey,
+            subject: { unbound: true },
+            runId: identity.runId,
+            role: identity.role,
+        });
+        if (rewriteRunDirectoryPathValue(recordedPathIdentity, unbound.runDirectory, runDirectory) !== currentPathIdentity) {
+            return false;
+        }
+        const placed = await findRoleRunDirectory([directory], identity.runId, identity.role);
+        return placed !== undefined && physicalPathIdentity(placed) === runDirectory;
+    }
+    return false;
+}
 /**
  * Apply the longest matching oldRunDirectory rewrite. Longer keys win so a
  * nested run path is not partially claimed by a shorter sibling prefix.
@@ -139,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");
@@ -207,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");
@@ -266,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");
@@ -290,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);
@@ -303,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
@@ -313,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",
+]);