@hraness/oh 0.3.1 → 0.4.0

package/spec/v2/libsql-semantic-cache-schema-v2.sql

@@ -0,0 +1,175 @@
+CREATE TABLE IF NOT EXISTS oh_semantic_schemas (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  schema_sha256 TEXT NOT NULL,
+  applied_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_isolations (
+    isolation_sha256 TEXT PRIMARY KEY,
+    authority_id TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_vectors (
+    isolation_sha256 TEXT NOT NULL,
+    profile_sha256 TEXT NOT NULL,
+    renderer_sha256 TEXT NOT NULL,
+    input_sha256 TEXT NOT NULL,
+    vector_sha256 TEXT NOT NULL,
+    vector BLOB NOT NULL,
+    created_at TEXT NOT NULL,
+    PRIMARY KEY(isolation_sha256, profile_sha256, renderer_sha256, input_sha256)
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_generations (
+    authority_id TEXT NOT NULL,
+    generation INTEGER NOT NULL CHECK(generation >= 0),
+    authority_sha256 TEXT NOT NULL,
+    isolation_sha256 TEXT NOT NULL,
+    profile_sha256 TEXT NOT NULL,
+    renderer_sha256 TEXT NOT NULL,
+    membership_sha256 TEXT NOT NULL,
+    generation_sha256 TEXT NOT NULL UNIQUE,
+    document_count INTEGER NOT NULL CHECK(document_count >= 0),
+    chunk_count INTEGER NOT NULL CHECK(chunk_count >= 0),
+    created_at TEXT NOT NULL,
+    PRIMARY KEY(authority_id, generation)
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_memberships (
+    authority_id TEXT NOT NULL,
+    generation INTEGER NOT NULL CHECK(generation >= 0),
+    generation_sha256 TEXT NOT NULL,
+    isolation_sha256 TEXT NOT NULL,
+    record_key TEXT NOT NULL,
+    record_sha256 TEXT NOT NULL,
+    ordinal INTEGER NOT NULL CHECK(ordinal >= 0),
+    input_sha256 TEXT NOT NULL,
+    PRIMARY KEY(authority_id, generation, record_key, ordinal)
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_heads (
+    authority_id TEXT PRIMARY KEY,
+    generation INTEGER NOT NULL CHECK(generation >= 0),
+    authority_sha256 TEXT NOT NULL,
+    isolation_sha256 TEXT NOT NULL,
+    profile_sha256 TEXT NOT NULL,
+    renderer_sha256 TEXT NOT NULL,
+    membership_sha256 TEXT NOT NULL,
+    generation_sha256 TEXT NOT NULL,
+    published_at TEXT NOT NULL
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_purges (
+    authority_id TEXT PRIMARY KEY,
+    isolation_sha256 TEXT NOT NULL,
+    profile_sha256 TEXT NOT NULL,
+    published_generation INTEGER CHECK(published_generation IS NULL OR published_generation >= 0),
+    published_generation_sha256 TEXT,
+    purged_at TEXT NOT NULL,
+    purge_marker_sha256 TEXT NOT NULL,
+    generation_count INTEGER NOT NULL CHECK(generation_count >= 0),
+    membership_count INTEGER NOT NULL CHECK(membership_count >= 0),
+    orphan_vector_count INTEGER NOT NULL CHECK(orphan_vector_count >= 0),
+    isolation_scope_count INTEGER NOT NULL CHECK(isolation_scope_count >= 0),
+    counts_recorded INTEGER NOT NULL CHECK(counts_recorded IN (0, 1))
+  ) STRICT;
+
+CREATE INDEX IF NOT EXISTS oh_semantic_isolations_authority
+    ON oh_semantic_isolations(authority_id, isolation_sha256);
+
+CREATE INDEX IF NOT EXISTS oh_semantic_memberships_generation
+    ON oh_semantic_memberships(authority_id, generation, record_key, ordinal);
+
+CREATE INDEX IF NOT EXISTS oh_semantic_memberships_input
+    ON oh_semantic_memberships(isolation_sha256, input_sha256);
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_isolations_no_update
+    BEFORE UPDATE ON oh_semantic_isolations
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic isolations are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_isolations_no_delete
+    BEFORE DELETE ON oh_semantic_isolations
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic isolations are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_isolations_purge_guard
+    BEFORE INSERT ON oh_semantic_isolations
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority was purged'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_vectors_no_update
+    BEFORE UPDATE ON oh_semantic_vectors
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic vectors are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_vectors_isolation_guard
+    BEFORE INSERT ON oh_semantic_vectors
+    WHEN NOT EXISTS (SELECT 1 FROM oh_semantic_isolations
+      WHERE isolation_sha256 = NEW.isolation_sha256)
+      OR EXISTS (SELECT 1 FROM oh_semantic_purges AS purge
+        JOIN oh_semantic_isolations AS isolation
+          ON isolation.authority_id = purge.authority_id
+        WHERE isolation.isolation_sha256 = NEW.isolation_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic vector isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_generations_no_update
+    BEFORE UPDATE ON oh_semantic_generations
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic generations are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_no_update
+    BEFORE UPDATE ON oh_semantic_memberships
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic memberships are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_generations_purge_guard
+    BEFORE INSERT ON oh_semantic_generations
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+      OR NOT EXISTS (SELECT 1 FROM oh_semantic_isolations
+        WHERE isolation_sha256 = NEW.isolation_sha256 AND authority_id = NEW.authority_id)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority or isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_purge_guard
+    BEFORE INSERT ON oh_semantic_memberships
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+      OR NOT EXISTS (SELECT 1 FROM oh_semantic_generations
+        WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+          AND generation_sha256 = NEW.generation_sha256
+          AND isolation_sha256 = NEW.isolation_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority or isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_published_guard
+    BEFORE INSERT ON oh_semantic_memberships
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_heads
+      WHERE authority_id = NEW.authority_id AND generation = NEW.generation)
+      AND NOT EXISTS (SELECT 1 FROM oh_semantic_memberships
+        WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+          AND generation_sha256 = NEW.generation_sha256
+          AND isolation_sha256 = NEW.isolation_sha256
+          AND record_key = NEW.record_key AND record_sha256 = NEW.record_sha256
+          AND ordinal = NEW.ordinal AND input_sha256 = NEW.input_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic generation is published'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_heads_insert_purge_guard
+    BEFORE INSERT ON oh_semantic_heads
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+      OR NOT EXISTS (SELECT 1 FROM oh_semantic_generations
+        WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+          AND generation_sha256 = NEW.generation_sha256
+          AND isolation_sha256 = NEW.isolation_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority or isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_heads_update_purge_guard
+    BEFORE UPDATE ON oh_semantic_heads
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+      OR NOT EXISTS (SELECT 1 FROM oh_semantic_generations
+        WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+          AND generation_sha256 = NEW.generation_sha256
+          AND isolation_sha256 = NEW.isolation_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority or isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_purges_no_update
+    BEFORE UPDATE ON oh_semantic_purges
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic purge markers are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_purges_no_delete
+    BEFORE DELETE ON oh_semantic_purges
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic purge markers are immutable'); END;

package/spec/v2/libsql-semantic-digest-fixture-v2.json

@@ -0,0 +1,14 @@
+{
+  "authorityId": "fixture:semantic-authority",
+  "authoritySha256": "d1eac8dd93ce6e04cb1316c670008250b98ec32cb0555f21d10b782ddffe03a7",
+  "content": "fixture body",
+  "generation": 7,
+  "generationSha256": "5d848fcd482ca72781af87da7b2ff3f68cd5b9ef571495bc734a5a2582c719d1",
+  "inputSha256": "b2309e89dd3f903934c7b5f4a4c8c51d5323d84a66928a2f017dd871492ef294",
+  "isolationSha256": "217df103dc50da7d3ba2883d9c1cbad01014b2b9eb20e4f94f737291c583d9a5",
+  "membershipSha256": "73ec3fcf8af17d99e2ae84878329c834e044bb47ff08ecd0dca6a596504b26b8",
+  "recordKey": "memory:fixture",
+  "recordSha256": "920d936e47e8f3cc5847017da5975ef73f8d84c04cb113880fb10575eeb614f9",
+  "title": "fixture title",
+  "v": 2
+}

package/spec/v2/manifest.json

@@ -0,0 +1,11 @@
+{
+  "cacheSchema": "./libsql-semantic-cache-schema-v2.sql",
+  "cacheSchemaSha256": "679edfc3cb02dc768843976093f90d5879d53e84b797ac60d77956a634facae9",
+  "digestFixture": "./libsql-semantic-digest-fixture-v2.json",
+  "id": "oh.semantic-cloud.v2",
+  "legacyCacheSchema": "../v1/libsql-semantic-cache-schema-v1.sql",
+  "profile": "../v1/cloudflare-embedding-profile.json",
+  "renderer": "../v1/cloudflare-embedding-renderer.json",
+  "specification": "./semantic-cloud.md",
+  "v": 2
+}

package/spec/v2/semantic-cloud.md

@@ -0,0 +1,106 @@
+# Hosted semantic cache V2
+
+Hosted semantic-cache V2 is the isolated successor to the immutable
+[semantic-cache V1 contract](../v1/semantic-cloud.md). It keeps the same fixed
+Cloudflare EmbeddingGemma profile and renderer, but changes only the rebuildable
+libSQL cache protocol. It does not change an Oh graph, record, operation, local
+embedding, or provider contract.
+
+Applications use `bootstrapOhLibSqlSemanticCacheV2` and
+`openOhLibSqlSemanticCacheV2`. The parallel
+`bootstrapOhLibSqlSemanticCacheV1`, `openOhLibSqlSemanticCacheV1`, V1 types,
+V1 result values, and V1 digest preimages remain the released V1 behavior. V1
+and V2 use the same physical table names and therefore cannot be open in one
+database simultaneously. A V1 database can be upgraded to V2; a V2 database
+cannot be opened as V1 or downgraded.
+
+The host MUST quiesce V1 stage, publish, head, and search traffic before
+upgrade. An already-open V1 object is not a V2 runtime capability. Bootstrap
+does, however, arbitrate a racing V1 purge: a purge committed before transition
+custody is copied, while a purge that reaches the changed schema cannot report
+success.
+
+## Isolation and identity
+
+Every V2 authority reference and every stage, publish, head, search, receipt,
+and purge operation binds an `isolationSha256`. It is a validated opaque
+SHA-256 supplied by the host. Private hosts SHOULD derive it from their private
+authority handle, cache epoch, and exact cache profile. When omitted, Oh derives:
+
+```json
+{"authorityId":"<authority>","kind":"oh.semantic-authority-isolation.v2","v":2}
+```
+
+and hashes the canonical JSON. One isolation belongs immutably to one authority,
+while one authority may reserve multiple isolation epochs. The digest never
+enters renderer or provider text.
+
+Vector primary identity is
+`(isolation_sha256, profile_sha256, renderer_sha256, input_sha256)`.
+Generations, memberships, and published heads retain the isolation explicitly.
+The membership digest hashes a canonical
+`oh.semantic-membership.v2` envelope; the generation digest hashes an
+`oh.semantic-generation.v2` envelope. Consequently identical rendered text in
+different authorities or epochs is embedded and stored independently. Isolation
+prevents reuse and deletion coupling; it is not encryption and a database holder
+can still observe equal raw input digests or vector bytes.
+
+All public V2 values use `v: 2`. Provider and renderer values remain V1 because
+those fixed contracts did not change.
+
+## Published reads and purge custody
+
+`publishedHead` returns `null` for an isolation mismatch. Search checks the
+same isolation before sending a query to the provider and again while reading
+memberships. Publish requires the staged generation's exact isolation.
+
+`purgeAuthority` accepts the current published isolation, writes the permanent
+authority tombstone, deletes every generation and membership for the authority,
+and deletes every vector in every isolation reserved by it. A mismatched current
+isolation is a conflict and authorizes no deletion. The receipt records the
+first execution's counts and returns them unchanged on replay. It contains
+`purgeMarkerSha256`, the canonical
+`oh.semantic-purge-receipt.v2` `purgeReceiptSha256`, and zero
+`residualGenerations`, `residualMemberships`, and
+`residualScopedVectors`. `purgeReceipt` replays the same content-free proof
+without issuing deletes.
+
+## V1-to-V2 transition
+
+Bootstrap recognizes only the exact published V1 inventory or the exact V2
+inventory. An upgrade first starts one atomic write transaction that:
+
+1. creates `oh_semantic_v1_purge_transition`;
+2. copies every V1 authority tombstone into it with one database-side
+   `INSERT ... SELECT`;
+3. only after that copy, drops the unsafe globally deduplicated V1 derived rows;
+   and
+4. creates the V2 schema without a V2 schema marker.
+
+The copy has no lifetime tombstone cap and returns no unbounded row set to the
+host. A concurrent V1 purge either commits before this transaction and is copied,
+or runs afterward against a non-V1 schema and cannot report success. Concurrent
+V2 bootstraps converge on the one transition table.
+
+While the transition table exists, `openOhLibSqlSemanticCacheV2` fails closed.
+Bootstrap reads transition rows in fixed pages. Each page atomically creates the
+V2 isolation and receipt for every legacy tombstone and deletes a transition row
+only when the complete computed V2 custody record exists. A crash before a page
+commit changes nothing; a crash after commit can replay safely. Live V1 heads,
+generations, memberships, and vectors are deliberately invalidated because their
+global vector identity cannot be assigned a private owner after the fact.
+
+Finalization inserts the exact V2 schema marker only when the transition table
+is empty, then drops that table in the same transaction. Until that commit,
+neither a partially projected database nor a V2 runtime is accepted. Legacy
+receipts use `countsRecorded: false`; new V2 purges use
+`countsRecorded: true`.
+
+The exact standalone schemas are
+[revision 1](../v1/libsql-semantic-cache-schema-v1.sql) and
+[revision 2](libsql-semantic-cache-schema-v2.sql). Fixed
+[V1](../v1/libsql-semantic-digest-fixture-v1.json) and
+[V2](libsql-semantic-digest-fixture-v2.json) fixtures make the incompatible
+digest domains explicit. Hosted failure remains a
+missing derived retrieval lane and MUST NOT weaken exact graph or Datalog
+operations.

package/src/cli.test.ts

@@ -1,9 +1,15 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { existsSync } from "node:fs";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, truncate, writeFile } 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 { OhSqliteStore } from "./sqlite/store";
+import { createOhSyncBundleV1, OH_SYNC_BUNDLE_MAX_BYTES_V1 } from "./sync";
+
 const roots: string[] = [];
 const CLI_PATH = join(import.meta.dir, "cli.ts");
 const REPOSITORY_ROOT = join(import.meta.dir, "..");
@@ -100,4 +106,50 @@ describe("oh CLI", () => {
     expect((await run(["contract", "--db", database, "--space", "contract.test"], root)).code).toBe(0);
     expect(existsSync(database)).toBe(false);
   });
+
+  test("imports a sync bundle atomically when a later operation is invalid", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-cli-atomic-import-test-"));
+    roots.push(root);
+    const database = join(root, "target.sqlite");
+    const bundlePath = join(root, "hostile-bundle.json");
+    const source = new OhSqliteStore({ path: ":memory:" });
+    const entity = (key: string, name: string) => createKnowledgeGraphRecordV1({
+      dependencies: [], key, kind: "entity", v: 1, value: { name },
+    });
+    source.commit({ actorId: "agent.test", changes: [{ kind: "put",
+      record: entity("entity:first", "First"), v: 1 }], expectedHead: source.head(),
+    operationId: "op_first" });
+    source.commit({ actorId: "agent.test", changes: [{ kind: "put",
+      record: entity("entity:second", "Second"), v: 1 }], expectedHead: source.head(),
+    operationId: "op_second" });
+    const [first, second] = source.exportOperations();
+    if (first === undefined || second === undefined) throw new Error("Expected two operations.");
+    const { operationSha256: _operationSha256, ...payload } = second;
+    const hostileSecond = createOhOperationV1({ ...payload,
+      graphRevisionSha256: canonicalSha256("hostile graph revision"),
+      recordsSha256: canonicalSha256("hostile records") });
+    await writeFile(bundlePath,
+      canonicalJson(createOhSyncBundleV1(source.spaceId, [first, hostileSecond])), "utf8");
+    source.close();
+
+    const imported = await run(["sync", "import", "--db", database, "--file", bundlePath]);
+    expect(imported.code).toBe(1);
+    expect(imported.stderr).toContain("does not reproduce");
+    const verified = await run(["verify", "--db", database]);
+    expect(verified.code).toBe(0);
+    expect(JSON.parse(verified.stdout)).toMatchObject({ operations: 0, records: 0 });
+  });
+
+  test("rejects an oversized sparse sync bundle before opening the database", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-cli-bounded-import-test-"));
+    roots.push(root);
+    const database = join(root, "target.sqlite");
+    const bundlePath = join(root, "oversized-bundle.json");
+    await writeFile(bundlePath, "", "utf8");
+    await truncate(bundlePath, OH_SYNC_BUNDLE_MAX_BYTES_V1 + 2);
+    const imported = await run(["sync", "import", "--db", database, "--file", bundlePath]);
+    expect(imported.code).toBe(1);
+    expect(imported.stderr).toContain("regular file of at most");
+    expect(existsSync(database)).toBe(false);
+  });
 });

package/src/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { readFile } from "node:fs/promises";
+import { lstat, readFile } from "node:fs/promises";
 
 import { canonicalJson, opaqueId, safeCode, type JsonValue } from "./canonical";
 import { OH_CONTRACT_MANIFEST_V1 } from "./contract";
@@ -7,9 +7,9 @@ import { OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1, createKnowledgeGraphRecordV1,
   type KnowledgeGraphRecordKindV1, type KnowledgeGraphRecordV1 } from "./graph";
 import { Oh } from "./sdk";
 import { OH_SQLITE_SCHEMA_VERSION } from "./sqlite/migrations";
-import { createOhSyncBundleV1, parseOhSyncBundleV1 } from "./sync";
+import { createOhSyncBundleV1, OH_SYNC_BUNDLE_MAX_BYTES_V1, parseOhSyncBundleV1 } from "./sync";
 
-export const OH_PACKAGE_VERSION = "0.3.1" as const;
+export const OH_PACKAGE_VERSION = "0.4.0" as const;
 
 type ParsedArguments = { options: Map<string, string[]>; positionals: string[] };
 type ValidatedInvocation = Readonly<{
@@ -174,7 +174,7 @@ async function validateInvocation(command: string, parsed: ParsedArguments): Pro
       assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, "file"]);
       const file = one(parsed, "file");
       if (file === undefined) throw new TypeError("sync import needs --file.");
-      syncBundle = parseOhSyncBundleV1(JSON.parse(await readFile(file, "utf8")));
+      syncBundle = parseOhSyncBundleV1(await readSyncBundleFile(file));
       if (syncBundle === null) throw new TypeError("Invalid sync bundle.");
     } else {
       throw new TypeError("sync needs export or import.");
@@ -191,6 +191,21 @@ async function validateInvocation(command: string, parsed: ParsedArguments): Pro
 
 function print(value: unknown): void { process.stdout.write(`${canonicalJson(value)}\n`); }
 
+async function readSyncBundleFile(path: string): Promise<unknown> {
+  // `sync export` writes one terminal LF after the bounded canonical bundle.
+  const maximumFileBytes = OH_SYNC_BUNDLE_MAX_BYTES_V1 + 1;
+  const metadata = await lstat(path);
+  if (!metadata.isFile() || !Number.isSafeInteger(metadata.size)
+    || metadata.size > maximumFileBytes) {
+    throw new RangeError(`Sync bundle file must be a regular file of at most ${maximumFileBytes} bytes.`);
+  }
+  const contents = await readFile(path);
+  if (contents.byteLength > maximumFileBytes) {
+    throw new RangeError(`Sync bundle file must be at most ${maximumFileBytes} bytes.`);
+  }
+  return JSON.parse(contents.toString("utf8")) as unknown;
+}
+
 const HELP = `oh ${OH_PACKAGE_VERSION}
 
 Usage:
@@ -283,14 +298,25 @@ export async function runOhCli(arguments_: readonly string[]): Promise<number> {
       if (action === "export") {
         const after = integer(one(parsed, "after"), "after") ?? 0;
         const limit = integer(one(parsed, "limit"), "limit") ?? 1000;
-        print(createOhSyncBundleV1(oh.store.spaceId, oh.store.exportOperations(after, limit))); return 0;
+        print(createOhSyncBundleV1(oh.store.spaceId, oh.store.exportOperations(after, limit), {
+          largestFittingPrefix: true,
+        })); return 0;
       }
       if (action === "import") {
         const bundle = validated.syncBundle;
         if (bundle === null) throw new TypeError("Invalid prepared sync import command.");
-        let imported = 0;
-        for (const operation of bundle.operations) if (oh.store.importOperation(operation).imported) imported += 1;
-        print({ head: oh.head(), imported, v: 1 }); return 0;
+        const first = bundle.operations[0];
+        if (first === undefined) {
+          print({ head: oh.head(), imported: 0, v: 1 }); return 0;
+        }
+        const imported = oh.store.importOperations({
+          expectedHead: {
+            operationSha256: first.parentOperationSha256,
+            sequence: first.sequence - 1,
+          },
+          operations: bundle.operations,
+        });
+        print({ head: imported.head, imported: imported.imported, v: 1 }); return 0;
       }
       throw new TypeError("sync needs export or import.");
     }

package/src/errors.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isOhConflictError,
+  isOhDependencyError,
+  isOhIntegrityError,
+  isOhOperationSizeError,
+  isOhProfileError,
+  OhConflictError,
+  OhDependencyError,
+  OhIntegrityError,
+  OhOperationSizeError,
+  OhProfileError,
+} from "./errors";
+
+const CORE_ERRORS = [
+  {
+    brand: "@hraness/oh/OhConflictError/v1",
+    ErrorClass: OhConflictError,
+    guard: isOhConflictError,
+    name: "OhConflictError",
+  },
+  {
+    brand: "@hraness/oh/OhIntegrityError/v1",
+    ErrorClass: OhIntegrityError,
+    guard: isOhIntegrityError,
+    name: "OhIntegrityError",
+  },
+  {
+    brand: "@hraness/oh/OhDependencyError/v1",
+    ErrorClass: OhDependencyError,
+    guard: isOhDependencyError,
+    name: "OhDependencyError",
+  },
+  {
+    brand: "@hraness/oh/OhProfileError/v1",
+    ErrorClass: OhProfileError,
+    guard: isOhProfileError,
+    name: "OhProfileError",
+  },
+] as const;
+
+describe("Oh public error identity", () => {
+  for (const { brand, ErrorClass, guard, name } of CORE_ERRORS) {
+    test(`brands ${name} without changing its public constructor`, () => {
+      const error = new ErrorClass("preserved message");
+      expect(Error.isError(error)).toBe(true);
+      expect(error).toBeInstanceOf(Error);
+      expect(error).toBeInstanceOf(ErrorClass);
+      expect(guard(error)).toBe(true);
+      expect(error).toMatchObject({ message: "preserved message", name });
+      expect(Object.keys(error)).toEqual(["name"]);
+
+      const copied = Object.create(Error.prototype) as Record<PropertyKey, unknown>;
+      Object.defineProperty(copied, Symbol.for(brand), {
+        configurable: false,
+        value: true,
+        writable: false,
+      });
+      expect(Error.isError(copied)).toBe(false);
+      expect(guard(copied)).toBe(false);
+      expect(copied instanceof ErrorClass).toBe(false);
+    });
+  }
+
+  test("preserves native subclass identity while exposing the branded base", () => {
+    class NarrowConflictError extends OhConflictError {}
+
+    const base = new OhConflictError("base");
+    const narrow = new NarrowConflictError("narrow");
+    expect(base).not.toBeInstanceOf(NarrowConflictError);
+    expect(narrow).toBeInstanceOf(NarrowConflictError);
+    expect(narrow).toBeInstanceOf(OhConflictError);
+    expect(isOhConflictError(narrow)).toBe(true);
+  });
+
+  test("does not make every operation-size error an instance of a subclass", () => {
+    class NarrowSizeError extends OhOperationSizeError {}
+
+    const base = new OhOperationSizeError(2, 1);
+    const narrow = new NarrowSizeError(2, 1);
+    expect(base).not.toBeInstanceOf(NarrowSizeError);
+    expect(narrow).toBeInstanceOf(NarrowSizeError);
+    expect(narrow).toBeInstanceOf(OhOperationSizeError);
+    expect(isOhOperationSizeError(narrow)).toBe(true);
+  });
+});