@hraness/oh 0.3.2 → 0.4.1

package/src/operation.ts

@@ -8,6 +8,7 @@ import {
   safeCode,
   type Sha256Hex,
 } from "./canonical";
+import { OhOperationSizeError } from "./errors";
 import { OH_CONTRACT_ID_V1 } from "./ontology";
 import { canonicalKnowledgeGraphChangesV1, OH_GRAPH_LIMITS_V1, type KnowledgeGraphChangeV1 } from "./graph";
 
@@ -58,12 +59,21 @@ function parsePayload(value: unknown): OhOperationPayloadV1 | null {
     : null;
 }
 
-export function createOhOperationV1(input: OhOperationPayloadV1): OhOperationV1 {
+export function createOhOperationV1(
+  input: OhOperationPayloadV1,
+  options: Readonly<{ maximumOperationBytes?: number }> = {},
+): OhOperationV1 {
+  const maximumOperationBytes = options.maximumOperationBytes ?? OH_OPERATION_MAX_BYTES_V1;
+  if (!Number.isSafeInteger(maximumOperationBytes) || maximumOperationBytes < 1
+    || maximumOperationBytes > OH_OPERATION_MAX_BYTES_V1) {
+    throw new TypeError("Invalid Oh operation byte bound.");
+  }
   const payload = parsePayload(input);
   if (payload === null) throw new TypeError("Invalid Oh operation payload.");
   const operation = { ...payload, operationSha256: canonicalSha256(payload) };
-  if (Buffer.byteLength(canonicalJson(operation), "utf8") > OH_OPERATION_MAX_BYTES_V1) {
-    throw new RangeError("Oh operation exceeds its canonical byte limit.");
+  const operationBytes = Buffer.byteLength(canonicalJson(operation), "utf8");
+  if (operationBytes > maximumOperationBytes) {
+    throw new OhOperationSizeError(operationBytes, maximumOperationBytes);
   }
   return operation;
 }

package/src/sqlite/port.test.ts

@@ -1,16 +1,22 @@
 import { afterEach, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
 import { mkdtemp, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
+import { canonicalSha256 } from "../canonical";
 import { createKnowledgeGraphRecordV1 } from "../graph";
+import { createOhOperationV1 } from "../operation";
 import {
   createOhStoreBindingV1,
   OH_CANONICAL_STORE_PROFILE_V1,
   OH_WORKING_STORE_PROFILE_V1,
+  OhConflictError,
   OhProfileError,
   OhPurgedSpaceError,
+  type OhHeadRefV1,
 } from "../store";
+import { createOhSyncBundleV1 } from "../sync";
 import { createOhSqliteStoreAuthorityV1 } from "./port";
 import { OhSqliteStore } from "./store";
 
@@ -115,12 +121,215 @@ describe("promise-based SQLite store port", () => {
     await authority.store.close();
   });
 
+  test("keeps pinned canonical replication on host control", async () => {
+    const authority = createOhSqliteStoreAuthorityV1({ path: ":memory:",
+      profile: OH_CANONICAL_STORE_PROFILE_V1, realmId: "realm:replication", spaceId: "replication" });
+    expect("replication" in authority.store).toBe(false);
+    const replication = authority.host.replication;
+    expect(replication).not.toBeNull();
+    if (replication === null) throw new Error("Expected canonical replication authority.");
+    expect(Object.isFrozen(replication)).toBe(true);
+    const empty = await authority.store.head();
+    const first = await authority.store.commit({ actorId: "host.test", changes: [{ kind: "put",
+      record: entity("entity:first", "First"), v: 1 }], expectedHead: empty,
+      instant: "2026-09-06T01:00:00.000Z", operationId: "op_first" });
+    const second = await authority.store.commit({ actorId: "host.test", changes: [{ kind: "put",
+      record: entity("entity:second", "Second"), v: 1 }], expectedHead: await authority.store.head(),
+      instant: "2026-09-06T01:01:00.000Z", operationId: "op_second" });
+    const pinned = await authority.store.head();
+    await authority.store.commit({ actorId: "host.test", changes: [{ kind: "put",
+      record: entity("entity:third", "Third"), v: 1 }], expectedHead: pinned,
+      instant: "2026-09-06T01:02:00.000Z", operationId: "op_third" });
+
+    const firstPage = await replication.exportBundle({
+      after: { operationSha256: empty.operationSha256, sequence: empty.sequence },
+      limit: 1,
+      through: { operationSha256: pinned.operationSha256, sequence: pinned.sequence },
+    });
+    expect(firstPage.bundle.operations.map(({ operationId }) => operationId)).toEqual(["op_first"]);
+    expect(firstPage).toMatchObject({
+      from: { operationSha256: null, sequence: 0 },
+      hasMore: true,
+      through: pinned,
+      to: { operationSha256: first.operationSha256, sequence: first.sequence },
+      v: 1,
+    });
+    const finalPage = await replication.exportBundle({
+      after: firstPage.to,
+      limit: 1,
+      through: { operationSha256: pinned.operationSha256, sequence: pinned.sequence },
+    });
+    expect(finalPage.bundle.operations.map(({ operationId }) => operationId)).toEqual(["op_second"]);
+    expect(finalPage).toMatchObject({
+      from: { operationSha256: first.operationSha256, sequence: first.sequence },
+      hasMore: false,
+      through: pinned,
+      to: { operationSha256: second.operationSha256, sequence: second.sequence },
+      v: 1,
+    });
+
+    const bundle = await replication.exportBundle({
+      after: { operationSha256: empty.operationSha256, sequence: empty.sequence },
+      through: { operationSha256: pinned.operationSha256, sequence: pinned.sequence },
+    });
+    expect(bundle.bundle.operations.map(({ operationId }) => operationId)).toEqual(["op_first", "op_second"]);
+    expect(bundle.bundle.operations.at(-1)?.operationSha256).toBe(second.operationSha256);
+    expect(bundle.bundle.operations).not.toContainEqual(expect.objectContaining({ operationId: "op_third" }));
+    expect(bundle).toMatchObject({ from: { sequence: 0 }, hasMore: false,
+      through: pinned, to: { sequence: 2 }, v: 1 });
+    await expect(replication.exportBundle({
+      after: { operationSha256: first.operationSha256, sequence: first.sequence },
+      through: { operationSha256: canonicalSha256("wrong through head"), sequence: pinned.sequence },
+    })).rejects.toThrow();
+
+    const working = createOhSqliteStoreAuthorityV1({ path: ":memory:",
+      profile: OH_WORKING_STORE_PROFILE_V1, realmId: "realm:working-replication",
+      spaceId: "working-replication" });
+    expect(working.host.replication).toBeNull();
+    await working.store.close();
+    await authority.store.close();
+  });
+
+  test("imports canonical replication bundles atomically and replays them exactly", async () => {
+    const source = createOhSqliteStoreAuthorityV1({ path: ":memory:",
+      profile: OH_CANONICAL_STORE_PROFILE_V1, realmId: "realm:atomic", spaceId: "atomic" });
+    const targetDatabase = new Database(":memory:", { strict: true });
+    const target = createOhSqliteStoreAuthorityV1({ database: targetDatabase,
+      profile: OH_CANONICAL_STORE_PROFILE_V1, realmId: "realm:atomic", spaceId: "atomic" });
+    const empty = await target.store.head();
+    const first = await source.store.commit({ actorId: "host.test", changes: [{ kind: "put",
+      record: entity("entity:first", "First"), v: 1 }], expectedHead: await source.store.head(),
+      instant: "2026-09-06T02:00:00.000Z", operationId: "op_atomic_first" });
+    const second = await source.store.commit({ actorId: "host.test", changes: [{ kind: "put",
+      record: entity("entity:second", "Second"), v: 1 }], expectedHead: await source.store.head(),
+      instant: "2026-09-06T02:01:00.000Z", operationId: "op_atomic_second" });
+    const { operationSha256: _operationSha256, ...secondPayload } = second;
+    const hostileSecond = createOhOperationV1({
+      ...secondPayload,
+      graphRevisionSha256: canonicalSha256("hostile graph revision"),
+      recordsSha256: canonicalSha256("hostile records"),
+    });
+    const hostile = createOhSyncBundleV1("atomic", [first, hostileSecond]);
+    const targetReplication = target.host.replication;
+    const sourceReplication = source.host.replication;
+    if (targetReplication === null || sourceReplication === null) {
+      throw new Error("Expected canonical replication authority.");
+    }
+    const firstBundle = createOhSyncBundleV1("atomic", [first]);
+    await expect(targetReplication.importBundle({
+      bundle: firstBundle,
+      expectedHead: { operationSha256: null, sequence: -0 },
+    })).rejects.toThrow(TypeError);
+    let rejectedBundleReads = 0;
+    const rejectedBundle = new Proxy({}, {
+      get() { rejectedBundleReads += 1; throw new Error("must not read bundle"); },
+      getOwnPropertyDescriptor() { rejectedBundleReads += 1; throw new Error("must not inspect bundle"); },
+      getPrototypeOf() { rejectedBundleReads += 1; throw new Error("must not inspect bundle"); },
+      ownKeys() { rejectedBundleReads += 1; throw new Error("must not inspect bundle"); },
+    });
+    await expect(targetReplication.importBundle({
+      bundle: rejectedBundle,
+      expectedHead: { operationSha256: null, sequence: -0 },
+    })).rejects.toThrow(TypeError);
+    expect(rejectedBundleReads).toBe(0);
+    let expectedHeadAccessorReads = 0;
+    const accessorExpectedHead = { operationSha256: null } as Record<PropertyKey, unknown>;
+    Object.defineProperty(accessorExpectedHead, "sequence", { enumerable: true,
+      get() { expectedHeadAccessorReads += 1; throw new Error("must not execute"); } });
+    await expect(targetReplication.importBundle({
+      bundle: firstBundle,
+      expectedHead: accessorExpectedHead as OhHeadRefV1,
+    })).rejects.toThrow(TypeError);
+    let expectedHeadProxyReads = 0;
+    const proxyExpectedHead = new Proxy({ operationSha256: null, sequence: 0 } as const, {
+      get() { expectedHeadProxyReads += 1; throw new Error("must not execute"); },
+    });
+    await expect(targetReplication.importBundle({
+      bundle: firstBundle,
+      expectedHead: proxyExpectedHead,
+    })).rejects.toThrow(TypeError);
+    expect(expectedHeadAccessorReads).toBe(0);
+    expect(expectedHeadProxyReads).toBe(0);
+    expect(await target.store.head()).toEqual(empty);
+    await expect(targetReplication.importBundle({
+      bundle: hostile,
+      expectedHead: { operationSha256: empty.operationSha256, sequence: empty.sequence },
+    })).rejects.toThrow("does not reproduce");
+    expect(await target.store.head()).toEqual(empty);
+    expect((await target.store.snapshot()).records).toEqual([]);
+    expect(await target.store.verify()).toMatchObject({ operations: 0, records: 0 });
+    for (const table of ["oh_operations", "oh_operation_records", "oh_records", "oh_dependencies",
+      "oh_search_documents", "oh_search_fts", "oh_sync_outbox"]) {
+      const count = targetDatabase.query<{ count: number }, []>(
+        `SELECT count(*) AS count FROM ${table}`,
+      ).get()?.count;
+      expect(count, table).toBe(0);
+    }
+
+    const sourceHead = await source.store.head();
+    const exact = await sourceReplication.exportBundle({
+      after: { operationSha256: empty.operationSha256, sequence: empty.sequence },
+      through: { operationSha256: sourceHead.operationSha256, sequence: sourceHead.sequence },
+    });
+    expect(await targetReplication.importBundle({
+      bundle: exact.bundle,
+      expectedHead: { operationSha256: empty.operationSha256, sequence: empty.sequence },
+    })).toMatchObject({ head: sourceHead, imported: 2, status: "imported" });
+    expect(await targetReplication.importBundle({
+      bundle: exact.bundle,
+      expectedHead: { operationSha256: empty.operationSha256, sequence: empty.sequence },
+    })).toMatchObject({ head: sourceHead, imported: 0, status: "already-present" });
+
+    const third = await target.store.commit({ actorId: "host.test", changes: [{ kind: "put",
+      record: entity("entity:third", "Third"), v: 1 }], expectedHead: await target.store.head(),
+    instant: "2026-09-06T02:02:00.000Z", operationId: "op_atomic_third" });
+    expect(await targetReplication.importBundle({
+      bundle: exact.bundle,
+      expectedHead: { operationSha256: empty.operationSha256, sequence: empty.sequence },
+    })).toMatchObject({ head: { operationSha256: third.operationSha256, sequence: third.sequence },
+      imported: 0, status: "already-present" });
+
+    const fork = createOhSqliteStoreAuthorityV1({ path: ":memory:",
+      profile: OH_CANONICAL_STORE_PROFILE_V1, realmId: "realm:atomic", spaceId: "atomic" });
+    const forkReplication = fork.host.replication;
+    if (forkReplication === null) throw new Error("Expected fork replication authority.");
+    await forkReplication.importBundle({
+      bundle: createOhSyncBundleV1("atomic", [first]),
+      expectedHead: { operationSha256: empty.operationSha256, sequence: empty.sequence },
+    });
+    const divergent = await fork.store.commit({ actorId: "host.fork", changes: [{ kind: "put",
+      record: entity("entity:fork", "Fork"), v: 1 }], expectedHead: await fork.store.head(),
+    instant: "2026-09-06T02:01:30.000Z", operationId: "op_atomic_fork" });
+    await expect(targetReplication.importBundle({
+      bundle: createOhSyncBundleV1("atomic", [divergent]),
+      expectedHead: { operationSha256: first.operationSha256, sequence: first.sequence },
+    })).rejects.toThrow(OhConflictError);
+    expect(await target.store.head()).toMatchObject({
+      operationSha256: third.operationSha256,
+      sequence: third.sequence,
+    });
+    const history = await target.store.changesSince({ operationSha256: null, sequence: 0 }, {
+      through: { operationSha256: third.operationSha256, sequence: third.sequence },
+    });
+    expect(history.operations.map(({ operationId }) => operationId))
+      .toEqual(["op_atomic_first", "op_atomic_second", "op_atomic_third"]);
+    expect(await target.store.verify()).toMatchObject({ operations: 3, records: 3 });
+
+    await fork.store.close();
+    await target.store.close();
+    await source.store.close();
+  });
+
   test("refuses operation replication for a bound working profile", () => {
     const store = new OhSqliteStore({ path: ":memory:", spaceId: "local-only" });
     store.bind(createOhStoreBindingV1({ profile: OH_WORKING_STORE_PROFILE_V1,
       realmId: "realm:local-only", spaceId: "local-only", v: 1 }));
     expect(() => store.exportOperations()).toThrow(OhProfileError);
     expect(() => store.importOperation({})).toThrow(OhProfileError);
+    expect(() => store.importOperations({
+      expectedHead: { operationSha256: null, sequence: 0 },
+      operations: [],
+    })).toThrow(OhProfileError);
     expect(store.verifyReplay()).toMatchObject({ operations: 0, records: 0 });
     store.close();
   });

package/src/sqlite/port.ts

@@ -1,3 +1,5 @@
+import { isProxy } from "node:util/types";
+
 import { canonicalJson } from "../canonical";
 import {
   createOhStoreBindingV1,
@@ -11,7 +13,6 @@ import {
   type OhHeadV1,
   type OhSnapshotV1,
   type OhSpacePurgeReceiptV1,
-  type OhStoreAuthorityV1,
   type OhStoreBindingV1,
   type OhStoreHostControlV1,
   type OhStoreProfileV1,
@@ -19,8 +20,17 @@ import {
   type OhStoreVerificationV1,
 } from "../store";
 import type { OhOperationV1 } from "../operation";
+import {
+  createOhSyncBundleV1,
+  parseOhSyncBundleV1,
+  parseOhSyncHeadRefV1,
+  type OhSyncBundleV1,
+} from "../sync";
 import type { OhSqliteDatabase } from "./driver";
-import { OhSqliteStore } from "./store";
+import {
+  OhSqliteStore,
+  type OhOperationImportResultV1,
+} from "./store";
 
 export type OhSqliteStoreAuthorityOptionsV1 = Readonly<{
   database?: OhSqliteDatabase;
@@ -30,6 +40,59 @@ export type OhSqliteStoreAuthorityOptionsV1 = Readonly<{
   spaceId?: string;
 }>;
 
+export interface OhSqliteCanonicalReplicationV1 {
+  readonly binding: OhStoreBindingV1;
+  exportBundle(input: Readonly<{
+    after: OhHeadRefV1;
+    limit?: number;
+    through: OhHeadRefV1;
+  }>): Promise<Readonly<{
+    bundle: OhSyncBundleV1;
+    from: OhChangesPageV1["from"];
+    hasMore: boolean;
+    through: OhChangesPageV1["through"];
+    to: OhChangesPageV1["to"];
+    v: 1;
+  }>>;
+  head(): Promise<OhHeadV1>;
+  importBundle(input: Readonly<{
+    bundle: unknown;
+    expectedHead: OhHeadRefV1;
+  }>): Promise<OhOperationImportResultV1>;
+}
+
+export interface OhSqliteStoreHostControlV1 extends OhStoreHostControlV1 {
+  readonly replication: OhSqliteCanonicalReplicationV1 | null;
+}
+
+export type OhSqliteStoreAuthorityV1 = Readonly<{
+  host: OhSqliteStoreHostControlV1;
+  store: OhStoreV1;
+}>;
+
+function exactReplicationImportInputV1(value: unknown): Readonly<{
+  bundle: unknown;
+  expectedHead: unknown;
+}> | null {
+  try {
+    if (typeof value !== "object" || value === null || Array.isArray(value) || isProxy(value)) return null;
+    const prototype = Object.getPrototypeOf(value);
+    const keys = Reflect.ownKeys(value);
+    if ((prototype !== Object.prototype && prototype !== null)
+      || keys.length !== 2 || !keys.includes("bundle") || !keys.includes("expectedHead")
+      || keys.some((key) => typeof key !== "string")) return null;
+    const bundle = Object.getOwnPropertyDescriptor(value, "bundle");
+    const expectedHead = Object.getOwnPropertyDescriptor(value, "expectedHead");
+    if (bundle === undefined || expectedHead === undefined
+      || !bundle.enumerable || !expectedHead.enumerable
+      || bundle.get !== undefined || bundle.set !== undefined
+      || expectedHead.get !== undefined || expectedHead.set !== undefined) return null;
+    return { bundle: bundle.value, expectedHead: expectedHead.value };
+  } catch {
+    return null;
+  }
+}
+
 export class OhSqliteStorePortV1 implements OhStoreV1 {
   readonly binding: OhStoreBindingV1;
   readonly #authority: OhSqliteStore;
@@ -91,7 +154,7 @@ export class OhSqliteStorePortV1 implements OhStoreV1 {
  */
 export function createOhSqliteStoreAuthorityV1(
   options: OhSqliteStoreAuthorityOptionsV1 = {},
-): OhStoreAuthorityV1 {
+): OhSqliteStoreAuthorityV1 {
   const profile = parseOhStoreProfileV1(options.profile ?? OH_CANONICAL_STORE_PROFILE_V1);
   if (profile === null) throw new TypeError("Invalid SQLite store profile.");
   const spaceId = options.spaceId ?? "default";
@@ -104,7 +167,57 @@ export function createOhSqliteStoreAuthorityV1(
   });
   const store = new OhSqliteStorePortV1(authority, binding);
   let purge: OhSpacePurgeReceiptV1 | null = null;
-  const host: OhStoreHostControlV1 = Object.freeze({
+  const replication: OhSqliteCanonicalReplicationV1 | null =
+    profile.capabilities.operationReplication
+      ? Object.freeze({
+          binding,
+          exportBundle: async (input: Readonly<{
+            after: OhHeadRefV1;
+            limit?: number;
+            through: OhHeadRefV1;
+          }>) => {
+            const page = authority.changesSince(input.after, {
+              ...(input.limit === undefined ? {} : { limit: input.limit }),
+              through: input.through,
+            });
+            const bundle = createOhSyncBundleV1(binding.spaceId, page.operations, {
+              largestFittingPrefix: true,
+            });
+            const last = bundle.operations.at(-1);
+            return Object.freeze({
+              bundle,
+              from: page.from,
+              hasMore: page.hasMore || bundle.operations.length < page.operations.length,
+              through: page.through,
+              to: last === undefined ? page.from : {
+                operationSha256: last.operationSha256,
+                sequence: last.sequence,
+              },
+              v: 1 as const,
+            });
+          },
+          head: async () => authority.head(),
+          importBundle: async (input: Readonly<{
+            bundle: unknown;
+            expectedHead: OhHeadRefV1;
+          }>) => {
+            const request = exactReplicationImportInputV1(input);
+            const expectedHead = request === null ? null : parseOhSyncHeadRefV1(request.expectedHead);
+            if (request === null || expectedHead === null) {
+              throw new TypeError("Invalid canonical replication request.");
+            }
+            const bundle = parseOhSyncBundleV1(request.bundle);
+            if (bundle === null || bundle.spaceId !== binding.spaceId) {
+              throw new TypeError("Invalid canonical replication bundle.");
+            }
+            return authority.importOperations({
+              expectedHead,
+              operations: bundle.operations,
+            });
+          },
+        })
+      : null;
+  const host: OhSqliteStoreHostControlV1 = Object.freeze({
     binding,
     purgeWorkingSpace: async (input: Readonly<{ purgedAt?: string }>) => {
       if (profile.profileKind !== "working" || !profile.capabilities.wholeSpacePurge) {
@@ -115,6 +228,7 @@ export function createOhSqliteStoreAuthorityV1(
       authority.close();
       return purge;
     },
+    replication,
   });
   return Object.freeze({ host, store });
 }

package/src/sqlite/store.test.ts

@@ -3,9 +3,12 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
+import { canonicalJson, canonicalSha256 } from "../canonical";
 import { createKnowledgeGraphRecordV1 } from "../graph";
+import { createOhOperationV1 } from "../operation";
 import { createOhStoreBindingV1, OH_WORKING_STORE_PROFILE_V1 } from "../store";
-import { OhConflictError, OhDependencyError, OhIntegrityError, OhSqliteStore } from "./store";
+import { OhConflictError, OhDependencyError, OhIntegrityError, OhOperationSizeError,
+  OhSqliteStore } from "./store";
 
 const roots: string[] = [];
 afterEach(async () => {
@@ -64,6 +67,40 @@ describe("Oh SQLite authority", () => {
     store.close();
   });
 
+  test("uses a distinct precommit error for host-declared operation byte bounds", () => {
+    const store = new OhSqliteStore({ path: ":memory:" });
+    const empty = store.head();
+    const changes = [{ kind: "put" as const,
+      record: record("entity:bounded", "Bounded"), v: 1 as const }];
+    const first = store.commit({ actorId: "agent.test", changes, expectedHead: empty,
+      operationId: "op_bounded_first" });
+    expect(() => store.commit({ actorId: "agent.test", changes, expectedHead: empty,
+      maximumOperationBytes: 1, operationId: "op_bounded_first" }))
+      .toThrow(OhOperationSizeError);
+    expect(() => store.commit({ actorId: "agent.test", changes: [{ kind: "put",
+      record: record("entity:rejected", "Rejected"), v: 1 }], expectedHead: store.head(),
+    maximumOperationBytes: 1, operationId: "op_bounded_rejected" }))
+      .toThrow(OhOperationSizeError);
+    expect(new OhOperationSizeError(2, 1)).toBeInstanceOf(RangeError);
+    expect(store.head()).toMatchObject({ operationSha256: first.operationSha256, sequence: 1 });
+    expect(store.exportOperations().map(({ operationId }) => operationId)).toEqual(["op_bounded_first"]);
+    expect(store.snapshotRecords().map(({ key }) => key)).toEqual(["entity:bounded"]);
+    store.close();
+  });
+
+  test("rejects copied size-error fields without a native branded error", () => {
+    const copied = Object.create(RangeError.prototype) as Record<PropertyKey, unknown>;
+    Object.defineProperties(copied, {
+      [Symbol.for("@hraness/oh/OhOperationSizeError/v1")]: {
+        configurable: false, value: true, writable: false,
+      },
+      code: { configurable: false, value: "oh.operation-size.v1", writable: false },
+      maximumOperationBytes: { configurable: false, value: 1, writable: false },
+      operationBytes: { configurable: false, value: 2, writable: false },
+    });
+    expect(copied instanceof OhOperationSizeError).toBe(false);
+  });
+
   test("rejects orphaned and cross-space rows as idempotent operations", () => {
     const changes = [{ kind: "put" as const, record: record("entity:orphan", "Orphan"), v: 1 as const }];
     const source = new OhSqliteStore({ path: ":memory:", spaceId: "orphan-target" });
@@ -181,6 +218,74 @@ describe("Oh SQLite authority", () => {
     store.close();
   });
 
+  test("verifies foreign keys and exact search materializations", () => {
+    const store = new OhSqliteStore({ path: ":memory:", spaceId: "search-integrity" });
+    store.commit({ actorId: "agent.test", changes: [{ kind: "put",
+      record: record("entity:a", "A"), v: 1 }], expectedHead: store.head(), operationId: "op_search" });
+    const document = store.database.query<{ text: string }, [string, string]>(
+      "SELECT text FROM oh_search_documents WHERE space_id = ? AND record_key = ?",
+    ).get(store.spaceId, "entity:a");
+    if (document === null) throw new Error("Expected materialized search document.");
+    store.database.query("UPDATE oh_search_documents SET text = ? WHERE space_id = ? AND record_key = ?")
+      .run("tampered", store.spaceId, "entity:a");
+    expect(() => store.verifyReplay()).toThrow("Materialized search documents");
+    store.database.query("UPDATE oh_search_documents SET text = ? WHERE space_id = ? AND record_key = ?")
+      .run(document.text, store.spaceId, "entity:a");
+    store.database.query(`INSERT INTO oh_search_fts(space_id, record_key, text)
+      SELECT space_id, record_key, text FROM oh_search_fts WHERE space_id = ? AND record_key = ?`)
+      .run(store.spaceId, "entity:a");
+    expect(() => store.verifyReplay()).toThrow("Materialized full-text search rows");
+    store.database.query("DELETE FROM oh_search_fts WHERE rowid = (SELECT max(rowid) FROM oh_search_fts)").run();
+    store.database.exec("PRAGMA foreign_keys = OFF");
+    store.database.query(`INSERT INTO oh_sync_state(remote_id, space_id, pulled_sequence,
+      pushed_sequence, remote_head_sha256, updated_at) VALUES (?, ?, 0, 0, NULL, ?)`)
+      .run("remote.alien", "alien-space", "2026-09-06T12:00:00.000Z");
+    store.database.exec("PRAGMA foreign_keys = ON");
+    expect(() => store.verifyReplay()).toThrow("foreign_key_check");
+    store.close();
+  });
+
+  test("rejects an exact replay prefix disconnected from the current authority head", () => {
+    const store = new OhSqliteStore({ path: ":memory:", spaceId: "replay-tail-integrity" });
+    const operations = [1, 2, 3].map((index) => store.commit({ actorId: "agent.test",
+      changes: [{ kind: "put", record: record(`entity:${index}`, `Entity ${index}`), v: 1 }],
+      expectedHead: store.head(), instant: `2026-09-06T12:0${index}:00.000Z`,
+      operationId: `op_tail_${index}` }));
+    const third = operations[2]!;
+    const { operationSha256: _operationSha256, ...thirdPayload } = third;
+    const disconnected = createOhOperationV1({
+      ...thirdPayload,
+      parentOperationSha256: canonicalSha256("disconnected parent"),
+    });
+    store.database.query(`UPDATE oh_operations SET operation_json = ?
+      WHERE space_id = ? AND sequence = 3`).run(canonicalJson(disconnected), store.spaceId);
+    expect(() => store.importOperations({
+      expectedHead: { operationSha256: null, sequence: 0 },
+      operations: operations.slice(0, 2),
+    })).toThrow(OhIntegrityError);
+    store.database.query(`UPDATE oh_operations SET operation_json = ?
+      WHERE space_id = ? AND sequence = 3`).run(canonicalJson(third), store.spaceId);
+    store.database.exec("PRAGMA foreign_keys = OFF");
+    store.database.query(`UPDATE oh_operation_records SET operation_sha256 = ?
+      WHERE operation_sha256 = ?`).run(disconnected.operationSha256, third.operationSha256);
+    store.database.query(`UPDATE oh_records SET operation_sha256 = ?
+      WHERE operation_sha256 = ?`).run(disconnected.operationSha256, third.operationSha256);
+    store.database.query(`UPDATE oh_sync_outbox SET operation_sha256 = ?
+      WHERE operation_sha256 = ?`).run(disconnected.operationSha256, third.operationSha256);
+    store.database.query(`UPDATE oh_operations SET operation_sha256 = ?, parent_operation_sha256 = ?,
+      operation_json = ? WHERE space_id = ? AND sequence = 3`).run(disconnected.operationSha256,
+      disconnected.parentOperationSha256, canonicalJson(disconnected), store.spaceId);
+    store.database.query("UPDATE oh_spaces SET head_operation_sha256 = ? WHERE space_id = ?")
+      .run(disconnected.operationSha256, store.spaceId);
+    store.database.exec("PRAGMA foreign_keys = ON");
+    expect(store.database.query<Record<string, unknown>, []>("PRAGMA foreign_key_check").all()).toEqual([]);
+    expect(() => store.importOperations({
+      expectedHead: { operationSha256: null, sequence: 0 },
+      operations: operations.slice(0, 2),
+    })).toThrow(OhIntegrityError);
+    store.close();
+  });
+
   test("verifies duplicated operation columns against canonical envelopes", () => {
     const store = new OhSqliteStore({ path: ":memory:" });
     store.commit({ actorId: "agent.test", changes: [{ kind: "put",