@geminixiang/mikan 1.0.0-beta.53 → 1.0.0-beta.55

package/dist/sessions/migrate-v3.js

@@ -16,11 +16,14 @@
  * v3 context computed by the reference converter below. The original file
  * is kept beside the migrated one as `<name>.v3.bak`.
  */
-import { existsSync, linkSync, lstatSync, readdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
-import { join } from "node:path";
+import { readFileSync } from "node:fs";
 import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "@earendil-works/pi-agent-core";
-import { SessionStore } from "../harness/session-store.js";
-import { atomicWritePrivateFile } from "../utils/file-guards.js";
+import { SessionStore } from "./session-store.js";
+import { commitMigration, findSessionFiles, optionalAnnotations, V4FileWriter, } from "./migrate-common.js";
+/** `session_info`, `label` and `leaf` become v4 values, not tree entries. */
+function isFactEntry(entry) {
+    return entry.type === "session_info" || entry.type === "label" || entry.type === "leaf";
+}
 /** Whether a file's first non-empty line is a v3 session header. */
 export function isV3SessionFile(filePath) {
     try {
@@ -35,8 +38,8 @@ export function isV3SessionFile(filePath) {
         return false;
     }
 }
-/** Read a v3 session file, ignoring a torn final line (crash tail). */
-function readV3SessionFile(filePath) {
+/** Parse every non-empty line, tolerating a torn final line (crash tail). */
+function parseJsonLines(filePath) {
     const lines = readFileSync(filePath, "utf-8")
         .split("\n")
         .map((line) => line.trim())
@@ -52,24 +55,37 @@ function readV3SessionFile(filePath) {
             throw new Error(`Invalid JSON on line ${index + 1} of ${filePath}`, { cause: error });
         }
     }
-    const header = records[0];
-    if (!header || header.type !== "session" || typeof header.id !== "string") {
-        throw new Error(`Not a v3 session file: ${filePath}`);
-    }
-    // Crash-era v3 files can contain duplicated lines (a retried append wrote
-    // the header+entry pair twice). The v3 runtime read entries into a Map, so
-    // duplicates were silently collapsed; v4 rejects duplicate mutation ids.
-    // Reproduce the v3 Map semantics: a repeated id replaces its payload while
-    // retaining the id's original insertion position.
+    return records;
+}
+/**
+ * Crash-era v3 files can contain duplicated lines (a retried append wrote the
+ * header+entry pair twice). The v3 runtime read entries into a Map, so
+ * duplicates were silently collapsed; v4 rejects duplicate mutation ids.
+ * Reproduce the v3 Map semantics: a repeated id replaces its payload while
+ * retaining the id's original insertion position.
+ */
+function dedupeEntries(records) {
     const entriesById = new Map();
-    for (const record of records.slice(1)) {
+    for (const record of records) {
         if (typeof record.type !== "string" || typeof record.id !== "string")
             continue;
         if (record.type === "session")
             continue;
         entriesById.set(record.id, record);
     }
-    return { header: header, entries: [...entriesById.values()] };
+    return [...entriesById.values()];
+}
+/** Read a v3 session file, ignoring a torn final line (crash tail). */
+function readV3SessionFile(filePath) {
+    const records = parseJsonLines(filePath);
+    const header = records[0];
+    if (!header || header.type !== "session" || typeof header.id !== "string") {
+        throw new Error(`Not a v3 session file: ${filePath}`);
+    }
+    return {
+        header: header,
+        entries: dedupeEntries(records.slice(1)),
+    };
 }
 function toEpochMillis(timestamp) {
     const parsed = Date.parse(timestamp);
@@ -96,6 +112,10 @@ function v3LeafId(entries) {
     }
     return leafId;
 }
+/** v3 kept `custom_message` payloads out of band; v4 stores a real message. */
+function customMessageOf(entry) {
+    return createCustomMessage(entry.customType, entry.content, entry.display, entry.details, toEpochMillis(entry.timestamp));
+}
 /** Convert one tree-shaping v3 entry to its v4 counterpart (facts excluded). */
 function convertEntry(entry, entries) {
     const base = {
@@ -108,11 +128,7 @@ function convertEntry(entry, entries) {
         case "message":
             return { ...base, type: "message", message: entry.message };
         case "custom_message":
-            return {
-                ...base,
-                type: "message",
-                message: createCustomMessage(entry.customType, entry.content, entry.display, entry.details, toEpochMillis(entry.timestamp)),
-            };
+            return { ...base, type: "message", message: customMessageOf(entry) };
         case "thinking_level_change":
         case "model_change":
         case "active_tools_change": {
@@ -132,8 +148,7 @@ function convertEntry(entry, entries) {
                 retainedTail: entry.retainedTail ?? compactionKeptMessages(entry, entries),
                 tokensBefore: entry.tokensBefore,
                 fromHook: false,
-                ...(entry.details !== undefined ? { details: entry.details } : {}),
-                ...(entry.usage !== undefined ? { usage: entry.usage } : {}),
+                ...optionalAnnotations(entry),
             };
         case "branch_summary":
             return {
@@ -142,8 +157,7 @@ function convertEntry(entry, entries) {
                 fromId: entry.fromId ?? null,
                 summary: entry.summary,
                 fromHook: false,
-                ...(entry.details !== undefined ? { details: entry.details } : {}),
-                ...(entry.usage !== undefined ? { usage: entry.usage } : {}),
+                ...optionalAnnotations(entry),
             };
         case "custom":
             return {
@@ -169,9 +183,8 @@ function resolveV4Parent(entry, entries) {
         const parent = byId.get(parentId);
         if (!parent)
             return null;
-        if (parent.type !== "session_info" && parent.type !== "label" && parent.type !== "leaf") {
+        if (!isFactEntry(parent))
             return parentId;
-        }
         parentId = parent.parentId;
     }
     return null;
@@ -191,60 +204,58 @@ function compactionKeptMessages(compaction, entries) {
     for (const entry of ancestors.slice(keptStart)) {
         if (entry.type === "message")
             messages.push(entry.message);
-        else if (entry.type === "custom_message") {
-            messages.push(createCustomMessage(entry.customType, entry.content, entry.display, entry.details, toEpochMillis(entry.timestamp)));
-        }
+        else if (entry.type === "custom_message")
+            messages.push(customMessageOf(entry));
     }
     return messages;
 }
 // ── reference converter (verification oracle) ───────────────────────────────
 /**
- * Convert a v3 branch to v4 entries with the pi-0.83 context semantics:
- * the last compaction is repositioned ahead of its kept range so pi's v4
- * transform reproduces the v3 context exactly. This mirrors what the
- * runtime shim did before mikan moved to native v4 files, and serves as
- * the verification oracle for migrated output.
+ * Reorder a v3 branch the way the pi-0.83 context shim did: the last
+ * compaction moves ahead of its kept range. The branch is returned unchanged
+ * when there is no such compaction or it already carries a `retainedTail`.
  */
-function referenceContextEntries(branch) {
-    let lastCompactionIndex = -1;
-    for (let i = branch.length - 1; i >= 0; i--) {
-        if (branch[i]?.type === "compaction") {
-            lastCompactionIndex = i;
-            break;
-        }
-    }
-    const lastCompaction = branch[lastCompactionIndex];
-    const firstKeptId = lastCompaction && !lastCompaction.retainedTail ? lastCompaction.firstKeptEntryId : undefined;
+function orderForReference(branch) {
+    const lastIndex = branch.findLastIndex((entry) => entry.type === "compaction");
+    const lastCompaction = branch[lastIndex];
+    const firstKeptId = lastCompaction?.retainedTail ? undefined : lastCompaction?.firstKeptEntryId;
     const firstKeptIndex = firstKeptId === undefined ? -1 : branch.findIndex((entry) => entry.id === firstKeptId);
-    const ordered = [];
-    if (firstKeptIndex !== -1 && lastCompaction) {
-        ordered.push(...branch.slice(0, firstKeptIndex));
-        ordered.push(lastCompaction);
-        for (const [index, entry] of branch.entries()) {
-            if (index >= firstKeptIndex && index !== lastCompactionIndex)
-                ordered.push(entry);
-        }
-    }
-    else {
-        ordered.push(...branch);
-    }
+    if (firstKeptIndex === -1 || !lastCompaction)
+        return { ordered: branch };
+    return {
+        ordered: [
+            ...branch.slice(0, firstKeptIndex),
+            lastCompaction,
+            ...branch.filter((_, index) => index >= firstKeptIndex && index !== lastIndex),
+        ],
+        repositioned: lastCompaction,
+    };
+}
+/** A repositioned compaction drops its kept range: the range now follows it. */
+function emptiedCompaction(entry) {
+    return {
+        type: "compaction",
+        id: entry.id,
+        seq: 0,
+        parentId: null,
+        timestamp: toEpochMillis(entry.timestamp),
+        summary: entry.summary,
+        retainedTail: [],
+        tokensBefore: entry.tokensBefore,
+        fromHook: false,
+    };
+}
+/**
+ * Convert a v3 branch to v4 entries with the pi-0.83 context semantics, so
+ * pi's v4 transform reproduces the v3 context exactly. This mirrors what the
+ * runtime shim did before mikan moved to native v4 files, and serves as the
+ * verification oracle for migrated output.
+ */
+function referenceContextEntries(branch) {
+    const { ordered, repositioned } = orderForReference(branch);
     const converted = [];
     for (const entry of ordered) {
-        if (entry.type === "compaction" && entry === lastCompaction && firstKeptIndex !== -1) {
-            converted.push({
-                type: "compaction",
-                id: entry.id,
-                seq: 0,
-                parentId: null,
-                timestamp: toEpochMillis(entry.timestamp),
-                summary: entry.summary,
-                retainedTail: [],
-                tokensBefore: entry.tokensBefore,
-                fromHook: false,
-            });
-            continue;
-        }
-        const piEntry = convertEntry(entry, []);
+        const piEntry = repositioned === entry ? emptiedCompaction(repositioned) : convertEntry(entry, []);
         if (piEntry)
             converted.push(piEntry);
     }
@@ -262,25 +273,25 @@ function isCurrentContextMessage(message) {
             message.stopReason !== "aborted" &&
             message.stopReason !== "deferred"));
 }
+function contextMessagesOf(entry) {
+    if (entry.type === "message") {
+        return isCurrentContextMessage(entry.message) ? [entry.message] : [];
+    }
+    if (entry.type === "compaction") {
+        return [
+            createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp),
+            ...entry.retainedTail.filter(isCurrentContextMessage),
+        ];
+    }
+    if (entry.type === "branch_summary" && entry.summary) {
+        return [createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)];
+    }
+    return [];
+}
 function referenceContextMessages(entries) {
     const compactionIndex = entries.findLastIndex((entry) => entry.type === "compaction");
-    const visible = compactionIndex === -1
-        ? entries
-        : [entries[compactionIndex], ...entries.slice(compactionIndex + 1)];
-    const messages = [];
-    for (const entry of visible) {
-        if (entry.type === "message") {
-            if (isCurrentContextMessage(entry.message))
-                messages.push(entry.message);
-        }
-        else if (entry.type === "compaction") {
-            messages.push(createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp), ...entry.retainedTail.filter(isCurrentContextMessage));
-        }
-        else if (entry.type === "branch_summary" && entry.summary) {
-            messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
-        }
-    }
-    return messages;
+    const visible = compactionIndex === -1 ? entries : entries.slice(compactionIndex);
+    return visible.flatMap(contextMessagesOf);
 }
 // ── v4 encoding ─────────────────────────────────────────────────────────────
 function buildV4Header(header) {
@@ -297,86 +308,68 @@ function buildV4Header(header) {
             : {}),
     };
 }
-function encodeV4File(file) {
-    const lines = [JSON.stringify(buildV4Header(file.header))];
-    let seq = 0;
-    const push = (write) => lines.push(JSON.stringify(write));
-    let name;
+/** Split a v3 entry stream into tree entries and the facts v4 stores as values. */
+function partitionEntries(entries) {
+    const tree = [];
     const labels = [];
-    for (const entry of file.entries) {
-        if (entry.type === "session_info") {
-            name = entry.name?.trim() || undefined;
-            continue;
-        }
-        if (entry.type === "label") {
-            labels.push({ targetId: entry.targetId, label: entry.label });
-            continue;
+    let name;
+    for (const entry of entries) {
+        switch (entry.type) {
+            case "session_info":
+                name = entry.name?.trim() || undefined;
+                break;
+            case "label":
+                labels.push({ targetId: entry.targetId, label: entry.label });
+                break;
+            case "leaf":
+                break;
+            default:
+                tree.push(entry);
         }
-        if (entry.type === "leaf")
-            continue;
-        const converted = convertEntry(entry, file.entries);
-        if (!converted)
-            continue;
-        converted.seq = ++seq;
-        push({ kind: "entry", ...converted });
     }
-    let leafId = v3LeafId(file.entries);
-    const byId = new Map(file.entries.map((entry) => [entry.id, entry]));
+    return { tree, name, labels };
+}
+/** The v4 branch tip: the v3 leaf, walked back past fact-only entries. */
+function resolveV4Leaf(entries) {
+    const byId = new Map(entries.map((entry) => [entry.id, entry]));
+    let leafId = v3LeafId(entries);
     while (leafId !== null) {
         const target = byId.get(leafId);
-        if (!target) {
-            leafId = null;
-            break;
-        }
-        if (target.type !== "session_info" && target.type !== "label" && target.type !== "leaf")
-            break;
+        if (!target)
+            return null;
+        if (!isFactEntry(target))
+            return leafId;
         leafId = target.parentId;
     }
-    push({
-        kind: "value",
-        op: "set",
-        seq: ++seq,
-        namespace: "pi.branch.tip",
-        key: "main",
-        value: leafId,
-    });
-    if (name !== undefined) {
-        push({
-            kind: "value",
-            op: "set",
-            seq: ++seq,
-            namespace: "pi.session.name",
-            key: "",
-            value: name,
-        });
-    }
-    for (const { targetId, label } of labels) {
-        if (label === undefined)
-            continue;
-        push({
-            kind: "value",
-            op: "set",
-            seq: ++seq,
-            namespace: "pi.entry.label",
-            key: targetId,
-            value: label,
-        });
-    }
-    const { type: _type, version: _version, id: _id, timestamp: _timestamp, cwd: _cwd, parentSession, parentSessionId: _parentSessionId, ...extras } = file.header;
+    return null;
+}
+/** Header fields v4 does not model survive as the durable `mikan/metadata` value. */
+function headerMetadata(header) {
+    const { type: _type, version: _version, id: _id, timestamp: _timestamp, cwd: _cwd, parentSession, parentSessionId: _parentSessionId, ...extras } = header;
     const metadata = extras;
     if (parentSession !== undefined)
         metadata.parentSessionPath = parentSession;
-    if (Object.keys(metadata).length > 0) {
-        push({
-            kind: "value",
-            op: "set",
-            seq: ++seq,
-            namespace: "mikan",
-            key: "metadata",
-            value: metadata,
-        });
+    return Object.keys(metadata).length > 0 ? metadata : undefined;
+}
+function encodeV4File(file) {
+    const writer = new V4FileWriter(buildV4Header(file.header));
+    const { tree, name, labels } = partitionEntries(file.entries);
+    for (const entry of tree) {
+        const converted = convertEntry(entry, file.entries);
+        if (converted)
+            writer.entry(converted);
+    }
+    writer.set("pi.branch.tip", "main", resolveV4Leaf(file.entries));
+    if (name !== undefined)
+        writer.set("pi.session.name", "", name);
+    for (const { targetId, label } of labels) {
+        if (label !== undefined)
+            writer.set("pi.entry.label", targetId, label);
     }
-    return `${lines.join("\n")}\n`;
+    const metadata = headerMetadata(file.header);
+    if (metadata)
+        writer.set("mikan", "metadata", metadata);
+    return writer.toString();
 }
 // ── migration driver ────────────────────────────────────────────────────────
 async function verifyMigratedFile(v4Path, source) {
@@ -402,15 +395,6 @@ async function verifyMigratedFile(v4Path, source) {
  * the v3 reference semantics before it replaces the original; the original
  * is preserved as `<file>.v3.bak`.
  */
-function backupAlreadyLinked(sourcePath, backupPath) {
-    if (!existsSync(backupPath))
-        return false;
-    const source = statSync(sourcePath);
-    const backup = statSync(backupPath);
-    if (source.dev === backup.dev && source.ino === backup.ino)
-        return true;
-    throw new Error(`Backup already exists: ${backupPath}`);
-}
 export async function migrateSessionFile(filePath, options) {
     if (!isV3SessionFile(filePath))
         return { file: filePath, status: "already-v4" };
@@ -418,50 +402,18 @@ export async function migrateSessionFile(filePath, options) {
     const source = readV3SessionFile(filePath);
     if (options?.dryRun)
         return { file: filePath, status: "migrated", detail: "dry run" };
-    const tempPath = `${filePath}.v4.tmp`;
-    const backupPath = `${filePath}.v3.bak`;
-    const backupLinked = backupAlreadyLinked(filePath, backupPath);
-    atomicWritePrivateFile(tempPath, encodeV4File(source));
-    try {
-        await verifyMigratedFile(tempPath, source);
-        if (!readFileSync(filePath).equals(sourceBytes))
-            throw new Error("source changed during migration");
-        if (!backupLinked)
-            linkSync(filePath, backupPath);
-        renameSync(tempPath, filePath);
-    }
-    catch (error) {
-        rmSync(tempPath, { force: true });
-        throw new Error(`Migration failed for ${filePath}`, { cause: error });
-    }
+    await commitMigration({
+        filePath,
+        sourceBytes,
+        encoded: encodeV4File(source),
+        tempPath: `${filePath}.v4.tmp`,
+        backupPath: `${filePath}.v3.bak`,
+        verify: (candidatePath) => verifyMigratedFile(candidatePath, source),
+    });
     return { file: filePath, status: "migrated" };
 }
 /** Recursively find candidate session files (.jsonl with a v3 header). */
 export function findV3SessionFiles(root) {
-    if (!existsSync(root))
-        return [];
-    const found = [];
-    const walk = (dir) => {
-        for (const name of readdirSync(dir)) {
-            const path = join(dir, name);
-            let stats;
-            try {
-                stats = lstatSync(path);
-            }
-            catch {
-                continue;
-            }
-            if (stats.isSymbolicLink())
-                continue;
-            if (stats.isDirectory()) {
-                walk(path);
-            }
-            else if (name.endsWith(".jsonl") && isV3SessionFile(path)) {
-                found.push(path);
-            }
-        }
-    };
-    walk(root);
-    return found;
+    return findSessionFiles(root, isV3SessionFile);
 }
 //# sourceMappingURL=migrate-v3.js.map