@cortexkit/opencode-magic-context 0.42.5 → 0.42.6

package/src/shared/conflict-detector.ts

@@ -3,11 +3,14 @@ import { join } from "node:path";
 import { readJsoncFile } from "./jsonc-parser";
 import { log } from "./logger";
 import { getOpenCodeConfigPaths } from "./opencode-config-dir";
+import type { OpenCodeHostGeneration } from "./opencode-db-path";
 
 interface OpenCodeConfig {
     compaction?: {
         auto?: boolean;
         prune?: boolean;
+        keep?: { tokens?: number };
+        buffer?: number;
     };
     // OpenCode allows plugins as plain strings or [name, options] tuples.
     plugin?: Array<string | [string, unknown]>;
@@ -62,6 +65,8 @@ export interface ConflictResult {
 export interface ResolvedCompaction {
     auto: boolean;
     prune: boolean;
+    keepTokens?: number;
+    buffer?: number;
 }
 
 /**
@@ -92,6 +97,7 @@ export interface ResolvedCompaction {
 export interface DetectConflictsOptions {
     compactionEnabled?: boolean;
     resolvedCompaction?: ResolvedCompaction;
+    hostGeneration?: OpenCodeHostGeneration;
 }
 
 /**
@@ -113,6 +119,7 @@ export function detectConflicts(
     options?: DetectConflictsOptions,
 ): ConflictResult {
     const compactionEnabled = options?.compactionEnabled ?? true;
+    const hostGeneration = options?.hostGeneration ?? "v1";
     const conflicts: ConflictResult["conflicts"] = {
         compactionAuto: false,
         compactionPrune: false,
@@ -129,7 +136,8 @@ export function detectConflicts(
     // wrongly disabling the plugin for users whose auto=false lives in a layer
     // the file reader cannot see). When the resolved fetch failed, fall back to
     // the file-based check unchanged.
-    let compactionResult = options?.resolvedCompaction ?? checkCompaction(directory);
+    let compactionResult =
+        options?.resolvedCompaction ?? checkCompaction(directory, hostGeneration);
     // OPENCODE_DISABLE_AUTOCOMPACT short-circuits BOTH arms: it is the first,
     // cheapest check and is correct regardless of which arm produced the value.
     // (checkCompaction already applies it internally for the file arm; this
@@ -141,7 +149,7 @@ export function detectConflicts(
     // compaction-off mode the user has explicitly handed the window to native
     // compaction (or nothing), so compaction.auto=true / prune=true are the
     // intended state, not a plugin-disabling conflict.
-    if (compactionEnabled && compactionResult.auto) {
+    if (hostGeneration === "v1" && compactionEnabled && compactionResult.auto) {
         conflicts.compactionAuto = true;
         reasons.push(
             options?.resolvedCompaction
@@ -149,7 +157,7 @@ export function detectConflicts(
                 : "OpenCode auto-compaction is enabled (compaction.auto=true)",
         );
     }
-    if (compactionEnabled && compactionResult.prune) {
+    if (hostGeneration === "v1" && compactionEnabled && compactionResult.prune) {
         conflicts.compactionPrune = true;
         reasons.push(
             options?.resolvedCompaction
@@ -192,7 +200,10 @@ export function detectConflicts(
         hasConflict: reasons.length > 0,
         reasons,
         conflicts,
-        nativeCompaction: { auto: compactionResult.auto, prune: compactionResult.prune },
+        nativeCompaction: {
+            auto: compactionResult.auto,
+            prune: hostGeneration === "v1" ? compactionResult.prune : false,
+        },
     };
 }
 
@@ -221,6 +232,8 @@ interface ResolvedCompactionBlock {
     compaction?: {
         auto?: boolean;
         prune?: boolean;
+        keep?: { tokens?: number };
+        buffer?: number;
     };
 }
 
@@ -249,6 +262,7 @@ interface ResolvedCompactionBlock {
 export async function resolveCompactionForBoot(
     client: OpencodeConfigClientLike,
     timeoutMs = 2_000,
+    hostGeneration: OpenCodeHostGeneration = "v1",
 ): Promise<ResolvedCompaction | null> {
     const controller = new AbortController();
     let timer: ReturnType<typeof setTimeout> | undefined;
@@ -276,6 +290,28 @@ export async function resolveCompactionForBoot(
         // The SDK's generated `Config` type has no `compaction` key, so read it
         // defensively from the runtime response.
         const compaction = (result?.data as ResolvedCompactionBlock | undefined)?.compaction;
+        if (hostGeneration === "v2") {
+            if (typeof compaction?.auto !== "boolean") {
+                log(
+                    `[magic-context] conflict-detector: resolved v2 config carried no explicit compaction.auto (${JSON.stringify(compaction) ?? "absent"}); falling back to file-based detection`,
+                );
+                return null;
+            }
+            const keepTokens = compaction.keep?.tokens;
+            const buffer = compaction.buffer;
+            if (
+                (keepTokens !== undefined && (!Number.isInteger(keepTokens) || keepTokens < 0)) ||
+                (buffer !== undefined && (!Number.isInteger(buffer) || buffer < 0))
+            ) {
+                return null;
+            }
+            return {
+                auto: compaction.auto,
+                prune: false,
+                ...(keepTokens === undefined ? {} : { keepTokens }),
+                ...(buffer === undefined ? {} : { buffer }),
+            };
+        }
         // Explicit booleans only. An absent block (or non-boolean values) means
         // the response shape did not carry the resolved state — fall back to the
         // file arm rather than resolving to the plugin-disabling default.
@@ -293,28 +329,30 @@ export async function resolveCompactionForBoot(
     }
 }
 
-function checkCompaction(directory: string): { auto: boolean; prune: boolean } {
+function checkCompaction(
+    directory: string,
+    hostGeneration: OpenCodeHostGeneration,
+): ResolvedCompaction {
     if (process.env.OPENCODE_DISABLE_AUTOCOMPACT) {
         return { auto: false, prune: false };
     }
 
     // Check project-level config first (higher precedence)
-    const projectResult = readProjectCompaction(directory);
+    const projectResult = readProjectCompaction(directory, hostGeneration);
     if (projectResult.resolved) return projectResult;
 
     // Fall back to user-level config
-    const userResult = readUserCompaction();
+    const userResult = readUserCompaction(hostGeneration);
     if (userResult.resolved) return userResult;
 
     // Default: OpenCode has compaction enabled by default
     return { auto: true, prune: false };
 }
 
-function readProjectCompaction(directory: string): {
-    auto: boolean;
-    prune: boolean;
-    resolved: boolean;
-} {
+function readProjectCompaction(
+    directory: string,
+    hostGeneration: OpenCodeHostGeneration,
+): ResolvedCompaction & { resolved: boolean } {
     // .opencode/ config has higher precedence
     const dotOcJsonc = join(directory, ".opencode", "opencode.jsonc");
     const dotOcJson = join(directory, ".opencode", "opencode.json");
@@ -323,8 +361,12 @@ function readProjectCompaction(directory: string): {
 
     if (dotOcConfig?.compaction) {
         const c = dotOcConfig.compaction;
-        if (c.auto !== undefined || c.prune !== undefined) {
-            return { auto: c.auto === true, prune: c.prune === true, resolved: true };
+        if (
+            c.auto !== undefined ||
+            (hostGeneration === "v1" && c.prune !== undefined) ||
+            (hostGeneration === "v2" && (c.keep?.tokens !== undefined || c.buffer !== undefined))
+        ) {
+            return resolvedCompactionBlock(c, hostGeneration);
         }
     }
 
@@ -336,15 +378,21 @@ function readProjectCompaction(directory: string): {
 
     if (rootConfig?.compaction) {
         const c = rootConfig.compaction;
-        if (c.auto !== undefined || c.prune !== undefined) {
-            return { auto: c.auto === true, prune: c.prune === true, resolved: true };
+        if (
+            c.auto !== undefined ||
+            (hostGeneration === "v1" && c.prune !== undefined) ||
+            (hostGeneration === "v2" && (c.keep?.tokens !== undefined || c.buffer !== undefined))
+        ) {
+            return resolvedCompactionBlock(c, hostGeneration);
         }
     }
 
     return { auto: false, prune: false, resolved: false };
 }
 
-function readUserCompaction(): { auto: boolean; prune: boolean; resolved: boolean } {
+function readUserCompaction(
+    hostGeneration: OpenCodeHostGeneration,
+): ResolvedCompaction & { resolved: boolean } {
     try {
         const paths = getOpenCodeConfigPaths({ binary: "opencode" });
         const config =
@@ -353,8 +401,13 @@ function readUserCompaction(): { auto: boolean; prune: boolean; resolved: boolea
 
         if (config?.compaction) {
             const c = config.compaction;
-            if (c.auto !== undefined || c.prune !== undefined) {
-                return { auto: c.auto === true, prune: c.prune === true, resolved: true };
+            if (
+                c.auto !== undefined ||
+                (hostGeneration === "v1" && c.prune !== undefined) ||
+                (hostGeneration === "v2" &&
+                    (c.keep?.tokens !== undefined || c.buffer !== undefined))
+            ) {
+                return resolvedCompactionBlock(c, hostGeneration);
             }
         }
     } catch {
@@ -363,6 +416,22 @@ function readUserCompaction(): { auto: boolean; prune: boolean; resolved: boolea
     return { auto: false, prune: false, resolved: false };
 }
 
+function resolvedCompactionBlock(
+    block: NonNullable<OpenCodeConfig["compaction"]>,
+    hostGeneration: OpenCodeHostGeneration,
+): ResolvedCompaction & { resolved: true } {
+    if (hostGeneration === "v2") {
+        return {
+            auto: block.auto !== false,
+            prune: false,
+            resolved: true,
+            ...(typeof block.keep?.tokens === "number" ? { keepTokens: block.keep.tokens } : {}),
+            ...(typeof block.buffer === "number" ? { buffer: block.buffer } : {}),
+        };
+    }
+    return { auto: block.auto === true, prune: block.prune === true, resolved: true };
+}
+
 // --- DCP detection ---
 
 /**

package/src/shared/models-dev-cache.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { resolveKnownHistorianContextLimit } from "../hooks/magic-context/derive-budgets";
 import {
     clearModelsDevCache,
     getModelsDevCacheState,
@@ -230,6 +231,30 @@ describe("models-dev-cache (SDK-only)", () => {
         expect(getSdkContextLimit("openai", "gpt-5.4-mini")).toBe(922000);
     });
 
+    test("explicit SDK-resolved config limit wins over a larger catalog or detected value", async () => {
+        // OpenCode's config.providers() has already applied opencode.json over its
+        // catalog. The cache must preserve that 120K effective value, and a later
+        // API-detected 262K value may narrow but never enlarge it.
+        await refreshModelLimitsFromApi(
+            makeClient([
+                {
+                    id: "regolo",
+                    models: {
+                        "qwen3.5-122b": { limit: { context: 120_000, output: 32_000 } },
+                    },
+                },
+            ]),
+        );
+
+        expect(
+            getSdkContextLimit("regolo", "qwen3.5-122b", 262_144, {
+                reservation: "none",
+                detectedLimitProvenance: "combined",
+            }),
+        ).toBe(120_000);
+        expect(resolveKnownHistorianContextLimit("regolo/qwen3.5-122b")).toBe(120_000);
+    });
+
     test("narrows raw context with detected wire truth before reserving output", async () => {
         await refreshModelLimitsFromApi(
             makeClient([

package/src/shared/opencode-db-path.test.ts

@@ -5,13 +5,17 @@ import { mkdirSync, mkdtempSync, rmSync, unlinkSync, utimesSync, writeFileSync }
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
+    assertOpenCodeStoreGeneration,
+    detectOpenCodeStoreGeneration,
     formatOpenCodeDbDoctorLine,
     formatOpenCodeDbMissingBanner,
     formatOpenCodeDbMissingStatusLine,
     openCodeDbPathExists,
     resetOpenCodeDbPathStateForTesting,
     resolveOpenCodeDbPath,
+    sourceOpenCodeDatabaseFilename,
 } from "./opencode-db-path";
+import { Database } from "./sqlite";
 
 const ORIGINAL_ENV = {
     XDG_DATA_HOME: process.env.XDG_DATA_HOME,
@@ -173,6 +177,98 @@ describe("resolveOpenCodeDbPath", () => {
         });
     });
 
+    it("uses the verbatim v2 channel filename table without changing v1 defaults", () => {
+        const { dataHome, openCodeDir } = useDataHome();
+        for (const channel of ["latest", "dev", "beta", "next", "prod"]) {
+            expect(sourceOpenCodeDatabaseFilename("v2", channel, {})).toBe("opencode.db");
+        }
+        expect(sourceOpenCodeDatabaseFilename("v2", "a/b c!._-", {})).toBe("opencode-abc._-.db");
+        expect(
+            resolveOpenCodeDbPath("v2", {
+                dataHome,
+                channel: "local",
+                env: { OPENCODE_DB: "opencode2.db" },
+            }),
+        ).toEqual({
+            path: join(openCodeDir, "opencode2.db"),
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+    });
+
+    it("detects store generations and refuses a mismatched schema before reading", () => {
+        const { openCodeDir } = useDataHome();
+        const v1Path = join(openCodeDir, "v1.db");
+        const v2Path = join(openCodeDir, "v2.db");
+        const v1 = new Database(v1Path);
+        const v2 = new Database(v2Path);
+        try {
+            v1.exec("CREATE TABLE message(id TEXT); CREATE TABLE part(id TEXT)");
+            v2.exec("CREATE TABLE session_message(id TEXT)");
+            expect(detectOpenCodeStoreGeneration(v1)).toBe("v1");
+            expect(detectOpenCodeStoreGeneration(v2)).toBe("v2");
+            expect(() => assertOpenCodeStoreGeneration(v2, "v1", v2Path)).toThrow(
+                "expected v1, found v2",
+            );
+            expect(() => assertOpenCodeStoreGeneration(v1, "v2", v1Path)).toThrow(
+                "expected v2, found v1",
+            );
+        } finally {
+            v1.close();
+            v2.close();
+        }
+    });
+
+    it("reads a live OpenCode 1.18.x store as v1 even though it ships session_message", () => {
+        const { openCodeDir } = useDataHome();
+        const livePath = join(openCodeDir, "live-v1.db");
+        const live = new Database(livePath);
+        try {
+            // Captured from a running OpenCode 1.18.30 store. session_message exists in v1,
+            // so a detector keyed on its presence calls a v1 host v2 and every v1 reader
+            // (historian chunk, marker discovery, message index, tool-owner backfill) then
+            // refuses. Keep this table list as observed, not as remembered.
+            for (const table of [
+                "account",
+                "event",
+                "message",
+                "part",
+                "permission",
+                "project",
+                "session",
+                "session_message",
+                "session_run_lease",
+                "todo",
+                "workspace",
+            ]) {
+                live.exec(`CREATE TABLE ${table}(id TEXT)`);
+            }
+            expect(detectOpenCodeStoreGeneration(live)).toBe("v1");
+            expect(() => assertOpenCodeStoreGeneration(live, "v1", livePath)).not.toThrow();
+            expect(() => assertOpenCodeStoreGeneration(live, "v2", livePath)).toThrow(
+                "expected v2, found v1",
+            );
+        } finally {
+            live.close();
+        }
+    });
+
+    it("treats a store with no schema yet as empty rather than as a conflicting host", () => {
+        const { openCodeDir } = useDataHome();
+        const freshPath = join(openCodeDir, "fresh.db");
+        const fresh = new Database(freshPath);
+        try {
+            // A host that has not written its first row looks like this. Readers have always
+            // seen it as empty; refusing here throws inside the historian, marker and index
+            // readers on every fresh data directory.
+            expect(detectOpenCodeStoreGeneration(fresh)).toBe("unknown");
+            expect(() => assertOpenCodeStoreGeneration(fresh, "v1", freshPath)).not.toThrow();
+            expect(() => assertOpenCodeStoreGeneration(fresh, "v2", freshPath)).not.toThrow();
+        } finally {
+            fresh.close();
+        }
+    });
+
     it("formats the missing banner, status, and doctor lines by value", () => {
         const { openCodeDir } = useDataHome();
         const lookedFor = [

package/src/shared/opencode-db-path.ts

@@ -3,6 +3,25 @@ import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 
 export type OpenCodeDbPathSource = "OPENCODE_DB" | "channel" | "default" | "discovered";
+export type OpenCodeHostGeneration = "v1" | "v2";
+export type OpenCodeStoreGeneration = OpenCodeHostGeneration | "unknown";
+
+export interface ResolveOpenCodeDbPathOptions {
+    dataHome?: string;
+    channel?: string;
+    env?: NodeJS.ProcessEnv;
+}
+
+export function openCodeHostGenerationFromVersion(
+    version: string | null | undefined,
+): OpenCodeHostGeneration {
+    const major = Number.parseInt(version?.match(/\d+/)?.[0] ?? "", 10);
+    return Number.isFinite(major) && major >= 2 ? "v2" : "v1";
+}
+
+export interface OpenCodeStoreSchemaDatabase {
+    prepare(sql: string): { all(...params: unknown[]): unknown[] };
+}
 
 export interface OpenCodeDbPathResolution {
     path: string;
@@ -24,16 +43,22 @@ let cachedResolution: CachedResolution | null = null;
 let lastReadFailure: OpenCodeDbReadFailure | null = null;
 const claimedDiagnostics = new Set<string>();
 
-function openCodeDataDir(): string {
-    return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "opencode");
+function openCodeDataDir(env: NodeJS.ProcessEnv = process.env, dataHome?: string): string {
+    return join(dataHome ?? env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "opencode");
 }
 
-function environmentKey(dataDir: string): string {
+function environmentKey(
+    dataDir: string,
+    hostGeneration: OpenCodeHostGeneration,
+    channel: string | undefined,
+    env: NodeJS.ProcessEnv,
+): string {
     return [
+        hostGeneration,
         dataDir,
-        process.env.OPENCODE_DB ?? "",
-        process.env.OPENCODE_DISABLE_CHANNEL_DB ?? "",
-        process.env.OPENCODE_CHANNEL ?? "",
+        env.OPENCODE_DB ?? "",
+        env.OPENCODE_DISABLE_CHANNEL_DB ?? "",
+        channel ?? env.OPENCODE_CHANNEL ?? "",
     ].join("\0");
 }
 
@@ -81,8 +106,11 @@ function discoverOpenCodeDb(dataDir: string): OpenCodeDbPathResolution {
     return { path: existing.path, source: "discovered", channel };
 }
 
-function resolveFresh(dataDir: string): OpenCodeDbPathResolution {
-    const explicit = process.env.OPENCODE_DB;
+function resolveV1Fresh(
+    dataDir: string,
+    env: NodeJS.ProcessEnv = process.env,
+): OpenCodeDbPathResolution {
+    const explicit = env.OPENCODE_DB;
     if (explicit !== undefined && explicit.length > 0) {
         if (explicit === ":memory:") {
             return { path: explicit, source: "OPENCODE_DB", channel: null };
@@ -94,12 +122,12 @@ function resolveFresh(dataDir: string): OpenCodeDbPathResolution {
         };
     }
 
-    const disableChannelDb = process.env.OPENCODE_DISABLE_CHANNEL_DB;
+    const disableChannelDb = env.OPENCODE_DISABLE_CHANNEL_DB;
     if (disableChannelDb === "1" || disableChannelDb === "true") {
         return { path: join(dataDir, "opencode.db"), source: "default", channel: null };
     }
 
-    const channel = process.env.OPENCODE_CHANNEL;
+    const channel = env.OPENCODE_CHANNEL;
     if (channel !== undefined && channel.length > 0) {
         return { path: channelPath(dataDir, channel), source: "channel", channel };
     }
@@ -107,10 +135,59 @@ function resolveFresh(dataDir: string): OpenCodeDbPathResolution {
     return discoverOpenCodeDb(dataDir);
 }
 
-/** Resolve an explicit DB override first, then channel paths; discover candidates when the compiled channel is unknown. */
-export function resolveOpenCodeDbPath(): OpenCodeDbPathResolution {
-    const dataDir = openCodeDataDir();
-    const key = environmentKey(dataDir);
+/** Match OpenCode 2's filename table and strip path separators from custom channels. */
+export function sourceOpenCodeDatabaseFilename(
+    hostGeneration: OpenCodeHostGeneration,
+    channel: string,
+    env: NodeJS.ProcessEnv = process.env,
+): string {
+    if (hostGeneration === "v1") {
+        const explicit = env.OPENCODE_DB;
+        if (explicit !== undefined && explicit.length > 0) return explicit;
+        if (env.OPENCODE_DISABLE_CHANNEL_DB === "1" || env.OPENCODE_DISABLE_CHANNEL_DB === "true") {
+            return "opencode.db";
+        }
+        return ["latest", "beta", "prod"].includes(channel)
+            ? "opencode.db"
+            : `opencode-${channel}.db`;
+    }
+
+    return (
+        env.OPENCODE_DB ??
+        (["latest", "dev", "beta", "next", "prod"].includes(channel) ||
+        env.OPENCODE_DISABLE_CHANNEL_DB === "1" ||
+        env.OPENCODE_DISABLE_CHANNEL_DB === "true"
+            ? "opencode.db"
+            : `opencode-${channel.replace(/[^a-zA-Z0-9._-]/g, "")}.db`)
+    );
+}
+
+function resolveV2Fresh(
+    dataDir: string,
+    channel: string,
+    env: NodeJS.ProcessEnv,
+): OpenCodeDbPathResolution {
+    const filename = sourceOpenCodeDatabaseFilename("v2", channel, env);
+    const explicit = env.OPENCODE_DB !== undefined;
+    return {
+        path: filename === ":memory:" ? filename : join(dataDir, filename),
+        source: explicit ? "OPENCODE_DB" : env.OPENCODE_CHANNEL ? "channel" : "default",
+        channel: explicit ? null : channel,
+    };
+}
+
+/**
+ * Resolve the store for one host generation. The default is the historical v1
+ * resolver, including candidate discovery and all existing diagnostic text.
+ */
+export function resolveOpenCodeDbPath(
+    hostGeneration: OpenCodeHostGeneration = "v1",
+    options: ResolveOpenCodeDbPathOptions = {},
+): OpenCodeDbPathResolution {
+    const env = options.env ?? process.env;
+    const dataDir = openCodeDataDir(env, options.dataHome);
+    const channel = options.channel ?? env.OPENCODE_CHANNEL;
+    const key = environmentKey(dataDir, hostGeneration, channel, env);
     if (
         cachedResolution?.key === key &&
         (!cachedResolution.existed || existsSync(cachedResolution.resolution.path))
@@ -119,7 +196,10 @@ export function resolveOpenCodeDbPath(): OpenCodeDbPathResolution {
         // An absent result is re-probed so a DB created after plugin boot is detected.
     }
 
-    const resolution = resolveFresh(dataDir);
+    const resolution =
+        hostGeneration === "v2"
+            ? resolveV2Fresh(dataDir, channel ?? "latest", env)
+            : resolveV1Fresh(dataDir, env);
     cachedResolution = {
         key,
         resolution,
@@ -128,6 +208,57 @@ export function resolveOpenCodeDbPath(): OpenCodeDbPathResolution {
     return resolution;
 }
 
+function schemaTableNames(
+    db: OpenCodeStoreSchemaDatabase,
+    schema: "main" | "oc_backfill" = "main",
+): Set<string> {
+    const rows = db
+        .prepare(
+            `SELECT name FROM ${schema}.sqlite_master WHERE type = 'table' AND name IN ('message', 'part', 'session', 'project', 'session_message')`,
+        )
+        .all() as Array<{ name?: unknown }>;
+    return new Set(rows.flatMap((row) => (typeof row.name === "string" ? [row.name] : [])));
+}
+
+/**
+ * Detect the persisted host schema.
+ *
+ * `session_message` does NOT identify v2: OpenCode 1.18.x ships that table beside `message`
+ * and `part` (verified against a live 1.18.30 store, pinned in this module's tests). Only the
+ * ABSENCE of the v1 message tables identifies a v2 store, so a v1 host is never mistaken for
+ * a v2 one. A store carrying neither is a host that has not written its schema yet.
+ */
+export function detectOpenCodeStoreGeneration(
+    db: OpenCodeStoreSchemaDatabase,
+    schema: "main" | "oc_backfill" = "main",
+): OpenCodeStoreGeneration {
+    const tables = schemaTableNames(db, schema);
+    const hasV1Messages = tables.has("message") && tables.has("part");
+    if (hasV1Messages) return "v1";
+    if (tables.has("session_message")) return "v2";
+    if (tables.has("session") || tables.has("project")) return "v1";
+    return "unknown";
+}
+
+/** Refuse before a generation-specific query can read the other host's schema. */
+export function assertOpenCodeStoreGeneration(
+    db: OpenCodeStoreSchemaDatabase,
+    expected: OpenCodeHostGeneration,
+    path: string,
+    schema: "main" | "oc_backfill" = "main",
+): void {
+    const actual = detectOpenCodeStoreGeneration(db, schema);
+    if (actual === expected) return;
+    // A store with none of these tables has no schema YET — a host that has not written its
+    // first row, or a fresh data directory. That is "nothing to read", not a conflicting host,
+    // and readers have always treated it as empty. Refusing here made every reader throw before
+    // OpenCode created its tables, which is how this guard took down 15 host e2e tests.
+    if (actual === "unknown") return;
+    throw new Error(
+        `OpenCode store generation mismatch at ${path}: expected ${expected}, found ${actual}; refusing generation-specific database access`,
+    );
+}
+
 export function openCodeDbPathExists(
     resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
 ): boolean {