@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/src/analyst-gate-cycles-read.ts

@@ -1,18 +1,15 @@
 /**
- * Sole nested-volume reader for gate-cycle facts under session/auditor-roles/.
+ * Sole reader for gate-cycle facts of the officers pointed at from current.json `officers`.
  *
- * Consumers: Analyst sole ledger scan (classifyScopedRun) and Terminal gate
- * projection (#478). Metric families must not open a second disk scan — they
- * consume retained facts. Terminal settlement reuses this same pairing seam
- * (no second auditor-roles scanner).
+ * Consumer: Analyst sole ledger scan (classifyScopedRun). Metric families must
+ * not open a second disk scan — they consume retained facts.
  *
  * Naming: records may carry pre-#440 menxia/jishizhong/fubaolang tool faces or
  * the current gatekeeper/inspector/notary English face. Projection always uses
  * the current English officer identity (inspector | notary).
  *
- * Missing auditor-roles directory (ENOENT only) → empty rounds (lawful zero).
- * Path present but not a directory (ENOTDIR) and discovered nested JSONL that
- * fails canonical read/parse must fail loudly (never silently under-count).
+ * Absent `officers` section → empty rounds (lawful zero). A pointer whose
+ * officer session fails canonical read/parse must fail loudly (never silently under-count).
  * An accepted gate terminating receipt (isError:false pair on dispatch/officer
  * tool) whose required typed facts are unusable — status, dispatch officer, or
  * first/last span missing/unknown/unparseable/inverted — also fails loudly via
@@ -25,9 +22,6 @@
  * `ak_auditor_parent_attempt_binding.parent.attemptEntryId` — never seat/time guessing.
  * An orphan accepted dispatch must not consume a later same-seat direct officer.
  */
-import { readdir } from "node:fs/promises";
-import { join } from "node:path";
-
 import {
   AUDITOR_PARENT_ATTEMPT_BINDING_ENTRY_TYPE,
 } from "./compliance-transport.ts";
@@ -38,7 +32,10 @@ import {
   type LedgerSessionRow,
 } from "./ledger-session-read.ts";
 
-import { isRecord, errorText, isEnoent } from "./unknown-value.ts";
+import { isRecord, isEnoent } from "./unknown-value.ts";
+import { retainedRunPathsMatch } from "./role-run-relocation.ts";
+import { runDirectoryOfSessionFile } from "./role-run-placement.ts";
+import { readOfficerPointers } from "./archivist-record-pointer.ts";
 
 /** One completed gate round: direct officer receipt or historical province/officer pair. */
 /** Honest origin discriminant: direct summons vs historical province dispatch. */
@@ -416,93 +413,39 @@ function pairGateRounds(
     .map((round, index) => ({ ...round, roundIndex: index + 1 }));
 }
 
-/** Resolve a direct-officer-run-pointer file to the officer session 正本 path. */
-async function resolveOfficerSessionFromPointerFile(
-  pointerPath: string,
-): Promise<{ sessionFile: string; officer?: "inspector" | "notary" }> {
-  const { readFile } = await import("node:fs/promises");
-  let raw: unknown;
-  try {
-    raw = JSON.parse(await readFile(pointerPath, "utf8"));
-  } catch (error) {
-    throw new Error(
-      `direct officer run pointer unreadable in ${pointerPath}: ${errorText(error)}`,
-      { cause: error },
-    );
-  }
-  if (!isRecord(raw) || raw.kind !== "direct-officer-run-pointer" || raw.version !== 1) {
-    throw new Error(`direct officer run pointer has unknown shape in ${pointerPath}`);
-  }
-  const sessionFile = raw.sessionFile;
-  if (typeof sessionFile !== "string" || sessionFile.trim() === "") {
-    throw new Error(`direct officer run pointer missing sessionFile in ${pointerPath}`);
-  }
-  const officer = raw.officer === "inspector" || raw.officer === "notary"
-    ? raw.officer : undefined;
-  return { sessionFile, ...(officer === undefined ? {} : { officer }) };
-}
-
 /**
- * Read and pair gate-cycle rounds from one or more auditor-roles directories.
- * Accepts historical nested JSONL volumes and #675 direct-officer-run-pointer
- * files that name the independent officer session 正本.
- * ENOENT (directory truly absent) → []. ENOTDIR and other errors propagate
- * (failure honesty — damaged topology must not wash to zero rounds).
+ * Read and pair gate-cycle rounds from the officer pointers booked in one
+ * run's current.json `officers` section; each pointer names the independent
+ * officer session 正本. Absent section → [] (lawful zero). A damaged pointer or
+ * officer session propagates — damaged topology must not wash to zero rounds.
  *
  * Pass `parentSessionFile` to keep only rounds whose attempt binding names that parent.
  */
-export async function readAnalystGateCyclesFromAuditorRoles(
-  auditorRolesDirectory: string | readonly string[],
+export async function readAnalystGateCyclesFromOfficers(
+  parentRunDirectory: string,
   options: {
     readonly parentSessionFile?: string;
   } = {},
 ): Promise<readonly AnalystGateCycleRound[]> {
-  const directories = typeof auditorRolesDirectory === "string"
-    ? [auditorRolesDirectory]
-    : auditorRolesDirectory;
   const volumes: ClassifiedVolume[] = [];
-  // Same officer session pointed at N times (historical multi-mint pointers, or
-  // one parent booking many leaves) must classify once — else each accepted
-  // seal is counted ×N in terminal gate-round (#753 acceptance A).
+  // Same officer session pointed at N times must classify once — else each
+  // accepted seal is counted ×N in gate-cycle statistics (#753 acceptance A).
   const classifiedOfficerSessions = new Set<string>();
-  for (const directory of directories) {
-    let names: string[];
-    try {
-      const entries = await readdir(directory, { withFileTypes: true });
-      names = entries
-        .filter(
-          (e) =>
-            e.isFile()
-            && (e.name.endsWith(".jsonl") || e.name.endsWith(".pointer.json")),
-        )
-        .map((e) => e.name)
-        .sort();
-    } catch (error) {
-      if (isEnoent(error)) continue;
-      throw error;
-    }
-    for (const name of names) {
-      const path = join(directory, name);
-      const fromPointer = name.endsWith(".pointer.json");
-      const pointer = fromPointer
-        ? await resolveOfficerSessionFromPointerFile(path)
-        : undefined;
-      const sessionPath = pointer?.sessionFile ?? path;
-      if (fromPointer) {
-        if (classifiedOfficerSessions.has(sessionPath)) continue;
-        classifiedOfficerSessions.add(sessionPath);
-      }
-      const classified = await classifyAuditorVolume(sessionPath, pointer?.officer);
-      for (const volume of classified) {
-        if (
-          options.parentSessionFile !== undefined &&
-          volume.parentSessionFile !== undefined &&
-          volume.parentSessionFile !== options.parentSessionFile
-        ) {
-          continue;
-        }
-        volumes.push(volume);
+  for (const pointer of await readOfficerPointers(parentRunDirectory)) {
+    if (classifiedOfficerSessions.has(pointer.sessionFile)) continue;
+    classifiedOfficerSessions.add(pointer.sessionFile);
+    const officer = pointer.officer === "inspector" || pointer.officer === "notary"
+      ? pointer.officer : undefined;
+    const classified = await classifyAuditorVolume(pointer.sessionFile, officer);
+    for (const volume of classified) {
+      if (
+        options.parentSessionFile !== undefined &&
+        volume.parentSessionFile !== undefined &&
+        !await retainedRunPathsMatch(volume.parentSessionFile, options.parentSessionFile, runDirectoryOfSessionFile(options.parentSessionFile))
+      ) {
+        continue;
       }
+      volumes.push(volume);
     }
   }
   return pairGateRounds(volumes);

package/src/analyst-ledger.ts

@@ -12,6 +12,7 @@
  * A2: classifyScopedRun retains typed per-run facts (frame span, tool intervals,
  * terminal face) for metric-family modules — no longer discarded after checks.
  */
+import { readSectionSync } from "./run-dossier.ts";
 import { readdir, readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 
@@ -21,9 +22,14 @@ import {
   physicalPathIdentity,
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
-import { listBookRunDirectories } from "./role-run-placement.ts";
+import {
+  listBookRunDirectories,
+  parseRunLeaf,
+  sessionFileOf,
+} from "./role-run-placement.ts";
 import { autopsyWriterLock, readRoleRunIdentity } from "./public-cli/run-lifecycle.ts";
 import { readRunTicketNumber } from "./run-ticket-number.ts";
+import { rewriteRunDirectoryPathValue } from "./role-run-relocation.ts";
 import {
   extractSessionModelSequence,
   extractSessionTimestampSpan,
@@ -34,8 +40,8 @@ import {
   type SessionToolInterval,
 } from "./ledger-session-read.ts";
 import {
-  readRunTerminalArtifact,
-  type RunTerminalArtifactFile,
+  readRunTerminal,
+  type RunTerminalFace,
 } from "./run-terminal-artifacts.ts";
 import type {
   AnalystFirstFrameAt,
@@ -45,7 +51,7 @@ import type {
   AnalystUnreadableRun,
 } from "./analyst-page.ts";
 import {
-  readAnalystGateCyclesFromAuditorRoles,
+  readAnalystGateCyclesFromOfficers,
   type AnalystGateCycleRound,
 } from "./analyst-gate-cycles-read.ts";
 
@@ -57,7 +63,7 @@ export type { AnalystGateCycleRound } from "./analyst-gate-cycles-read.ts";
 const LIVE_RUN_STATES = new Set(["admitted", "running", "resumable"]);
 
 /**
- * Read lifecycle state from the existing run-state.json face.
+ * Read lifecycle state from the state.jsonl run-state fact row.
  * Used only to distinguish live in-flight runs from terminal no-receipt.
  */
 async function readExistingRunLifecycleState(
@@ -124,19 +130,11 @@ async function classifyGhostCandidate(input: {
   };
 }
 
-function parseRunDirectoryName(
-  name: string,
-): { runId: string; role: string } | undefined {
-  const at = name.lastIndexOf("@");
-  if (at <= 0 || at === name.length - 1) return undefined;
-  return { runId: name.slice(0, at), role: name.slice(at + 1) };
-}
-
 /**
  * Invocation scope faces used for issue 圈定 (C4 / #399).
  * projectRoot is retained for narrow path match and conflict facts;
  * ticketNumber is the #176 typed face when present (integer ≥ 1).
- * Single read of invocation.json — no second parse kernel.
+ * Single read of the current.json invocation section — no second parse kernel.
  */
 type InvocationScopeFields = {
   readonly projectRoot: string;
@@ -156,15 +154,8 @@ async function listLedgerBookNames(booksRoot: string): Promise<string[]> {
 async function readInvocationScopeFields(
   runDirectory: string,
 ): Promise<InvocationScopeFields | undefined> {
-  let raw: string;
-  try {
-    raw = await readFile(join(runDirectory, "invocation.json"), "utf8");
-  } catch (error) {
-    if (isMissingPathError(error)) return undefined;
-    throw error;
-  }
-  const parsed: unknown = JSON.parse(raw);
-  if (!isRecord(parsed)) return undefined;
+  const parsed = readSectionSync(runDirectory, "invocation");
+  if (parsed === undefined) return undefined;
   if (typeof parsed.projectRoot !== "string" || parsed.projectRoot.trim() === "") {
     return undefined;
   }
@@ -214,20 +205,13 @@ async function resolveSessionFile(
   runDirectory: string,
 ): Promise<string> {
   // Prefer invocation.sessionFile when present; fall back to S-family principal.
-  try {
-    const raw = await readFile(join(runDirectory, "invocation.json"), "utf8");
-    const parsed: unknown = JSON.parse(raw);
-    if (
-      isRecord(parsed)
-      && typeof parsed.sessionFile === "string"
-      && parsed.sessionFile.trim() !== ""
-    ) {
-      return parsed.sessionFile;
-    }
-  } catch (error) {
-    if (!isMissingPathError(error)) throw error;
+  const parsed = readSectionSync(runDirectory, "invocation");
+  if (parsed !== undefined && typeof parsed.sessionFile === "string" && parsed.sessionFile.trim() !== "") {
+    return typeof parsed.runDirectory === "string"
+      ? rewriteRunDirectoryPathValue(parsed.sessionFile, parsed.runDirectory, runDirectory) as string
+      : parsed.sessionFile;
   }
-  return join(runDirectory, "session", "session.jsonl");
+  return sessionFileOf(runDirectory);
 }
 
 /**
@@ -327,7 +311,7 @@ export type AnalystRunTerminalFace =
   | { readonly status: "absent" }
   | {
       readonly status: "present";
-      readonly file: RunTerminalArtifactFile;
+      readonly face: RunTerminalFace;
       readonly body: Record<string, unknown>;
       /** Nonblank producer role — sole owner is readRunTerminalArtifact. */
       readonly role: string;
@@ -352,9 +336,9 @@ export type AnalystReadableRunFacts = {
    */
   readonly models: readonly string[];
   /**
-   * Paired gate-cycle rounds from session/auditor-roles/ (#446).
-   * Missing directory → empty (lawful zero rounds).
-   * Damaged discovered nested JSONL → leg unreadable (`auditor-roles` source).
+   * Paired gate-cycle rounds of the officers booked in current.json (#446).
+   * No officers booked → empty (lawful zero rounds).
+   * A damaged officer pointer or session → leg unreadable (`auditor-roles` source).
    */
   readonly gateCycles: readonly AnalystGateCycleRound[];
 };
@@ -515,10 +499,14 @@ async function classifyScopedRun(input: {
   }
 
   try {
-    const artifact = await readRunTerminalArtifact(input.runDirectory);
+    const read = readRunTerminal(input.runDirectory);
+    // A no_receipt terminal is the explicit form of "no accepted receipt".
+    const artifact = read.status === "present" && read.face === "no_receipt"
+      ? { status: "absent" as const }
+      : read;
     if (artifact.status === "unreadable") {
       missingSources.push("terminal-artifact");
-      reasons.push(`${artifact.file}: ${artifact.reason}`);
+      reasons.push(`terminal: ${artifact.reason}`);
     } else if (artifact.status === "absent") {
       if (lifecycle === "admitted" || lifecycle === "running") {
         // No terminal yet: ghost report only, or live in-flight omit.
@@ -530,10 +518,10 @@ async function classifyScopedRun(input: {
       }
       terminal = { status: "absent" };
     } else {
-      // role already required nonblank by readRunTerminalArtifact (single owner).
+      // role already required nonblank by readRunTerminal (single owner).
       terminal = {
         status: "present",
-        file: artifact.file,
+        face: artifact.face,
         body: artifact.body,
         role: artifact.body.role as string,
       };
@@ -574,16 +562,13 @@ async function classifyScopedRun(input: {
     );
   }
 
-  // Nested auditor-roles gate pairs stay inside the sole scan (families must
+  // Officer gate pairs stay inside the sole scan (families must
   // not readdir this tree again). Missing directory → []. Damaged discovered
   // nested JSONL is page-local unreadable — never silently under-count rounds.
   let gateCycles: readonly AnalystGateCycleRound[];
   try {
-    const parentSessionFile = join(input.runDirectory, "session", "session.jsonl");
-    gateCycles = await readAnalystGateCyclesFromAuditorRoles(
-      join(input.runDirectory, "session", "auditor-roles"),
-      { parentSessionFile },
-    );
+    const parentSessionFile = sessionFileOf(input.runDirectory);
+    gateCycles = await readAnalystGateCyclesFromOfficers(input.runDirectory, { parentSessionFile });
   } catch (error) {
     return {
       kind: "unreadable",
@@ -697,7 +682,7 @@ export async function scanAnalystIssueRuns(input: {
 
     for (const runDirectory of runDirectories) {
       const runName = basename(runDirectory);
-      const parsed = parseRunDirectoryName(runName);
+      const parsed = parseRunLeaf(runName);
       if (parsed === undefined) continue;
 
       let scopeFields: InvocationScopeFields | undefined;

package/src/analyst-metric-families/acceptance-success-rework.ts

@@ -97,7 +97,10 @@ export type AnalystAcceptanceSuccessReworkSection = {
   readonly rework: AnalystReworkLens;
 };
 
-/** Locate collector groups array: receipt.groups or top-level groups. */
+/**
+ * Locate collector groups array from the canonical typed receipt faces.
+ * Same leaf order as extractStatus: body / receipt / decisiveFacts / payloads.
+ */
 function findCollectorGroups(body: Record<string, unknown>): unknown {
   if (Array.isArray(body.groups)) return body.groups;
   const receipt = body.receipt;
@@ -106,6 +109,15 @@ function findCollectorGroups(body: Record<string, unknown>): unknown {
   if (isRecord(outcome)) {
     const facts = outcome.decisiveFacts;
     if (isRecord(facts) && Array.isArray(facts.groups)) return facts.groups;
+    // Typed sealed receipt: settlement keeps payloads on attempt-history; the
+    // terminal reader rehydrates them via attemptHistoryIdentity. Groups are the
+    // collector leaf on that receipt — never invent a second discriminator.
+    if (Array.isArray(outcome.payloads)) {
+      for (let index = outcome.payloads.length - 1; index >= 0; index -= 1) {
+        const payload = outcome.payloads[index];
+        if (isRecord(payload) && Array.isArray(payload.groups)) return payload.groups;
+      }
+    }
   }
   return undefined;
 }
@@ -116,6 +128,17 @@ export function extractStatus(body: Record<string, unknown>): string | undefined
   if (isRecord(outcome) && typeof outcome.status === "string" && outcome.status.trim() !== "") {
     return outcome.status;
   }
+  // Typed sealed receipt: settlement keeps payloads on attempt-history; the
+  // terminal reader rehydrates them via attemptHistoryIdentity. Status is the role's
+  // own leaf on that receipt — never invent a second mapping.
+  if (isRecord(outcome) && Array.isArray(outcome.payloads)) {
+    for (let index = outcome.payloads.length - 1; index >= 0; index -= 1) {
+      const payload = outcome.payloads[index];
+      if (isRecord(payload) && typeof payload.status === "string" && payload.status.trim() !== "") {
+        return payload.status;
+      }
+    }
+  }
   const receipt = body.receipt;
   if (isRecord(receipt) && typeof receipt.status === "string" && receipt.status.trim() !== "") {
     return receipt.status;

package/src/analyst-metric-families/gate-cycles.ts

@@ -26,7 +26,7 @@ export type AnalystGateCyclesLeg = {
   readonly runId: string;
   readonly book: string;
   readonly role: string;
-  /** Paired dispatch↔officer volume count (0 when no auditor-roles). */
+  /** Paired dispatch↔officer volume count (0 when no officers booked). */
   readonly roundCount: number;
   readonly rounds: readonly AnalystGateCyclesRoundRow[];
 };

package/src/analyst-metric-families/round-timeline.ts

@@ -82,13 +82,10 @@ function projectTerminal(facts: AnalystReadableRunFacts): AnalystRoundTimelineTe
   if (facts.terminal.status === "absent") {
     return { kind: "death", channel: "no-receipt" };
   }
-  if (facts.terminal.file === "error.json") {
+  if (facts.terminal.face === "error") {
     return { kind: "death", channel: "error" };
   }
-  if (facts.terminal.file === "audit-incomplete.json") {
-    return { kind: "death", channel: "audit-incomplete" };
-  }
-  // report.json — receipt face; classCount only when producer wrote a number.
+  // report face — receipt; classCount only when producer wrote a number.
   const status = extractStatus(facts.terminal.body);
   const classCount = readClassCount(facts.terminal.body);
   const receiptStatus = status ?? "unparsed";

package/src/analyst-page.ts

@@ -28,9 +28,9 @@ export type AnalystMissingSource =
   /** Model-groups mode: leg has no usable session model identity. */
   | "session-model"
   /**
-   * Nested session/auditor-roles volume was discovered but failed canonical
-   * read/parse (#446). Missing auditor-roles directory is lawful zero rounds,
-   * not this face.
+   * A booked officer pointer or its session failed canonical read/parse (#446).
+   * No officers booked is lawful zero rounds, not this face.
+   * Public label stays `auditor-roles` (终局来源标签以外不得改名).
    */
   | "auditor-roles";
 

package/src/archivist-record-entry.ts

@@ -31,6 +31,7 @@ import {
 } from "./archivist-record-topology.ts";
 import type { HostRecordSession, RecordSessionHost } from "./host-contracts.ts";
 import { piRecordSessionHost } from "./pi/record-session-host.ts";
+import { sitianVolumeDirectory } from "./sitian-appender.ts";
 export {
   DIRECT_OFFICER_RUN_POINTER_KIND,
   bookDirectOfficerRunPointer,
@@ -47,7 +48,7 @@ const CURRENT_SESSION_LEDGER = "current-session.json";
 type CurrentSessionRecord = { readonly sessionFile: string };
 
 function readCurrentSession(sessionDir: string): string {
-  const ledger = join(sessionDir, CURRENT_SESSION_LEDGER);
+  const ledger = currentSessionLedgerPath(sessionDir);
   try {
     const value: unknown = JSON.parse(readFileSync(ledger, "utf8"));
     if (
@@ -68,7 +69,7 @@ function readCurrentSession(sessionDir: string): string {
 }
 
 function writeCurrentSession(sessionDir: string, sessionFile: string): void {
-  const ledger = join(sessionDir, CURRENT_SESSION_LEDGER);
+  const ledger = currentSessionLedgerPath(sessionDir);
   try {
     writeFileSync(ledger, `${JSON.stringify({ sessionFile })}\n`, { flag: "wx" });
   } catch (error) {
@@ -292,7 +293,7 @@ export type RecordSessionParent = {
 export type CreateRecordSessionOptions = {
   /** Role working directory passed to the record session; not a placement input. */
   readonly cwd: string;
-  /** What kind of record this is (e.g. "auditor-roles"). Single path segment; not a destination path. */
+  /** What kind of record this is (e.g. "attendance"). Single path segment; not a destination path. */
   readonly kind: string;
   /** Parent session — nesting authority for ordinary kinds; optional parentSession link for navigator. */
   readonly parent?: RecordSessionParent;
@@ -372,7 +373,7 @@ export type RecordSessionOpen = {
  * symlink). New principals mint under the already-validated sessionDir.
  * Navigator work-subject nests use their AK ledger; worker-submission-gate asks the
  * host to continue its recent native session without selecting a stored file path.
- * Other ordinary no-subject children (auditor-roles, …) always mint fresh.
+ * Other ordinary no-subject children (attendance, …) always mint fresh.
  * New persisted principals materialize their deferred session header before return so
  * custom-entry-only writers do not need a parallel delayed-header helper.
  *
@@ -420,7 +421,7 @@ export function createRecordSessionOpen(
     // Ordinary kinds: durable parent's file is the sole nesting authority. A divergent
     // SessionManager directory must not create a second placement route.
     // Do not restore generic bookDir/<kind> fallback for foreign/unrooted parents.
-    sessionDir = join(dirname(parentResolved), options.kind);
+    sessionDir = sitianVolumeDirectory(dirname(parentResolved), options.kind);
     parentSession = parentFile;
     mayResumeSameNest = options.kind === WORKER_SUBMISSION_GATE_KIND;
   }