@akagilnc/pi-workflow-roles 0.1.5365 → 0.1.5375

package/src/public-cli/invocation.ts

@@ -27,6 +27,7 @@ import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
 import {
   ensureRoleRunDirectory,
   ensureRoleRunPlacement,
+  isUnboundRunDirectory,
   listBookRunDirectories,
   roleRunArtifactsDirectory,
   roleRunPlacement,
@@ -36,7 +37,7 @@ import type {
   DurablePrincipal,
   DurablePrincipalAuthority,
 } from "../host-contracts.ts";
-import type { PackagedRole } from "../packaged-role-registry.ts";
+import type { PackagedRole, PublicRoleRecord } from "../packaged-role-registry.ts";
 import {
   packagedAdmittedSubject,
   packagedArgvResult,
@@ -109,6 +110,8 @@ import {
 } from "./option-definitions.ts";
 import type { PublicThinkingLevel } from "./registry.ts";
 
+import { errorText, isRecord } from "../unknown-value.ts";
+
 export type FrozenAttachment = {
   /** Original caller path retained only as provenance. */
   readonly provenancePath: string;
@@ -445,39 +448,46 @@ export async function recordEffectiveInvocationModel(
   host?: string,
   engineModel?: string | null,
 ): Promise<void> {
-  const ledgerPath = join(runDirectory, "invocation.json");
-  const current = JSON.parse(await readFile(ledgerPath, "utf8")) as Record<
-    string,
-    unknown
-  >;
-  const next: Record<string, unknown> = { ...current };
-  if (model !== undefined) {
-    next.provider = model.provider;
-    next.model = model.model;
-    if (model.thinking === undefined) {
-      delete next.thinking;
-    } else {
-      next.thinking = model.thinking;
+  await updateDurableJsonPage(join(runDirectory, "invocation.json"), (current) => {
+    const next: Record<string, unknown> = { ...current };
+    if (model !== undefined) {
+      next.provider = model.provider;
+      next.model = model.model;
+      if (model.thinking === undefined) {
+        delete next.thinking;
+      } else {
+        next.thinking = model.thinking;
+      }
     }
-  }
-  if (engine === null) {
-    delete next.engine;
-  } else if (engine !== undefined) {
-    next.engine = engine;
-  }
-  if (engineModel === null) {
-    delete next.engineModel;
-  } else if (engineModel !== undefined) {
-    next.engineModel = engineModel;
-  }
-  if (host !== undefined) {
-    next.host = host;
-  }
-  await writeFile(
-    ledgerPath,
-    `${JSON.stringify(next, null, 2)}\n`,
-    "utf8",
-  );
+    if (engine === null) {
+      delete next.engine;
+    } else if (engine !== undefined) {
+      next.engine = engine;
+    }
+    if (engineModel === null) {
+      delete next.engineModel;
+    } else if (engineModel !== undefined) {
+      next.engineModel = engineModel;
+    }
+    if (host !== undefined) {
+      next.host = host;
+    }
+    return next;
+  });
+}
+
+/**
+ * Read one durable JSON object, let the caller keep its field rules, and write
+ * the page back. `undefined` means the caller decided not to change the page.
+ */
+async function updateDurableJsonPage(
+  path: string,
+  update: (current: Record<string, unknown>) => Record<string, unknown> | undefined,
+): Promise<void> {
+  const current = JSON.parse(await readFile(path, "utf8")) as Record<string, unknown>;
+  const next = update(current);
+  if (next === undefined) return;
+  await writeFile(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
 }
 
 /** Merge observed launch-time fields into the single existing invocation.json identity page. */
@@ -485,16 +495,10 @@ async function mergeInvocationIdentityPage(
   runDirectory: string,
   fields: Record<string, unknown>,
 ): Promise<void> {
-  const ledgerPath = join(runDirectory, "invocation.json");
-  const current = JSON.parse(await readFile(ledgerPath, "utf8")) as Record<string, unknown>;
-  await writeFile(
-    ledgerPath,
-    `${JSON.stringify({
-      ...current,
-      ...fields,
-    }, null, 2)}\n`,
-    "utf8",
-  );
+  await updateDurableJsonPage(join(runDirectory, "invocation.json"), (current) => ({
+    ...current,
+    ...fields,
+  }));
 }
 
 /**
@@ -509,27 +513,20 @@ export async function persistAdmittedSourceRunPath(
   if (sourceRunPath.trim() === "") {
     throw new Error("persistAdmittedSourceRunPath requires a non-empty sourceRunPath");
   }
-  const admittedPath = admitted.admittedRequestPath;
-  const current = JSON.parse(await readFile(admittedPath, "utf8")) as Record<
-    string,
-    unknown
-  >;
-  if (typeof current.sourceRunPath === "string" && current.sourceRunPath !== sourceRunPath) {
-    throw new Error(
-      `persistAdmittedSourceRunPath refuses to replace ${current.sourceRunPath} with ${sourceRunPath}`,
-    );
-  }
-  const sameSubject = auditorSubject === undefined || current.auditorSubject === auditorSubject;
-  if (current.sourceRunPath === sourceRunPath && sameSubject) return;
-  await writeFile(
-    admittedPath,
-    `${JSON.stringify({
+  await updateDurableJsonPage(admitted.admittedRequestPath, (current) => {
+    if (typeof current.sourceRunPath === "string" && current.sourceRunPath !== sourceRunPath) {
+      throw new Error(
+        `persistAdmittedSourceRunPath refuses to replace ${current.sourceRunPath} with ${sourceRunPath}`,
+      );
+    }
+    const sameSubject = auditorSubject === undefined || current.auditorSubject === auditorSubject;
+    if (current.sourceRunPath === sourceRunPath && sameSubject) return undefined;
+    return {
       ...current,
       sourceRunPath,
       ...(auditorSubject === undefined ? {} : { auditorSubject }),
-    }, null, 2)}\n`,
-    "utf8",
-  );
+    };
+  });
 }
 
 /**
@@ -551,25 +548,21 @@ export async function recordAdmittedCorrelation(
   admitted: AdmittedRoleInvocation,
   correlationId: string,
 ): Promise<void> {
-  const current = JSON.parse(
-    await readFile(admitted.admittedRequestPath, "utf8"),
-  ) as Record<string, unknown>;
-  const prior = [
-    ...(Array.isArray(current.correlationIds)
-      ? current.correlationIds.filter((value): value is string =>
-          typeof value === "string" && value.trim() !== ""
-        )
-      : []),
-    ...(typeof current.correlationId === "string" && current.correlationId.trim() !== ""
-      ? [current.correlationId]
-      : []),
-  ];
-  const correlationIds = [...new Set([...prior, correlationId])];
-  await writeFile(
-    admitted.admittedRequestPath,
-    `${JSON.stringify({ ...current, correlationId, correlationIds }, null, 2)}\n`,
-    "utf8",
-  );
+  let correlationIds: string[] = [];
+  await updateDurableJsonPage(admitted.admittedRequestPath, (current) => {
+    const prior = [
+      ...(Array.isArray(current.correlationIds)
+        ? current.correlationIds.filter((value): value is string =>
+            typeof value === "string" && value.trim() !== ""
+          )
+        : []),
+      ...(typeof current.correlationId === "string" && current.correlationId.trim() !== ""
+        ? [current.correlationId]
+        : []),
+    ];
+    correlationIds = [...new Set([...prior, correlationId])];
+    return { ...current, correlationId, correlationIds };
+  });
   await mergeInvocationIdentityPage(admitted.runDirectory, {
     correlationId,
     correlationIds,
@@ -588,7 +581,7 @@ export async function relocateAdmittedRunToTicket(
   authority: DurablePrincipalAuthority,
   heldLease?: { relocate(runDirectory: string): void },
 ): Promise<RunDirectoryRelocation | undefined> {
-  if (admitted.ticketNumber === undefined || !admitted.runDirectory.includes(`${sep}unbound${sep}runs${sep}`)) return undefined;
+  if (admitted.ticketNumber === undefined || !isUnboundRunDirectory(admitted.runDirectory)) return undefined;
   const oldRunDirectory = admitted.runDirectory;
   const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(oldRunDirectory));
   const target = roleRunPlacement(ledgerHome, {
@@ -670,12 +663,13 @@ export async function recordChildDiaristRun(
   parent: AdmittedRoleInvocation,
   childRunId: string,
 ): Promise<void> {
-  const page = JSON.parse(await readFile(parent.admittedRequestPath, "utf8")) as Record<string, unknown>;
-  const existing = Array.isArray(page.childDiaristRunIds)
-    ? page.childDiaristRunIds.filter((runId): runId is string => typeof runId === "string")
-    : [];
-  const childDiaristRunIds = existing.includes(childRunId) ? existing : [...existing, childRunId];
-  await writeFile(parent.admittedRequestPath, `${JSON.stringify({ ...page, childDiaristRunIds }, null, 2)}\n`, "utf8");
+  await updateDurableJsonPage(parent.admittedRequestPath, (page) => {
+    const existing = Array.isArray(page.childDiaristRunIds)
+      ? page.childDiaristRunIds.filter((runId): runId is string => typeof runId === "string")
+      : [];
+    const childDiaristRunIds = existing.includes(childRunId) ? existing : [...existing, childRunId];
+    return { ...page, childDiaristRunIds };
+  });
 }
 
 /**
@@ -692,16 +686,15 @@ export async function bindTicketNumberOnRunDirectory(
     "bindTicketNumberOnRunDirectory",
   );
   const admittedPath = join(runDirectory, "admitted-request.json");
-  const admitted = JSON.parse(await readFile(admittedPath, "utf8")) as Record<
-    string,
-    unknown
-  >;
-  if (admitted.ticketNumber === ticketNumber) return;
-  await writeFile(
-    admittedPath,
-    `${JSON.stringify({ ...admitted, ticketNumber }, null, 2)}\n`,
-    "utf8",
-  );
+  let unchanged = false;
+  await updateDurableJsonPage(admittedPath, (admitted) => {
+    if (admitted.ticketNumber === ticketNumber) {
+      unchanged = true;
+      return undefined;
+    }
+    return { ...admitted, ticketNumber };
+  });
+  if (unchanged) return;
   await mergeInvocationIdentityPage(runDirectory, { ticketNumber });
 }
 
@@ -1097,20 +1090,34 @@ function requireOptionPath(
  * next option), and a leading `-` (read as the next Skill option). Not a
  * general free-text gate — only the projection admission seam.
  */
+function skillArgTokenFault(
+  value: string | undefined,
+): "empty" | "whitespace" | "optionLike" | undefined {
+  if (value === undefined || value.trim() === "") return "empty";
+  if (/\s/.test(value)) return "whitespace";
+  if (value.startsWith("-")) return "optionLike";
+  return undefined;
+}
+
 function requireSkillArgToken(
   value: string | undefined,
   messages: { empty: string; whitespace: string; optionLike: string },
 ): string {
-  if (value === undefined || value.trim() === "") {
-    throw new CliUsageError(messages.empty);
-  }
-  if (/\s/.test(value)) {
-    throw new CliUsageError(messages.whitespace);
-  }
-  if (value.startsWith("-")) {
-    throw new CliUsageError(messages.optionLike);
-  }
-  return value;
+  const fault = skillArgTokenFault(value);
+  if (fault !== undefined) throw new CliUsageError(messages[fault]);
+  return value as string;
+}
+
+/**
+ * Durable reviewer base on resume. Same token rule as fresh `--base`,
+ * with the resume-owned missing/damaged split.
+ */
+export function admittedReviewerBaseFault(
+  value: string | undefined,
+): "missing" | "damaged" | undefined {
+  const fault = skillArgTokenFault(value);
+  if (fault === undefined) return undefined;
+  return fault === "empty" ? "missing" : "damaged";
 }
 
 /**
@@ -1420,6 +1427,11 @@ export type PublicSeatParse = {
  * Sole admit call. Kind comes from the composition-root record.
  * Placement stays ticketAdmissionFields. Seat field checks live in this function only.
  */
+type RoleForAdmission<K extends PublicRoleRecord["admission"]> = Extract<
+  PublicRoleRecord,
+  { readonly admission: K }
+>["role"];
+
 export function admitPublicRole<R extends PackagedRole>(
   role: R,
   parsed: PublicSeatParse,
@@ -1427,6 +1439,8 @@ export function admitPublicRole<R extends PackagedRole>(
   override?: {
     readonly assertedTicketNumber?: number;
     readonly deferPersistence?: boolean;
+    /** Locator already resolved on the new-summon path. Absent callers still resolve. */
+    readonly resolvedSourceRun?: NotarySourceRunLocator;
   },
 ): Promise<Extract<AdmittedRoleInvocation, { readonly role: R }>>;
 export async function admitPublicRole(
@@ -1436,6 +1450,8 @@ export async function admitPublicRole(
   override?: {
     readonly assertedTicketNumber?: number;
     readonly deferPersistence?: boolean;
+    /** Locator already resolved on the new-summon path. Absent callers still resolve. */
+    readonly resolvedSourceRun?: NotarySourceRunLocator;
   },
 ): Promise<AdmittedRoleInvocation> {
   const record = packagedRoleMetadata(role);
@@ -1454,7 +1470,7 @@ export async function admitPublicRole(
   switch (record.admission) {
     case "instruction":
       return admitStandardMaterialInvocation(
-        role as "judge" | "inspector" | "gatekeeper" | "navigator" | "auditor" | "diarist" | "secretariat",
+        role as RoleForAdmission<"instruction">,
         {
           ...shared,
           instruction,
@@ -1493,9 +1509,6 @@ export async function admitPublicRole(
       });
     }
     case "worker-packet": {
-      if (parsed.project !== undefined) {
-        requireOptionPath("--project", parsed.project);
-      }
       if (instruction.trim() === "") {
         throw new CliUsageError("fixer requires a nonblank repair instruction");
       }
@@ -1553,25 +1566,14 @@ export async function admitPublicRole(
       });
     }
     case "collect-target": {
-      if (parsed.project !== undefined) {
-        requireOptionPath("--project", parsed.project);
-      }
-      let explicitPrNumber: number | undefined;
-      if (parsed.prNumber !== undefined) {
-        try {
-          explicitPrNumber = parseCollectorPrNumber(parsed.prNumber);
-        } catch (error) {
-          const detail = error instanceof Error ? error.message : String(error);
-          throw new CliUsageError(detail, { cause: error });
-        }
-      }
+      const explicitPrNumber = parsed.prNumber;
       const projectRoot = resolve(parsed.project ?? shared.cwd);
       let repository: CollectorRepository;
       if (parsed.repo !== undefined) {
         try {
           repository = parseCollectorRepository(parsed.repo);
         } catch (error) {
-          const detail = error instanceof Error ? error.message : String(error);
+          const detail = errorText(error);
           throw new CliUsageError(detail, { cause: error });
         }
       } else {
@@ -1585,7 +1587,7 @@ export async function admitPublicRole(
           manifestCanonicalJson = manifest.canonicalJson;
         } catch (error) {
           throw new CliUsageError(
-            error instanceof Error ? error.message : String(error),
+            errorText(error),
             { cause: error },
           );
         }
@@ -1615,19 +1617,12 @@ export async function admitPublicRole(
       return { ...admittedCollector, repository };
     }
     case "case-identity": {
-      if (parsed.project !== undefined) {
-        requireOptionPath("--project", parsed.project);
-      }
-      const issueNumber = parsed.issueNumber ?? Number.NaN;
-      if (
-        !Number.isInteger(issueNumber) ||
-        issueNumber < 1 ||
-        !DOCTOR_ISSUE_NUMBER_PATTERN.test(String(issueNumber))
-      ) {
+      if (parsed.issueNumber === undefined) {
         throw new CliUsageError(
-          `doctor --issue must be a positive integer, got ${issueNumber}`,
+          `doctor --issue must be a positive integer, got ${Number.NaN}`,
         );
       }
+      const issueNumber = parsed.issueNumber;
       let frozenAttachments: readonly FrozenAttachment[] = [];
       const admittedDoctor = await admitStandardMaterialInvocation("doctor", {
         ...shared,
@@ -1647,7 +1642,7 @@ export async function admitPublicRole(
             });
           } catch (error) {
             if (error instanceof CliUsageError) throw error;
-            const detail = error instanceof Error ? error.message : String(error);
+            const detail = errorText(error);
             throw new CliUsageError(detail, { cause: error });
           }
           if (parsed.runs === undefined) {
@@ -1665,7 +1660,7 @@ export async function admitPublicRole(
             caseRunsPath = await realpath(caseRunsPath);
           } catch (error) {
             if (error instanceof CliUsageError) throw error;
-            const detail = error instanceof Error ? error.message : String(error);
+            const detail = errorText(error);
             throw new CliUsageError(
               `doctor case could not be constructed from retained evidence: ${detail}`,
               { cause: error },
@@ -1683,22 +1678,21 @@ export async function admitPublicRole(
       return { ...admittedDoctor, attachments: frozenAttachments };
     }
     case "source-locator": {
-      if (parsed.project !== undefined) {
-        requireOptionPath("--project", parsed.project);
-      }
       const projectRoot = resolve(parsed.project ?? shared.cwd);
-      let sourceRun: NotarySourceRunLocator;
-      try {
-        sourceRun = await resolveNotarySourceRunLocator({
-          projectRoot,
-          sourceRun: parsed.sourceRun ?? "",
-          home: shared.home,
-        });
-      } catch (error) {
-        if (error instanceof NotarySourceRunError) {
-          throw new CliUsageError(error.message, { cause: error });
+      let sourceRun = override?.resolvedSourceRun;
+      if (sourceRun === undefined) {
+        try {
+          sourceRun = await resolveNotarySourceRunLocator({
+            projectRoot,
+            sourceRun: parsed.sourceRun ?? "",
+            home: shared.home,
+          });
+        } catch (error) {
+          if (error instanceof NotarySourceRunError) {
+            throw new CliUsageError(error.message, { cause: error });
+          }
+          throw error;
         }
-        throw error;
       }
       // Board ticket on the source run wins; otherwise the summons ticket. Code does not infer one.
       const inheritedTicketNumber = await readBoardTicketNumber(sourceRun.runDirectory);
@@ -1719,9 +1713,6 @@ export async function admitPublicRole(
       });
     }
     case "gleaner": {
-      if (parsed.project !== undefined) {
-        requireOptionPath("--project", parsed.project);
-      }
       const baseRevision = parsed.baseRevision ?? "";
       if (baseRevision.trim() === "") {
         throw new CliUsageError("--base requires a nonempty revision");
@@ -1736,16 +1727,19 @@ export async function admitPublicRole(
       });
     }
     case "review-basis": {
-      const lens = requireReviewerLens(parsed.lens);
-      if (parsed.project !== undefined) {
-        requireOptionPath("--project", parsed.project);
+      if (parsed.lens === undefined) {
+        throw new CliUsageError("--lens requires completeness or correctness");
+      }
+      if (parsed.baseRevision === undefined) {
+        throw new CliUsageError("--base requires a nonempty revision");
       }
-      const baseRevision = requireReviewerBaseRevision(parsed.baseRevision);
       const rawRefs = parsed.authorityRefs ?? [];
       if (rawRefs.length === 0) {
         throw new CliUsageError("reviewer requires --authority-ref <ref>");
       }
-      const authorityRefs = Object.freeze(rawRefs.map((ref) => requireAuthorityRef(ref)));
+      const lens = parsed.lens;
+      const baseRevision = parsed.baseRevision;
+      const authorityRefs = Object.freeze([...rawRefs]);
       const admittedReviewer = await admitStandardMaterialInvocation("reviewer", {
         ...shared,
         instruction,
@@ -1760,9 +1754,6 @@ export async function admitPublicRole(
       return { ...admittedReviewer, authorityRefs };
     }
     case "merge-envelope": {
-      if (parsed.project !== undefined) {
-        requireOptionPath("--project", parsed.project);
-      }
       if (instruction.trim() === "") {
         throw new CliUsageError("merger requires a nonblank task instruction");
       }
@@ -1885,9 +1876,6 @@ async function placeRoleAdmission(options: {
   /** Countersign reserves coordinates, then materializes after identity lookup. */
   readonly materialize?: boolean;
 }): Promise<PlacedRoleAdmission> {
-  if (options.project !== undefined) {
-    requireOptionPath("--project", options.project);
-  }
   const projectRoot = resolve(options.project ?? options.cwd);
   const runId = options.runId ?? (options.createRunId ?? uuidv7)();
   const ticketFields = ticketAdmissionFields(options.assertedTicketNumber);
@@ -1988,7 +1976,7 @@ async function persistPlacedAdmission(
  * doctor resolves the case, then freezes attachments; merger writes merger-input.json).
  */
 async function admitStandardMaterialInvocation<
-  R extends "judge" | "inspector" | "gatekeeper" | "navigator" | "auditor" | "diarist" | "secretariat" | "countersign" | "gleaner-left" | "reviewer" | "notary" | "coder" | "fixer" | "collector" | "doctor" | "merger",
+  R extends PackagedRole,
   Extra extends object = {},
 >(
   role: R,
@@ -2217,8 +2205,8 @@ export async function loadAdmittedJudgeRequest(
     const raw = JSON.parse(
       await readFile(join(runDirectory, "admitted-request.json"), "utf8"),
     ) as unknown;
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-    const record = raw as Record<string, unknown>;
+    if (!isRecord(raw)) return undefined;
+    const record = raw;
     if (!packagedPublicInstructionSubject(record.role)) return undefined;
     if (typeof record.instruction !== "string") return undefined;
     if (typeof record.instructionEmpty !== "boolean") return undefined;
@@ -2260,7 +2248,7 @@ export type AdmitFixerInvocationOptions = {
 
 function parsePositivePrOption(raw: string | undefined): number {
   if (raw === undefined || raw.trim() === "") throw new CliUsageError("--pr requires a positive pull request number");
-  try { return parseCollectorPrNumber(raw); } catch (error) { throw new CliUsageError(error instanceof Error ? error.message : String(error), { cause: error }); }
+  try { return parseCollectorPrNumber(raw); } catch (error) { throw new CliUsageError(errorText(error), { cause: error }); }
 }
 function parseRepoOption(raw: string | undefined): string {
   if (raw === undefined || raw.trim() === "") throw new CliUsageError("--repo requires owner/repo");
@@ -2308,7 +2296,7 @@ export function resolveGitHubRemoteRepository(
   try {
     return parseCollectorRepository(ownerRepo);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorText(error);
     throw new CliUsageError(detail, { cause: error });
   }
 }
@@ -2393,7 +2381,7 @@ export async function resolveDoctorCaseRunsPath(options: {
   try {
     real = await realpath(resolved);
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
+    const detail = errorText(error);
     throw new CliUsageError(
       `doctor --runs is not a readable retained runs root: ${detail}`,
       { cause: error },
@@ -2415,7 +2403,6 @@ export async function resolveDoctorCaseRunsPath(options: {
   return real;
 }
 
-
 export type AdmitReviewerInvocationOptions = {
   home: string;
   principalAuthority: DurablePrincipalAuthority;