@akagilnc/pi-workflow-roles 0.1.4062 → 0.1.4196

package/dist/archivist-record-entry.js

@@ -1,18 +1,35 @@
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  realpathSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
 import { dirname, resolve, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
-import { resolveBookKeyFromGit } from "./activation-ledger-git.js";
 import {
   ActivationLedgerError,
-  activationBookDirectory,
   ensureRealDirectoryTree,
+  errnoCode,
   errorText,
   pathContainedIn,
   physicallyContainedIn,
   resolveActivationLedgerHomeForPath
 } from "./activation-ledger-topology.js";
-import { subjectKeyedRecordDirectory } from "./archivist-record-topology.js";
-import { subjectKeyedRecordDirectory as subjectKeyedRecordDirectory2 } from "./archivist-record-topology.js";
+import {
+  NAVIGATOR_RECORD_KIND,
+  resolveNavigatorWorkSubjectPlacement
+} from "./archivist-record-topology.js";
+import {
+  NAVIGATOR_RECORD_KIND as NAVIGATOR_RECORD_KIND2,
+  resolveNavigatorWorkSubjectPlacement as resolveNavigatorWorkSubjectPlacement2
+} from "./archivist-record-topology.js";
 const CURRENT_SESSION_LEDGER = "current-session.json";
 function readCurrentSession(sessionDir) {
   const ledger = join(sessionDir, CURRENT_SESSION_LEDGER);
@@ -41,6 +58,151 @@ function writeCurrentSession(sessionDir, sessionFile) {
     );
   }
 }
+function isCurrentSessionClaimRace(error) {
+  if (!(error instanceof ActivationLedgerError)) return errnoCode(error) === "EEXIST";
+  return errnoCode(error.cause) === "EEXIST";
+}
+function currentSessionLedgerPath(sessionDir) {
+  return join(sessionDir, CURRENT_SESSION_LEDGER);
+}
+const SESSION_HEADER_CHUNK_BYTES = 4096;
+const MAX_SESSION_HEADER_SCAN_BYTES = 1024 * 1024;
+function readBoundedSessionHeader(filePath) {
+  const fd = openSync(filePath, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(SESSION_HEADER_CHUNK_BYTES);
+    const decoder = new StringDecoder("utf8");
+    let pending = "";
+    let scanned = 0;
+    const consume = (chunk) => {
+      pending += chunk;
+      let lineStart = 0;
+      let newlineIndex = pending.indexOf("\n", lineStart);
+      while (newlineIndex !== -1) {
+        const line = pending.slice(lineStart, newlineIndex);
+        lineStart = newlineIndex + 1;
+        newlineIndex = pending.indexOf("\n", lineStart);
+        if (line.trim() === "") continue;
+        pending = pending.slice(lineStart);
+        const header = parseSessionHeaderLine(line);
+        return header === void 0 ? { kind: "rejected" } : { kind: "accepted", header };
+      }
+      pending = pending.slice(lineStart);
+      return { kind: "incomplete" };
+    };
+    const finishPending = (tail) => {
+      const result = consume(tail);
+      if (result.kind === "accepted") return result.header;
+      if (result.kind === "rejected") return void 0;
+      if (pending.trim() === "") return void 0;
+      const header = parseSessionHeaderLine(pending);
+      pending = "";
+      return header;
+    };
+    while (scanned < MAX_SESSION_HEADER_SCAN_BYTES) {
+      const toRead = Math.min(buffer.length, MAX_SESSION_HEADER_SCAN_BYTES - scanned);
+      const bytesRead = readSync(fd, buffer, 0, toRead, null);
+      if (bytesRead === 0) {
+        return finishPending(decoder.end());
+      }
+      scanned += bytesRead;
+      const found = consume(decoder.write(buffer.subarray(0, bytesRead)));
+      if (found.kind === "accepted") return found.header;
+      if (found.kind === "rejected") return void 0;
+    }
+    const probe = Buffer.allocUnsafe(1);
+    if (readSync(fd, probe, 0, 1, null) === 0) {
+      return finishPending(decoder.end());
+    }
+    return void 0;
+  } finally {
+    closeSync(fd);
+  }
+}
+function parseSessionHeaderLine(line) {
+  if (line.trim() === "") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || parsed.type !== "session" || typeof parsed.id !== "string" || parsed.id.length === 0) {
+    return void 0;
+  }
+  const cwd = parsed.cwd;
+  return {
+    type: "session",
+    id: parsed.id,
+    ...typeof cwd === "string" ? { cwd } : {}
+  };
+}
+function mostRecentNavigatorSessionFile(sessionDir, cwd) {
+  const absoluteSessionDir = resolve(sessionDir);
+  const absoluteCwd = resolve(cwd);
+  let names;
+  try {
+    names = readdirSync(absoluteSessionDir);
+  } catch (error) {
+    throw new ActivationLedgerError(
+      `archivist navigator nest is not readable (${sessionDir}): ${errorText(error)}`,
+      { cause: error }
+    );
+  }
+  const matched = [];
+  for (const name of names) {
+    if (!name.endsWith(".jsonl")) continue;
+    const filePath = join(absoluteSessionDir, name);
+    let st;
+    try {
+      st = statSync(filePath);
+    } catch (error) {
+      throw new ActivationLedgerError(
+        `archivist navigator session file is not stat-able (${filePath}): ${errorText(error)}`,
+        { cause: error }
+      );
+    }
+    if (!st.isFile()) continue;
+    let header;
+    try {
+      header = readBoundedSessionHeader(filePath);
+    } catch (error) {
+      throw new ActivationLedgerError(
+        `archivist navigator session header is not readable (${filePath}): ${errorText(error)}`,
+        { cause: error }
+      );
+    }
+    if (header === void 0) continue;
+    if (typeof header.cwd !== "string" || header.cwd.length === 0) continue;
+    if (resolve(header.cwd) !== absoluteCwd) continue;
+    matched.push({ path: filePath, mtimeMs: st.mtimeMs });
+  }
+  if (matched.length === 0) return void 0;
+  matched.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return matched[0].path;
+}
+function resolveNavigatorNestContinuation(sessionDir, cwd) {
+  const ledgerPath = currentSessionLedgerPath(sessionDir);
+  if (existsSync(ledgerPath)) {
+    const recentFile = readCurrentSession(sessionDir);
+    assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
+    return recentFile;
+  }
+  const adopted = mostRecentNavigatorSessionFile(sessionDir, cwd);
+  if (adopted === void 0) return void 0;
+  assertRecentFinalFileUnderSessionDir(sessionDir, adopted);
+  try {
+    writeCurrentSession(sessionDir, adopted);
+    return adopted;
+  } catch (error) {
+    if (isCurrentSessionClaimRace(error)) {
+      const recentFile = readCurrentSession(sessionDir);
+      assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
+      return recentFile;
+    }
+    throw error;
+  }
+}
 const WORKER_SUBMISSION_GATE_KIND = "worker-submission-gate";
 function assertRecentFinalFileUnderSessionDir(sessionDir, recentFile) {
   const absoluteSessionDir = resolve(sessionDir);
@@ -77,34 +239,55 @@ function assertRecentFinalFileUnderSessionDir(sessionDir, recentFile) {
 function createRecordSessionOpen(options) {
   const cwd = options.cwd;
   const parentFile = options.parent?.getSessionFile();
-  const ledgerHome = resolveActivationLedgerHomeForPath(parentFile);
   let sessionDir;
   let parentSession;
-  if (options.subject !== void 0) {
-    sessionDir = subjectKeyedRecordDirectory({
+  let mayResumeSameNest;
+  let ledgerHome;
+  if (options.kind === NAVIGATOR_RECORD_KIND && options.subject !== void 0) {
+    const placement = resolveNavigatorWorkSubjectPlacement({
       cwd,
-      kind: options.kind,
       subject: options.subject,
-      ...parentFile === void 0 || parentFile.length === 0 ? {} : { parentSessionFile: parentFile }
+      ...parentFile === void 0 || parentFile.length === 0 ? {} : { parentSessionFile: parentFile },
+      ...options.home === void 0 ? {} : { home: options.home }
     });
+    sessionDir = placement.sessionDir;
+    ledgerHome = placement.ledgerHome;
     parentSession = parentFile && parentFile.length > 0 ? parentFile : void 0;
+    mayResumeSameNest = true;
   } else if (parentFile === void 0 || parentFile.length === 0) {
-    return { session: SessionManager.inMemory(cwd), resumed: false };
+    if (options.subject === void 0) {
+      return { session: SessionManager.inMemory(cwd), resumed: false };
+    }
+    throw new Error("Durable record ownership requires a parent session inside the ledger home");
   } else {
+    ledgerHome = resolveActivationLedgerHomeForPath(parentFile);
     const parentResolved = resolve(parentFile);
-    sessionDir = physicallyContainedIn(ledgerHome, parentResolved) ? join(dirname(parentResolved), options.kind) : join(activationBookDirectory(ledgerHome, resolveBookKeyFromGit(cwd)), options.kind);
+    if (!physicallyContainedIn(ledgerHome, parentResolved)) {
+      throw new Error("Durable record ownership requires a parent session inside the ledger home");
+    }
+    sessionDir = join(dirname(parentResolved), options.kind);
     parentSession = parentFile;
+    mayResumeSameNest = options.kind === WORKER_SUBMISSION_GATE_KIND;
   }
   const nestAlreadyExists = existsSync(sessionDir);
   ensureRealDirectoryTree(ledgerHome, sessionDir);
-  const mayResumeSameNest = options.subject !== void 0 || options.kind === WORKER_SUBMISSION_GATE_KIND;
   if (mayResumeSameNest && nestAlreadyExists) {
-    const recentFile = readCurrentSession(sessionDir);
-    assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
-    return {
-      session: SessionManager.open(recentFile, sessionDir, cwd),
-      resumed: true
-    };
+    if (options.kind === NAVIGATOR_RECORD_KIND) {
+      const recentFile = resolveNavigatorNestContinuation(sessionDir, cwd);
+      if (recentFile !== void 0) {
+        return {
+          session: SessionManager.open(recentFile, sessionDir, cwd),
+          resumed: true
+        };
+      }
+    } else {
+      const recentFile = readCurrentSession(sessionDir);
+      assertRecentFinalFileUnderSessionDir(sessionDir, recentFile);
+      return {
+        session: SessionManager.open(recentFile, sessionDir, cwd),
+        resumed: true
+      };
+    }
   }
   const session = SessionManager.create(
     cwd,
@@ -151,9 +334,10 @@ function bookDirectOfficerRunPointer(options) {
 }
 export {
   DIRECT_OFFICER_RUN_POINTER_KIND,
+  NAVIGATOR_RECORD_KIND2 as NAVIGATOR_RECORD_KIND,
   WORKER_SUBMISSION_GATE_KIND,
   bookDirectOfficerRunPointer,
   createRecordSession,
   createRecordSessionOpen,
-  subjectKeyedRecordDirectory2 as subjectKeyedRecordDirectory
+  resolveNavigatorWorkSubjectPlacement2 as resolveNavigatorWorkSubjectPlacement
 };

package/dist/archivist-record-topology.js

@@ -1,20 +1,40 @@
+/**
+ * Pure archivist record placement topology (ADR 0048 / 0065 / dossier-topology).
+ * No SessionManager / pi-coding-agent — cold public-bin and ledger discovery
+ * may import this without pulling open-session runtime into the graph.
+ *
+ * Navigator work-subject is the sole book-top subject partition (#852):
+ * books/<book>/navigator/<work-subject-digest>/. Callers must not re-hash
+ * subject or re-join book/navigator/digest themselves.
+ */
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { resolveBookKeyFromGit } from "./activation-ledger-git.js";
-import {
-  activationBookDirectory,
-  resolveActivationLedgerHome,
-  resolveActivationLedgerHomeForPath
-} from "./activation-ledger-topology.js";
-function subjectKeyedRecordDirectory(input) {
-  const ledgerHome = input.parentSessionFile !== void 0 && input.parentSessionFile.length > 0 ? resolveActivationLedgerHomeForPath(input.parentSessionFile) : resolveActivationLedgerHome(input.home);
-  const digest = createHash("sha256").update(input.subject).digest("hex").slice(0, 32);
-  return join(
-    activationBookDirectory(ledgerHome, resolveBookKeyFromGit(input.cwd)),
-    input.kind,
-    digest
-  );
+import { activationBookDirectory, resolveActivationLedgerHome, tryHomeFromAkRolesPath, } from "./activation-ledger-topology.js";
+/** Book-top partition for cross-ticket navigator route-memory (dossier-topology). */
+export const NAVIGATOR_RECORD_KIND = "navigator";
+/**
+ * Sole navigator work-subject placement under the ledger book.
+ * Returns ledgerHome and nest once so createRecordSessionOpen does not re-branch
+ * parent/home. Work-subject key shape is sha256(subject) hex truncated to 32
+ * (#852 out of scope — shape unchanged).
+ *
+ * parentSessionFile contributes home only when tryHomeFromAkRolesPath succeeds;
+ * otherwise the explicit home (from HostContext.runDirectory) is kept. Never
+ * invents a second home via passwd/env fallback from a foreign parent path.
+ */
+export function resolveNavigatorWorkSubjectPlacement(input) {
+    let ledgerHome;
+    if (input.parentSessionFile !== undefined && input.parentSessionFile.length > 0) {
+        const fromParent = tryHomeFromAkRolesPath(input.parentSessionFile);
+        if (fromParent !== undefined && fromParent.length > 0) {
+            ledgerHome = resolveActivationLedgerHome(fromParent);
+        }
+    }
+    ledgerHome ??= resolveActivationLedgerHome(input.home);
+    const digest = createHash("sha256").update(input.subject).digest("hex").slice(0, 32);
+    return {
+        ledgerHome,
+        sessionDir: join(activationBookDirectory(ledgerHome, resolveBookKeyFromGit(input.cwd)), NAVIGATOR_RECORD_KIND, digest),
+    };
 }
-export {
-  subjectKeyedRecordDirectory
-};

package/dist/auditor-dossier-tool.js

@@ -1,4 +1,5 @@
 import { dirname, join, resolve } from "node:path";
+import { roleRunArtifactsDirectory } from "./role-run-placement.js";
 import { Type } from "typebox";
 const AUDITOR_DOSSIER_TOOL_NAME = "ak_get_run_dossier";
 function auditorRunDirectory(context) {
@@ -25,7 +26,7 @@ function createAuditorDossierTool(runDirectory) {
         admittedRequest: join(runDirectory, "admitted-request.json"),
         parentSessionCandidate: join(runDirectory, "session", "session.jsonl"),
         attachments: join(runDirectory, "attachments"),
-        artifacts: join(runDirectory, "artifacts")
+        artifacts: roleRunArtifactsDirectory(runDirectory)
       };
       return {
         content: [{ type: "text", text: JSON.stringify(details) }],

package/dist/diarist-contracts.js

@@ -7,8 +7,104 @@
  * #779: no frozen candidate catalog; LLM finds sources and submits whole blocks.
  * Mechanical layer does not judge LLM output (no quote/ticket/relevance verify).
  */
+import { isSafePositiveTicketNumber, requireSafePositiveTicketNumber, } from "./run-ticket-number.js";
 export const DIARIST_OUTPUT_TOOL_NAME = "ak_diarist_output";
 export const DIARIST_ACCEPTED_TEXT = "起居郎回执已接受";
+/**
+ * Sole shape projection for a typed co-review ticket set (#871).
+ * Positive safe integers, first-seen order, duplicates dropped. Not content judgment.
+ * Returns null when `raw` is not an array (callers classify absent vs durable damage).
+ * Returns a possibly empty list when `raw` is an array (unlawful members skipped).
+ * When `principalTicket` is set, that ticket is guaranteed as a member (prepended if missing).
+ */
+export function projectCourtTicketNumbers(raw, options) {
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    const seen = new Set();
+    for (const item of raw) {
+        if (!isSafePositiveTicketNumber(item))
+            continue;
+        if (seen.has(item))
+            continue;
+        seen.add(item);
+        out.push(item);
+    }
+    const principal = options?.principalTicket;
+    if (principal === undefined)
+        return out;
+    requireSafePositiveTicketNumber(principal, "projectCourtTicketNumbers principalTicket");
+    if (seen.has(principal))
+        return out;
+    return [principal, ...out];
+}
+/**
+ * Durable-field interpreter for #871 co-review sets.
+ * Absent key (old-format run) is not damage. Present but empty / non-array /
+ * partially unlawful / missing principal is damage — callers must fail closed,
+ * never wash into main-only.
+ */
+export function interpretDurableCourtTicketNumbers(record, options) {
+    if (!Object.hasOwn(record, "courtTicketNumbers")) {
+        return { kind: "absent" };
+    }
+    const raw = record.courtTicketNumbers;
+    if (!Array.isArray(raw)) {
+        return {
+            kind: "damage",
+            reason: "courtTicketNumbers is present but not an array",
+        };
+    }
+    if (raw.length === 0) {
+        return {
+            kind: "damage",
+            reason: "courtTicketNumbers is present but empty",
+        };
+    }
+    for (let i = 0; i < raw.length; i += 1) {
+        const item = raw[i];
+        if (!isSafePositiveTicketNumber(item)) {
+            return {
+                kind: "damage",
+                reason: `courtTicketNumbers[${i}] is not a safe positive integer`,
+            };
+        }
+    }
+    // Members are all lawful numbers; sole projection owns dedupe/order.
+    const tickets = projectCourtTicketNumbers(raw);
+    if (tickets === null || tickets.length === 0) {
+        return {
+            kind: "damage",
+            reason: "courtTicketNumbers projected empty after lawful members",
+        };
+    }
+    const principal = options?.principalTicket;
+    if (principal !== undefined) {
+        if (!isSafePositiveTicketNumber(principal)) {
+            return {
+                kind: "damage",
+                reason: "courtTicketNumbers principal ticket is not a safe positive integer",
+            };
+        }
+        if (!tickets.includes(principal)) {
+            return {
+                kind: "damage",
+                reason: `courtTicketNumbers is missing principal ticket #${principal}`,
+            };
+        }
+    }
+    return { kind: "ok", tickets: Object.freeze([...tickets]) };
+}
+/** True when two durable #871 sets are byte-identical sequences. */
+export function sameCourtTicketNumbers(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let i = 0; i < left.length; i += 1) {
+        if (left[i] !== right[i])
+            return false;
+    }
+    return true;
+}
 export function validateRecordedDiaristOutput(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("Diarist output has no execution discriminator");

package/dist/doctor-evidence.js

@@ -108,9 +108,10 @@ function deriveSession(content, id) {
 /** Read Pi's retained session directory as the sole raw material for one case. */
 export async function loadDoctorCase(runsPath) {
     const root = await realpath(runsPath);
-    const match = root.split(sep).join("/").match(/\/\.ak-roles\/books\/[^/]+\/issues\/([1-9]\d*)\/runs$/);
+    // Canonical <book>/<ticket>/runs; legacy issues/<n>/runs remains read-only compatible.
+    const match = root.split(sep).join("/").match(/\/\.ak-roles\/books\/[^/]+\/(?:issues\/)?([1-9]\d*)\/runs$/);
     if (!match)
-        throw new Error("Doctor case must be an .ak-roles/books/<book>/issues/<n>/runs directory");
+        throw new Error("Doctor case must be an .ak-roles/books/<book>/<n>/runs directory");
     const evidence = [], sessions = [], statuses = [], commits = [];
     const turns = { count: 0, sources: [] }, calls = { count: 0, sources: [] }, tokens = { count: 0, sources: [] };
     for (const path of await discoverCaseFiles(root)) {