@akagilnc/pi-workflow-roles 0.1.5797 → 0.1.5820

package/dist/auditor-role.js

@@ -0,0 +1,7 @@
+/**
+ * Public Auditor (审刑院) role — filed-officer envelope (#675).
+ */
+import { AUDITOR_OUTPUT_TOOL_NAME, } from "./package-contracts/auditor-output.js";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.js";
+export { AUDITOR_OUTPUT_TOOL_NAME };
+export const AUDITOR_TOOL_SPEC = roleSubmissionDeclaration("auditor");

package/dist/book-topology-migration-placement.js

@@ -0,0 +1,404 @@
+import { readdir, readFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathContainedIn } from "./activation-ledger-topology.js";
+import { isUnboundRunDirectory, roleRunPlacement } from "./role-run-placement.js";
+export { isUnboundRunDirectory };
+import { MIGRATION_TICKET_DERIVATION_PAGE, readMigrationBoardTicketNumber, readMigrationDerivedTicketNumber, } from "./run-ticket-number.js";
+import { readPageSync } from "./run-dossier.js";
+import { isRecord, isEnoent } from "./unknown-value.js";
+const TICKET_NUMBER_RE = /^[1-9][0-9]*$/;
+const RUN_DIR_NAME_RE = /^([^@]+)@([^@]+)$/;
+/** Book-key directories under a books root; missing root → []. */
+export async function listMigrationBookKeys(booksDirectory) {
+    try {
+        const entries = await readdir(booksDirectory, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+}
+/** Directory entries sorted by name; missing directory → []. */
+export async function listMigrationDirents(directory) {
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        return [...entries].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+}
+export function ticketNumberFromUnknown(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+        return value;
+    if (typeof value === "string" && TICKET_NUMBER_RE.test(value))
+        return Number(value);
+    return undefined;
+}
+export function isTicketNumberString(value) {
+    return TICKET_NUMBER_RE.test(value);
+}
+/**
+ * Ticket number contained in a worktree path's final segment.
+ * #852: 「工作树路径末段所含票号」— shared by #865 and #866.
+ * Exactly one digit run that is itself a safe positive ticket spelling;
+ * multiple or zero digit runs are undecidable → undefined (unbound).
+ */
+export function ticketNumberFromWorktreeBasename(pathBasename) {
+    const matches = pathBasename.match(/\d+/g);
+    if (matches === null || matches.length !== 1)
+        return undefined;
+    const spelling = matches[0];
+    if (!TICKET_NUMBER_RE.test(spelling))
+        return undefined;
+    const ticketNumber = Number(spelling);
+    if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1)
+        return undefined;
+    return ticketNumber;
+}
+/**
+ * projectRoot from a retained run's durable pages.
+ * New落点 (state rows) first, then pre-#1161 page files at the migration boundary.
+ * ENOENT → try next / undefined; bad JSON and non-ENOENT IO propagate.
+ */
+async function readProjectRootFromRun(runDirectory) {
+    for (const section of ["admitted", "invocation", "runState"]) {
+        try {
+            const page = readPageSync(runDirectory, section);
+            const projectRoot = page?.projectRoot;
+            if (typeof projectRoot === "string" && projectRoot.length > 0) {
+                return { projectRoot, sourcePage: `state.jsonl:${section}` };
+            }
+        }
+        catch (error) {
+            if (!isEnoent(error))
+                throw error;
+        }
+    }
+    for (const page of ["admitted-request.json", "invocation.json", "run-state.json"]) {
+        const path = join(runDirectory, page);
+        try {
+            const raw = JSON.parse(await readFile(path, "utf8"));
+            if (!isRecord(raw))
+                continue;
+            const projectRoot = raw.projectRoot;
+            if (typeof projectRoot === "string" && projectRoot.length > 0) {
+                return { projectRoot, sourcePage: page };
+            }
+        }
+        catch (error) {
+            if (isEnoent(error))
+                continue;
+            throw error;
+        }
+    }
+    return undefined;
+}
+/**
+ * Ticket binding for a retained run directory (#852 / #865 / #866):
+ * effective placement ticket (board pages, else migration-derived page) first,
+ * then worktree basename containment when the leaf holds a ticket number.
+ * Migration placement may use derived facts; LLM/board identity writers must not.
+ */
+export async function resolveMigratingRunTicket(runDirectory) {
+    const boardTicket = await readMigrationBoardTicketNumber(runDirectory);
+    if (boardTicket !== undefined) {
+        return {
+            ticketNumber: boardTicket,
+            derivation: { method: "board", source: runDirectory },
+        };
+    }
+    const derivedTicket = await readMigrationDerivedTicketNumber(runDirectory);
+    if (derivedTicket !== undefined) {
+        return {
+            ticketNumber: derivedTicket,
+            derivation: {
+                method: "project-root-basename",
+                source: runDirectory,
+                sourcePage: MIGRATION_TICKET_DERIVATION_PAGE,
+            },
+        };
+    }
+    const project = await readProjectRootFromRun(runDirectory);
+    if (project === undefined)
+        return { ticketNumber: undefined, derivation: undefined };
+    const leaf = basename(project.projectRoot.replace(/\\/g, "/"));
+    const ticketNumber = ticketNumberFromWorktreeBasename(leaf);
+    if (ticketNumber === undefined)
+        return { ticketNumber: undefined, derivation: undefined };
+    return {
+        ticketNumber,
+        derivation: {
+            method: "project-root-basename",
+            source: project.projectRoot,
+            sourcePage: project.sourcePage,
+        },
+    };
+}
+export function bookHistoricalRoots(booksDirectory, backupBooksDirectory, bookKey) {
+    return [join(booksDirectory, bookKey), join(backupBooksDirectory, bookKey)];
+}
+function runLeafFromRelative(path) {
+    const segments = path.replaceAll("\\", "/").split("/").filter((segment) => segment.length > 0);
+    const runsIndex = segments.lastIndexOf("runs");
+    if (runsIndex < 0 || runsIndex + 1 >= segments.length)
+        return undefined;
+    const leaf = segments[runsIndex + 1];
+    if (leaf === undefined || leaf === "." || leaf === "..")
+        return undefined;
+    return leaf;
+}
+/** Bind a path to this book's historical roots, then take complete leaf + source-relative run dir. */
+export function runRefFromBoundPath(path, bookRoots) {
+    for (const root of bookRoots) {
+        const rootResolved = resolve(root);
+        const candidate = isAbsolute(path) ? resolve(path) : resolve(rootResolved, path);
+        if (candidate === rootResolved || !pathContainedIn(rootResolved, candidate))
+            continue;
+        const rel = relative(rootResolved, candidate).split(sep).join("/");
+        const leaf = runLeafFromRelative(rel);
+        if (leaf === undefined)
+            continue;
+        const parts = rel.split("/").filter((part) => part.length > 0);
+        const runsIndex = parts.indexOf("runs");
+        if (runsIndex < 0 || runsIndex + 1 >= parts.length)
+            continue;
+        return { leaf, sourceRelative: parts.slice(0, runsIndex + 2).join("/") };
+    }
+    return undefined;
+}
+async function listRunLeafEntries(runsDirectory) {
+    const entries = await listMigrationDirents(runsDirectory);
+    return entries.map((entry) => ({
+        name: entry.name,
+        isDirectory: entry.isDirectory(),
+    }));
+}
+/**
+ * Every retained run tree under one backup book: legacy flat `runs/`,
+ * already-canonical `<ticket>/runs/`, `unbound/runs/`, and legacy
+ * `issues/<ticket>/runs/`.
+ */
+export async function listBackupRunLeaves(backupBookDirectory) {
+    const leaves = [];
+    const collect = async (relativeDir, layout) => {
+        const runsDirectory = join(backupBookDirectory, ...relativeDir.split("/"));
+        for (const entry of await listRunLeafEntries(runsDirectory)) {
+            leaves.push({
+                relativePath: `${relativeDir}/${entry.name}`,
+                sourcePath: join(runsDirectory, entry.name),
+                leafName: entry.name,
+                isDirectory: entry.isDirectory,
+                layout,
+            });
+        }
+    };
+    await collect("runs", "flat");
+    await collect("unbound/runs", "unbound");
+    for (const subject of await listMigrationDirents(backupBookDirectory)) {
+        if (!subject.isDirectory() || !isTicketNumberString(subject.name))
+            continue;
+        await collect(`${subject.name}/runs`, "ticket");
+    }
+    for (const issue of await listMigrationDirents(join(backupBookDirectory, "issues"))) {
+        if (!issue.isDirectory() || !isTicketNumberString(issue.name))
+            continue;
+        await collect(`issues/${issue.name}/runs`, "issues");
+    }
+    return leaves;
+}
+async function listExactPlacedRunPaths(bookDir, leafName) {
+    const matches = [];
+    const subjectEntries = await listMigrationDirents(bookDir);
+    const runsDirs = [
+        join(bookDir, "runs"),
+        ...subjectEntries.filter((entry) => entry.isDirectory()).map((entry) => join(bookDir, entry.name, "runs")),
+    ];
+    for (const runsDir of runsDirs) {
+        const entries = await listMigrationDirents(runsDir);
+        if (entries.some((entry) => entry.name === leafName)) {
+            matches.push(join(runsDir, leafName));
+        }
+    }
+    return matches;
+}
+function destPathFromSourceRelative(booksDirectory, bookKey, sourceRelative) {
+    const parts = sourceRelative.replaceAll("\\", "/").split("/").filter((part) => part.length > 0);
+    const runsIndex = parts.indexOf("runs");
+    if (runsIndex < 0 || runsIndex + 1 >= parts.length)
+        return undefined;
+    const leaf = parts[runsIndex + 1];
+    const before = parts.slice(0, runsIndex);
+    if (leaf === undefined)
+        return undefined;
+    // Legacy issues/<ticket>/runs/<leaf> → canonical <ticket>/runs/<leaf>.
+    if (before.length === 2
+        && before[0] === "issues"
+        && before[1] !== undefined
+        && isTicketNumberString(before[1])) {
+        return join(booksDirectory, bookKey, before[1], "runs", leaf);
+    }
+    if (before.length !== 1)
+        return undefined;
+    const subject = before[0];
+    if (subject === undefined)
+        return undefined;
+    if (subject !== "unbound" && !isTicketNumberString(subject))
+        return undefined;
+    return join(booksDirectory, bookKey, subject, "runs", leaf);
+}
+function placedRunFromPath(runDirectory) {
+    return {
+        runDirectory,
+        disposition: isUnboundRunDirectory(runDirectory) ? "unbound" : "placed",
+    };
+}
+async function listPrincipalPlacedRunPaths(bookDir, runId) {
+    const matches = [...await listExactPlacedRunPaths(bookDir, runId)];
+    const subjectEntries = await listMigrationDirents(bookDir);
+    const runsDirs = [
+        join(bookDir, "runs"),
+        ...subjectEntries.filter((entry) => entry.isDirectory()).map((entry) => join(bookDir, entry.name, "runs")),
+    ];
+    const prefix = `${runId}@`;
+    for (const runsDir of runsDirs) {
+        for (const entry of await listMigrationDirents(runsDir)) {
+            const name = entry.name;
+            if (!name.startsWith(prefix) || name.slice(runId.length + 1).includes("@"))
+                continue;
+            const path = join(runsDir, name);
+            if (!matches.includes(path))
+                matches.push(path);
+        }
+    }
+    return matches;
+}
+function uniquePlacedRun(leafName, matches) {
+    if (matches.length === 0)
+        return undefined;
+    if (matches.length === 1)
+        return placedRunFromPath(matches[0]);
+    throw new Error(`book topology migration cannot uniquely place run ${leafName}: ${matches.join(", ")}`);
+}
+/** Locate an exact run leaf under bookDir/runs, bookDir/<subject>/runs, bookDir/unbound/runs. */
+export async function findBookRunDirectory(bookDir, runId, role) {
+    if (runId.trim() === "")
+        return undefined;
+    const leafName = role !== undefined && role.length > 0 ? `${runId}@${role}` : runId;
+    const matches = role !== undefined && role.length > 0
+        ? await listExactPlacedRunPaths(bookDir, leafName)
+        : await listPrincipalPlacedRunPaths(bookDir, runId);
+    const unique = uniquePlacedRun(leafName, matches);
+    if (unique === undefined)
+        return undefined;
+    const foundRole = unique.runDirectory.split(/[/\\]/).pop()?.split("@")[1] ?? role ?? "";
+    return { runDirectory: unique.runDirectory, role: foundRole };
+}
+/** Historical flat `runs/<leaf>` alias under a book root (not ticket/unbound). */
+export function isFlatRunsRelative(sourceRelative, leafName) {
+    const parts = sourceRelative.replaceAll("\\", "/").split("/").filter((part) => part.length > 0);
+    return parts.length === 2 && parts[0] === "runs" && parts[1] === leafName;
+}
+/** Destination run already placed by T9. Follow complete leaf; bind source path when given. */
+export async function findPlacedMigratingRun(booksDirectory, bookKey, leafName, sourceRelative) {
+    if (leafName.trim() === "")
+        return undefined;
+    const bookDir = join(booksDirectory, bookKey);
+    const matches = await listExactPlacedRunPaths(bookDir, leafName);
+    if (sourceRelative !== undefined && sourceRelative.length > 0) {
+        const preferred = destPathFromSourceRelative(booksDirectory, bookKey, sourceRelative);
+        if (preferred !== undefined) {
+            const hit = matches.find((path) => path === preferred);
+            if (hit !== undefined)
+                return placedRunFromPath(hit);
+            // T9 may have used the board ticket to move an historical unbound leaf
+            // under `<ticket>/runs`. The complete leaf is the placement identity;
+            // when it remains unique, downstream record/mixed/T11 consumers must
+            // follow that authoritative T9 result rather than re-derive unbound.
+            if (sourceRelative.replaceAll("\\", "/").startsWith("unbound/runs/")) {
+                return uniquePlacedRun(leafName, matches);
+            }
+            return undefined;
+        }
+        // Historical flat `runs/<leaf>` alias after T9 nested the unique complete leaf.
+        if (isFlatRunsRelative(sourceRelative, leafName)) {
+            return uniquePlacedRun(leafName, matches);
+        }
+        return undefined;
+    }
+    return uniquePlacedRun(leafName, matches);
+}
+/** True when this book retains exactly one directory named leafName across layouts. */
+export async function uniqueRunLeafExistsInBook(bookDir, leafName) {
+    if (leafName.trim() === "")
+        return false;
+    const matches = await listExactPlacedRunPaths(bookDir, leafName);
+    return matches.length === 1;
+}
+/**
+ * No path / role evidence: follow runId only when exactly one `runId@role`
+ * (or bare runId) exists across this book's layouts. Zero or multi → undefined.
+ */
+export async function findUniquePrincipalPlacedRun(booksDirectory, bookKey, runId) {
+    if (runId.trim() === "")
+        return undefined;
+    const matches = await listPrincipalPlacedRunPaths(join(booksDirectory, bookKey), runId);
+    if (matches.length !== 1)
+        return undefined;
+    return placedRunFromPath(matches[0]);
+}
+/**
+ * Destination run directory via the sole live placement authority (roleRunPlacement).
+ * booksDirectory is the books/ root; ledger home is its parent.
+ */
+export function destinationRunDirectory(booksDirectory, bookKey, ticketNumber, runId, role) {
+    const ledgerHome = dirname(booksDirectory);
+    const subject = ticketNumber !== undefined
+        ? { ticketNumber }
+        : { unbound: true };
+    return roleRunPlacement(ledgerHome, {
+        bookKey,
+        subject,
+        runId,
+        role,
+    }).runDirectory;
+}
+/** Extract runId@role from a sessionParent path when it points at a run session. */
+export function runCoordsFromSessionParent(sessionParent) {
+    if (typeof sessionParent !== "string" || sessionParent.length === 0)
+        return undefined;
+    const normalized = sessionParent.replace(/\\/g, "/");
+    const marker = "/runs/";
+    const index = normalized.lastIndexOf(marker);
+    if (index < 0)
+        return undefined;
+    const after = normalized.slice(index + marker.length);
+    const leaf = after.split("/")[0] ?? "";
+    const match = RUN_DIR_NAME_RE.exec(leaf);
+    if (match === null)
+        return undefined;
+    return { runId: match[1], role: match[2] };
+}
+export function runIdFromSubject(subject) {
+    if (typeof subject === "string" && subject.length > 0)
+        return subject;
+    if (isRecord(subject) && typeof subject.runId === "string" && subject.runId.length > 0) {
+        return subject.runId;
+    }
+    return undefined;
+}
+export function ticketNumberFromSubject(subject) {
+    if (typeof subject === "string" || typeof subject === "number") {
+        return ticketNumberFromUnknown(subject);
+    }
+    if (isRecord(subject))
+        return ticketNumberFromUnknown(subject.ticketNumber);
+    return undefined;
+}

package/dist/book-topology-migration.js

@@ -0,0 +1,125 @@
+import { mkdir, readdir, rename } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { physicalPathIdentity, physicallyContainedIn, } from "./activation-ledger-topology.js";
+import { autopsyWriterLock, describeErrorIdentity, } from "./public-cli/run-lifecycle.js";
+/** Shared reconciliation projection. Counting outcomes makes the closure true by construction. */
+export function reconcileMigrationPartition(partition, unit, outcomes) {
+    let placed = 0;
+    let unbound = 0;
+    let discarded = 0;
+    const malformedRows = [];
+    for (const outcome of outcomes) {
+        if (outcome.disposition === "placed")
+            placed += 1;
+        else if (outcome.disposition === "unbound")
+            unbound += 1;
+        else
+            discarded += 1;
+        if ("malformed" in outcome) {
+            malformedRows.push({ source: outcome.source, raw: outcome.malformedRaw });
+        }
+    }
+    return {
+        partition,
+        unit,
+        before: outcomes.length,
+        placed,
+        unbound,
+        discarded,
+        malformedRows,
+    };
+}
+async function findWriterLocks(root) {
+    const locks = [];
+    async function walk(directory) {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.name === "writer.lock") {
+                const kind = entry.isFile() ? "file"
+                    : entry.isDirectory() ? "directory"
+                        : entry.isSymbolicLink() ? "symbolic link"
+                            : entry.isFIFO() ? "FIFO"
+                                : entry.isSocket() ? "socket"
+                                    : entry.isCharacterDevice() ? "character device"
+                                        : entry.isBlockDevice() ? "block device"
+                                            : "unknown filesystem object";
+                locks.push({ path, regularFile: entry.isFile(), kind });
+            }
+            else if (entry.isDirectory()) {
+                await walk(path);
+            }
+        }
+    }
+    await walk(root);
+    return locks;
+}
+/**
+ * Refuse migration from a role whose canonical dossier is inside books/, and
+ * while a writer lease proves a run is currently active. Retained lifecycle
+ * state is history, not holder liveness.
+ */
+export async function assertBookTopologyMigrationPrerequisites(booksDirectory, env = process.env) {
+    const runDirectory = env.AK_ROLE_RUN_DIR;
+    if (runDirectory !== undefined
+        && (physicalPathIdentity(booksDirectory) === physicalPathIdentity(runDirectory)
+            || physicallyContainedIn(booksDirectory, runDirectory))) {
+        throw new Error(`book topology migration cannot run from a role dossier inside books/: ${runDirectory}`);
+    }
+    const active = [];
+    for (const candidate of await findWriterLocks(booksDirectory)) {
+        const lockPath = candidate.path;
+        if (!candidate.regularFile) {
+            throw new Error(`cannot establish zero in-flight runs from ${lockPath}: writer lock is a ${candidate.kind}, holder liveness unverifiable`);
+        }
+        const holder = await autopsyWriterLock(lockPath);
+        if (holder.verdict === "alive") {
+            active.push(`${lockPath} (live pid ${holder.pid})`);
+        }
+        else if (holder.verdict === "unknown") {
+            const cause = holder.reason === "unreadable"
+                ? `unreadable: ${describeErrorIdentity(holder.readFailure)}`
+                : `unparseable holder: ${JSON.stringify(holder.content)}`;
+            throw new Error(`cannot establish zero in-flight runs from ${lockPath}: ${cause}`);
+        }
+    }
+    if (active.length > 0) {
+        throw new Error(`book topology migration requires zero in-flight runs:\n${active.join("\n")}`);
+    }
+}
+export function datedBooksBackupDirectory(booksDirectory, now = new Date()) {
+    const date = now.toISOString().slice(0, 10);
+    return join(dirname(booksDirectory), `${basename(booksDirectory)}-${date}`);
+}
+/** Atomic same-parent rename: the readable pre-migration tree is never packed. */
+export async function renameBooksToDatedBackup(booksDirectory, now = new Date()) {
+    const backup = datedBooksBackupDirectory(booksDirectory, now);
+    await rename(booksDirectory, backup);
+    return backup;
+}
+export async function migrateBookTopology(input) {
+    if (input.migrators.length === 0) {
+        throw new Error("book topology migration has no partition migrators");
+    }
+    const ledgerHome = resolve(input.ledgerHome ?? join(homedir(), ".ak-roles"));
+    const booksDirectory = join(ledgerHome, "books");
+    await assertBookTopologyMigrationPrerequisites(booksDirectory, input.env);
+    const backupBooksDirectory = await renameBooksToDatedBackup(booksDirectory, input.now);
+    await mkdir(booksDirectory);
+    const context = {
+        backupBooksDirectory,
+        booksDirectory,
+    };
+    const partitions = [];
+    for (const migrator of input.migrators) {
+        const report = await migrator.migrate(context);
+        if (report.partition !== migrator.partition) {
+            throw new Error(`partition report mismatch: expected ${migrator.partition}, received ${report.partition}`);
+        }
+        if (report.before !== report.placed + report.unbound + report.discarded) {
+            throw new Error(`partition reconciliation did not close: ${report.partition}`);
+        }
+        partitions.push(report);
+    }
+    return { backupBooksDirectory, booksDirectory, partitions };
+}