@akagilnc/pi-workflow-roles 0.1.4062 → 0.1.4196

package/dist/public-cli/invocation.js

@@ -4,12 +4,15 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { lstat, mkdir, readFile, realpath, writeFile, } from "node:fs/promises";
-import { basename, isAbsolute, join, resolve, sep } from "node:path";
+import { lstat, readFile, realpath, rename, writeFile, } from "node:fs/promises";
+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 { readRunTicketNumber } from "../run-ticket-number.js";
+import { ensureRoleRunDirectory, ensureRoleRunPlacement, roleRunArtifactsDirectory, roleRunPlacement, } from "../role-run-placement.js";
+import { isSafePositiveTicketNumber, readBoardTicketNumber, requireSafePositiveTicketNumber, } from "../run-ticket-number.js";
+import { rewriteRoleRunDurablePages, rewriteRunDirectoryPathFields, rewriteRunDirectoryPathValue, } from "../role-run-relocation.js";
 import { loadDoctorCase, } from "../doctor-evidence.js";
+import { projectCourtTicketNumbers } from "../diarist-contracts.js";
 import { emptyCollectorManifest, loadCollectorManifest, parseCollectorPrNumber, parseCollectorRepository, } from "../collector-config.js";
 import { resolveCollectorTarget } from "../collector-target.js";
 import { ownerRepoFromGitHubRemoteUrl } from "./github-remote.js";
@@ -23,18 +26,20 @@ 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";
-/** Issue principal + derive ledger placement through the injected authority only. */
+/** Issue a principal from the single authoritative role-run placement. */
 export function issueAdmissionPlacement(authority, request) {
-    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,
     };
@@ -159,19 +164,81 @@ export async function persistAdmittedSourceRunPath(admitted, sourceRunPath) {
  * Never clears an existing binding.
  */
 export async function bindAdmittedTicketNumber(admitted, ticketNumber) {
-    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.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, courtTicketNumbers) {
+    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"));
-    await writeFile(admittedPath, `${JSON.stringify({ ...current, ticketNumber }, null, 2)}\n`, "utf8");
+    await writeFile(admittedPath, `${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, authority, heldLease) {
+    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;
+    rewriteRunDirectoryPathFields(admittedRecord, [
+        "runDirectory",
+        "admittedRequestPath",
+        "taskPath",
+        "packetPath",
+        "prerequisitesPath",
+        "requestManifestPath",
+        "mergerInputPath",
+    ], oldRunDirectory, target.runDirectory);
+    for (const attachment of admitted.attachments) {
+        attachment.frozenPath = rewriteRunDirectoryPathValue(attachment.frozenPath, oldRunDirectory, target.runDirectory);
+    }
+    const principal = authority.seal(target);
+    admitted.principal = principal;
+    await rewriteRoleRunDurablePages({
+        pagesDirectory: target.runDirectory,
+        oldRunDirectory,
+        newRunDirectory: target.runDirectory,
+    });
 }
 /**
  * Bind ticket identity onto a run directory's durable pages when the admitted
@@ -179,9 +246,7 @@ export async function bindAdmittedTicketNumber(admitted, ticketNumber) {
  * Idempotent when the same number is already on the pages.
  */
 export async function bindTicketNumberOnRunDirectory(runDirectory, ticketNumber) {
-    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"));
@@ -526,7 +591,11 @@ export async function freezeAttachmentsIntoRun(attachmentPaths, runDirectory, su
     return freezeAttachments(attachmentPaths, attachmentsDirectory);
 }
 function ticketAdmissionFields(ticketNumber) {
-    return ticketNumber === undefined ? {} : { ticketNumber };
+    if (ticketNumber === undefined)
+        return {};
+    return {
+        ticketNumber: requireSafePositiveTicketNumber(ticketNumber, "assertedTicketNumber"),
+    };
 }
 /**
  * Shared instruction-seat admission for Judge and Inspector: project check,
@@ -541,15 +610,17 @@ async function admitStandardMaterialInvocation(role, options) {
     }
     const projectRoot = resolve(options.project ?? options.cwd);
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    // 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 = options.correlationId === undefined
         ? {}
@@ -573,6 +644,7 @@ async function admitStandardMaterialInvocation(role, options) {
             sha256: a.sha256,
             mediaKind: a.mediaKind,
         })),
+        ...ticketFields,
     };
     const admittedRequestPath = join(runDirectory, "admitted-request.json");
     await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
@@ -592,6 +664,7 @@ async function admitStandardMaterialInvocation(role, options) {
         principal,
         admittedRequestPath,
         ...correlationFields,
+        ...ticketFields,
     };
 }
 /**
@@ -664,15 +737,13 @@ export async function admitCountersignInvocation(options) {
     }
     const projectRoot = resolve(options.project ?? options.cwd);
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    const { principal, 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.
     const instruction = options.instruction;
@@ -745,9 +816,8 @@ export async function loadAdmittedJudgeRequest(runDirectory) {
     }
 }
 export async function ensureRunArtifactsDir(runDirectory) {
-    const dir = join(runDirectory, "artifacts");
-    await mkdir(dir, { recursive: true });
-    return dir;
+    const directory = roleRunArtifactsDirectory(runDirectory);
+    return ensureRoleRunDirectory(resolveActivationLedgerHome(homeFromRunDirectory(runDirectory)), directory);
 }
 /**
  * Admit a Coder Role run on the common Invocation request.
@@ -767,15 +837,13 @@ export async function admitCoderInvocation(options) {
     }
     const projectRoot = resolve(options.project ?? options.cwd);
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    const { principal, 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);
     const taskPath = join(runDirectory, "task.md");
     await writeFile(taskPath, instruction, "utf8");
@@ -876,15 +944,13 @@ export async function admitFixerInvocation(options) {
     }
     const projectRoot = resolve(options.project ?? options.cwd);
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    const { principal, 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);
     let prerequisitesPath;
     if (prerequisitesSource !== undefined) {
@@ -1138,15 +1204,13 @@ export async function admitCollectorInvocation(options) {
     }
     const manifestDigest = manifest.digest;
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    const { principal, 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
     // head/commit association — task-text scrape is not a target lock.
@@ -1223,7 +1287,8 @@ export function buildCollectorTransportPrompt(admitted, engineMaterial) {
 /** Positive Issue number grammar shared with Doctor case path identity. */
 const DOCTOR_ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/;
 /** Match retained Doctor case runs roots (ADR 0017 / loadDoctorCase). */
-const DOCTOR_CASE_RUNS_PATH_PATTERN = /\/\.ak-roles\/books\/[^/]+\/issues\/([1-9]\d*)\/runs$/;
+/** 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$/;
 /**
  * Parse a positive Issue number for public Doctor admission.
  * Leading zeros and non-integers are structural rejects.
@@ -1308,7 +1373,8 @@ export function parseDoctorArgv(args) {
  */
 export async function resolveDoctorCaseRunsPath(options) {
     const ledgerHome = resolveActivationLedgerHome(options.home);
-    const defaultRuns = join(activationBookDirectory(ledgerHome, options.bookKey), "issues", String(options.issueNumber), "runs");
+    // Canonical topology: <book>/<ticket>/runs (docs/dossier-topology.md).
+    const defaultRuns = join(activationBookDirectory(ledgerHome, options.bookKey), String(options.issueNumber), "runs");
     if (options.runs === undefined) {
         return defaultRuns;
     }
@@ -1336,7 +1402,7 @@ export async function resolveDoctorCaseRunsPath(options) {
     const normalized = real.split(sep).join("/");
     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");
+        throw new CliUsageError("doctor --runs must be an .ak-roles/books/<book>/<n>/runs directory");
     }
     if (Number(match[1]) !== options.issueNumber) {
         throw new CliUsageError(`doctor --runs issue ${match[1]} does not match --issue ${options.issueNumber}`);
@@ -1360,10 +1426,11 @@ export async function admitDoctorInvocation(options) {
     }
     const projectRoot = resolve(options.project ?? options.cwd);
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    const { principal, sessionDirectory, sessionFile, runDirectory, attachmentsDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
         cwd: projectRoot,
         runId,
         role: "doctor",
+        subject: { unbound: true },
         home: options.home,
     });
     let caseRunsPath;
@@ -1402,9 +1469,6 @@ export async function admitDoctorInvocation(options) {
         const detail = error instanceof Error ? error.message : String(error);
         throw new CliUsageError(`doctor case could not be constructed from retained evidence: ${detail}`, { cause: error });
     }
-    const attachmentsDirectory = join(runDirectory, "attachments");
-    ensureRealDirectoryTree(ledgerHome, sessionDirectory);
-    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
     const attachments = await freezeAttachments(options.attachmentPaths ?? [], attachmentsDirectory);
     const instruction = options.instruction ?? "";
     const instructionEmpty = instruction.trim() === "";
@@ -1529,15 +1593,19 @@ 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, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    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",
         runId,
@@ -1647,13 +1715,13 @@ export async function admitGleanerLeftInvocation(options) {
     }
     const projectRoot = resolve(options.project ?? options.cwd);
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    const { principal, 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() === "";
     const admitted = {
@@ -1767,15 +1835,13 @@ export async function admitReviewerInvocation(options) {
     const authorityRefs = Object.freeze((options.authorityRefs ?? []).map((ref) => requireAuthorityRef(ref)));
     const projectRoot = resolve(options.project ?? options.cwd);
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    const { principal, 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);
     const instruction = options.instruction;
@@ -1928,15 +1994,13 @@ export async function admitMergerInvocation(options) {
     const projectRoot = resolve(options.project ?? options.cwd);
     const derived = await deriveMergerEnvelopeFromActiveMerge(projectRoot, options.gitState ?? createProductionMergerGitState(projectRoot));
     const runId = (options.createRunId ?? uuidv7)();
-    const { principal, sessionDirectory, sessionFile, runDirectory, ledgerHome, bookKey, } = issueAdmissionPlacement(options.principalAuthority, {
+    const { principal, 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);
     // Intent materials seed primary-source investigation; the method owns the work.
     const targetLabel = derived.targetObjectId === "" ? "(none observed)" : derived.targetObjectId;