@akagilnc/pi-workflow-roles 0.1.5365 → 0.1.5375

package/dist/public-cli/invocation.js

@@ -9,7 +9,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { activationBookDirectory, ensureRealDirectoryTree, homeFromRunDirectory, pathContainedIn, resolveActivationLedgerHome, } from "../activation-ledger-topology.js";
 import { resolveBookKeyFromGit } from "../activation-ledger-git.js";
-import { ensureRoleRunDirectory, ensureRoleRunPlacement, listBookRunDirectories, roleRunArtifactsDirectory, roleRunPlacement, } from "../role-run-placement.js";
+import { ensureRoleRunDirectory, ensureRoleRunPlacement, isUnboundRunDirectory, listBookRunDirectories, roleRunArtifactsDirectory, roleRunPlacement, } from "../role-run-placement.js";
 import { packagedAdmittedSubject, packagedArgvResult, packagedBareToken, packagedBaseIsRevision, packagedEmitsAuthorityRefs, packagedPublicInstructionSubject, packagedRoleMetadata, packagedStoresSourceRunRaw, packagedSubjectChoices, } from "../packaged-role-registry.js";
 import { isSafePositiveTicketNumber, readBoardTicketNumber, requireSafePositiveTicketNumber, } from "../run-ticket-number.js";
 import { rewriteRunDirectoryPathFields, rewriteRunDirectoryPathValue, } from "../role-run-relocation.js";
@@ -27,6 +27,7 @@ import { NotarySourceRunError, resolveNotarySourceRunLocator, } from "../notary-
 import { appendEngineSessionMaterial, } from "../package-resources/engine-material.js";
 import { CliUsageError } from "./cli-errors.js";
 import { REJECTED_PUBLIC_SPELLINGS, createTypedOptionConsumer, evaluateAnalystModeOptionContract, optionsForOwner, resolveAnalystMode, } from "./option-definitions.js";
+import { errorText, isRecord } from "../unknown-value.js";
 /** Issue a principal from the single authoritative role-run placement. */
 export function issueAdmissionPlacement(authority, request) {
     const ledgerHome = resolveActivationLedgerHome(request.home);
@@ -103,44 +104,53 @@ async function writeRoleInvocationLedger(source, role, effectiveModel) {
  * Host stays write-if-present (`string` only).
  */
 export async function recordEffectiveInvocationModel(runDirectory, model, engine, host, engineModel) {
-    const ledgerPath = join(runDirectory, "invocation.json");
-    const current = JSON.parse(await readFile(ledgerPath, "utf8"));
-    const next = { ...current };
-    if (model !== undefined) {
-        next.provider = model.provider;
-        next.model = model.model;
-        if (model.thinking === undefined) {
-            delete next.thinking;
+    await updateDurableJsonPage(join(runDirectory, "invocation.json"), (current) => {
+        const next = { ...current };
+        if (model !== undefined) {
+            next.provider = model.provider;
+            next.model = model.model;
+            if (model.thinking === undefined) {
+                delete next.thinking;
+            }
+            else {
+                next.thinking = model.thinking;
+            }
         }
-        else {
-            next.thinking = model.thinking;
+        if (engine === null) {
+            delete next.engine;
         }
-    }
-    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");
+        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, update) {
+    const current = JSON.parse(await readFile(path, "utf8"));
+    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. */
 async function mergeInvocationIdentityPage(runDirectory, fields) {
-    const ledgerPath = join(runDirectory, "invocation.json");
-    const current = JSON.parse(await readFile(ledgerPath, "utf8"));
-    await writeFile(ledgerPath, `${JSON.stringify({
+    await updateDurableJsonPage(join(runDirectory, "invocation.json"), (current) => ({
         ...current,
         ...fields,
-    }, null, 2)}\n`, "utf8");
+    }));
 }
 /**
  * Persist parent --source-run path onto admitted-request for officer resume lookup (#747).
@@ -150,19 +160,19 @@ export async function persistAdmittedSourceRunPath(admitted, sourceRunPath, audi
     if (sourceRunPath.trim() === "") {
         throw new Error("persistAdmittedSourceRunPath requires a non-empty sourceRunPath");
     }
-    const admittedPath = admitted.admittedRequestPath;
-    const current = JSON.parse(await readFile(admittedPath, "utf8"));
-    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({
-        ...current,
-        sourceRunPath,
-        ...(auditorSubject === undefined ? {} : { auditorSubject }),
-    }, null, 2)}\n`, "utf8");
+    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 }),
+        };
+    });
 }
 /**
  * Bind a post-admission resolved ticketNumber onto the in-memory admitted
@@ -177,17 +187,19 @@ export async function bindAdmittedTicketNumber(admitted, ticketNumber) {
 }
 /** Persist each direct caller observed while a retained run is resumed. */
 export async function recordAdmittedCorrelation(admitted, correlationId) {
-    const current = JSON.parse(await readFile(admitted.admittedRequestPath, "utf8"));
-    const prior = [
-        ...(Array.isArray(current.correlationIds)
-            ? current.correlationIds.filter((value) => 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 = [];
+    await updateDurableJsonPage(admitted.admittedRequestPath, (current) => {
+        const prior = [
+            ...(Array.isArray(current.correlationIds)
+                ? current.correlationIds.filter((value) => 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,
@@ -198,7 +210,7 @@ export async function recordAdmittedCorrelation(admitted, correlationId) {
 }
 /** File a role run under its latest typed ticket identity. */
 export async function relocateAdmittedRunToTicket(admitted, authority, heldLease) {
-    if (admitted.ticketNumber === undefined || !admitted.runDirectory.includes(`${sep}unbound${sep}runs${sep}`))
+    if (admitted.ticketNumber === undefined || !isUnboundRunDirectory(admitted.runDirectory))
         return undefined;
     const oldRunDirectory = admitted.runDirectory;
     const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(oldRunDirectory));
@@ -264,12 +276,13 @@ export async function relocateAdmittedRunToTicket(admitted, authority, heldLease
 }
 /** Persist the exact child identity; later parent binding never inspects siblings. */
 export async function recordChildDiaristRun(parent, childRunId) {
-    const page = JSON.parse(await readFile(parent.admittedRequestPath, "utf8"));
-    const existing = Array.isArray(page.childDiaristRunIds)
-        ? page.childDiaristRunIds.filter((runId) => 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) => typeof runId === "string")
+            : [];
+        const childDiaristRunIds = existing.includes(childRunId) ? existing : [...existing, childRunId];
+        return { ...page, childDiaristRunIds };
+    });
 }
 /**
  * Bind ticket identity onto a run directory's durable pages when the admitted
@@ -279,10 +292,16 @@ export async function recordChildDiaristRun(parent, childRunId) {
 export async function bindTicketNumberOnRunDirectory(runDirectory, ticketNumber) {
     requireSafePositiveTicketNumber(ticketNumber, "bindTicketNumberOnRunDirectory");
     const admittedPath = join(runDirectory, "admitted-request.json");
-    const admitted = JSON.parse(await readFile(admittedPath, "utf8"));
-    if (admitted.ticketNumber === ticketNumber)
+    let unchanged = false;
+    await updateDurableJsonPage(admittedPath, (admitted) => {
+        if (admitted.ticketNumber === ticketNumber) {
+            unchanged = true;
+            return undefined;
+        }
+        return { ...admitted, ticketNumber };
+    });
+    if (unchanged)
         return;
-    await writeFile(admittedPath, `${JSON.stringify({ ...admitted, ticketNumber }, null, 2)}\n`, "utf8");
     await mergeInvocationIdentityPage(runDirectory, { ticketNumber });
 }
 /** Add the identity returned by the production Pi launch seam to its existing ledger page. */
@@ -528,18 +547,31 @@ function requireOptionPath(flag, value) {
  * 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) {
+    if (value === undefined || value.trim() === "")
+        return "empty";
+    if (/\s/.test(value))
+        return "whitespace";
+    if (value.startsWith("-"))
+        return "optionLike";
+    return undefined;
+}
 function requireSkillArgToken(value, messages) {
-    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);
-    }
+    const fault = skillArgTokenFault(value);
+    if (fault !== undefined)
+        throw new CliUsageError(messages[fault]);
     return value;
 }
+/**
+ * Durable reviewer base on resume. Same token rule as fresh `--base`,
+ * with the resume-owned missing/damaged split.
+ */
+export function admittedReviewerBaseFault(value) {
+    const fault = skillArgTokenFault(value);
+    if (fault === undefined)
+        return undefined;
+    return fault === "empty" ? "missing" : "damaged";
+}
 /**
  * Reviewer --base admission: nonempty single Skill-arg token (shared rule with
  * requireAuthorityRef). Multi-token / option-like values smuggle extra flags
@@ -789,9 +821,6 @@ export async function admitPublicRole(role, parsed, env, override) {
             });
         }
         case "worker-packet": {
-            if (parsed.project !== undefined) {
-                requireOptionPath("--project", parsed.project);
-            }
             if (instruction.trim() === "") {
                 throw new CliUsageError("fixer requires a nonblank repair instruction");
             }
@@ -844,19 +873,7 @@ export async function admitPublicRole(role, parsed, env, override) {
             });
         }
         case "collect-target": {
-            if (parsed.project !== undefined) {
-                requireOptionPath("--project", parsed.project);
-            }
-            let explicitPrNumber;
-            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;
             if (parsed.repo !== undefined) {
@@ -864,7 +881,7 @@ export async function admitPublicRole(role, parsed, env, override) {
                     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 });
                 }
             }
@@ -879,7 +896,7 @@ export async function admitPublicRole(role, parsed, env, override) {
                     manifestCanonicalJson = manifest.canonicalJson;
                 }
                 catch (error) {
-                    throw new CliUsageError(error instanceof Error ? error.message : String(error), { cause: error });
+                    throw new CliUsageError(errorText(error), { cause: error });
                 }
             }
             const manifestDigest = manifest.digest;
@@ -907,15 +924,10 @@ export async function admitPublicRole(role, parsed, env, override) {
             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))) {
-                throw new CliUsageError(`doctor --issue must be a positive integer, got ${issueNumber}`);
+            if (parsed.issueNumber === undefined) {
+                throw new CliUsageError(`doctor --issue must be a positive integer, got ${Number.NaN}`);
             }
+            const issueNumber = parsed.issueNumber;
             let frozenAttachments = [];
             const admittedDoctor = await admitStandardMaterialInvocation("doctor", {
                 ...shared,
@@ -937,7 +949,7 @@ export async function admitPublicRole(role, parsed, env, override) {
                     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) {
@@ -955,7 +967,7 @@ export async function admitPublicRole(role, parsed, env, override) {
                     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 });
                     }
                     frozenAttachments = await freezeAttachments(attachmentPaths, placed.attachmentsDirectory);
@@ -970,23 +982,22 @@ export async function admitPublicRole(role, parsed, env, override) {
             return { ...admittedDoctor, attachments: frozenAttachments };
         }
         case "source-locator": {
-            if (parsed.project !== undefined) {
-                requireOptionPath("--project", parsed.project);
-            }
             const projectRoot = resolve(parsed.project ?? shared.cwd);
-            let sourceRun;
-            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);
@@ -1007,9 +1018,6 @@ export async function admitPublicRole(role, parsed, env, override) {
             });
         }
         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");
@@ -1024,16 +1032,19 @@ export async function admitPublicRole(role, parsed, env, override) {
             });
         }
         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,
@@ -1048,9 +1059,6 @@ export async function admitPublicRole(role, parsed, env, override) {
             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");
             }
@@ -1106,9 +1114,6 @@ function admissionSubject(ticketNumber) {
  * Every public seat persists through this function. Seat-only fields are supplied by the caller.
  */
 async function placeRoleAdmission(options) {
-    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);
@@ -1318,7 +1323,7 @@ export async function materializeCountersignInvocation(admitted, options) {
 export async function loadAdmittedJudgeRequest(runDirectory) {
     try {
         const raw = JSON.parse(await readFile(join(runDirectory, "admitted-request.json"), "utf8"));
-        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        if (!isRecord(raw))
             return undefined;
         const record = raw;
         if (!packagedPublicInstructionSubject(record.role))
@@ -1350,7 +1355,7 @@ function parsePositivePrOption(raw) {
         return parseCollectorPrNumber(raw);
     }
     catch (error) {
-        throw new CliUsageError(error instanceof Error ? error.message : String(error), { cause: error });
+        throw new CliUsageError(errorText(error), { cause: error });
     }
 }
 function parseRepoOption(raw) {
@@ -1392,7 +1397,7 @@ export function resolveGitHubRemoteRepository(projectRoot) {
         return parseCollectorRepository(ownerRepo);
     }
     catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
+        const detail = errorText(error);
         throw new CliUsageError(detail, { cause: error });
     }
 }
@@ -1452,7 +1457,7 @@ export async function resolveDoctorCaseRunsPath(options) {
         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 });
     }
     const normalized = real.split(sep).join("/");