@akagilnc/pi-workflow-roles 0.1.4035 → 0.1.4193

package/src/book-topology-runs-migrator.ts

@@ -0,0 +1,244 @@
+/**
+ * #865 T9: migrate retained runs into ticket-scoped or unbound placement.
+ * Inventory covers legacy flat `runs/`, existing `<ticket>/runs/`, and
+ * `unbound/runs/`. Attribution reuses the shared migrating-run helper;
+ * already-canonical trees copy as-is.
+ */
+import { cp, mkdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, sep } from "node:path";
+
+import {
+  destinationRunDirectory,
+  isMigrationEnoent,
+  isTicketNumberString,
+  listBackupRunLeaves,
+  listMigrationBookKeys,
+  resolveMigratingRunTicket,
+} from "./book-topology-migration-placement.ts";
+import {
+  reconcileMigrationPartition,
+  type BookTopologyMigrationContext,
+  type BookTopologyPartitionMigrator,
+  type MigrationItemOutcome,
+} from "./book-topology-migration.ts";
+import {
+  rewriteRoleRunDurablePages,
+  type RunDirectoryPathRewrite,
+} from "./role-run-relocation.ts";
+import { MIGRATION_TICKET_DERIVATION_PAGE } from "./run-ticket-number.ts";
+
+const RUNS_PARTITION = "runs";
+
+const RUN_LEAF =
+  /^([A-Za-z0-9][A-Za-z0-9._-]*)@([A-Za-z][A-Za-z0-9_-]*)$/;
+
+type RunLeaf = { readonly runId: string; readonly role: string };
+
+type PlannedRunMove = {
+  readonly sourcePath: string;
+  readonly sourceIdentity: string;
+  readonly isDirectory: boolean;
+  readonly disposition: "placed" | "unbound";
+  readonly targetPath: string;
+  readonly historicalRunDirectory: string | undefined;
+  readonly derivation:
+    | { readonly ticketNumber: number; readonly projectRoot: string; readonly sourcePage: string }
+    | undefined;
+};
+
+function parseRunLeaf(name: string): RunLeaf | undefined {
+  const match = RUN_LEAF.exec(name);
+  if (match === null) return undefined;
+  return { runId: match[1]!, role: match[2]! };
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isMigrationEnoent(error)) return false;
+    throw error;
+  }
+}
+
+async function writeDerivationPage(
+  targetRunDirectory: string,
+  derivation: {
+    readonly ticketNumber: number;
+    readonly projectRoot: string;
+    readonly sourcePage: string;
+  },
+): Promise<void> {
+  const page = {
+    ticketNumber: derivation.ticketNumber,
+    derivation: "worktree-path-basename" as const,
+    source: {
+      page: derivation.sourcePage,
+      field: "projectRoot",
+      path: derivation.projectRoot,
+      basename: basename(derivation.projectRoot),
+    },
+  };
+  await writeFile(
+    join(targetRunDirectory, MIGRATION_TICKET_DERIVATION_PAGE),
+    `${JSON.stringify(page, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+async function copyRunTree(
+  source: string,
+  target: string,
+  isDirectory: boolean,
+): Promise<void> {
+  await mkdir(dirname(target), { recursive: true });
+  if (isDirectory) {
+    await cp(source, target, { recursive: true, preserveTimestamps: true });
+    return;
+  }
+  await cp(source, target, { preserveTimestamps: true });
+}
+
+async function planBookMoves(
+  backupBooksDirectory: string,
+  booksDirectory: string,
+  bookKey: string,
+): Promise<readonly PlannedRunMove[]> {
+  const backupBook = join(backupBooksDirectory, bookKey);
+  const claimed = new Map<string, string>();
+  const planned: PlannedRunMove[] = [];
+
+  for (const leaf of await listBackupRunLeaves(backupBook)) {
+    const sourceIdentity = relative(backupBooksDirectory, leaf.sourcePath)
+      .split(sep)
+      .join("/");
+    const parsed = leaf.isDirectory ? parseRunLeaf(leaf.leafName) : undefined;
+
+    let targetPath: string;
+    let disposition: "placed" | "unbound";
+    let historicalRunDirectory: string | undefined;
+    let derivation: PlannedRunMove["derivation"];
+
+    if (leaf.layout === "issues") {
+      // issues/<ticket>/runs/<leaf> → <ticket>/runs/<leaf>; conflict refuses below.
+      const parts = leaf.relativePath.replaceAll("\\", "/").split("/");
+      const ticketStr = parts[1];
+      if (ticketStr !== undefined && isTicketNumberString(ticketStr)) {
+        targetPath = join(booksDirectory, bookKey, ticketStr, "runs", leaf.leafName);
+        disposition = "placed";
+        historicalRunDirectory = join(
+          booksDirectory,
+          bookKey,
+          "issues",
+          ticketStr,
+          "runs",
+          leaf.leafName,
+        );
+      } else {
+        targetPath = join(booksDirectory, bookKey, "unbound", "runs", leaf.leafName);
+        disposition = "unbound";
+        historicalRunDirectory = join(booksDirectory, bookKey, leaf.relativePath);
+      }
+      derivation = undefined;
+    } else if (leaf.layout !== "flat") {
+      targetPath = join(booksDirectory, bookKey, leaf.relativePath);
+      disposition = leaf.layout === "unbound" ? "unbound" : "placed";
+      historicalRunDirectory = undefined;
+      derivation = undefined;
+    } else if (parsed === undefined) {
+      targetPath = join(booksDirectory, bookKey, "unbound", "runs", leaf.leafName);
+      disposition = "unbound";
+      historicalRunDirectory = join(booksDirectory, bookKey, "runs", leaf.leafName);
+      derivation = undefined;
+    } else {
+      const ticket = await resolveMigratingRunTicket(leaf.sourcePath);
+      targetPath = destinationRunDirectory(
+        booksDirectory,
+        bookKey,
+        ticket.ticketNumber,
+        parsed.runId,
+        parsed.role,
+      );
+      disposition = ticket.ticketNumber === undefined ? "unbound" : "placed";
+      historicalRunDirectory = join(booksDirectory, bookKey, "runs", leaf.leafName);
+      derivation =
+        ticket.derivation?.method === "project-root-basename"
+          && ticket.ticketNumber !== undefined
+          ? {
+              ticketNumber: ticket.ticketNumber,
+              projectRoot: ticket.derivation.source,
+              sourcePage: ticket.derivation.sourcePage,
+            }
+          : undefined;
+    }
+
+    const prior = claimed.get(targetPath);
+    if (prior !== undefined) {
+      throw new Error(
+        `book topology migration refuses to overwrite ${targetPath} (already claimed by ${prior}) with ${leaf.sourcePath}`,
+      );
+    }
+    claimed.set(targetPath, leaf.sourcePath);
+    planned.push({
+      sourcePath: leaf.sourcePath,
+      sourceIdentity,
+      isDirectory: leaf.isDirectory,
+      disposition,
+      targetPath,
+      historicalRunDirectory,
+      derivation,
+    });
+  }
+  return planned;
+}
+
+export const bookTopologyRunsMigrator: BookTopologyPartitionMigrator = {
+  partition: RUNS_PARTITION,
+  async migrate(context: BookTopologyMigrationContext) {
+    const outcomes: MigrationItemOutcome[] = [];
+    const { backupBooksDirectory, booksDirectory } = context;
+
+    for (const bookKey of await listMigrationBookKeys(backupBooksDirectory)) {
+      const planned = await planBookMoves(
+        backupBooksDirectory,
+        booksDirectory,
+        bookKey,
+      );
+
+      const crossRunRewrites: RunDirectoryPathRewrite[] = planned
+        .filter((move) => move.isDirectory && move.historicalRunDirectory !== undefined)
+        .map((move) => ({
+          oldRunDirectory: move.historicalRunDirectory!,
+          newRunDirectory: move.targetPath,
+        }));
+
+      for (const move of planned) {
+        if (await pathExists(move.targetPath)) {
+          throw new Error(
+            `book topology migration refuses to overwrite ${move.targetPath} with ${move.sourcePath}`,
+          );
+        }
+        await copyRunTree(move.sourcePath, move.targetPath, move.isDirectory);
+        if (move.isDirectory) {
+          await rewriteRoleRunDurablePages({
+            pagesDirectory: move.targetPath,
+            oldRunDirectory: move.historicalRunDirectory ?? move.targetPath,
+            newRunDirectory: move.targetPath,
+            crossRunRewrites,
+          });
+        }
+        if (move.isDirectory && move.derivation !== undefined) {
+          await writeDerivationPage(move.targetPath, move.derivation);
+        }
+
+        outcomes.push({
+          disposition: move.disposition,
+          source: move.sourceIdentity,
+        });
+      }
+    }
+
+    return reconcileMigrationPartition(RUNS_PARTITION, "entries", outcomes);
+  },
+};

package/src/diarist-contracts.ts

@@ -12,6 +12,10 @@ import type {
   TicketProvenanceSourceKind,
   TicketProvenanceSourceRef,
 } from "./ticket-provenance-contracts.ts";
+import {
+  isSafePositiveTicketNumber,
+  requireSafePositiveTicketNumber,
+} from "./run-ticket-number.ts";
 
 export const DIARIST_OUTPUT_TOOL_NAME = "ak_diarist_output";
 export const DIARIST_ACCEPTED_TEXT = "起居郎回执已接受";
@@ -39,6 +43,15 @@ export type DiaristOutput =
        * LLM owns recognition; mechanical layer does not re-judge the number.
        */
       readonly ticketNumber?: number | null;
+      /**
+       * #871 typed co-review set (ADR 0075 `diarist-resolves-ticket-llm-layer` narrow extension).
+       * Positive integers = tickets that should each receive a diary this court (includes main).
+       * Field absent → no new set this turn (resume keeps stored run fact; first court defaults to [main]).
+       * Explicit empty array → single-ticket face [main] whole-set replace.
+       * Non-empty with zero lawful members after type projection is not a new set (call site).
+       * Mechanical layer only type-projects/dedupes and guarantees principal membership when applying a set.
+       */
+      readonly courtTicketNumbers?: readonly number[] | null;
       /** Whole blocks to append under the asserted ticket. Empty list is lawful. */
       readonly entries?: readonly DiaristEntrySubmission[];
     }
@@ -48,6 +61,109 @@ export type DiaristOutput =
       readonly reason: string;
     };
 
+/**
+ * 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: unknown,
+  options?: { readonly principalTicket?: number },
+): readonly number[] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: number[] = [];
+  const seen = new Set<number>();
+  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: Record<string, unknown>,
+  options?: { readonly principalTicket?: number },
+):
+  | { readonly kind: "absent" }
+  | { readonly kind: "ok"; readonly tickets: readonly number[] }
+  | { readonly kind: "damage"; readonly reason: string } {
+  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: readonly number[],
+  right: readonly number[],
+): boolean {
+  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: unknown): DiaristOutput {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new Error("Diarist output has no execution discriminator");

package/src/diarist-role.ts

@@ -35,6 +35,12 @@ export const diaristOutputSchema = withInfrastructureFailureDeclaration(
             "本庭对象票号（正整数）或 null/省略＝真无票；下游走 typed 键；认不出用 status=escalate，不洗成无录。机械层不重判。",
         }),
       ),
+      courtTicketNumbers: Type.Optional(
+        Type.Unknown({
+          description:
+            "#871 本次合审应各自成录的票号集合（正整数数组，含主票）；单票可省略。机械层只做类型/去重投影，不从散文猜票。",
+        }),
+      ),
       reason: Type.Optional(
         Type.String({
           description: "status 为 escalate 时：认不出本庭对象的原因",

package/src/diarist.ts

@@ -42,6 +42,7 @@ export type DiaristCommitFacts = {
 export async function commitDiaristEntries(input: {
   readonly ticketNumber: number;
   readonly cwd: string;
+  readonly sessionParent: string;
   readonly home?: string;
   readonly entries: readonly unknown[];
 }): Promise<DiaristCommitFacts> {
@@ -59,6 +60,7 @@ export async function commitDiaristEntries(input: {
     appendTicketProvenanceEntry({
       ticketNumber,
       cwd,
+      sessionParent: input.sessionParent,
       ...homeOpt,
       payload: submitted,
       source: "diarist",

package/src/doctor-auditor.ts

@@ -26,7 +26,7 @@ export type DoctorAuditOptions = {
  */
 export function createPiDoctorAuditor(): (options: DoctorAuditOptions) => Promise<ComplianceDecision> {
   return async (options) => {
-    const dossier = resolveAuditDossier();
+    const dossier = resolveAuditDossier(options.context);
     requireAuditMaterials(dossier);
     const subjects = readDoctorAuditSubjects(options.context);
     requireAuditMaterials(subjects);

package/src/doctor-evidence.ts

@@ -37,7 +37,10 @@ function deriveSession(content: string, id: string): SessionDerivation {
 
 /** Read Pi's retained session directory as the sole raw material for one case. */
 export async function loadDoctorCase(runsPath: string): Promise<DoctorCase> {
-  const root = await realpath(runsPath); 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");
+  const root = await realpath(runsPath);
+  // 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>/<n>/runs directory");
   const evidence: DoctorEvidenceEntry[] = [], sessions: DoctorCaseCost["sessions"] = [], statuses: DoctorCaseCost["statuses"] = [], commits: DoctorCaseCost["commits"] = [];
   const turns: DoctorCount = { count: 0, sources: [] }, calls: DoctorCount = { count: 0, sources: [] }, tokens: DoctorCount = { count: 0, sources: [] };
   for (const path of await discoverCaseFiles(root)) { const id = relative(root, path).split(sep).join("/"); const bytes = await readFile(path); const content = bytes.toString("utf8"); const kind = id.endsWith(".jsonl") ? "session" : "stderr"; evidence.push({ id, kind, byteLength: bytes.byteLength, contentLength: content.length, sha256: sha256Hex(bytes), content }); if (kind === "stderr") continue; const result = deriveSession(content, id); sessions.push(result.session); statuses.push(...result.statuses); commits.push(...result.commits); accumulate(turns, result.turns, id); accumulate(calls, result.calls, id); accumulate(tokens, result.tokens, id); }

package/src/doctor-role.ts

@@ -8,7 +8,7 @@ import { DOCTOR_ACCEPTED_AUDIT_NO_RECEIPT_TEXT, DOCTOR_ACCEPTED_TEXT, DOCTOR_EVI
 import { sitianReport } from "./sitian-facade.ts";
 
 export { DOCTOR_EVIDENCE_TOOL_NAME, DOCTOR_OUTPUT_TOOL_NAME };
-export const DOCTOR_CASE_FLAG = { name: "ak-doctor-case", definition: { description: "Retained .ak-roles/books/<book>/issues/<n>/runs directory", type: "string" as const } } as const;
+export const DOCTOR_CASE_FLAG = { name: "ak-doctor-case", definition: { description: "Retained .ak-roles/books/<book>/<n>/runs directory", type: "string" as const } } as const;
 export type DoctorRoleDependencies = { loadSoul(): Promise<string>; loadCase(path: string): Promise<DoctorCase>; auditCompliance(options: { context: HostContext; signal?: AbortSignal }): Promise<ComplianceDecision> };
 function appendCandidate(ctx: HostContext, data: unknown): void {
   try {

package/src/dossier-resolution.ts

@@ -1,10 +1,13 @@
 /**
  * Unique dossier-resolution seam for 审刑院 (#233).
- * Machine pointers only: cwd + AK_ROLE_RUN_DIR. No latest-run / mtime / global scan.
+ * Machine pointers only: cwd + per-turn HostContext (Pi child env fallback).
+ * No latest-run / mtime / global scan.
  */
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.ts";
+
 export const AUDIT_RUN_DIR_ENV = "AK_ROLE_RUN_DIR" as const;
 export const DOCTOR_CANDIDATE_ENTRY_TYPE = "ak_doctor_audit_candidate" as const;
 
@@ -33,18 +36,33 @@ export type SubjectIncomplete = {
 };
 export type SubjectResolution = SubjectOk | SubjectIncomplete;
 
+function isHostContext(value: object): value is HostContext {
+  return "sessionManager" in value;
+}
+
+function dossierPointerFrom(source?: HostContext | NodeJS.ProcessEnv): string | undefined {
+  if (source !== undefined && isHostContext(source)) {
+    return runDirectoryFromHostContext(source);
+  }
+  const env = source ?? process.env;
+  const raw = env[AUDIT_RUN_DIR_ENV];
+  return typeof raw === "string" && raw.trim() !== "" ? raw : undefined;
+}
+
 /**
- * Resolve the per-run dossier pointer injected by the public CLI.
+ * Resolve the per-run dossier pointer.
  *
+ * ACP/headless: typed HostContext.runDirectory.
+ * Pi child: HostContext projected from env, or env fallback when no context.
  * Absent pointer = bare Pi internal seam (ADR 0052): audit proceeds; the model
- * self-locates the dossier from its own fall-volume position per soul. Public CLI
- * always injects the pointer — only then does the machine validate the path.
- * Concurrent runs stay isolated because a present pointer is per-process.
+ * self-locates the dossier from its own fall-volume position per soul.
  */
-export function resolveAuditDossier(env: NodeJS.ProcessEnv = process.env): DossierResolution {
-  const raw = env[AUDIT_RUN_DIR_ENV];
+export function resolveAuditDossier(
+  source?: HostContext | NodeJS.ProcessEnv,
+): DossierResolution {
+  const raw = dossierPointerFrom(source);
   // Bare Pi activation seam: no machine gate when the pointer was never injected.
-  if (typeof raw !== "string" || raw.trim() === "") {
+  if (raw === undefined) {
     return { status: "ok" };
   }
   const runDirectory = resolve(raw);

package/src/external-host-turn-loop.ts

@@ -9,6 +9,7 @@ import type {
   RoleTurnRequest,
   RoleTurnResult,
 } from "./host-contracts.ts";
+import { isOfficerReviewSeat } from "./host-contracts.ts";
 
 export const EXTERNAL_ROLE_TURN_ROUND_LIMIT = 8 as const;
 
@@ -54,8 +55,16 @@ export function mergeRoleTurnAbortSignals(
   return AbortSignal.any([prepared, request]);
 }
 
+/**
+ * Host-transition prior-native paths are machine handoff material (#617 DK-4).
+ * #879: station-child officer dialogue must not receive those paths spliced into
+ * the review prompt — officers already hold --source-run / binding pointers.
+ */
 export function promptWithPriorNativePaths(basePrompt: string, request: RoleTurnRequest): string {
   if (request.continuation.kind !== "resume") return basePrompt;
+  if (request.stationChild === true && isOfficerReviewSeat(request.activation.role)) {
+    return basePrompt;
+  }
   const paths = request.hostTransition?.priorNativePaths;
   if (paths === undefined || paths.length === 0) return basePrompt;
   return `${basePrompt}\n${paths.join("\n")}`;

package/src/gatekeeper-pass-envelope.ts

@@ -74,6 +74,11 @@ export async function requireGatekeeperPass(options: {
   readonly signal?: AbortSignal;
   readonly hostActions: GatekeeperPassHostActions;
   readonly toolCallId: string;
+  /**
+   * In-flight parent typed payload for this gate turn (#879). Relayed verbatim
+   * as officer dialogue content; binding pointer stays the parent run directory.
+   */
+  readonly submission?: unknown;
   /** Lowest seam: same as runGatekeeper options.summonOfficer — offline tracers only. */
   readonly summonOfficer?: GateOfficerSummon;
 }): Promise<void> {
@@ -85,6 +90,7 @@ export async function requireGatekeeperPass(options: {
       subject: options.subject,
       ...(options.signal === undefined ? {} : { signal: options.signal }),
       ...(options.summonOfficer === undefined ? {} : { summonOfficer: options.summonOfficer }),
+      ...(options.submission === undefined ? {} : { submission: options.submission }),
       ...(reask === undefined ? {} : { reask }),
     });
     const gatekeeper = projected.result;