@akagilnc/pi-workflow-roles 0.1.5483 → 0.1.5571

package/dist/public-cli/invocation.js

@@ -9,10 +9,11 @@ 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, isUnboundRunDirectory, listBookRunDirectories, roleRunArtifactsDirectory, roleRunPlacement, } from "../role-run-placement.js";
+import { ensureRoleRunDirectory, ensureRoleRunPlacement, formatRunLeaf, isUnboundRunDirectory, listBookRunDirectories, 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 { isSafePositiveTicketNumber, parseTicketNumber, readBoardTicketNumber, requireSafePositiveTicketNumber, } from "../run-ticket-number.js";
 import { rewriteRunDirectoryPathFields, rewriteRunDirectoryPathValue, } from "../role-run-relocation.js";
+import { readPageSync, renderCurrentSync, updateSectionSync, writeSectionSync } from "../run-dossier.js";
 import { loadDoctorCase, } from "../doctor-evidence.js";
 import { emptyCollectorManifest, loadCollectorManifest, parseCollectorPrNumber, parseCollectorRepository, } from "../collector-config.js";
 import { ownerRepoFromGitHubRemoteUrl } from "./github-remote.js";
@@ -48,17 +49,16 @@ export function issueAdmissionPlacement(authority, request) {
     };
 }
 /**
- * Unique admitted-request.json persistence projection: top-level sessionDirectory/sessionFile
+ * Unique `admitted` section projection of current.json: top-level sessionDirectory/sessionFile
  * (base wire shape). Memory Admitted keeps only the opaque principal — never dual-carry.
  */
-async function writeAdmittedRequestPersistence(admittedRequestPath, body, coordinates) {
+function writeAdmittedRequestPersistence(runDirectory, body, coordinates) {
     const { principal: _omitPrincipal, ...rest } = body;
-    const projection = {
+    writeSectionSync(runDirectory, "admitted", {
         ...rest,
         sessionDirectory: coordinates.sessionDirectory,
         sessionFile: coordinates.sessionFile,
-    };
-    await writeFile(admittedRequestPath, `${JSON.stringify(projection, null, 2)}\n`, "utf8");
+    });
 }
 /** Project effective model onto ledger fields; absent thinking stays absent. */
 function effectiveModelLedgerFields(model) {
@@ -72,7 +72,7 @@ function effectiveModelLedgerFields(model) {
 }
 export { homeFromRunDirectory };
 /**
- * Persist one `invocation.json` identity page for the public run.
+ * Persist the `invocation` identity section of current.json for the public run.
  * Admission is the sole source for every field; this is the only identity
  * projection and callers never provide an independent ledger shape.
  * When an effective model is known at admission, provider/model (and thinking
@@ -91,7 +91,7 @@ async function writeRoleInvocationLedger(source, role, effectiveModel) {
         ...(source.ticketNumber === undefined ? {} : { ticketNumber: source.ticketNumber }),
         ...effectiveModelLedgerFields(effectiveModel),
     };
-    await writeFile(join(source.runDirectory, "invocation.json"), `${JSON.stringify(identity, null, 2)}\n`, "utf8");
+    writeSectionSync(source.runDirectory, "invocation", identity);
 }
 /**
  * Merge the effective launch model / engine / host onto the existing invocation
@@ -104,7 +104,7 @@ async function writeRoleInvocationLedger(source, role, effectiveModel) {
  * Host stays write-if-present (`string` only).
  */
 export async function recordEffectiveInvocationModel(runDirectory, model, engine, host, engineModel) {
-    await updateDurableJsonPage(join(runDirectory, "invocation.json"), (current) => {
+    updateSectionSync(runDirectory, "invocation", (current) => {
         const next = { ...current };
         if (model !== undefined) {
             next.provider = model.provider;
@@ -134,33 +134,22 @@ export async function recordEffectiveInvocationModel(runDirectory, model, engine
         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. */
+/** Merge observed launch-time fields into the single existing invocation section of current.json. */
 async function mergeInvocationIdentityPage(runDirectory, fields) {
-    await updateDurableJsonPage(join(runDirectory, "invocation.json"), (current) => ({
+    updateSectionSync(runDirectory, "invocation", (current) => ({
         ...current,
         ...fields,
     }));
 }
 /**
- * Persist parent --source-run path onto admitted-request for officer resume lookup (#747).
+ * Persist parent --source-run path onto the admitted section for officer resume lookup (#747).
  * Reuses the existing notary sourceRunPath key; does not invent a new field name.
  */
 export async function persistAdmittedSourceRunPath(admitted, sourceRunPath, auditorSubject) {
     if (sourceRunPath.trim() === "") {
         throw new Error("persistAdmittedSourceRunPath requires a non-empty sourceRunPath");
     }
-    await updateDurableJsonPage(admitted.admittedRequestPath, (current) => {
+    updateSectionSync(admitted.runDirectory, "admitted", (current) => {
         if (typeof current.sourceRunPath === "string" && current.sourceRunPath !== sourceRunPath) {
             throw new Error(`persistAdmittedSourceRunPath refuses to replace ${current.sourceRunPath} with ${sourceRunPath}`);
         }
@@ -176,7 +165,7 @@ export async function persistAdmittedSourceRunPath(admitted, sourceRunPath, audi
 }
 /**
  * Bind a post-admission resolved ticketNumber onto the in-memory admitted
- * object and both durable pages (invocation.json + admitted-request.json).
+ * object and both durable sections (invocation + admitted).
  * A later typed role receipt replaces an earlier assertion (#1025).
  */
 export async function bindAdmittedTicketNumber(admitted, ticketNumber) {
@@ -188,7 +177,7 @@ export async function bindAdmittedTicketNumber(admitted, ticketNumber) {
 /** Persist each direct caller observed while a retained run is resumed. */
 export async function recordAdmittedCorrelation(admitted, correlationId) {
     let correlationIds = [];
-    await updateDurableJsonPage(admitted.admittedRequestPath, (current) => {
+    updateSectionSync(admitted.runDirectory, "admitted", (current) => {
         const prior = [
             ...(Array.isArray(current.correlationIds)
                 ? current.correlationIds.filter((value) => typeof value === "string" && value.trim() !== "")
@@ -225,12 +214,11 @@ export async function relocateAdmittedRunToTicket(admitted, authority, heldLease
     // Keep that failure before the filesystem commit point.
     const principal = authority.seal(target);
     if (admitted.role !== "diarist") {
-        const parentPage = JSON.parse(await readFile(admitted.admittedRequestPath, "utf8"));
-        const childRunIds = parentPage.childDiaristRunIds;
+        const childRunIds = readPageSync(oldRunDirectory, "admitted")?.childDiaristRunIds;
         for (const childRunId of Array.isArray(childRunIds) ? childRunIds : []) {
             if (typeof childRunId !== "string")
                 continue;
-            const childDirectory = join(dirname(oldRunDirectory), `${childRunId}@diarist`);
+            const childDirectory = join(dirname(oldRunDirectory), formatRunLeaf(childRunId, "diarist"));
             // A child that already filed under a ticket keeps its own assertion.
             if (!existsSync(childDirectory))
                 continue;
@@ -245,6 +233,15 @@ export async function relocateAdmittedRunToTicket(admitted, authority, heldLease
             await rehomeUnboundTicketProvenance(childDirectory, admitted.ticketNumber, admitted.projectRoot, homeFromRunDirectory(oldRunDirectory));
             ensureRoleRunDirectory(ledgerHome, dirname(childTarget.runDirectory));
             await rename(childDirectory, childTarget.runDirectory);
+            // Finished child legs will not settle again; refresh derived host.original
+            // after the rename commit. A derived render fault must not undo or block
+            // the committed placement (#1161 L1) — note and keep the true cause.
+            try {
+                renderCurrentSync(childTarget.runDirectory);
+            }
+            catch (error) {
+                process.stderr.write(`[invocation] current.json render refused after child relocate; placement kept: ${childTarget.runDirectory}: ${errorText(error)}\n`);
+            }
         }
     }
     // The first ticket assignment moves only an unbound diarist's own diary.
@@ -255,13 +252,13 @@ export async function relocateAdmittedRunToTicket(admitted, authority, heldLease
     // outside the atomic directory move.
     // Persisted paths are resolved from typed run identity on read.
     await rename(oldRunDirectory, target.runDirectory);
-    // rename moved the open lock inode with the directory. Transfer cleanup
-    // ownership immediately after the commit.
+    // rename moved the open lock inode with the directory. Transfer cleanup and
+    // admitted path ownership immediately after the commit — before any derived
+    // render that may refuse (#1161 L1 / BASE order).
     heldLease?.relocate(target.runDirectory);
     const admittedRecord = admitted;
     rewriteRunDirectoryPathFields(admittedRecord, [
         "runDirectory",
-        "admittedRequestPath",
         "taskPath",
         "packetPath",
         "prerequisitesPath",
@@ -272,11 +269,15 @@ export async function relocateAdmittedRunToTicket(admitted, authority, heldLease
         attachment.frozenPath = rewriteRunDirectoryPathValue(attachment.frozenPath, oldRunDirectory, target.runDirectory);
     }
     admitted.principal = principal;
+    // current.json projects host.original from this run directory. Ownership is
+    // already transferred; a refuse still carries the true cause to the caller
+    // (#1161 L1) without leaving the leg under the unbound path.
+    renderCurrentSync(target.runDirectory);
     return { oldRunDirectory, newRunDirectory: target.runDirectory };
 }
 /** Persist the exact child identity; later parent binding never inspects siblings. */
 export async function recordChildDiaristRun(parent, childRunId) {
-    await updateDurableJsonPage(parent.admittedRequestPath, (page) => {
+    updateSectionSync(parent.runDirectory, "admitted", (page) => {
         const existing = Array.isArray(page.childDiaristRunIds)
             ? page.childDiaristRunIds.filter((runId) => typeof runId === "string")
             : [];
@@ -291,9 +292,8 @@ export async function recordChildDiaristRun(parent, childRunId) {
  */
 export async function bindTicketNumberOnRunDirectory(runDirectory, ticketNumber) {
     requireSafePositiveTicketNumber(ticketNumber, "bindTicketNumberOnRunDirectory");
-    const admittedPath = join(runDirectory, "admitted-request.json");
     let unchanged = false;
-    await updateDurableJsonPage(admittedPath, (admitted) => {
+    updateSectionSync(runDirectory, "admitted", (admitted) => {
         if (admitted.ticketNumber === ticketNumber) {
             unchanged = true;
             return undefined;
@@ -334,17 +334,16 @@ export async function recordLaunchedRolePackageIdentity(runDirectory, identity)
         entryMode: identity.entryMode,
     });
 }
+/** Trim, then the shared ticket spelling. Callers keep their own diagnostic text. */
+function rejectUnlessTicketNumber(raw, message) {
+    const parsed = parseTicketNumber(raw.trim());
+    if (parsed === undefined)
+        throw new CliUsageError(message);
+    return parsed;
+}
 /** Positive ticket number for analyst query-scope face (and shared integer parse). */
 export function parsePositiveTicketNumber(raw, flag) {
-    const trimmed = raw.trim();
-    if (!ANALYST_TICKET_NUMBER_PATTERN.test(trimmed)) {
-        throw new CliUsageError(`${flag} must be a positive integer, got ${raw}`);
-    }
-    const value = Number(trimmed);
-    if (!Number.isSafeInteger(value) || value < 1) {
-        throw new CliUsageError(`${flag} must be a positive integer, got ${raw}`);
-    }
-    return value;
+    return rejectUnlessTicketNumber(raw, `${flag} must be a positive integer, got ${raw}`);
 }
 /**
  * One token scan for public argv.
@@ -702,8 +701,13 @@ async function freezeRegularFileAttachment(sourcePath, destinationDir, index) {
     };
 }
 /** Freeze attachments only — ticket binding is the shared LLM seat path (#635). */
-async function freezeAttachments(attachmentPaths, attachmentsDirectory) {
+async function freezeAttachments(ledgerHome, attachmentPaths, attachmentsDirectory) {
     const attachments = [];
+    // attachments/ appears only when something is frozen; created through the
+    // ledger's symlink-rejecting tree walk, never a plain mkdir.
+    if (attachmentPaths.length > 0) {
+        ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    }
     for (let i = 0; i < attachmentPaths.length; i += 1) {
         const frozen = await freezeRegularFileAttachment(attachmentPaths[i], attachmentsDirectory, i);
         attachments.push(frozen.attachment);
@@ -721,7 +725,7 @@ export async function freezeAttachmentsIntoRun(attachmentPaths, runDirectory, su
     const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(runDirectory));
     const attachmentsDirectory = join(runDirectory, "attachments", summonsKey);
     ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
-    return freezeAttachments(attachmentPaths, attachmentsDirectory);
+    return freezeAttachments(ledgerHome, attachmentPaths, attachmentsDirectory);
 }
 /** Freeze prepared bytes and metadata through one path for birth or retained runs. */
 export async function freezePreparedAttachmentsIntoRun(prepared, runDirectory, summonsKey) {
@@ -957,7 +961,7 @@ export async function admitPublicRole(role, parsed, env, override) {
                     }
                     let caseIdentity;
                     try {
-                        const patient = await loadDoctorCase(caseRunsPath);
+                        const patient = await loadDoctorCase(caseRunsPath, parsed.runs === undefined ? undefined : placed.projectRoot);
                         if (patient.identity.issueNumber !== issueNumber) {
                             throw new CliUsageError(`doctor case issue ${patient.identity.issueNumber} does not match --issue ${issueNumber}`);
                         }
@@ -970,7 +974,7 @@ export async function admitPublicRole(role, parsed, env, override) {
                         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);
+                    frozenAttachments = await freezeAttachments(placed.ledgerHome, attachmentPaths, placed.attachmentsDirectory);
                     return {
                         issueNumber,
                         caseRunsPath,
@@ -1127,7 +1131,7 @@ async function placeRoleAdmission(options) {
     });
     const attachments = options.freezeAttachments === false
         ? []
-        : await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+        : await freezeAttachments(ledgerHome, options.attachmentPaths, attachmentsDirectory);
     return {
         runId,
         bookKey,
@@ -1152,8 +1156,7 @@ function persistedAttachmentRefs(attachments) {
     }));
 }
 async function persistPlacedAdmission(admitted, placed, model) {
-    const admittedRequestPath = join(placed.runDirectory, "admitted-request.json");
-    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+    writeAdmittedRequestPersistence(placed.runDirectory, admitted, {
         sessionDirectory: placed.sessionDirectory,
         sessionFile: placed.sessionFile,
     });
@@ -1162,11 +1165,10 @@ async function persistPlacedAdmission(admitted, placed, model) {
         sessionDirectory: placed.sessionDirectory,
         sessionFile: placed.sessionFile,
     }, admitted.role, model);
-    return admittedRequestPath;
 }
 /**
  * Shared admission: project check, placement, attachment freeze,
- * admitted-request and invocation ledger write.
+ * admitted and invocation section write.
  * Countersign passes deferPersistence so same-ticket lookup can reserve coordinates
  * before materializeCountersignInvocation writes the page.
  * Seats whose extra facts are known before placement pass them as admittedFields.
@@ -1215,9 +1217,8 @@ async function admitStandardMaterialInvocation(role, options) {
         attachments: persistedAttachmentRefs(placed.attachments),
         ...placed.ticketFields,
     };
-    const admittedRequestPath = defer
-        ? join(placed.runDirectory, "admitted-request.json")
-        : await persistPlacedAdmission(admitted, placed, options.model);
+    if (!defer)
+        await persistPlacedAdmission(admitted, placed, options.model);
     return {
         role,
         runId: placed.runId,
@@ -1228,7 +1229,6 @@ async function admitStandardMaterialInvocation(role, options) {
         attachments: placed.attachments,
         runDirectory: placed.runDirectory,
         principal: placed.principal,
-        admittedRequestPath,
         ...correlationFields,
         ...placed.ticketFields,
         ...admittedFields,
@@ -1305,7 +1305,6 @@ export async function materializeCountersignInvocation(admitted, options) {
     });
     const placement = placed;
     admitted.runDirectory = placement.runDirectory;
-    admitted.admittedRequestPath = join(placement.runDirectory, "admitted-request.json");
     admitted.principal = placement.principal;
     const ticketFields = ticketAdmissionFields(options.ticketNumber);
     if (ticketFields.ticketNumber !== undefined) {
@@ -1313,19 +1312,18 @@ export async function materializeCountersignInvocation(admitted, options) {
     }
     const attachments = await freezePreparedAttachmentsIntoRun(options.preparedAttachments, admitted.runDirectory);
     admitted.attachments = attachments;
-    await writeAdmittedRequestPersistence(admitted.admittedRequestPath, admitted, {
+    writeAdmittedRequestPersistence(admitted.runDirectory, admitted, {
         sessionDirectory: placement.sessionDirectory,
         sessionFile: placement.sessionFile,
     });
     await writeRoleInvocationLedger({ ...admitted, sessionDirectory: placement.sessionDirectory, sessionFile: placement.sessionFile }, admitted.role, options.model);
 }
-/** Load admitted-request.json written at admission (Navigator work-context seam). */
+/** Load the admitted section written at admission (Navigator work-context seam). */
 export async function loadAdmittedJudgeRequest(runDirectory) {
     try {
-        const raw = JSON.parse(await readFile(join(runDirectory, "admitted-request.json"), "utf8"));
-        if (!isRecord(raw))
+        const record = readPageSync(runDirectory, "admitted");
+        if (record === undefined)
             return undefined;
-        const record = raw;
         if (!packagedPublicInstructionSubject(record.role))
             return undefined;
         if (typeof record.instruction !== "string")
@@ -1344,10 +1342,6 @@ export async function loadAdmittedJudgeRequest(runDirectory) {
         return undefined;
     }
 }
-export async function ensureRunArtifactsDir(runDirectory) {
-    const directory = roleRunArtifactsDirectory(runDirectory);
-    return ensureRoleRunDirectory(resolveActivationLedgerHome(homeFromRunDirectory(runDirectory)), directory);
-}
 function parsePositivePrOption(raw) {
     if (raw === undefined || raw.trim() === "")
         throw new CliUsageError("--pr requires a positive pull request number");
@@ -1411,26 +1405,17 @@ function isGitRemoteMissing(error) {
     const status = error.status;
     return status === 2;
 }
-/** 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). */
-/** 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.
  */
 export function parseDoctorIssueNumber(raw) {
-    const trimmed = raw.trim();
-    if (!DOCTOR_ISSUE_NUMBER_PATTERN.test(trimmed)) {
-        throw new CliUsageError(`doctor --issue must be a positive integer, got ${raw}`);
-    }
-    return Number(trimmed);
+    return rejectUnlessTicketNumber(raw, `doctor --issue must be a positive integer, got ${raw}`);
 }
 /**
  * Resolve the retained Doctor case runs root from Issue identity.
- * Default is the #78 book locator; optional --runs must stay project-confined
- * and match Doctor case grammar for the same issue number.
+ * Default is the #78 book locator; optional --runs must stay project-confined.
+ * loadDoctorCase owns retained-root grammar at IO; admission matches its case identity.
  */
 export async function resolveDoctorCaseRunsPath(options) {
     const ledgerHome = resolveActivationLedgerHome(options.home);
@@ -1460,14 +1445,6 @@ export async function resolveDoctorCaseRunsPath(options) {
         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("/");
-    const match = normalized.match(DOCTOR_CASE_RUNS_PATH_PATTERN);
-    if (!match) {
-        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}`);
-    }
     return real;
 }
 /** Frozen Skill arg projection shared by initial and resume (never reverse-parsed). */
@@ -1501,23 +1478,13 @@ export async function deriveMergerEnvelopeFromActiveMerge(projectRoot, gitState
         resolutionScope,
     });
 }
-const ANALYST_TICKET_NUMBER_PATTERN = /^[1-9]\d*$/;
 /**
  * Parse a positive ticket / issue number for public analyst admission.
  * Leading zeros and non-integers are structural rejects (same face as #176).
  * `flag` names the actual argv face in diagnostics (cohort group lists reuse this).
  */
 export function parseAnalystTicketNumber(raw, flag = "--ticket") {
-    const trimmed = raw.trim();
-    if (!ANALYST_TICKET_NUMBER_PATTERN.test(trimmed)) {
-        throw new CliUsageError(`analyst ${flag} must be a positive integer, got ${raw}`);
-    }
-    const value = Number(trimmed);
-    // Digit-only strings beyond MAX_SAFE_INTEGER round or become Infinity — reject.
-    if (!Number.isSafeInteger(value) || value < 1) {
-        throw new CliUsageError(`analyst ${flag} must be a positive integer, got ${raw}`);
-    }
-    return value;
+    return rejectUnlessTicketNumber(raw, `analyst ${flag} must be a positive integer, got ${raw}`);
 }
 /**
  * Parse one cohort issue token: bare positive integer or `book:N`.
@@ -1532,7 +1499,7 @@ export function parseAnalystCohortIssueToken(raw, flag) {
     const sep = trimmed.lastIndexOf(":");
     if (sep > 0) {
         const rhs = trimmed.slice(sep + 1);
-        if (ANALYST_TICKET_NUMBER_PATTERN.test(rhs)) {
+        if (parseTicketNumber(rhs) !== undefined) {
             const bookKey = trimmed.slice(0, sep);
             if (bookKey.trim() === "") {
                 throw new CliUsageError(`${flag} book:N requires a non-empty book key, got ${raw}`);