@scotthuang/agent-knock-knock 0.8.1 → 0.10.0

package/dist/src/store.js

@@ -1,14 +1,18 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { sessionIdForConversation, turnIdForConversation, validateMessage } from "./protocol.js";
+import { assertManagedSessionState, managedSessionStatesFromConversations, managedSessionStorageKey } from "./managed-session.js";
 const PRIVATE_DIRECTORY_MODE = 0o700;
 const PRIVATE_FILE_MODE = 0o600;
 const STORE_SCHEMA = "agent-knock-knock/store";
 const STORE_MANIFEST_FILE = "manifest.json";
 const STORE_CONVERSATIONS_DIRECTORY = "conversations";
 const STORE_RUNTIME_DIRECTORY = "runtime";
+const STORE_SESSIONS_DIRECTORY = "sessions";
+const STORE_TRANSITIONS_DIRECTORY = "transitions";
 const STORE_WRITER_LOCK_FILE = ".akk-writer.lock";
 const STORE_MANIFEST_TEMP_PREFIX = `.${STORE_MANIFEST_FILE}.`;
 const STORE_MANIFEST_TEMP_SUFFIX = ".tmp";
@@ -21,7 +25,8 @@ const NO_FOLLOW_FLAG = typeof fs.constants.O_NOFOLLOW === "number"
     ? fs.constants.O_NOFOLLOW
     : 0;
 export const STORE_FORMAT_VERSION = 1;
-export const STORE_WRITER_PROTOCOL = 1;
+export const STORE_WRITER_PROTOCOL = 3;
+const STORE_UPGRADEABLE_WRITER_PROTOCOLS = new Set([1, 2]);
 const STORE_WRITER_LEASE_BRAND = Symbol("akk-store-writer-lease");
 const activeStoreWriterLease = new AsyncLocalStorage();
 export class StoreCompatibilityError extends Error {
@@ -41,8 +46,46 @@ export function defaultLogDir(workspace = process.cwd()) {
 }
 export function ensureDir(dir) {
     const resolvedDir = path.resolve(dir);
-    assertNotSymlink(resolvedDir, "store directory");
-    fs.mkdirSync(resolvedDir, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+    const missing = [];
+    let cursor = resolvedDir;
+    while (true) {
+        try {
+            const existing = fs.lstatSync(cursor);
+            if (existing.isSymbolicLink() || !existing.isDirectory()) {
+                throw new Error(`store directory must be a real directory, not a symlink: ${cursor}`);
+            }
+            break;
+        }
+        catch (error) {
+            if (!isNodeError(error, "ENOENT")) {
+                throw error;
+            }
+            missing.unshift(cursor);
+            const parent = path.dirname(cursor);
+            if (parent === cursor) {
+                throw new Error(`could not find an existing parent directory for ${dir}`);
+            }
+            cursor = parent;
+        }
+    }
+    for (const directory of missing) {
+        try {
+            fs.mkdirSync(directory, { mode: PRIVATE_DIRECTORY_MODE });
+        }
+        catch (error) {
+            if (!isNodeError(error, "EEXIST")) {
+                throw error;
+            }
+        }
+        const created = fs.lstatSync(directory);
+        if (created.isSymbolicLink() || !created.isDirectory()) {
+            throw new Error(`store directory must be a real directory, not a symlink: ${directory}`);
+        }
+        fs.chmodSync(directory, PRIVATE_DIRECTORY_MODE);
+        // Persist each newly created directory entry before a child entry can be
+        // treated as durable. This also covers a recursively new custom Store path.
+        fsyncDirectory(path.dirname(directory));
+    }
     const stat = fs.lstatSync(resolvedDir);
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw new Error(`store directory must be a real directory, not a symlink: ${dir}`);
@@ -55,6 +98,9 @@ export function storeManifestPath(storeDir = defaultStoreDir()) {
 export function storeConversationsDir(storeDir = defaultStoreDir()) {
     return path.join(storeDir, STORE_CONVERSATIONS_DIRECTORY);
 }
+export function storeSessionsDir(storeDir = defaultStoreDir()) {
+    return path.join(storeDir, STORE_SESSIONS_DIRECTORY);
+}
 export function inspectStoreCompatibility(storeDir = defaultStoreDir()) {
     const resolvedStoreDir = path.resolve(storeDir);
     const manifestPath = storeManifestPath(resolvedStoreDir);
@@ -72,7 +118,16 @@ export function inspectStoreCompatibility(storeDir = defaultStoreDir()) {
     if (!storeStat.isDirectory()) {
         throw new Error(`store directory must be a real directory: ${storeDir}`);
     }
-    if (!fs.existsSync(manifestPath)) {
+    let manifestStat;
+    try {
+        manifestStat = fs.lstatSync(manifestPath);
+    }
+    catch (error) {
+        if (!isNodeError(error, "ENOENT")) {
+            throw error;
+        }
+    }
+    if (!manifestStat) {
         if (storeHasConversationData(resolvedStoreDir)) {
             return {
                 status: "legacy",
@@ -91,15 +146,26 @@ export function inspectStoreCompatibility(storeDir = defaultStoreDir()) {
             writable: true
         };
     }
+    if (manifestStat.isSymbolicLink() || !manifestStat.isFile()) {
+        throw new Error(`store manifest must be a regular file: ${manifestPath}`);
+    }
     const manifest = readStoreManifest(manifestPath);
     const readable = manifest.format_version === STORE_FORMAT_VERSION;
-    const writable = readable && manifest.writer_protocol === STORE_WRITER_PROTOCOL;
+    const compatible = readable && manifest.writer_protocol === STORE_WRITER_PROTOCOL;
+    const upgradeable = readable &&
+        STORE_UPGRADEABLE_WRITER_PROTOCOLS.has(manifest.writer_protocol);
+    const writable = compatible || upgradeable;
     return {
-        status: readable && writable ? "compatible" : "incompatible",
+        status: compatible
+            ? "compatible"
+            : upgradeable
+                ? "upgradeable"
+                : "incompatible",
         store_dir: storeDir,
         manifest_path: manifestPath,
         readable,
         writable,
+        upgradeable,
         format_version: manifest.format_version,
         writer_protocol: manifest.writer_protocol,
         ...(!readable
@@ -242,13 +308,17 @@ export function logPathForStatePath(statePath) {
     return statePath.replace(/\.state\.json$/, ".ndjson");
 }
 export function saveState(statePath, conversation) {
+    // Validate the state identity before acquiring a writer lease. In particular,
+    // a malformed state must not initialize or upgrade the Store manifest.
+    assertConversationStateIdentity(conversation);
     const paths = assertCanonicalConversationDataPath(statePath, "state.json");
+    assertConversationStateIdentity(conversation, path.basename(paths.conversationDir));
+    assertConversationStorageMetadata(statePath, conversation);
     withStoreWriterLease(paths.storeDir, () => {
         saveStateWithWriterLease(statePath, conversation);
     });
 }
 function saveStateWithWriterLease(statePath, conversation) {
-    validateConversationId(conversation.conversation_id);
     secureConversationStorageMetadata(statePath, conversation);
     prepareDataDirectory(statePath);
     const serialized = `${JSON.stringify(conversation, null, 2)}\n`;
@@ -289,7 +359,7 @@ export function loadState(statePath) {
     assertNotSymlink(path.dirname(statePath), "conversation directory");
     const fd = openRegularFileNoFollow(statePath, fs.constants.O_RDONLY, "state file");
     try {
-        return JSON.parse(fs.readFileSync(fd, "utf8"));
+        return withConversationIdentity(JSON.parse(fs.readFileSync(fd, "utf8")));
     }
     finally {
         fs.closeSync(fd);
@@ -336,6 +406,31 @@ function withCanonicalConversationStorage(conversation, paths) {
         event_log_path: path.resolve(paths.logPath)
     };
 }
+function withConversationIdentity(conversation) {
+    const { sessionId, turnId } = assertConversationStateIdentity(conversation);
+    return {
+        ...conversation,
+        session_id: sessionId,
+        turn_id: turnId
+    };
+}
+function assertConversationStateIdentity(value, expectedConversationId) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("conversation state must be an object");
+    }
+    const conversation = value;
+    validateConversationId(conversation.conversation_id);
+    const sessionId = sessionIdForConversation(conversation);
+    const turnId = turnIdForConversation(conversation);
+    if (turnId !== conversation.conversation_id) {
+        throw new Error(`conversation turn_id ${turnId} does not match its store identity ${conversation.conversation_id}`);
+    }
+    if (expectedConversationId !== undefined &&
+        conversation.conversation_id !== expectedConversationId) {
+        throw new Error(`conversation id ${conversation.conversation_id} does not match its store directory ${expectedConversationId}`);
+    }
+    return { conversation, sessionId, turnId };
+}
 export function appendEvent(logPath, event) {
     const paths = assertCanonicalConversationDataPath(logPath, "events.ndjson");
     withStoreWriterLease(paths.storeDir, () => {
@@ -444,6 +539,12 @@ function prepareDataDirectory(dataPath) {
     }
 }
 function secureConversationStorageMetadata(statePath, conversation) {
+    const paths = assertConversationStorageMetadata(statePath, conversation);
+    ensureStoreWritable(paths.storeDir);
+    ensureStoreDir(paths.storeDir, paths.conversationDir);
+    ensureDir(paths.conversationDir);
+}
+function assertConversationStorageMetadata(statePath, conversation) {
     if (typeof conversation.store_dir !== "string" ||
         typeof conversation.conversation_dir !== "string" ||
         typeof conversation.state_path !== "string") {
@@ -455,9 +556,7 @@ function secureConversationStorageMetadata(statePath, conversation) {
         path.resolve(paths.statePath) !== path.resolve(statePath)) {
         throw new Error(`conversation storage metadata does not match state path: ${statePath}`);
     }
-    ensureStoreWritable(paths.storeDir);
-    ensureStoreDir(paths.storeDir, paths.conversationDir);
-    ensureDir(paths.conversationDir);
+    return paths;
 }
 function secureEventStorageMetadata(logPath, event) {
     if (typeof event.conversation_id !== "string") {
@@ -495,6 +594,132 @@ function assertCanonicalConversationDataPath(dataPath, expectedBasename) {
     }
     return canonical;
 }
+function managedSessionStatePath(storeDir, sessionId) {
+    return path.join(storeSessionsDir(storeDir), managedSessionStorageKey(sessionId), "state.json");
+}
+function tryReadMaterializedManagedSession(statePath, expectedSessionId) {
+    try {
+        const fd = openRegularFileNoFollow(statePath, fs.constants.O_RDONLY, "managed session state");
+        try {
+            const parsed = JSON.parse(fs.readFileSync(fd, "utf8"));
+            assertManagedSessionState(parsed, expectedSessionId);
+            return parsed;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function materializeManagedSessionStatesWhileLocked(storeDir, states, replaceMigrationRevisionOne) {
+    const sessionsDir = storeSessionsDir(storeDir);
+    assertNotSymlink(sessionsDir, "managed sessions directory");
+    ensureDir(sessionsDir);
+    const writes = [];
+    for (const state of states) {
+        assertManagedSessionState(state, state.session_id);
+        const statePath = managedSessionStatePath(storeDir, state.session_id);
+        const existing = tryReadMaterializedManagedSession(statePath, state.session_id);
+        if (existing && JSON.stringify(existing) === JSON.stringify(state)) {
+            continue;
+        }
+        if (existing &&
+            !(replaceMigrationRevisionOne &&
+                existing.revision === 1 &&
+                existing.lineage.created_by === "migration")) {
+            throw new Error(`managed Session ${state.session_id} already has non-migration state; ` +
+                "refusing to overwrite it during Store materialization");
+        }
+        writes.push({ path: statePath, state });
+    }
+    for (const write of writes) {
+        atomicSaveManagedSessionState(write.path, write.state);
+    }
+    // Record-directory creation and every state rename are durable before a
+    // protocol-3 manifest can become visible.
+    fsyncDirectory(sessionsDir);
+    fsyncDirectory(storeDir);
+}
+function assertUpgradeableManagedSessionTree(storeDir, expectedStates) {
+    const sessionsDir = storeSessionsDir(storeDir);
+    let rootStat;
+    try {
+        rootStat = fs.lstatSync(sessionsDir);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new Error(`managed sessions directory must be a real directory: ${sessionsDir}`);
+    }
+    const expectedByKey = new Map(expectedStates.map((state) => [managedSessionStorageKey(state.session_id), state]));
+    for (const entry of fs.readdirSync(sessionsDir, { withFileTypes: true })) {
+        const entryPath = path.join(sessionsDir, entry.name);
+        if (entry.isSymbolicLink() ||
+            !entry.isDirectory() ||
+            !/^[0-9a-f]{64}$/u.test(entry.name)) {
+            throw new Error(`predecessor Store contains an invalid managed Session entry: ${entryPath}`);
+        }
+        const expected = expectedByKey.get(entry.name);
+        if (!expected) {
+            throw new Error(`predecessor Store contains unexpected managed Session state: ${entryPath}`);
+        }
+        const statePath = path.join(entryPath, "state.json");
+        // An expected empty record directory is a recoverable crash residue. Any
+        // present state must already be a strict, correctly keyed Session record.
+        tryReadMaterializedManagedSession(statePath, expected.session_id);
+    }
+}
+function atomicSaveManagedSessionState(statePath, state) {
+    const recordDir = path.dirname(statePath);
+    const sessionsDir = path.dirname(recordDir);
+    assertNotSymlink(sessionsDir, "managed sessions directory");
+    ensureDir(recordDir);
+    assertNotSymlink(recordDir, "managed session directory");
+    const recordStat = fs.lstatSync(recordDir);
+    if (!recordStat.isDirectory()) {
+        throw new Error(`managed session directory must be a real directory: ${recordDir}`);
+    }
+    assertWritableDataPath(statePath, "managed session state");
+    const tempPath = path.join(recordDir, `.state.json.${process.pid}.${randomUUID()}.tmp`);
+    let fd;
+    try {
+        fd = fs.openSync(tempPath, fs.constants.O_CREAT |
+            fs.constants.O_EXCL |
+            fs.constants.O_WRONLY |
+            NO_FOLLOW_FLAG, PRIVATE_FILE_MODE);
+        fs.fchmodSync(fd, PRIVATE_FILE_MODE);
+        fs.writeFileSync(fd, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        assertWritableDataPath(statePath, "managed session state");
+        fs.renameSync(tempPath, statePath);
+        fs.chmodSync(statePath, PRIVATE_FILE_MODE);
+        fsyncDirectory(recordDir);
+    }
+    finally {
+        if (fd !== undefined) {
+            fs.closeSync(fd);
+        }
+        try {
+            fs.unlinkSync(tempPath);
+        }
+        catch (error) {
+            if (!isNodeError(error, "ENOENT")) {
+                throw error;
+            }
+        }
+    }
+}
 function ensureStoreDir(storeDir, currentConversationDir) {
     const resolvedStoreDir = path.resolve(storeDir);
     assertNotSymlink(resolvedStoreDir, "store directory");
@@ -519,6 +744,11 @@ function ensureStoreDir(storeDir, currentConversationDir) {
         if (entry.name === STORE_RUNTIME_DIRECTORY && entry.isDirectory()) {
             return true;
         }
+        if ((entry.name === STORE_SESSIONS_DIRECTORY ||
+            entry.name === STORE_TRANSITIONS_DIRECTORY) &&
+            entry.isDirectory()) {
+            return true;
+        }
         if (entryPath !== resolvedConversationsDir || !entry.isDirectory()) {
             return false;
         }
@@ -541,10 +771,7 @@ function ensureStoreDir(storeDir, currentConversationDir) {
 function prepareStoreRootForWriterLock(storeDir) {
     const resolvedStoreDir = path.resolve(storeDir);
     if (!fs.existsSync(resolvedStoreDir)) {
-        fs.mkdirSync(resolvedStoreDir, {
-            recursive: true,
-            mode: PRIVATE_DIRECTORY_MODE
-        });
+        ensureDir(resolvedStoreDir);
     }
     assertNotSymlink(resolvedStoreDir, "store directory");
     const stat = fs.lstatSync(resolvedStoreDir);
@@ -561,11 +788,16 @@ function ensureStoreWritableWhileLocked(storeDir) {
         createStoreManifest(storeDir);
         compatibility = inspectStoreCompatibility(storeDir);
     }
+    else if (compatibility.status === "upgradeable") {
+        upgradeStoreWriterProtocolWhileLocked(storeDir);
+        compatibility = inspectStoreCompatibility(storeDir);
+    }
     assertWritableCompatibility(compatibility);
     // Permission repair is a write and therefore happens only after the
     // manifest has been validated under the root writer lock.
     fs.chmodSync(storeDir, PRIVATE_DIRECTORY_MODE);
     ensureDir(storeConversationsDir(storeDir));
+    ensureDir(storeSessionsDir(storeDir));
     return readStoreManifest(storeManifestPath(storeDir));
 }
 function assertWritableCompatibility(compatibility) {
@@ -656,9 +888,175 @@ function createStoreManifest(storeDir) {
         throw error;
     }
 }
+/** Upgrade the one explicitly supported predecessor while holding the root lock. */
+function upgradeStoreWriterProtocolWhileLocked(storeDir) {
+    const manifestPath = storeManifestPath(storeDir);
+    const previous = readStoreManifestSnapshot(manifestPath);
+    assertUpgradeableStoreManifest(previous.manifest, storeDir);
+    // Protocol 3 makes Session state the routing/binding authority. Validate all
+    // predecessor Turns, derive every Session without using mutable Turn
+    // recency, and durably materialize those records before publishing the new
+    // manifest. Turn files and event logs remain byte-for-byte untouched.
+    const stateSnapshots = readUpgradeableStoreStateSnapshots(storeDir);
+    const sessions = managedSessionStatesFromConversations(stateSnapshots.map(({ conversation }) => conversation));
+    assertUpgradeableManagedSessionTree(storeDir, sessions);
+    materializeManagedSessionStatesWhileLocked(storeDir, sessions, true);
+    const upgraded = {
+        ...previous.manifest,
+        writer_protocol: STORE_WRITER_PROTOCOL,
+        created_at: previous.manifest.created_at
+    };
+    const tempPath = path.join(storeDir, `${STORE_MANIFEST_TEMP_PREFIX}${process.pid}.${randomUUID()}${STORE_MANIFEST_TEMP_SUFFIX}`);
+    let fd;
+    try {
+        fd = fs.openSync(tempPath, fs.constants.O_CREAT |
+            fs.constants.O_EXCL |
+            fs.constants.O_WRONLY |
+            NO_FOLLOW_FLAG, PRIVATE_FILE_MODE);
+        fs.fchmodSync(fd, PRIVATE_FILE_MODE);
+        fs.writeFileSync(fd, `${JSON.stringify(upgraded, null, 2)}\n`, "utf8");
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+        // A process that ignores the root writer lock must not trick us into
+        // replacing a different manifest. Re-check both file identity and the
+        // supported predecessor immediately before the atomic rename.
+        revalidateUpgradeableStoreStateSnapshots(storeDir, stateSnapshots);
+        const current = readStoreManifestSnapshot(manifestPath);
+        if (current.device !== previous.device ||
+            current.inode !== previous.inode ||
+            current.manifest.schema !== previous.manifest.schema ||
+            current.manifest.format_version !== previous.manifest.format_version ||
+            current.manifest.writer_protocol !== previous.manifest.writer_protocol ||
+            current.manifest.created_at !== previous.manifest.created_at) {
+            throw new Error("AKK store manifest changed while upgrading writer protocol; refusing to replace it");
+        }
+        const manifestPathStat = fs.lstatSync(manifestPath, { bigint: true });
+        if (manifestPathStat.isSymbolicLink() ||
+            !manifestPathStat.isFile() ||
+            manifestPathStat.dev !== current.device ||
+            manifestPathStat.ino !== current.inode) {
+            throw new Error("AKK store manifest path changed while upgrading writer protocol; refusing to replace it");
+        }
+        fs.renameSync(tempPath, manifestPath);
+        fsyncDirectory(storeDir);
+    }
+    finally {
+        if (fd !== undefined) {
+            fs.closeSync(fd);
+        }
+        try {
+            fs.unlinkSync(tempPath);
+        }
+        catch (error) {
+            if (!isNodeError(error, "ENOENT")) {
+                throw error;
+            }
+        }
+    }
+}
+function assertUpgradeableStoreManifest(manifest, storeDir) {
+    if (manifest.schema !== STORE_SCHEMA ||
+        manifest.format_version !== STORE_FORMAT_VERSION ||
+        !STORE_UPGRADEABLE_WRITER_PROTOCOLS.has(manifest.writer_protocol)) {
+        throw new StoreCompatibilityError(`store is not one of the supported writer protocol predecessors ${[
+            ...STORE_UPGRADEABLE_WRITER_PROTOCOLS
+        ].join(", ")}`, inspectStoreCompatibility(storeDir));
+    }
+}
+function readUpgradeableStoreStateSnapshots(storeDir) {
+    const conversationsDir = storeConversationsDir(storeDir);
+    let conversationsStat;
+    try {
+        conversationsStat = fs.lstatSync(conversationsDir);
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT")) {
+            return [];
+        }
+        throw error;
+    }
+    if (conversationsStat.isSymbolicLink() || !conversationsStat.isDirectory()) {
+        throw new Error(`conversations directory must be a real directory: ${conversationsDir}`);
+    }
+    const snapshots = [];
+    for (const entry of fs.readdirSync(conversationsDir, { withFileTypes: true })) {
+        const conversationDir = path.join(conversationsDir, entry.name);
+        const conversationStat = fs.lstatSync(conversationDir);
+        if (conversationStat.isSymbolicLink()) {
+            throw new Error(`conversation directory must not be a symlink: ${conversationDir}`);
+        }
+        if (!conversationStat.isDirectory()) {
+            continue;
+        }
+        const statePath = path.join(conversationDir, "state.json");
+        let stateStat;
+        try {
+            stateStat = fs.lstatSync(statePath);
+        }
+        catch (error) {
+            if (isNodeError(error, "ENOENT")) {
+                continue;
+            }
+            throw error;
+        }
+        if (stateStat.isSymbolicLink() || !stateStat.isFile()) {
+            throw new Error(`state file must be a regular file: ${statePath}`);
+        }
+        const stateFd = openRegularFileNoFollow(statePath, fs.constants.O_RDONLY, "state file");
+        try {
+            let parsed;
+            let contents;
+            try {
+                contents = fs.readFileSync(stateFd, "utf8");
+                parsed = JSON.parse(contents);
+            }
+            catch (error) {
+                throw new Error(`invalid conversation state during Store upgrade: ${statePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const identity = assertConversationStateIdentity(parsed, entry.name);
+            const stat = fs.fstatSync(stateFd, { bigint: true });
+            snapshots.push({
+                conversation: {
+                    ...identity.conversation,
+                    session_id: identity.sessionId,
+                    turn_id: identity.turnId
+                },
+                statePath,
+                device: stat.dev,
+                inode: stat.ino,
+                contentsSha256: createHash("sha256").update(contents).digest("hex")
+            });
+        }
+        finally {
+            fs.closeSync(stateFd);
+        }
+    }
+    return snapshots;
+}
+function revalidateUpgradeableStoreStateSnapshots(storeDir, snapshots) {
+    const current = readUpgradeableStoreStateSnapshots(storeDir);
+    const expectedByPath = new Map(snapshots.map((snapshot) => [snapshot.statePath, snapshot]));
+    if (current.length !== snapshots.length) {
+        throw new Error("conversation set changed during Store upgrade");
+    }
+    for (const actual of current) {
+        const expected = expectedByPath.get(actual.statePath);
+        if (!expected ||
+            actual.device !== expected.device ||
+            actual.inode !== expected.inode ||
+            actual.contentsSha256 !== expected.contentsSha256) {
+            throw new Error(`conversation state changed during Store upgrade: ${actual.statePath}`);
+        }
+    }
+}
 function readStoreManifest(manifestPath) {
+    return readStoreManifestSnapshot(manifestPath).manifest;
+}
+function readStoreManifestSnapshot(manifestPath) {
     const fd = openRegularFileNoFollow(manifestPath, fs.constants.O_RDONLY, "store manifest");
     try {
+        const stat = fs.fstatSync(fd, { bigint: true });
         const parsed = JSON.parse(fs.readFileSync(fd, "utf8"));
         if (parsed.schema !== STORE_SCHEMA ||
             !Number.isSafeInteger(parsed.format_version) ||
@@ -666,7 +1064,11 @@ function readStoreManifest(manifestPath) {
             typeof parsed.created_at !== "string") {
             throw new Error(`invalid AKK store manifest: ${manifestPath}`);
         }
-        return parsed;
+        return {
+            manifest: parsed,
+            device: stat.dev,
+            inode: stat.ino
+        };
     }
     finally {
         fs.closeSync(fd);
@@ -885,9 +1287,12 @@ function isNodeError(error, code) {
     return error instanceof Error && error.code === code;
 }
 export function messageEvent(message) {
+    validateMessage(message);
     return {
         ts: message.ts,
         conversation_id: message.conversation_id,
+        session_id: message.session_id ?? message.conversation_id,
+        turn_id: message.turn_id ?? message.conversation_id,
         event: "message",
         from: message.from,
         to: message.to,