@jskit-ai/assistant-core 0.1.200 → 0.1.202

package/test/conversationReplacement.test.js

@@ -0,0 +1,172 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createConversationRuntime, createMemoryConversationStorage } from "../src/server/conversation/index.js";
+import { createAiConnectionResolver } from "../../connectors-catalog/src/server/ai.js";
+
+const configuration = { systemPrompt: "Answer the current question.", integrationId: "assistant" };
+const connections = createAiConnectionResolver({
+  configuration: { schemaVersion: 1, registrations: {}, integrations: {
+    assistant: { provider: "ai", accountMode: "shared", scopes: [], authentication: { method: "none" }, settings: { model: "opencode/big-pickle" } }
+  } }, authorize: () => ({ applicationId: "test", subjectId: "owner" })
+});
+
+async function fixture(t, options = {}) {
+  const storage = options.storage || createMemoryConversationStorage();
+  const requests = [];
+  const runtimes = [];
+  const state = { allowed: true, failCommit: false, commitFailures: 0 };
+  const failingStorage = { ...storage, write: (id, callback) => storage.write(id, async transaction => {
+    const previous = await transaction.readMetadata();
+    const result = await callback(transaction);
+    const next = await transaction.readMetadata();
+    if (state.failCommit && previous.runtime?.replacement && !next.runtime?.replacement) {
+      state.commitFailures++;
+      throw new Error("Storage offline during replacement commit");
+    }
+    return result;
+  }) };
+  function runtime() {
+    const value = createConversationRuntime({ storage: failingStorage, connections,
+      authorize: () => state.allowed, limits: options.limits,
+      fetch: async (_url, init) => {
+        const body = JSON.parse(init.body); requests.push(body);
+        if (options.fetch) return options.fetch(body, init);
+        const text = `Reply ${requests.length}`;
+        const chunk = { choices: [{ index: 0, delta: { content: text }, finish_reason: "stop" }] };
+        return new Response(`data: ${JSON.stringify(chunk)}\n\n`, { headers: { "content-type": "text/event-stream" } });
+      }
+    });
+    runtimes.push(value);
+    return value;
+  }
+  t.after(async () => { for (const value of runtimes) await value.close(); });
+  const first = runtime();
+  const conversation = await first.open({ id: "one", configuration });
+  async function say(text, messageId) { await conversation.send({ text, messageId }); return conversation.wait(); }
+  const replacement = async (patch = {}) => ({ operationId: "replace-one", expectedSegmentId: (await conversation.read()).segmentId,
+    reason: "renewal", briefing: "Retain the agreed colour: blue.", ...patch });
+  return { storage, conversation, first, runtime, requests, state, say, replacement };
+}
+
+test("renewal preserves logical history and receipts while subsequent inference carries the saved briefing", async t => {
+  const f = await fixture(t);
+  await f.say("Keep my context", "first");
+  const operation = await f.replacement();
+  const result = await f.conversation.replace(operation);
+  assert.notEqual(result.segmentId, operation.expectedSegmentId);
+  assert.equal(f.requests.length, 1, "Replacement itself does not perform inference");
+  await f.say("Continue", "second");
+  const sent = f.requests[1].messages;
+  assert.equal(sent.at(-1).content, "Continue");
+  assert.match(sent[1].content, /Retain the agreed colour: blue/);
+  assert.match(sent[1].content, /Keep my context/);
+  assert.match(sent[1].content, /Reply 1/);
+  assert.equal(sent.filter(message => message.content === "Keep my context").length, 0);
+  const snapshot = await f.conversation.read();
+  assert.deepEqual(snapshot.conversationLog.map(turn => turn.user.text), ["Keep my context", "Continue"]);
+  assert.equal((await f.conversation.send({ text: "Keep my context", messageId: "first" })).duplicate, true);
+  const retry = await f.conversation.replace(operation);
+  assert.equal(retry.duplicate, true);
+  assert.equal(retry.segmentId, result.segmentId);
+  await assert.rejects(f.conversation.replace({ ...operation, briefing: "Different" }), { code: "conversation_replacement_conflict" });
+});
+
+test("completed historical branch markers retain history filtering and admission receipts", async t => {
+  const f = await fixture(t);
+  await f.say("Retained", "first");
+  const previous = await f.say("Discarded", "second");
+  const discarded = previous.conversationLog[1];
+  await f.storage.write("one", transaction => transaction.updateTurnMetadata(discarded.turnId, {
+    runtime: { ...discarded.metadata.runtime, supersededBy: "historical-successor" }
+  }));
+  assert.deepEqual((await f.conversation.read()).conversationLog.map(turn => turn.user.text), ["Retained"]);
+  await f.say("Continue", "third");
+  assert.match(JSON.stringify(f.requests[2].messages), /Retained/);
+  assert.doesNotMatch(JSON.stringify(f.requests[2].messages), /Discarded/);
+  assert.equal((await f.conversation.send({ text: "Discarded", messageId: "second" })).duplicate, true);
+  const recorded = await f.storage.read("one", async tx => Promise.all((await tx.listTurnIds()).map(id => tx.readTurn(id))));
+  assert.equal(recorded.length, 3);
+  assert.ok(recorded[1].metadata.runtime.supersededBy);
+});
+
+test("unfinished historical Undo operations require offline inspection without changing saved state", async t => {
+  const f = await fixture(t);
+  await f.say("Before", "first");
+  const operation = await f.replacement();
+  const metadata = await f.storage.read("one", transaction => transaction.readMetadata());
+  for (const patch of [{ reason: "rewind" },
+    { request: { ...operation, operation: "replace", reason: "rewind" } },
+    { request: { ...operation, operation: "replace", throughTurnId: null } },
+    { supersededTurns: ["000001"] }]) {
+    const saved = structuredClone(metadata);
+    saved.runtime.replacement = { request: { ...operation, operation: "replace" }, reason: "renewal", engine: "api",
+      configuration, segmentId: "historical-successor", seen: {}, ...patch };
+    await f.storage.write("one", transaction => transaction.writeMetadata(saved));
+    await assert.rejects(f.conversation.replace(operation), { code: "conversation_rewind_inspection_required" });
+    await assert.rejects(f.runtime().open({ id: "one" }), { code: "conversation_rewind_inspection_required" });
+    assert.deepEqual(await f.storage.read("one", transaction => transaction.readMetadata()), saved);
+    assert.equal((await f.conversation.read()).conversationLog.length, 1);
+    assert.equal(f.requests.length, 1);
+  }
+});
+
+test("an interrupted replacement blocks sending and resumes exactly once after application restart", async t => {
+  const f = await fixture(t);
+  await f.say("Before", "first");
+  const operation = await f.replacement();
+  f.state.failCommit = true;
+  await assert.rejects(f.conversation.replace(operation), /Storage offline/);
+  assert.equal((await f.conversation.read()).status, "replacement-pending");
+  await assert.rejects(f.conversation.send({ text: "Too early", messageId: "early" }), { code: "conversation_replacement_pending" });
+  await assert.rejects(f.conversation.configure({ systemPrompt: "Too early" }), { code: "conversation_replacement_pending" });
+  await f.first.close();
+  f.state.failCommit = false;
+  const resumed = await f.runtime().open({ id: "one" });
+  const result = await resumed.replace(operation);
+  await resumed.send({ text: "After", messageId: "after" });
+  const saved = await f.storage.read("one", tx => tx.readMetadata());
+  assert.equal(saved.runtime.predecessors.length, 1);
+  assert.equal(saved.runtime.segmentId, result.segmentId);
+  assert.equal((await resumed.wait()).conversationLog.length, 2);
+  assert.equal(f.requests.length, 2);
+});
+
+test("invalid, stale and forbidden replacement requests do not alter the conversation", async t => {
+  const f = await fixture(t);
+  const operation = await f.replacement();
+  await assert.rejects(f.conversation.replace({ ...operation, expectedSegmentId: "stale" }), { code: "conversation_replacement_conflict" });
+  await assert.rejects(f.conversation.replace({ ...operation, reason: "rewind" }), { code: "conversation_invalid_replacement" });
+  await assert.rejects(f.conversation.replace({ ...operation, reason: "rewind", throughTurnId: "missing" }), { code: "conversation_invalid_replacement" });
+  await assert.rejects(f.conversation.replace({ ...operation, reason: "rewind", throughTurnId: null }), { code: "conversation_invalid_replacement" });
+  await assert.rejects(f.conversation.replace({ ...operation, throughTurnId: null }), { code: "conversation_invalid_replacement" });
+  await assert.rejects(f.conversation.replace({ ...operation, engine: "missing" }), /does not yet support/);
+  f.state.allowed = false;
+  await assert.rejects(f.conversation.replace(operation), { code: "conversation_forbidden" });
+  f.state.allowed = true;
+  assert.equal((await f.conversation.read()).segmentId, operation.expectedSegmentId);
+  assert.equal((await f.conversation.read()).replacement, null);
+});
+
+test("carry-over explicitly marks omitted history and rejects an oversized briefing before replacement", async t => {
+  const f = await fixture(t, { limits: { maxContinuityCharacters: 800 } });
+  await f.say("X".repeat(2500), "first");
+  const operation = await f.replacement({ briefing: "" });
+  await assert.rejects(f.conversation.replace({ ...operation, briefing: "X".repeat(900) }), /briefing exceeds/);
+  assert.equal((await f.conversation.read()).replacement, null);
+  await f.conversation.replace(operation);
+  await f.say("Continue", "second");
+  assert.match(f.requests[1].messages[1].content, /"omittedMessages":1/);
+  assert.ok(f.requests[1].messages[1].content.length <= 800);
+});
+
+test("host scope belongs to a conversation and cannot be changed through another open handle", async t => {
+  const f = await fixture(t);
+  const host = { workdir: "/application/one", env: { HOME: "/accounts/one" } };
+  const one = await f.first.open({ id: "scoped-one", host, configuration });
+  const two = await f.first.open({ id: "scoped-two", host: { workdir: "/application/two" }, configuration });
+  await assert.rejects(f.first.open({ id: "scoped-one", host: { workdir: "/application/other" } }), { code: "conversation_host_mismatch" });
+  await one.send({ messageId: "one", text: "One" });
+  await two.send({ messageId: "two", text: "Two" });
+  assert.equal((await one.wait()).conversationLog.length, 1);
+  assert.equal((await two.wait()).conversationLog.length, 1);
+});

package/test/conversationRuntime.test.js

@@ -0,0 +1,241 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createConversationHookBridge } from "../src/server/conversation/index.js";
+import { createClaudeConversationTurn } from "../src/server/conversation/claudeTurn.js";
+import { createCodexConversationAdapter } from "../src/server/conversation/providers/codex.js";
+import { createOpenCodeConversationAdapter } from "../src/server/conversation/providers/opencode.js";
+
+function claudeHost() {
+  let process = null;
+  const launches = [], requests = [];
+  const state = { active: false, fail: false, stopFails: false };
+  const runtime = createClaudeConversationTurn({ conversationId: "retained-history", process: {
+    getProcess: () => process, isActive: () => state.active,
+    startProcess: async (input) => {
+      launches.push(input);
+      process = { client: { request: async (request) => {
+        requests.push(request);
+        if (state.fail) throw new Error("native failure");
+      } } };
+      return process;
+    },
+    stopProcess: async () => { if (state.stopFails) throw new Error("cleanup unverified"); process = null; }
+  } });
+  return { runtime, state, launches, requests, loseProcess: () => { process = null; } };
+}
+const claudeInput = { systemPrompt: "Use the calendar tools.", contextIdentity: "calendar/model-one",
+  model: "one", settings: { effortLevel: "high" }, liveUpdateIdentity: "calendar-schema" };
+
+test("a standalone Claude consumer reuses, updates and replaces processes without changing native history", async () => {
+  const f = claudeHost();
+  const input = { ...claudeInput, nativeId: "retained-history" };
+  await Promise.all([f.runtime.prepare(input), f.runtime.prepare(input)]);
+  assert.equal(f.launches.length, 1);
+  assert.deepEqual(f.launches[0].instructionArguments, ["--append-system-prompt", input.systemPrompt, "--system-prompt-snapshot", "off"]);
+  await f.runtime.prepare({ ...input, contextIdentity: "calendar/model-two", model: "two" });
+  assert.equal(f.launches.length, 1);
+  assert.deepEqual(f.requests.at(-1), { subtype: "set_model", model: "two" });
+  const changed = { ...input, systemPrompt: "Use the updated calendar tools.", instructionMode: "replace" };
+  await f.runtime.prepare(changed);
+  assert.equal(f.launches.length, 2);
+  assert.equal(f.launches[1].nativeId, "retained-history");
+  assert.deepEqual(f.launches[1].instructionArguments, ["--system-prompt", changed.systemPrompt, "--system-prompt-snapshot", "off"]);
+  f.loseProcess();
+  await f.runtime.prepare(changed);
+  assert.equal(f.launches.length, 3);
+});
+
+test("Claude rejects active prompt changes without invalidating ordinary steering", async () => {
+  const f = claudeHost();
+  await f.runtime.prepare(claudeInput);
+  f.state.active = true;
+  await assert.rejects(f.runtime.prepare({ ...claudeInput, systemPrompt: "Changed" }), /Stop the current/);
+  await f.runtime.prepare(claudeInput);
+  assert.equal(f.launches.length, 1);
+});
+
+test("Claude restarts when only the native instruction mode changes", async () => {
+  const f = claudeHost();
+  await f.runtime.prepare(claudeInput);
+  await f.runtime.prepare({ ...claudeInput, instructionMode: "replace" });
+  assert.equal(f.launches.length, 2);
+  assert.deepEqual(f.launches[1].instructionArguments, ["--system-prompt", claudeInput.systemPrompt, "--system-prompt-snapshot", "off"]);
+});
+
+test("Claude does not acknowledge failed native settings or launch past failed cleanup", async () => {
+  const f = claudeHost();
+  f.state.fail = true;
+  await assert.rejects(f.runtime.prepare(claudeInput), /native failure/);
+  f.state.fail = false;
+  await f.runtime.prepare(claudeInput);
+  assert.equal(f.launches.length, 2);
+  f.state.stopFails = true;
+  await assert.rejects(f.runtime.prepare({ ...claudeInput, systemPrompt: "Updated" }), /cleanup unverified/);
+  assert.equal(f.launches.length, 2);
+});
+
+function codexHost() {
+  const state = { status: "idle", process: "process-1", prompt: "Calendar instructions", provider: "openai", fail: false };
+  const requests = [];
+  const client = { async request(method, input) {
+    requests.push({ method, input });
+    if (method === "thread/read") return { thread: { historyMode: "paginated", status: state.status, modelProvider: state.provider } };
+    if (method === "thread/goal/get") return { goal: null };
+    if (method === "thread/inject_items") return {};
+    if (method === "thread/loaded/list") return { data: state.status === "notLoaded" ? [] : ["native-history"] };
+    if (method === "thread/unsubscribe") { state.status = "notLoaded"; return { status: "unsubscribed" }; }
+    if (method === "thread/resume") {
+      if (state.fail) throw new Error("resume failed");
+      state.status = "idle";
+      return { modelProvider: input.modelProvider || state.provider };
+    }
+    throw new Error(`Unexpected native request: ${method}`);
+  } };
+  const runtime = createCodexConversationAdapter({ client: async () => client,
+    runtime: () => ({ executionId: state.process }), runRequest: (run) => run(),
+    readInstructions: () => state.prompt,
+    prepareEnvironment: async () => ({ TOOL_ENDPOINT: "current" }),
+    prepareHistory: async (params) => params,
+    threadParameters: (params) => params,
+    verifyEnvironment: async () => {},
+    prepareResume: async (id, params) => { requests.push({ method: "host.prepareResume", input: { id } }); return params; }
+  });
+  return { runtime, state, requests, client };
+}
+
+test("a standalone Codex consumer installs developer instructions and recovers the same thread without replay", async () => {
+  const f = codexHost();
+  const params = await f.runtime.prepareInstructions({ cwd: "/calendar", systemPrompt: f.state.prompt });
+  assert.equal(params.developerInstructions, f.state.prompt);
+  assert.equal(Object.hasOwn(params, "systemPrompt"), false);
+  let sent = 0;
+  const send = () => { sent += 1; };
+  await f.runtime.withThreadContext("native-history", {}, send);
+  assert.equal(f.requests.find(r => r.method === "thread/resume").input.developerInstructions, f.state.prompt);
+  f.requests.length = 0;
+  await f.runtime.withThreadContext("native-history", {}, send);
+  assert.equal(f.requests.some(r => r.method === "thread/resume"), false);
+  assert.equal(f.requests.some(r => r.method === "thread/inject_items"), false);
+  f.state.prompt = "Changed calendar instructions";
+  await f.runtime.withThreadContext("native-history", {}, send);
+  assert.equal(f.requests.find(r => r.method === "thread/resume").input.threadId, "native-history");
+  const revision = f.requests.find(r => r.method === "thread/inject_items").input.items[0];
+  assert.equal(revision.role, "developer");
+  assert.match(revision.content[0].text, /Changed calendar instructions/);
+  assert.equal(sent, 3);
+  f.state.fail = true;
+  f.state.prompt = "Unavailable installation";
+  await assert.rejects(f.runtime.withThreadContext("native-history", {}, send), /could not be verified/);
+  assert.equal(sent, 3);
+  assert.equal(f.runtime.bindingCount, 0);
+  f.state.fail = false;
+  await f.runtime.withThreadContext("native-history", {}, () => { sent += 1; throw new Error("ambiguous send"); }).catch(error => {
+    assert.match(error.message, /ambiguous send/);
+  });
+  assert.equal(sent, 4, "an uncertain caller operation is never replayed");
+});
+
+test("Codex refreshes restricted persistent conversations without importing host execution resources", async () => {
+  const f = codexHost();
+  const params = f.runtime.threadParameters({
+    ...(await f.runtime.prepareInstructions({ systemPrompt: f.state.prompt })),
+    config: { shell_environment_policy: { inherit: "none", set: {} } }
+  }, {});
+  f.runtime.registerThread("restricted", { client: f.client, params, managed: false });
+  await f.runtime.withThreadContext("restricted", {}, () => {});
+  assert.equal(f.requests.some(r => r.method === "thread/resume"), false);
+  f.state.prompt = "Updated restricted instructions";
+  await f.runtime.withThreadContext("restricted", {}, () => {});
+  const resumed = f.requests.find(r => r.method === "thread/resume").input;
+  assert.equal(resumed.developerInstructions, f.state.prompt);
+  assert.equal(resumed.config.shell_environment_policy.set.TOOL_ENDPOINT, undefined);
+  assert.deepEqual(Object.keys(resumed.config.shell_environment_policy.set), ["JSKIT_CONVERSATION_INSTRUCTIONS"]);
+});
+
+test("Codex distinguishes native process replacement from a retained loaded thread", async () => {
+  const f = codexHost();
+  await f.runtime.withThreadContext("history", {}, () => {});
+  f.requests.length = 0;
+  f.state.process = "process-2";
+  f.state.status = "notLoaded";
+  await f.runtime.withThreadContext("history", {}, () => {});
+  assert.equal(f.requests.filter(r => r.method === "host.prepareResume").length, 1);
+  assert.equal(f.requests.filter(r => r.method === "thread/resume").length, 1);
+});
+
+test("OpenCode restores current system instructions after compaction, changes and failed reads", async () => {
+  let version = "one", reads = 0, fail = false;
+  const runtime = createOpenCodeConversationAdapter({ resolveInstructions: async (id) => id === "unknown" ? null : ({
+    identity: version, placement: "replace", read: async () => { reads += 1; if (fail) throw new Error("owner unavailable"); return `Calendar ${version}`; }
+  }) });
+  const output = { system: ["Native defaults"] };
+  await runtime.transformSystem({ sessionID: "calendar" }, output);
+  await runtime.transformSystem({ sessionID: "calendar" }, output);
+  assert.equal(reads, 1);
+  assert.deepEqual(output.system, ["Calendar one"]);
+  version = "two";
+  await runtime.transformSystem({ sessionID: "calendar" }, output);
+  assert.deepEqual(output.system, ["Calendar two"]);
+  runtime.event({ event: { type: "session.compacted", properties: { sessionID: "calendar" } } });
+  fail = true;
+  await assert.rejects(runtime.transformSystem({ sessionID: "calendar" }, output), /owner unavailable/);
+  fail = false;
+  await runtime.transformSystem({ sessionID: "calendar" }, output);
+  assert.equal(reads, 4);
+  const standalone = { system: ["Standalone guidance"] };
+  await runtime.transformSystem({ sessionID: "unknown" }, standalone);
+  assert.deepEqual(standalone.system, ["Standalone guidance"]);
+});
+
+test("OpenCode rereads unversioned instructions before each inference without duplicate contributions", async () => {
+  let text = "Initial project guidance", reads = 0;
+  const runtime = createOpenCodeConversationAdapter({ resolveInstructions: () => ({
+    read: () => { reads += 1; return text; }
+  }) });
+  const output = { system: ["Native defaults"] };
+  await runtime.transformSystem({ sessionID: "project" }, output);
+  text = "Changed project guidance";
+  await runtime.transformSystem({ sessionID: "project" }, output);
+  assert.equal(reads, 2);
+  assert.deepEqual(output.system, ["Native defaults", text]);
+});
+
+test("hook delivery distinguishes unclaimed sessions, native placement and a missing declared owner", async () => {
+  let prompt = "Complete project and application instructions";
+  const deliver = createConversationHookBridge({
+    resolveConversation: async ({ providerSessionId }) => providerSessionId === "standalone" ? null : {
+      delivery: providerSessionId === "native" ? "native" : "hook"
+    },
+    readInstructions: async () => { if (!prompt) throw new Error("owner unavailable"); return prompt; }
+  });
+  assert.deepEqual(await deliver({ scope: "session", providerSessionId: "standalone" }), { kind: "unclaimed" });
+  assert.deepEqual(await deliver({ scope: "session", providerSessionId: "native" }), { kind: "delivery", text: "" });
+  assert.deepEqual(await deliver({ scope: "session", providerSessionId: "managed" }), { kind: "delivery", text: prompt });
+  prompt = "Refreshed at compaction";
+  assert.equal((await deliver({ scope: "session", providerSessionId: "managed" })).text, prompt);
+  prompt = "";
+  await assert.rejects(deliver({ scope: "session", providerSessionId: "managed" }), /owner unavailable/);
+  const native = createConversationHookBridge({ resolveConversation: () => ({ delivery: "native" }) });
+  assert.deepEqual(await native({ scope: "session" }), { kind: "delivery", text: "" });
+  const missing = createConversationHookBridge({ resolveConversation: () => ({ delivery: "hook" }) });
+  await assert.rejects(missing({ scope: "session" }), /instruction resolver/);
+});
+
+test("OpenCode retries invalid content and rejects an invalidated in-flight read", async () => {
+  let content = " ";
+  let release;
+  const runtime = createOpenCodeConversationAdapter({ resolveInstructions: async () => ({
+    identity: "same-source", read: () => content === "pending" ? new Promise(resolve => { release = resolve; }) : content
+  }) });
+  await assert.rejects(runtime.transformSystem({ sessionID: "one" }, { system: [] }), /must contain text/);
+  content = "Current instructions";
+  const output = { system: [] };
+  await runtime.transformSystem({ sessionID: "one" }, output);
+  assert.deepEqual(output.system, [content]);
+  content = "pending";
+  const inFlight = runtime.transformSystem({ sessionID: "two" }, { system: [] });
+  await new Promise(resolve => setImmediate(resolve));
+  runtime.invalidate("two");
+  release("Obsolete instructions");
+  await assert.rejects(inFlight, /context changed while reading/);
+});

package/test/conversationRuntimeStateUpgrade.test.js

@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { upgradeConversationRuntimeState } from "../src/server/conversation/runtimeStateUpgrade.js";
+
+const configuration = { systemPrompt: "Retained instructions", model: "saved-model" };
+const request = { messageId: "uncertain", text: "Authored text", origin: "user", attachments: [{ attachmentId: "file" }],
+  at: "2026-10-02T00:00:00.000Z", seen: { "old/user/": "native-version" }, data: { retained: true } };
+const bindings = {
+  api: undefined,
+  codex: { threadId: "saved-thread", workdir: "/workspace", configRoot: "/codex", executionId: "saved-execution" },
+  claude: { conversationId: "saved-conversation", workdir: "/workspace", configRoot: "/claude", sent: true },
+  opencode: { sessionId: "saved-session", workdir: "/workspace", directory: "/private/session", databasePath: "/shared/opencode.db" }
+};
+const segment = (engine, extra = {}) => ({ segmentId: `${engine}-segment`, engine, configuration,
+  seen: { "old/user/": "native-version" }, ...(bindings[engine] ? { binding: bindings[engine] } : {}), ...extra });
+const record = (engine = "claude", extra = {}) => ({
+  metadata: { application: { retained: true }, runtime: { ...segment(engine), version: 2, predecessors: [], ...extra } },
+  conversationLog: [{ turnId: "old", metadata: { runtime: { engine: "codex", segmentId: "codex-segment", status: "interrupted" } },
+    messages: [{ role: "user", text: "Accepted before model selection", messageId: "old-message" }] }]
+});
+
+test("offline conversion preserves exact native bindings and authored requests without inventing a prompt", () => {
+  const value = record("claude", { predecessors: [segment("codex", { request: structuredClone(request) })] });
+  const before = structuredClone(value);
+  const result = upgradeConversationRuntimeState(value);
+  assert.equal(result.changed, true);
+  assert.equal(result.metadata.runtime.version, 3);
+  assert.equal(result.metadata.runtime.lastEngine, "codex", "Selection alone is not delivery");
+  assert.deepEqual(result.metadata.application, before.metadata.application);
+  assert.deepEqual(result.metadata.runtime.binding, before.metadata.runtime.binding);
+  assert.deepEqual(result.metadata.runtime.seen, before.metadata.runtime.seen);
+  assert.deepEqual(result.metadata.runtime.predecessors[0], { ...before.metadata.runtime.predecessors[0],
+    request: { ...request, inspectionOnly: true, threadId: "saved-thread" } });
+  assert.equal(Object.hasOwn(result.metadata.runtime.predecessors[0].request, "message"), false);
+  assert.equal(Object.hasOwn(result.metadata.runtime.predecessors[0].request, "attempted"), false);
+  assert.match(result.warnings[0], /not reconstructed.*not be replayed/);
+  assert.deepEqual(value, before, "The transformer does not mutate its source");
+});
+
+test("pre-runtime transcripts gain no binding and current converted records are no-ops", () => {
+  const metadata = { application: "retained" };
+  assert.deepEqual(upgradeConversationRuntimeState({ metadata, conversationLog: [] }), { metadata, changed: false, warnings: [] });
+  const value = record("codex", { request: structuredClone(request) });
+  const first = upgradeConversationRuntimeState(value);
+  const second = upgradeConversationRuntimeState({ ...value, metadata: first.metadata });
+  assert.equal(second.changed, false);
+  assert.equal(second.metadata, first.metadata);
+  assert.deepEqual(second.warnings, []);
+});
+
+test("unfinished replacements retain their operation and inspect the destination's exact identity", () => {
+  const replacement = { ...segment("opencode"), request: { operationId: "selection", expectedSegmentId: "claude-segment", operation: "select" },
+    reason: "engine-change", submission: structuredClone(request), continuity: "Retained context", supersededTurns: [] };
+  const value = record("claude", { replacement });
+  const result = upgradeConversationRuntimeState(value);
+  assert.deepEqual(result.metadata.runtime.replacement, { ...replacement,
+    submission: { ...request, inspectionOnly: true, threadId: "saved-session" } });
+  assert.deepEqual(value.metadata.runtime.replacement, replacement);
+});
+
+test("replacement preparation timestamps stay on the existing operation without backfilling older records", () => {
+  for (const preparation of [{}, { preparedAt: "2026-10-03T00:00:00.000Z" }]) {
+    const value = record("claude", { replacement: { ...segment("claude", { segmentId: "successor" }),
+      request: { operationId: "renewal", expectedSegmentId: "claude-segment", operation: "replace" },
+      reason: "renewal", ...preparation }, predecessors: [segment("codex", preparation)] });
+    const before = structuredClone(value);
+    const result = upgradeConversationRuntimeState(value);
+    assert.deepEqual(result.metadata.runtime.replacement, before.metadata.runtime.replacement);
+    assert.deepEqual(result.metadata.runtime.predecessors, before.metadata.runtime.predecessors);
+    assert.equal(upgradeConversationRuntimeState({ ...value, metadata: result.metadata }).changed, false);
+    assert.deepEqual(value, before);
+  }
+  for (const extra of [{ replacement: { ...segment("claude"), preparedAt: 1 } },
+    { predecessors: [segment("codex", { preparedAt: null })] }]) {
+    assert.throws(() => upgradeConversationRuntimeState(record("claude", extra)), { code: "conversation_runtime_upgrade_unavailable" });
+  }
+});
+
+test("private OpenCode database bindings block preflight in current, retained and replacement state", () => {
+  const unsupported = segment("opencode", { binding: { ...bindings.opencode, databasePath: undefined } });
+  for (const value of [record("opencode", unsupported), record("claude", { predecessors: [unsupported] }),
+    record("claude", { replacement: { ...unsupported, request: { operationId: "pending" } } })]) {
+    const before = structuredClone(value);
+    assert.throws(() => upgradeConversationRuntimeState(value), /complete offline native-history upgrade.*database was not changed/);
+    assert.deepEqual(value, before);
+  }
+});
+
+test("unfinished historical Undo journals block offline conversion while completed markers remain intact", () => {
+  for (const version of [2, 3]) {
+    for (const patch of [{ reason: "rewind" }, { request: { operationId: "old", reason: "rewind" } },
+      { request: { operationId: "old", throughTurnId: null } }, { supersededTurns: ["old"] }]) {
+      const value = record("api", { version, lastEngine: "api", replacement: { ...segment("api"),
+        request: { operationId: "old", reason: "renewal" }, reason: "renewal", ...patch } });
+      const before = structuredClone(value);
+      assert.throws(() => upgradeConversationRuntimeState(value), /unfinished Undo.*offline.*no history was changed/);
+      assert.deepEqual(value, before);
+    }
+  }
+  const completed = record("api", { version: 3, lastEngine: "api", predecessors: [segment("api", {
+    segmentId: "previous", successorId: "api-segment", replacement: { operationId: "done", reason: "rewind", throughTurnId: null }
+  })] });
+  completed.conversationLog[0].metadata.runtime.supersededBy = "api-segment";
+  const before = structuredClone(completed);
+  assert.deepEqual(upgradeConversationRuntimeState(completed), { metadata: completed.metadata, changed: false, warnings: [] });
+  assert.deepEqual(completed, before);
+});
+
+test("unknown formats and ambiguous pending identities fail without guessing or modifying input", () => {
+  for (const value of [record("codex", { version: 1 }),
+    record("codex", { binding: { ...bindings.codex, threadId: "" }, request: structuredClone(request) }),
+    record("codex", { request: { ...request, message: "Unknown partially converted prompt" } }),
+    record("codex", { request: { ...request, attachmentManifest: "Unknown partially converted paths" } })]) {
+    const before = structuredClone(value);
+    assert.throws(() => upgradeConversationRuntimeState(value), { code: "conversation_runtime_upgrade_unavailable" });
+    assert.deepEqual(value, before);
+  }
+});
+
+test("API reservations keep their admission contract and unattributed history is not native delivery proof", () => {
+  const value = record("api", { request: structuredClone(request) });
+  value.conversationLog[0].metadata = { application: "legacy" };
+  const result = upgradeConversationRuntimeState(value);
+  assert.equal(result.metadata.runtime.lastEngine, "");
+  assert.deepEqual(result.metadata.runtime.request, request);
+  assert.deepEqual(result.warnings, []);
+});
+
+test("current journals distinguish an unsent reservation from a frozen attempted native prompt", () => {
+  const reserved = record("codex", { version: 3, lastEngine: "codex", binding: { ...bindings.codex, threadId: "" },
+    request: { ...request, attempted: false } });
+  assert.equal(upgradeConversationRuntimeState(reserved).changed, false);
+  const frozen = record("codex", { version: 3, lastEngine: "codex", request: { ...request, attempted: true,
+    threadId: "saved-thread", message: "The exact rendered native prompt", displayMessage: request.text,
+    displayAttachments: request.attachments, attachmentIds: ["file"], contextText: "The exact private history",
+    contextAttachments: [{ attachmentId: "earlier-file" }], attachmentManifest: "\n\nAttached files:\n@file \"name\": \"/authorized/file\"" } });
+  assert.equal(upgradeConversationRuntimeState(frozen).changed, false);
+  for (const patch of [{ attempted: undefined }, { message: undefined }, { threadId: "another-thread" },
+    { inspectionOnly: false }, { contextAttachments: undefined }, { attachmentManifest: null }]) {
+    assert.throws(() => upgradeConversationRuntimeState({ ...frozen,
+      metadata: { ...frozen.metadata, runtime: { ...frozen.metadata.runtime,
+        request: { ...frozen.metadata.runtime.request, ...patch } } } }), { code: "conversation_runtime_upgrade_unavailable" });
+  }
+});