@akagilnc/pi-workflow-roles 0.1.5797 → 0.1.5820

package/dist/book-topology-mixed-volume-migrators.js

@@ -0,0 +1,322 @@
+import { appendFile, cp, lstat, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+/** Historical side-branch nest name under a run session (pre-#1178). */
+const WORKER_SUBMISSION_GATE_KIND = "worker-submission-gate";
+import { reconcileMigrationPartition, } from "./book-topology-migration.js";
+import { bookHistoricalRoots, findPlacedMigratingRun, listMigrationBookKeys, listMigrationDirents, runRefFromBoundPath, } from "./book-topology-migration-placement.js";
+import { isRecord, isEnoent } from "./unknown-value.js";
+const SITIAN_MIXED_VOLUME_PARTITIONS = [
+    "attendance",
+    "auditor",
+    "dispatch-error",
+    "gate",
+];
+const CURRENT_SESSION_LEDGER = "current-session.json";
+function posixRelative(from, to) {
+    return relative(from, to).split(sep).join("/");
+}
+function addPathCandidate(paths, seen, value) {
+    if (typeof value !== "string" || value.length === 0 || seen.has(value))
+        return;
+    seen.add(value);
+    paths.push(value);
+}
+/** Path fields that can carry a decidable run leaf (`.../runs/<leaf>/...`). */
+function pathCandidatesFromRecord(record) {
+    const paths = [];
+    const seen = new Set();
+    addPathCandidate(paths, seen, record.sessionParent);
+    addPathCandidate(paths, seen, record.parentSession);
+    if (!isRecord(record.payload))
+        return paths;
+    const payload = record.payload;
+    addPathCandidate(paths, seen, payload.sessionParent);
+    addPathCandidate(paths, seen, payload.parentSession);
+    addPathCandidate(paths, seen, payload.sessionFile);
+    if (isRecord(payload.parent)) {
+        addPathCandidate(paths, seen, payload.parent.sessionFile);
+        addPathCandidate(paths, seen, payload.parent.sessionParent);
+        addPathCandidate(paths, seen, payload.parent.parentSession);
+    }
+    if (isRecord(payload.data)) {
+        addPathCandidate(paths, seen, payload.data.sessionParent);
+        addPathCandidate(paths, seen, payload.data.parentSession);
+        addPathCandidate(paths, seen, payload.data.sessionFile);
+        addPathCandidate(paths, seen, payload.data.file);
+    }
+    return paths;
+}
+function describeFsKind(entry) {
+    if (entry.isFile())
+        return "file";
+    if (entry.isDirectory())
+        return "directory";
+    if (entry.isSymbolicLink())
+        return "symbolic link";
+    if (entry.isFIFO())
+        return "FIFO";
+    if (entry.isSocket())
+        return "socket";
+    if (entry.isCharacterDevice())
+        return "character device";
+    if (entry.isBlockDevice())
+        return "block device";
+    return "unknown filesystem object";
+}
+function runRefFromRecord(record, bookRoots) {
+    for (const path of pathCandidatesFromRecord(record)) {
+        const ref = runRefFromBoundPath(path, bookRoots);
+        if (ref !== undefined)
+            return ref;
+    }
+    return undefined;
+}
+async function readRegularBackupFile(path) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return undefined;
+        throw error;
+    }
+    if (!info.isFile()) {
+        throw new Error(`cannot migrate mixed volume from ${path}: source is a ${describeFsKind(info)}, not a regular file`);
+    }
+    return readFile(path, "utf8");
+}
+/**
+ * Worker-submission-gate volumes are Pi session files. Ownership is only the
+ * session header's parentSession — never later message/payload path fields.
+ * Malformed JSONL rows are reported separately; they do not select the leaf.
+ */
+function inspectWorkerSubmissionGateVolume(text, bookRoots) {
+    const malformedRows = [];
+    let firstRecord = true;
+    let leaf;
+    let sourceRelative;
+    for (const row of jsonlRows(text)) {
+        const isHeader = firstRecord;
+        firstRecord = false;
+        let parsed;
+        try {
+            parsed = JSON.parse(row.raw);
+        }
+        catch {
+            malformedRows.push({ lineNumber: row.lineNumber, raw: row.raw });
+            continue;
+        }
+        if (!isRecord(parsed)) {
+            malformedRows.push({ lineNumber: row.lineNumber, raw: row.raw });
+            continue;
+        }
+        // Sole attribution evidence: the first JSONL record's parentSession.
+        if (isHeader &&
+            parsed.type === "session" &&
+            typeof parsed.parentSession === "string") {
+            const ref = runRefFromBoundPath(parsed.parentSession, bookRoots);
+            leaf = ref?.leaf;
+            sourceRelative = ref?.sourceRelative;
+        }
+    }
+    return { leaf, sourceRelative, malformedRows };
+}
+function volumeDestinationFile(booksDirectory, bookKey, destRun, kind, fileName) {
+    if (destRun === undefined) {
+        return join(booksDirectory, bookKey, "unbound", kind, fileName);
+    }
+    return join(destRun.runDirectory, "session", kind, fileName);
+}
+async function placedRunForLeaf(cache, booksDirectory, bookKey, leaf, sourceRelative) {
+    const cacheKey = `${bookKey}\0${sourceRelative ?? ""}\0${leaf}`;
+    if (cache.has(cacheKey))
+        return cache.get(cacheKey);
+    const placed = await findPlacedMigratingRun(booksDirectory, bookKey, leaf, sourceRelative);
+    cache.set(cacheKey, placed);
+    return placed;
+}
+async function appendRawLine(file, raw) {
+    await mkdir(dirname(file), { recursive: true });
+    await appendFile(file, `${raw}\n`, "utf8");
+}
+function jsonlRows(text) {
+    const lines = text.split("\n");
+    const rows = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const raw = lines[index];
+        if (index === lines.length - 1 && raw.length === 0)
+            continue;
+        if (!raw.trim())
+            continue;
+        rows.push({ lineNumber: index + 1, raw });
+    }
+    return rows;
+}
+async function migrateCurrentSessionPointer(input) {
+    const sourceFile = join(input.sourceDir, CURRENT_SESSION_LEDGER);
+    const raw = await readRegularBackupFile(sourceFile);
+    if (raw === undefined)
+        return;
+    let sessionFile;
+    try {
+        const parsed = JSON.parse(raw);
+        if (isRecord(parsed) && typeof parsed.sessionFile === "string" && parsed.sessionFile.length > 0) {
+            sessionFile = parsed.sessionFile;
+        }
+    }
+    catch {
+        sessionFile = undefined;
+    }
+    let destinationSessionFile;
+    if (sessionFile !== undefined) {
+        const pointed = resolve(input.sourceDir, sessionFile);
+        destinationSessionFile = input.volumeDestinations.get(pointed)
+            ?? input.volumeDestinations.get(sessionFile);
+    }
+    if (destinationSessionFile === undefined) {
+        await mkdir(dirname(input.unboundPointerFile), { recursive: true });
+        await writeFile(input.unboundPointerFile, raw.endsWith("\n") ? raw : `${raw}\n`, "utf8");
+        return;
+    }
+    const pointerFile = join(dirname(destinationSessionFile), CURRENT_SESSION_LEDGER);
+    await mkdir(dirname(pointerFile), { recursive: true });
+    await writeFile(pointerFile, `${JSON.stringify({ sessionFile: destinationSessionFile })}\n`, "utf8");
+}
+async function migrateSitianMixedVolume(partition, context) {
+    const outcomes = [];
+    const placedCache = new Map();
+    const { backupBooksDirectory, booksDirectory } = context;
+    for (const bookKey of await listMigrationBookKeys(backupBooksDirectory)) {
+        const sourceDir = join(backupBooksDirectory, bookKey, partition);
+        const recordsFile = join(sourceDir, "records.jsonl");
+        const bookRoots = bookHistoricalRoots(booksDirectory, backupBooksDirectory, bookKey);
+        const text = await readRegularBackupFile(recordsFile);
+        if (text === undefined) {
+            await migrateCurrentSessionPointer({
+                sourceDir,
+                volumeDestinations: new Map(),
+                unboundPointerFile: join(booksDirectory, bookKey, "unbound", partition, CURRENT_SESSION_LEDGER),
+            });
+            continue;
+        }
+        // Line placement builds the sole volume→dest map for current-session rewrite.
+        const placedDests = new Set();
+        const sourceIdentity = posixRelative(backupBooksDirectory, recordsFile);
+        for (const row of jsonlRows(text)) {
+            const source = `${sourceIdentity}:${row.lineNumber}`;
+            let parsed;
+            try {
+                parsed = JSON.parse(row.raw);
+            }
+            catch {
+                const dest = volumeDestinationFile(booksDirectory, bookKey, undefined, partition, "records.jsonl");
+                await appendRawLine(dest, row.raw);
+                placedDests.add(dest);
+                outcomes.push({
+                    disposition: "unbound",
+                    source,
+                    malformed: true,
+                    malformedRaw: row.raw,
+                });
+                continue;
+            }
+            if (!isRecord(parsed)) {
+                const dest = volumeDestinationFile(booksDirectory, bookKey, undefined, partition, "records.jsonl");
+                await appendRawLine(dest, row.raw);
+                placedDests.add(dest);
+                outcomes.push({
+                    disposition: "unbound",
+                    source,
+                    malformed: true,
+                    malformedRaw: row.raw,
+                });
+                continue;
+            }
+            const ref = runRefFromRecord(parsed, bookRoots);
+            const destRun = ref === undefined
+                ? undefined
+                : await placedRunForLeaf(placedCache, booksDirectory, bookKey, ref.leaf, ref.sourceRelative);
+            const dest = volumeDestinationFile(booksDirectory, bookKey, destRun, partition, "records.jsonl");
+            await appendRawLine(dest, row.raw);
+            placedDests.add(dest);
+            outcomes.push({
+                disposition: destRun?.disposition === "placed" ? "placed" : "unbound",
+                source,
+            });
+        }
+        const volumeDestinations = new Map();
+        if (placedDests.size === 1) {
+            const onlyDest = placedDests.values().next().value;
+            volumeDestinations.set(resolve(recordsFile), onlyDest);
+            volumeDestinations.set(resolve(join(booksDirectory, bookKey, partition, "records.jsonl")), onlyDest);
+        }
+        await migrateCurrentSessionPointer({
+            sourceDir,
+            volumeDestinations,
+            unboundPointerFile: join(booksDirectory, bookKey, "unbound", partition, CURRENT_SESSION_LEDGER),
+        });
+    }
+    return reconcileMigrationPartition(partition, "lines", outcomes);
+}
+async function migrateWorkerSubmissionGate(context) {
+    const outcomes = [];
+    const volumeMalformedRows = [];
+    const placedCache = new Map();
+    const { backupBooksDirectory, booksDirectory } = context;
+    const kind = WORKER_SUBMISSION_GATE_KIND;
+    for (const bookKey of await listMigrationBookKeys(backupBooksDirectory)) {
+        const sourceDir = join(backupBooksDirectory, bookKey, kind);
+        const entries = await listMigrationDirents(sourceDir);
+        if (entries.length === 0)
+            continue;
+        const bookRoots = bookHistoricalRoots(booksDirectory, backupBooksDirectory, bookKey);
+        const volumes = entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+            .map((entry) => entry.name)
+            .sort();
+        for (const name of volumes) {
+            const sourcePath = join(sourceDir, name);
+            const source = posixRelative(backupBooksDirectory, sourcePath);
+            const text = await readRegularBackupFile(sourcePath);
+            if (text === undefined)
+                continue;
+            const inspected = inspectWorkerSubmissionGateVolume(text, bookRoots);
+            const destRun = inspected.leaf === undefined
+                ? undefined
+                : await placedRunForLeaf(placedCache, booksDirectory, bookKey, inspected.leaf, inspected.sourceRelative);
+            const dest = volumeDestinationFile(booksDirectory, bookKey, destRun, kind, name);
+            await mkdir(dirname(dest), { recursive: true });
+            await cp(sourcePath, dest, { preserveTimestamps: true });
+            // One outcome per volume keeps the entries closure; bad rows attach below.
+            outcomes.push({
+                disposition: destRun?.disposition === "placed" ? "placed" : "unbound",
+                source,
+            });
+            for (const bad of inspected.malformedRows) {
+                volumeMalformedRows.push({
+                    source: `${source}:${bad.lineNumber}`,
+                    raw: bad.raw,
+                });
+            }
+        }
+    }
+    const report = reconcileMigrationPartition(kind, "entries", outcomes);
+    return {
+        ...report,
+        // Malformed rows are evidence on the volume bytes, not extra entry units.
+        malformedRows: [...report.malformedRows, ...volumeMalformedRows],
+    };
+}
+const bookTopologySitianMixedVolumeMigrators = SITIAN_MIXED_VOLUME_PARTITIONS.map((partition) => ({
+    partition,
+    migrate: (context) => migrateSitianMixedVolume(partition, context),
+}));
+const bookTopologyWorkerSubmissionGateMigrator = {
+    partition: WORKER_SUBMISSION_GATE_KIND,
+    migrate: migrateWorkerSubmissionGate,
+};
+export const BOOK_TOPOLOGY_MIXED_VOLUME_MIGRATORS = [
+    ...bookTopologySitianMixedVolumeMigrators,
+    bookTopologyWorkerSubmissionGateMigrator,
+];

package/dist/book-topology-partition-migrators.js

@@ -0,0 +1,23 @@
+import { BOOK_TOPOLOGY_MIXED_VOLUME_MIGRATORS } from "./book-topology-mixed-volume-migrators.js";
+import { BOOK_TOPOLOGY_T11_MIGRATORS } from "./book-topology-migrators-t11.js";
+import { BOOK_TOPOLOGY_RECORD_CLASS_MIGRATORS } from "./book-topology-record-class-migrators.js";
+import { bookTopologyRunsMigrator } from "./book-topology-runs-migrator.js";
+/**
+ * One assembly point for the independently implemented legacy partitions.
+ * #865–#868 populate this list; the orchestrator refuses an empty migration.
+ * #866 contributes record-class migrators (ticket-provenance / submission-ledger /
+ * attempt-history / misplaced-record-class). Runs (#865) should precede run-owned
+ * record classes when both are assembled.
+ *
+ * T11 (#867) registration order: auditor-roles, issues, deprecated-kinds,
+ * deprecated-run-pages, navigator, collector-handbook, manual-archives.
+ * auditor-roles prefers a run already placed by T9 when that nest exists.
+ * deprecated-run-pages must run after the runs migrator (T9): it deletes
+ * matching pages from already-placed destination runs.
+ */
+export const BOOK_TOPOLOGY_PARTITION_MIGRATORS = [
+    bookTopologyRunsMigrator,
+    ...BOOK_TOPOLOGY_RECORD_CLASS_MIGRATORS,
+    ...BOOK_TOPOLOGY_T11_MIGRATORS,
+    ...BOOK_TOPOLOGY_MIXED_VOLUME_MIGRATORS,
+];