@akagilnc/pi-workflow-roles 0.1.2369 → 0.1.2377

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.2369",
+  "version": "0.1.2377",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

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

@@ -1,8 +1,10 @@
 /**
  * Sole nested-volume reader for gate-cycle facts under session/auditor-roles/.
  *
- * Called only from the Analyst sole ledger scan (classifyScopedRun). Metric
- * families must not open a second disk scan — they consume retained facts.
+ * Consumers: Analyst sole ledger scan (classifyScopedRun) and Terminal menxia
+ * 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).
  *
  * Naming: records may carry pre-#440 menxia/jishizhong/fubaolang tool faces or
  * the current gatekeeper/inspector/notary English face. Projection always uses
@@ -40,8 +42,20 @@ export type AnalystGateCycleRound = {
   readonly officerWallMs: number;
   readonly officerStartedAt: string;
   readonly officerEndedAt: string;
-  /** findings[] length only — prose never retained. */
+  /**
+   * Typed string findings retained from the accepted officer receipt (#478 Terminal
+   * projection). Analyst metrics still consume findingsCount only — never prose.
+   */
+  readonly findings: readonly string[];
+  /** findings.length — retained so metric families need not re-derive. */
   readonly findingsCount: number;
+  /** Accepted dispatch receipt status (paired rounds are always "dispatch"). */
+  readonly dispatchStatus: string;
+  /**
+   * Optional seat-reduction reason from the accepted dispatch receipt.
+   * Absent when the dispatch did not write a non-empty reason — never invented.
+   */
+  readonly dispatchReason?: string;
 };
 
 const DISPATCH_TOOLS = new Set(["ak_menxia_output", "ak_gatekeeper_output"]);
@@ -80,6 +94,22 @@ function normalizeOfficerArg(raw: unknown): "inspector" | "notary" | undefined {
   return OFFICER_ARG_ALIASES[raw.trim()];
 }
 
+/** Typed string findings only — non-strings dropped; missing/non-array → []. */
+function asStringFindings(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+/**
+ * Optional non-empty dispatch reason. Trim only decides emptiness; a non-empty
+ * durable reason is returned as written (gatekeeper keeps reason as-is).
+ */
+function optionalDispatchReason(raw: unknown): string | undefined {
+  if (typeof raw !== "string") return undefined;
+  if (raw.trim() === "") return undefined;
+  return raw;
+}
+
 type AcceptedGateToolCall = {
   readonly toolName: string;
   readonly args: Record<string, unknown> | undefined;
@@ -177,6 +207,8 @@ type ClassifiedVolume =
       readonly kind: "dispatch";
       readonly startedAt: string;
       readonly officer: "inspector" | "notary";
+      readonly status: string;
+      readonly reason?: string;
     }
   | {
       readonly kind: "officer";
@@ -184,6 +216,7 @@ type ClassifiedVolume =
       readonly endedAt: string;
       readonly officer: "inspector" | "notary";
       readonly status: string;
+      readonly findings: readonly string[];
       readonly findingsCount: number;
       readonly officerWallMs: number;
     };
@@ -200,8 +233,8 @@ async function classifyAuditorVolume(
 
   const span = requireAcceptedGateSpan(rows, filePath);
   const status = requireAcceptedGateStatus(call.args, filePath);
-  const findings = call.args?.findings;
-  const findingsCount = Array.isArray(findings) ? findings.length : 0;
+  const findings = asStringFindings(call.args?.findings);
+  const findingsCount = findings.length;
 
   if (DISPATCH_TOOLS.has(call.toolName)) {
     // Gatekeeper contract terminals: dispatch | incomplete. Incomplete is a
@@ -218,10 +251,13 @@ async function classifyAuditorVolume(
         `accepted dispatch receipt missing or unknown officer in ${filePath}`,
       );
     }
+    const reason = optionalDispatchReason(call.args?.reason);
     return {
       kind: "dispatch",
       startedAt: span.startedAt,
       officer,
+      status,
+      ...(reason === undefined ? {} : { reason }),
     };
   }
 
@@ -238,6 +274,7 @@ async function classifyAuditorVolume(
     endedAt: span.endedAt,
     officer,
     status,
+    findings,
     findingsCount,
     officerWallMs: span.wallMs,
   };
@@ -278,7 +315,10 @@ function pairGateRounds(
       officerWallMs: match.officer.officerWallMs,
       officerStartedAt: match.officer.startedAt,
       officerEndedAt: match.officer.endedAt,
+      findings: match.officer.findings,
       findingsCount: match.officer.findingsCount,
+      dispatchStatus: vol.status,
+      ...(vol.reason === undefined ? {} : { dispatchReason: vol.reason }),
     });
   }
 

package/src/public-cli/settlement.ts

@@ -8,6 +8,11 @@ import { constants as fsConstants } from "node:fs";
 import { appendFile, lstat, mkdir, open, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
+import {
+  readAnalystGateCyclesFromAuditorRoles,
+  type AnalystGateCycleRound,
+} from "../analyst-gate-cycles-read.ts";
+
 import { isAuditEscalationResult } from "../audit-escalation.ts";
 import { AUDITOR_SOUL_ROLES } from "../auditor-soul.ts";
 import { DOCTOR_AUDIT_TOOL_NAME } from "../doctor-auditor.ts";
@@ -119,6 +124,8 @@ import {
   type AuditIncompleteResidual,
   type ControlledFailureCause,
   type TerminalArtifactRef,
+  type TerminalMenxiaFact,
+  type TerminalMenxiaSeat,
   type TerminalNavigatorFact,
   type TerminalResult,
   type TerminalResume,
@@ -2088,21 +2095,27 @@ export async function trySettleComplianceAuditIncompleteTerminalResult(
     outputToolName,
   );
   if (extracted === undefined) return undefined;
+  // Catch covers publication only — menxia read errors keep their session/JSONL identity
+  // and must not be washed into the publication-failure label.
+  let evidence: TerminalArtifactRef;
   try {
-    const evidence = await publishComplianceAuditIncompleteEvidence(
+    evidence = await publishComplianceAuditIncompleteEvidence(
       admitted,
       extracted.outcome,
     );
-    return {
-      roleOutcome: extracted.outcome,
-      navigator: extractNavigatorFact(entries),
-      artifacts: [evidence],
-      runId: admitted.runId,
-    };
   } catch (error) {
     // Publication failure is a non-lawful terminal, never an accepted audit result.
     return auditPublicationFailureTerminal(admitted, entries, extracted.outcome, error);
   }
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome: extracted.outcome,
+      navigator: extractNavigatorFact(entries),
+      artifacts: [evidence],
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Lawful Judge outcomes extracted from session (never a fabricated failure Receipt). */
@@ -2249,6 +2262,75 @@ function parseNavigatorAttendanceDetails(
   };
 }
 
+/**
+ * Project paired gate-cycle rounds onto the public Terminal menxia region (#478).
+ * actualSeats are derived only from accepted paired receipts — never from soul
+ * expected/missing officer judgments.
+ */
+export function projectTerminalMenxiaFact(
+  rounds: readonly AnalystGateCycleRound[],
+): TerminalMenxiaFact | undefined {
+  if (rounds.length === 0) return undefined;
+  const seen = new Set<TerminalMenxiaSeat>();
+  // Every paired round implies an accepted gatekeeper dispatch volume.
+  seen.add("gatekeeper");
+  for (const round of rounds) seen.add(round.officer);
+  const actualSeats = (["gatekeeper", "inspector", "notary"] as const).filter(
+    (seat) => seen.has(seat),
+  );
+  return {
+    actualSeats,
+    rounds: rounds.map((round) => ({
+      roundIndex: round.roundIndex,
+      dispatch: {
+        status: round.dispatchStatus,
+        officer: round.officer,
+        ...(round.dispatchReason === undefined
+          ? {}
+          : { reason: round.dispatchReason }),
+      },
+      officer: {
+        seat: round.officer,
+        status: round.status,
+        findings: round.findings,
+      },
+    })),
+  };
+}
+
+/**
+ * Read menxia facts from the run's session/auditor-roles nest via the sole
+ * nested-volume reader (#446/#478). Missing directory → undefined (no-gate
+ * zero change). Damaged discovered volumes propagate — never wash to "no gate".
+ */
+export async function extractMenxiaFactFromSessionDirectory(
+  sessionDirectory: string,
+): Promise<TerminalMenxiaFact | undefined> {
+  const rounds = await readAnalystGateCyclesFromAuditorRoles(
+    join(sessionDirectory, "auditor-roles"),
+  );
+  return projectTerminalMenxiaFact(rounds);
+}
+
+/**
+ * Attach optional menxia projection onto a settled Terminal base.
+ * Shared by every settle path so auditor-roles is scanned once here only.
+ * `runId` is not required — resumable failures omit it by contract.
+ * Menxia read damage propagates with its real identity (never washed to no-gate
+ * or swallowed); callers that already hold a controlled failure still surface the
+ * JSONL/session cause rather than pretend the gate was absent.
+ */
+async function withOptionalMenxiaProjection<
+  T extends {
+    roleOutcome: TerminalRoleOutcome;
+    navigator: TerminalNavigatorFact;
+    artifacts: readonly TerminalArtifactRef[];
+  },
+>(base: T, sessionDirectory: string): Promise<T & { menxia?: TerminalMenxiaFact }> {
+  const menxia = await extractMenxiaFactFromSessionDirectory(sessionDirectory);
+  return menxia === undefined ? base : { ...base, menxia };
+}
+
 export function extractNavigatorFact(
   entries: readonly SessionEntry[],
 ): TerminalNavigatorFact {
@@ -2580,12 +2662,15 @@ async function settleLawfulJudgeTerminalResult(
     roleOutcome,
     admitted.sessionDirectory,
   );
-  return {
-    roleOutcome,
-    navigator,
-    artifacts,
-    runId: admitted.runId,
-  };
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome,
+      navigator,
+      artifacts,
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /**
@@ -2638,12 +2723,15 @@ async function settleLawfulCoderTerminalResult(
         : { methodProvenance: options.methodProvenance }),
     },
   );
-  return {
-    roleOutcome: extracted.outcome,
-    navigator,
-    artifacts,
-    runId: admitted.runId,
-  };
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome: extracted.outcome,
+      navigator,
+      artifacts,
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Settle a lawful Coder Terminal from the admitted session (shared #106 success interface). */
@@ -2847,12 +2935,15 @@ async function settleLawfulFixerTerminalResult(
       methodInvocations,
     },
   );
-  return {
-    roleOutcome: extracted.outcome,
-    navigator,
-    artifacts,
-    runId: admitted.runId,
-  };
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome: extracted.outcome,
+      navigator,
+      artifacts,
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Settle a lawful Fixer Terminal from the admitted session (shared #106 success interface). */
@@ -3005,12 +3096,15 @@ async function settleLawfulCollectorTerminalResult(
     admitted.sessionDirectory,
     { collectorReceipt: extracted.receipt },
   );
-  return {
-    roleOutcome: extracted.outcome,
-    navigator,
-    artifacts,
-    runId: admitted.runId,
-  };
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome: extracted.outcome,
+      navigator,
+      artifacts,
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Settle a lawful Collector Terminal from the admitted session. */
@@ -3189,12 +3283,15 @@ async function settleLawfulDoctorTerminalResult(
     admitted.sessionDirectory,
     extracted.output === undefined ? {} : { doctorOutput: extracted.output },
   );
-  return {
-    roleOutcome: extracted.outcome,
-    navigator,
-    artifacts,
-    runId: admitted.runId,
-  };
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome: extracted.outcome,
+      navigator,
+      artifacts,
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Settle a lawful Doctor Terminal from the admitted session. */
@@ -3283,12 +3380,15 @@ async function settleLawfulNotaryTerminalResult(
     return undefined;
   }
   const navigator = extractNavigatorFact(entries);
-  return {
-    roleOutcome: extracted.outcome,
-    navigator,
-    artifacts: [],
-    runId: admitted.runId,
-  };
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome: extracted.outcome,
+      navigator,
+      artifacts: [],
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Settle a lawful Notary Terminal from the admitted session. */
@@ -3549,12 +3649,15 @@ async function settleLawfulReviewerTerminalResult(
       methodInvocations,
     },
   );
-  return {
-    roleOutcome: extracted.outcome,
-    navigator,
-    artifacts,
-    runId: admitted.runId,
-  };
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome: extracted.outcome,
+      navigator,
+      artifacts,
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Settle a lawful Reviewer Terminal from the admitted session (shared #106 success interface). */
@@ -3815,12 +3918,15 @@ async function settleLawfulMergerTerminalResult(
       methodInvocations,
     },
   );
-  return {
-    roleOutcome: extracted.outcome,
-    navigator,
-    artifacts,
-    runId: admitted.runId,
-  };
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome: extracted.outcome,
+      navigator,
+      artifacts,
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Settle a lawful Merger Terminal from the admitted session (shared #106 success interface). */
@@ -4170,10 +4276,16 @@ export async function settleFailureTerminalResult(
           const facts = parseNoReceiptLifecycleFacts(raw);
           if (facts.runPointer === admitted.runDirectory && facts.attemptPointer === `current:${admitted.runDirectory}`) {
             const decisiveFacts: NoReceiptLifecycleFacts = facts;
-            return {
-              roleOutcome: { kind: "no_receipt", role: admitted.role, status: "no-accepted-receipt", ...facts, decisiveFacts },
-              navigator: await extractNavigatorFactFromAdmittedSession(admitted), artifacts: [], runId: admitted.runId,
-            };
+            // #478: no_receipt is still a public Terminal — project accepted gate facts.
+            return withOptionalMenxiaProjection(
+              {
+                roleOutcome: { kind: "no_receipt", role: admitted.role, status: "no-accepted-receipt", ...facts, decisiveFacts },
+                navigator: await extractNavigatorFactFromAdmittedSession(admitted),
+                artifacts: [],
+                runId: admitted.runId,
+              },
+              admitted.sessionDirectory,
+            );
           }
         } catch { /* malformed lifecycle bytes remain the existing nonzero output failure */ }
       }
@@ -4213,12 +4325,16 @@ export async function settleFailureTerminalResult(
       diagnostic: publicDiagnostic,
       decisiveFacts: publicFacts,
     };
-    return {
-      roleOutcome,
-      navigator: redactNavigatorFactForPublicTerminal(navigator, admitted.runId),
-      artifacts: [],
-      resume: options.resume,
-    };
+    // #478: resume desensitization stays; menxia is additive typed fact only.
+    return withOptionalMenxiaProjection(
+      {
+        roleOutcome,
+        navigator: redactNavigatorFactForPublicTerminal(navigator, admitted.runId),
+        artifacts: [],
+        resume: options.resume,
+      },
+      admitted.sessionDirectory,
+    );
   }
   const roleOutcome: TerminalRoleOutcome = {
     kind: "failure",
@@ -4227,12 +4343,16 @@ export async function settleFailureTerminalResult(
     diagnostic: failure.diagnostic,
     decisiveFacts,
   };
-  return {
-    roleOutcome,
-    navigator,
-    artifacts,
-    runId: admitted.runId,
-  };
+  // #478: ordinary controlled failure still surfaces accepted gate facts.
+  return withOptionalMenxiaProjection(
+    {
+      roleOutcome,
+      navigator,
+      artifacts,
+      runId: admitted.runId,
+    },
+    admitted.sessionDirectory,
+  );
 }
 
 /** Judge-named alias retained for #107 call sites. */

package/src/public-cli/terminal.ts

@@ -215,6 +215,42 @@ export type TerminalResume = {
   readonly command: string;
 };
 
+/** Current English menxia seat faces projected on Terminal (#478). */
+export type TerminalMenxiaSeat = "gatekeeper" | "inspector" | "notary";
+
+/** One accepted province dispatch receipt (status/officer + optional reduce-seat reason). */
+export type TerminalMenxiaDispatch = {
+  readonly status: string;
+  readonly officer: "inspector" | "notary";
+  /** Present only when the accepted dispatch wrote a non-empty reason. */
+  readonly reason?: string;
+};
+
+/** One accepted officer report: seat, status, full typed findings. */
+export type TerminalMenxiaOfficerReport = {
+  readonly seat: "inspector" | "notary";
+  readonly status: string;
+  readonly findings: readonly string[];
+};
+
+/** One paired dispatch↔officer gate round on the public Terminal. */
+export type TerminalMenxiaRound = {
+  readonly roundIndex: number;
+  readonly dispatch: TerminalMenxiaDispatch;
+  readonly officer: TerminalMenxiaOfficerReport;
+};
+
+/**
+ * Optional menxia province projection (#478).
+ * Absent when no accepted paired gate rounds exist (no-gate zero change).
+ * Only durable accepted child receipts — never soul-derived expected/missing seats.
+ */
+export type TerminalMenxiaFact = {
+  /** Seats that actually ran, derived from accepted paired receipts. */
+  readonly actualSeats: readonly TerminalMenxiaSeat[];
+  readonly rounds: readonly TerminalMenxiaRound[];
+};
+
 /** Public free-text stand-in when an exact Role run ID is stripped outside resume.command. */
 export const REDACTED_RUN_ID_TOKEN = "[run-id]" as const;
 
@@ -240,6 +276,11 @@ export type TerminalResult = {
   roleOutcome: TerminalRoleOutcome;
   navigator: TerminalNavigatorFact;
   artifacts: readonly TerminalArtifactRef[];
+  /**
+   * Optional menxia province facts (#478). Present only when accepted paired
+   * gate rounds exist under session/auditor-roles; omitted on no-gate runs.
+   */
+  menxia?: TerminalMenxiaFact;
   /** Call-local auto-resume observation (0..2) for this single LLM call; read-only, not persisted. */
   autoResumeCount?: number;
 } & (
@@ -330,6 +371,22 @@ export function formatTerminalResult(result: TerminalResult): string {
   for (const artifact of result.artifacts) {
     lines.push(`artifact\t${artifact.kind}\t${encodeTerminalField(artifact.path)}`);
   }
+  // Menxia region is unfrozen presentation of typed facts (ADR 0052) — machines
+  // read result.menxia, never these row labels.
+  if (result.menxia !== undefined) {
+    lines.push(
+      `menxia\t${encodeTerminalField(result.menxia.actualSeats.join(","))}\t${result.menxia.rounds.length}`,
+    );
+    for (const round of result.menxia.rounds) {
+      const reason =
+        round.dispatch.reason === undefined
+          ? ""
+          : encodeTerminalField(round.dispatch.reason);
+      lines.push(
+        `menxia-round\t${round.roundIndex}\t${round.dispatch.status}\t${round.dispatch.officer}\t${reason}\t${round.officer.seat}\t${encodeTerminalField(round.officer.status)}\t${encodeTerminalField(JSON.stringify(round.officer.findings))}`,
+      );
+    }
+  }
   if (result.resume !== undefined) {
     // Resumable failure: run ID is revealed only inside the complete resume command.
     lines.push(`resume\t${encodeTerminalField(result.resume.command)}`);