@akagilnc/pi-workflow-roles 0.1.4062 → 0.1.4196

package/src/public-cli/invocation.ts

@@ -6,12 +6,12 @@ import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import {
   lstat,
-  mkdir,
   readFile,
   realpath,
+  rename,
   writeFile,
 } from "node:fs/promises";
-import { basename, isAbsolute, join, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 
 import {
   activationBookDirectory,
@@ -21,14 +21,31 @@ import {
   resolveActivationLedgerHome,
 } from "../activation-ledger-topology.ts";
 import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
+import {
+  ensureRoleRunDirectory,
+  ensureRoleRunPlacement,
+  roleRunArtifactsDirectory,
+  roleRunPlacement,
+  type RoleRunSubject,
+} from "../role-run-placement.ts";
 import type {
   DurablePrincipal,
   DurablePrincipalAuthority,
 } from "../host-contracts.ts";
-import { readRunTicketNumber } from "../run-ticket-number.ts";
+import {
+  isSafePositiveTicketNumber,
+  readBoardTicketNumber,
+  requireSafePositiveTicketNumber,
+} from "../run-ticket-number.ts";
+import {
+  rewriteRoleRunDurablePages,
+  rewriteRunDirectoryPathFields,
+  rewriteRunDirectoryPathValue,
+} from "../role-run-relocation.ts";
 import {
   loadDoctorCase,
 } from "../doctor-evidence.ts";
+import { projectCourtTicketNumbers } from "../diarist-contracts.ts";
 import type { DoctorCaseIdentity } from "../doctor-contracts.ts";
 import {
   emptyCollectorManifest,
@@ -121,6 +138,17 @@ export type AdmittedJudgeInvocation = AdmittedRoleInvocationBase & {
 
 export type AdmittedCountersignInvocation = AdmittedRoleInvocationBase & {
   readonly role: "countersign";
+  /**
+   * #871 typed co-review set for this countersign run (durable run fact).
+   * Main ticket remains `ticketNumber`; this set drives per-ticket court diarist refresh.
+   * Whole-set replace on new typed submission — never union with history.
+   */
+  courtTicketNumbers?: readonly number[];
+  /**
+   * Load-time durable set damage diagnostic (#871 B7). Resume must settle as
+   * countersign controlled failure with this text — never structural exit 2 or main-only.
+   */
+  courtTicketNumbersDamage?: string;
 };
 
 export type AdmittedGleanerLeftInvocation = AdmittedRoleInvocationBase & {
@@ -261,30 +289,36 @@ export type AdmissionPlacement = {
   readonly sessionDirectory: string;
   readonly sessionFile: string;
   readonly runDirectory: string;
+  readonly artifactsDirectory: string;
+  readonly attachmentsDirectory: string;
   readonly ledgerHome: string;
   readonly bookKey: string;
 };
 
-/** Issue principal + derive ledger placement through the injected authority only. */
+/** Issue a principal from the single authoritative role-run placement. */
 export function issueAdmissionPlacement(
   authority: DurablePrincipalAuthority,
   request: {
     readonly cwd: string;
     readonly runId: string;
     readonly role: AdmittedRoleInvocation["role"];
+    /** Identity already asserted by 起居郎; never derive this from CLI parameters. */
+    readonly subject: RoleRunSubject;
     readonly home?: string;
   },
 ): AdmissionPlacement {
-  const principal = authority.issue(request);
-  const { sessionDirectory, sessionFile } = authority.decode(principal);
-  const runDirectory = join(sessionDirectory, "..");
   const ledgerHome = resolveActivationLedgerHome(request.home);
   const bookKey = resolveBookKeyFromGit(request.cwd);
+  const placement = roleRunPlacement(ledgerHome, {
+    bookKey,
+    subject: request.subject,
+    runId: request.runId,
+    role: request.role,
+  });
+  ensureRoleRunPlacement(ledgerHome, placement);
   return {
-    principal,
-    sessionDirectory,
-    sessionFile,
-    runDirectory,
+    principal: authority.seal(placement),
+    ...placement,
     ledgerHome,
     bookKey,
   };
@@ -476,17 +510,50 @@ export async function bindAdmittedTicketNumber(
   admitted: AdmittedRoleInvocation,
   ticketNumber: number,
 ): Promise<void> {
-  if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1) {
-    throw new Error(`bindAdmittedTicketNumber requires a safe positive integer, got ${String(ticketNumber)}`);
-  }
   if (admitted.ticketNumber !== undefined) {
     if (admitted.ticketNumber === ticketNumber) return;
     throw new Error(
       `bindAdmittedTicketNumber refuses to replace existing ticket #${admitted.ticketNumber} with #${ticketNumber}`,
     );
   }
+  await bindTicketNumberOnRunDirectory(admitted.runDirectory, ticketNumber);
   (admitted as { ticketNumber?: number }).ticketNumber = ticketNumber;
-  await mergeInvocationIdentityPage(admitted.runDirectory, { ticketNumber });
+}
+
+/**
+ * #871: persist the typed co-review set as a countersign run fact (admitted-request +
+ * invocation.json). Whole-set replace — never union with a prior set. Main ticket
+ * binding stays on `ticketNumber` alone. Projection reuses the sole contract helper;
+ * principal membership is mandatory.
+ */
+export async function bindCourtTicketNumbersOnAdmitted(
+  admitted: AdmittedCountersignInvocation,
+  courtTicketNumbers: readonly number[],
+): Promise<void> {
+  if (admitted.ticketNumber === undefined) {
+    throw new Error(
+      "bindCourtTicketNumbersOnAdmitted requires a bound principal ticketNumber",
+    );
+  }
+  const principal = requireSafePositiveTicketNumber(
+    admitted.ticketNumber,
+    "bindCourtTicketNumbersOnAdmitted principal ticketNumber",
+  );
+  // Strict write path: every member must already be a lawful number (no soft filter).
+  for (const item of courtTicketNumbers) {
+    if (!isSafePositiveTicketNumber(item)) {
+      throw new Error(
+        `bindCourtTicketNumbersOnAdmitted requires safe positive integers, got ${String(item)}`,
+      );
+    }
+  }
+  const projected = projectCourtTicketNumbers(courtTicketNumbers, {
+    principalTicket: principal,
+  });
+  if (projected === null || projected.length === 0) {
+    throw new Error("bindCourtTicketNumbersOnAdmitted requires a non-empty ticket set");
+  }
+  const frozen = Object.freeze([...projected]);
   const admittedPath = admitted.admittedRequestPath;
   const current = JSON.parse(await readFile(admittedPath, "utf8")) as Record<
     string,
@@ -494,9 +561,64 @@ export async function bindAdmittedTicketNumber(
   >;
   await writeFile(
     admittedPath,
-    `${JSON.stringify({ ...current, ticketNumber }, null, 2)}\n`,
+    `${JSON.stringify({ ...current, courtTicketNumbers: frozen }, null, 2)}\n`,
     "utf8",
   );
+  await mergeInvocationIdentityPage(admitted.runDirectory, {
+    courtTicketNumbers: frozen,
+  });
+  admitted.courtTicketNumbers = frozen;
+}
+
+/** Move a settled first-entry run from unbound to its asserted ticket directory. */
+export async function relocateAdmittedRunToTicket(
+  admitted: AdmittedRoleInvocation,
+  authority: DurablePrincipalAuthority,
+  heldLease?: { relocate(runDirectory: string): void },
+): Promise<void> {
+  if (admitted.ticketNumber === undefined || !admitted.runDirectory.includes(`${sep}unbound${sep}runs${sep}`)) return;
+  const oldRunDirectory = admitted.runDirectory;
+  const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(oldRunDirectory));
+  const target = roleRunPlacement(ledgerHome, {
+    bookKey: admitted.bookKey,
+    subject: { ticketNumber: admitted.ticketNumber },
+    runId: admitted.runId,
+    role: admitted.role,
+  });
+  ensureRoleRunDirectory(ledgerHome, dirname(target.runDirectory));
+  await rename(oldRunDirectory, target.runDirectory);
+  heldLease?.relocate(target.runDirectory);
+
+  const admittedRecord = admitted as unknown as Record<string, unknown>;
+  rewriteRunDirectoryPathFields(
+    admittedRecord,
+    [
+      "runDirectory",
+      "admittedRequestPath",
+      "taskPath",
+      "packetPath",
+      "prerequisitesPath",
+      "requestManifestPath",
+      "mergerInputPath",
+    ],
+    oldRunDirectory,
+    target.runDirectory,
+  );
+  for (const attachment of admitted.attachments) {
+    (attachment as { frozenPath: string }).frozenPath = rewriteRunDirectoryPathValue(
+      attachment.frozenPath,
+      oldRunDirectory,
+      target.runDirectory,
+    ) as string;
+  }
+  const principal = authority.seal(target);
+  (admitted as { principal: DurablePrincipal }).principal = principal;
+
+  await rewriteRoleRunDurablePages({
+    pagesDirectory: target.runDirectory,
+    oldRunDirectory,
+    newRunDirectory: target.runDirectory,
+  });
 }
 
 /**
@@ -508,11 +630,10 @@ export async function bindTicketNumberOnRunDirectory(
   runDirectory: string,
   ticketNumber: number,
 ): Promise<void> {
-  if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1) {
-    throw new Error(
-      `bindTicketNumberOnRunDirectory requires a safe positive integer, got ${String(ticketNumber)}`,
-    );
-  }
+  requireSafePositiveTicketNumber(
+    ticketNumber,
+    "bindTicketNumberOnRunDirectory",
+  );
   const admittedPath = join(runDirectory, "admitted-request.json");
   const invocationPath = join(runDirectory, "invocation.json");
   const admitted = JSON.parse(await readFile(admittedPath, "utf8")) as Record<
@@ -1089,7 +1210,13 @@ export async function freezeAttachmentsIntoRun(
 function ticketAdmissionFields(
   ticketNumber: number | undefined,
 ): { ticketNumber?: number } {
-  return ticketNumber === undefined ? {} : { ticketNumber };
+  if (ticketNumber === undefined) return {};
+  return {
+    ticketNumber: requireSafePositiveTicketNumber(
+      ticketNumber,
+      "assertedTicketNumber",
+    ),
+  };
 }
 
 export type AdmitJudgeInvocationOptions = {
@@ -1107,6 +1234,8 @@ export type AdmitJudgeInvocationOptions = {
 
 export type AdmitInspectorInvocationOptions = AdmitJudgeInvocationOptions & {
   correlationId?: string;
+  /** Typed identity handed off by 起居郎 or inherited from an already-bound run. */
+  assertedTicketNumber?: number;
 };
 
 export type AdmitGatekeeperInvocationOptions = AdmitInspectorInvocationOptions;
@@ -1123,7 +1252,7 @@ async function admitStandardMaterialInvocation<
   R extends "judge" | "inspector" | "gatekeeper" | "navigator" | "auditor" | "diarist",
 >(
   role: R,
-  options: AdmitJudgeInvocationOptions & { correlationId?: string },
+  options: AdmitInspectorInvocationOptions,
 ): Promise<AdmittedRoleInvocationBase & { readonly role: R }> {
   // Empty project override must not reach resolve("") → cwd (silent default).
   if (options.project !== undefined) {
@@ -1131,22 +1260,25 @@ async function admitStandardMaterialInvocation<
   }
   const projectRoot = resolve(options.project ?? options.cwd);
   const runId = (options.createRunId ?? uuidv7)();
+  // Validate asserted ticket before placement so 0/NaN never become subjects.
+  const ticketFields = ticketAdmissionFields(options.assertedTicketNumber);
   const {
     principal,
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role,
+    subject: ticketFields.ticketNumber === undefined
+      ? { unbound: true }
+      : { ticketNumber: ticketFields.ticketNumber },
     home: options.home,
   });
-  const attachmentsDirectory = join(runDirectory, "attachments");
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
   const correlationFields =
@@ -1173,6 +1305,7 @@ async function admitStandardMaterialInvocation<
       sha256: a.sha256,
       mediaKind: a.mediaKind,
     })),
+    ...ticketFields,
   };
   const admittedRequestPath = join(runDirectory, "admitted-request.json");
   await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
@@ -1197,6 +1330,7 @@ async function admitStandardMaterialInvocation<
     principal,
     admittedRequestPath,
     ...correlationFields,
+    ...ticketFields,
   };
 }
 
@@ -1324,17 +1458,16 @@ export async function admitCountersignInvocation(
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "countersign",
+    subject: { unbound: true },
     home: options.home,
   });
-  const attachmentsDirectory = join(runDirectory, "attachments");
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
   // Ticket binding is LLM-only post-admission (#635); admission stays unbound.
@@ -1418,9 +1551,11 @@ export async function loadAdmittedJudgeRequest(
 }
 
 export async function ensureRunArtifactsDir(runDirectory: string): Promise<string> {
-  const dir = join(runDirectory, "artifacts");
-  await mkdir(dir, { recursive: true });
-  return dir;
+  const directory = roleRunArtifactsDirectory(runDirectory);
+  return ensureRoleRunDirectory(
+    resolveActivationLedgerHome(homeFromRunDirectory(runDirectory)),
+    directory,
+  );
 }
 
 export type AdmitCoderInvocationOptions = {
@@ -1464,17 +1599,16 @@ export async function admitCoderInvocation(
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "coder",
+    subject: { unbound: true },
     home: options.home,
   });
-  const attachmentsDirectory = join(runDirectory, "attachments");
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
 
@@ -1611,17 +1745,16 @@ export async function admitFixerInvocation(
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "fixer",
+    subject: { unbound: true },
     home: options.home,
   });
-  const attachmentsDirectory = join(runDirectory, "attachments");
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
 
@@ -1918,17 +2051,16 @@ export async function admitCollectorInvocation(
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "collector",
+    subject: { unbound: true },
     home: options.home,
   });
-  const attachmentsDirectory = join(runDirectory, "attachments");
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
   // #676 A: freeze task materials BEFORE target resolution so the role receives
   // real instruction + attachments. Admission binds only explicit --pr or unique
@@ -2015,8 +2147,9 @@ export function buildCollectorTransportPrompt(
 const DOCTOR_ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/;
 
 /** Match retained Doctor case runs roots (ADR 0017 / loadDoctorCase). */
+/** Canonical Doctor case: `<book>/<ticket>/runs`. Legacy `issues/<n>/runs` is read-only compat. */
 const DOCTOR_CASE_RUNS_PATH_PATTERN =
-  /\/\.ak-roles\/books\/[^/]+\/issues\/([1-9]\d*)\/runs$/;
+  /\/\.ak-roles\/books\/[^/]+\/(?:issues\/)?([1-9]\d*)\/runs$/;
 
 /**
  * Parse a positive Issue number for public Doctor admission.
@@ -2131,9 +2264,9 @@ export async function resolveDoctorCaseRunsPath(options: {
   runs?: string;
 }): Promise<string> {
   const ledgerHome = resolveActivationLedgerHome(options.home);
+  // Canonical topology: <book>/<ticket>/runs (docs/dossier-topology.md).
   const defaultRuns = join(
     activationBookDirectory(ledgerHome, options.bookKey),
-    "issues",
     String(options.issueNumber),
     "runs",
   );
@@ -2177,7 +2310,7 @@ export async function resolveDoctorCaseRunsPath(options: {
   const match = normalized.match(DOCTOR_CASE_RUNS_PATH_PATTERN);
   if (!match) {
     throw new CliUsageError(
-      "doctor --runs must be an .ak-roles/books/<book>/issues/<n>/runs directory",
+      "doctor --runs must be an .ak-roles/books/<book>/<n>/runs directory",
     );
   }
   if (Number(match[1]) !== options.issueNumber) {
@@ -2217,12 +2350,14 @@ export async function admitDoctorInvocation(
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "doctor",
+    subject: { unbound: true },
     home: options.home,
   });
 
@@ -2266,9 +2401,6 @@ export async function admitDoctorInvocation(
     );
   }
 
-  const attachmentsDirectory = join(runDirectory, "attachments");
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
   const attachments = await freezeAttachments(options.attachmentPaths ?? [], attachmentsDirectory);
 
@@ -2423,24 +2555,27 @@ export async function admitNotaryInvocation(options: {
     throw error;
   }
 
+  // Notary inherits board identity only — migration-derived stays display/placement.
+  const inheritedTicketNumber = await readBoardTicketNumber(sourceRun.runDirectory);
   const runId = options.createRunId?.() ?? uuidv7();
   const {
     principal,
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "notary",
+    subject: inheritedTicketNumber === undefined
+      ? { unbound: true }
+      : { ticketNumber: inheritedTicketNumber },
     home: options.home,
   });
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  const ticketFields = ticketAdmissionFields(
-    await readRunTicketNumber(sourceRun.runDirectory),
-  );
+  const ticketFields = ticketAdmissionFields(inheritedTicketNumber);
 
   const admitted = {
     role: "notary" as const,
@@ -2582,15 +2717,16 @@ export async function admitGleanerLeftInvocation(
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "gleaner-left",
+    subject: { unbound: true },
     home: options.home,
   });
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
 
   const instruction = options.instruction;
   const instructionEmpty = instruction.trim() === "";
@@ -2746,17 +2882,16 @@ export async function admitReviewerInvocation(
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "reviewer",
+    subject: { unbound: true },
     home: options.home,
   });
-  const attachmentsDirectory = join(runDirectory, "attachments");
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
   // Public parse already rejects attachments; keep freeze loop for structural symmetry.
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
@@ -2955,17 +3090,16 @@ export async function admitMergerInvocation(
     sessionDirectory,
     sessionFile,
     runDirectory,
+    attachmentsDirectory,
     ledgerHome,
     bookKey,
   } = issueAdmissionPlacement(options.principalAuthority, {
     cwd: projectRoot,
     runId,
     role: "merger",
+    subject: { unbound: true },
     home: options.home,
   });
-  const attachmentsDirectory = join(runDirectory, "attachments");
-  ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-  ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
 
   const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
 

package/src/public-cli/option-definitions.ts

@@ -645,8 +645,8 @@ const DOCTOR_OPTIONS = [
     repeatable: false,
     form: "option",
     description: {
-      en: "Optional project-relative .ak-roles/books/<book>/issues/<n>/runs override matching --issue.",
-      zh: "可选项目相对 .ak-roles/books/<book>/issues/<n>/runs 覆盖，且须匹配 --issue。",
+      en: "Optional project-relative .ak-roles/books/<book>/<n>/runs override matching --issue.",
+      zh: "可选项目相对 .ak-roles/books/<book>/<n>/runs 覆盖，且须匹配 --issue。",
     },
   },
 ] as const satisfies readonly PublicOptionDefinition[];