@hraness/oh 0.4.1 → 0.4.2

package/src/semantic.ts

@@ -1,158 +1,12 @@
-import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-
-import { canonicalJson, canonicalSha256, hasExactKeys, isPlainRecord, parseSha256Hex,
-  safeCode, sha256Hex, type Sha256Hex } from "./canonical";
-import { OH_GRAPH_LIMITS_V1, type KnowledgeGraphRecordV1 } from "./graph";
+import type { KnowledgeGraphRecordV1 } from "./graph";
+import { OH_EMBEDDING_PROFILE_V1, type OhSemanticSearchBackendV1, type QmdStoreFactoryV1 } from "./semantic-model";
+import { makeSemanticBoundary } from "./semantic-runtime";
 import type { OhSqliteStore } from "./sqlite/store";
 
-export const OH_EMBEDDING_PROFILE_V1 = Object.freeze({
-  dimensions: 768,
-  distance: "cosine",
-  documentation: "https://ai.google.dev/gemma/docs/embeddinggemma",
-  documentFormat: "title: {title} | text: {content}",
-  engine: "@tobilu/qmd@2.5.3",
-  model: "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf",
-  normalization: "l2",
-  queryFormat: "task: search result | query: {query}",
-  v: 1,
-} as const);
-
-export type OhEmbeddingProfileV1 = typeof OH_EMBEDDING_PROFILE_V1;
-
-export function formatOhEmbeddingQueryV1(query: string): string {
-  return `task: search result | query: ${query}`;
-}
-
-export function formatOhEmbeddingDocumentV1(title: string, content: string): string {
-  return `title: ${title} | text: ${content}`;
-}
-
-export function normalizeOhEmbeddingV1(vector: readonly number[]): readonly number[] {
-  if (vector.length !== OH_EMBEDDING_PROFILE_V1.dimensions
-    || vector.some((component) => !Number.isFinite(component))) {
-    throw new TypeError(`Embedding vectors must contain ${OH_EMBEDDING_PROFILE_V1.dimensions} finite values.`);
-  }
-  const scale = vector.reduce((maximum, component) => Math.max(maximum, Math.abs(component)), 0);
-  if (scale === 0) throw new TypeError("Embedding vectors must have nonzero magnitude.");
-  const scaledMagnitude = Math.sqrt(vector.reduce((sum, component) => {
-    const scaled = component / scale;
-    return sum + scaled * scaled;
-  }, 0));
-  if (!Number.isFinite(scaledMagnitude) || scaledMagnitude === 0) {
-    throw new TypeError("Embedding vectors must have finite nonzero magnitude.");
-  }
-  const normalized = vector.map((component) => (component / scale) / scaledMagnitude);
-  if (normalized.some((component) => !Number.isFinite(component))) {
-    throw new TypeError("Embedding vectors must normalize to finite values.");
-  }
-  return normalized;
-}
-
-export function cosineSimilarityV1(left: readonly number[], right: readonly number[]): number {
-  const normalizedLeft = normalizeOhEmbeddingV1(left);
-  const normalizedRight = normalizeOhEmbeddingV1(right);
-  return normalizedLeft.reduce((sum, component, index) => sum + component * (normalizedRight[index] as number), 0);
-}
-
-export type OhSemanticSearchResultV1 = Readonly<{
-  key: string;
-  recordSha256: Sha256Hex;
-  score: number;
-  v: 1;
-}>;
-
-export interface OhSemanticSearchBackendV1 {
-  readonly profile: OhEmbeddingProfileV1;
-  close(): Promise<void>;
-  index(records: readonly KnowledgeGraphRecordV1[]): Promise<Readonly<{ indexed: number; v: 1 }>>;
-  search(query: string, limit: number, authority: OhSqliteStore): Promise<readonly OhSemanticSearchResultV1[]>;
-}
-
-type QmdStore = {
-  close(): Promise<void>;
-  embed(options: Readonly<{ collection: string; model: string }>): Promise<unknown>;
-  searchVector(query: string, options: Readonly<{ collection: string; limit: number }>): Promise<unknown>;
-  update(options: Readonly<{ collections: readonly string[] }>): Promise<unknown>;
-};
-export type QmdStoreFactoryV1 = (options: Readonly<{
-  config: Readonly<Record<string, unknown>>;
-  dbPath: string;
-}>) => Promise<QmdStore>;
-
-const qmdModuleSpecifier: string = "@tobilu/qmd";
-async function defaultQmdStoreFactory(options: Parameters<QmdStoreFactoryV1>[0]): Promise<QmdStore> {
-  let module: unknown;
-  try { module = await import(qmdModuleSpecifier); } catch {
-    throw new Error("Semantic search needs the optional @tobilu/qmd@2.5.3 package.");
-  }
-  const createStore = (module as { createStore?: unknown }).createStore;
-  if (typeof createStore !== "function") throw new Error("The installed QMD package has no compatible createStore export.");
-  return await (createStore as QmdStoreFactoryV1)(options);
-}
-
-type SemanticManifestV1 = Readonly<{
-  entries: Readonly<Record<string, Readonly<{ key: string; recordSha256: Sha256Hex }>>>;
-  profileSha256: Sha256Hex;
-  v: 1;
-}>;
-
-function recordDocument(record: KnowledgeGraphRecordV1): string {
-  return `# ${record.key}\n\nkind: ${record.kind}\n\n${canonicalJson(record.value)}\n`;
-}
-
-const QMD_VECTOR_RESULT_KEYS = [
-  "body", "bodyLength", "chunkPos", "collectionName", "context", "displayPath", "docid",
-  "filepath", "hash", "modifiedAt", "score", "source", "title",
-] as const;
-type ParsedQmdVectorResult = Readonly<{
-  body: string;
-  filename: string;
-  hash: Sha256Hex;
-  score: number;
-  title: string;
-}>;
-
-function semanticManifest(entries: Record<string, { key: string; recordSha256: Sha256Hex }>): SemanticManifestV1 {
-  const immutableEntries: Record<string, Readonly<{ key: string; recordSha256: Sha256Hex }>> = {};
-  for (const [filename, entry] of Object.entries(entries)) {
-    immutableEntries[filename] = Object.freeze({ ...entry });
-  }
-  return Object.freeze({
-    entries: Object.freeze(immutableEntries),
-    profileSha256: canonicalSha256(OH_EMBEDDING_PROFILE_V1),
-    v: 1,
-  });
-}
-
-function parseQmdVectorResult(value: unknown): ParsedQmdVectorResult | null {
-  if (!isPlainRecord(value) || !hasExactKeys(value, QMD_VECTOR_RESULT_KEYS)) return null;
-  const pathMatch = typeof value.filepath === "string"
-    ? /^qmd:\/\/oh\/([a-f0-9]{64}\.md)$/u.exec(value.filepath)
-    : null;
-  const filename = pathMatch?.[1];
-  const hash = parseSha256Hex(value.hash);
-  const title = safeCode(value.title, 512);
-  if (filename === undefined || value.displayPath !== `oh/${filename}` || value.collectionName !== "oh"
-    || value.source !== "vec" || value.context !== null || value.modifiedAt !== ""
-    || hash === null || value.docid !== hash.slice(0, 6) || title === null
-    || typeof value.body !== "string" || typeof value.bodyLength !== "number" || !Number.isSafeInteger(value.bodyLength)
-    || value.bodyLength < 0 || value.bodyLength > OH_GRAPH_LIMITS_V1.recordBytes + 4096
-    || value.body.length !== value.bodyLength || hash !== sha256Hex(value.body) || typeof value.chunkPos !== "number"
-    || !Number.isSafeInteger(value.chunkPos) || value.chunkPos < 0
-    || typeof value.score !== "number" || !Number.isFinite(value.score) || value.score < 0 || value.score > 1) {
-    return null;
-  }
-  return { body: value.body, filename, hash, score: value.score, title };
-}
-
-function parseQmdVectorResults(value: unknown): readonly ParsedQmdVectorResult[] {
-  if (!Array.isArray(value) || value.length > 100) {
-    throw new Error("QMD returned an invalid vector result batch.");
-  }
-  return value.map(parseQmdVectorResult)
-    .filter((result): result is ParsedQmdVectorResult => result !== null);
-}
+export { OH_EMBEDDING_PROFILE_V1, cosineSimilarityV1, formatOhEmbeddingDocumentV1,
+  formatOhEmbeddingQueryV1, normalizeOhEmbeddingV1 } from "./semantic-model";
+export type { OhEmbeddingProfileV1, OhSemanticSearchBackendV1,
+  OhSemanticSearchResultV1, QmdStoreFactoryV1 } from "./semantic-model";
 
 /**
  * Optional, rebuildable local QMD index. SQLite records remain authoritative;
@@ -160,185 +14,21 @@ function parseQmdVectorResults(value: unknown): readonly ParsedQmdVectorResult[]
  */
 export class OhQmdSemanticBackendV1 implements OhSemanticSearchBackendV1 {
   readonly profile = OH_EMBEDDING_PROFILE_V1;
-  readonly #cacheDirectory: string;
-  readonly #databasePath: string;
-  readonly #factory: QmdStoreFactoryV1;
-  #manifest: SemanticManifestV1 = semanticManifest({});
-  #manifestLoad: Promise<void> | null = null;
-  #store: Promise<QmdStore> | null = null;
-  #storeClose: Promise<void> | null = null;
-  #closure: Promise<void> | null = null;
-  #indexQueue: Promise<void> = Promise.resolve();
-  readonly #activeSearches = new Set<Promise<unknown>>();
-  #closed = false;
+  readonly #boundary;
 
   constructor(options: Readonly<{ cacheDirectory: string; databasePath?: string; storeFactory?: QmdStoreFactoryV1 }>) {
-    this.#cacheDirectory = resolve(options.cacheDirectory);
-    this.#databasePath = resolve(options.databasePath ?? join(this.#cacheDirectory, "qmd.sqlite"));
-    this.#factory = options.storeFactory ?? defaultQmdStoreFactory;
-  }
-
-  async #open(): Promise<QmdStore> {
-    if (this.#closed) throw new Error("The semantic backend is closed.");
-    this.#store ??= this.#initializeStore();
-    const store = await this.#store;
-    if (this.#closed) {
-      await this.#closeStore(store);
-      throw new Error("The semantic backend is closed.");
-    }
-    return store;
-  }
-
-  async #initializeStore(): Promise<QmdStore> {
-    const documents = join(this.#cacheDirectory, "documents");
-    await mkdir(documents, { recursive: true });
-    await this.#loadManifest();
-    if (this.#closed) throw new Error("The semantic backend is closed.");
-    const store = await this.#factory({
-      dbPath: this.#databasePath,
-      config: {
-        collections: { oh: { path: documents, pattern: "*.md" } },
-        models: { embed: OH_EMBEDDING_PROFILE_V1.model },
-      },
-    });
-    if (this.#closed) {
-      await this.#closeStore(store);
-      throw new Error("The semantic backend is closed.");
-    }
-    return store;
-  }
-
-  #closeStore(store: QmdStore): Promise<void> {
-    this.#storeClose ??= Promise.resolve().then(() => store.close());
-    return this.#storeClose;
-  }
-
-  #loadManifest(): Promise<void> {
-    this.#manifestLoad ??= this.#readManifest();
-    return this.#manifestLoad;
-  }
-
-  async #readManifest(): Promise<void> {
-    let text: string;
-    try { text = await readFile(join(this.#cacheDirectory, "manifest.json"), "utf8"); }
-    catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
-      throw error;
-    }
-    let value: unknown;
-    try { value = JSON.parse(text); } catch { throw new Error("The semantic manifest is not JSON."); }
-    if (canonicalJson(value) !== text || !isPlainRecord(value)
-      || !hasExactKeys(value, ["entries", "profileSha256", "v"]) || value.v !== 1
-      || value.profileSha256 !== canonicalSha256(OH_EMBEDDING_PROFILE_V1) || !isPlainRecord(value.entries)
-      || Object.keys(value.entries).length > 65_536) throw new Error("The semantic manifest is incompatible or invalid.");
-    const entries: Record<string, { key: string; recordSha256: Sha256Hex }> = {};
-    for (const [filename, candidate] of Object.entries(value.entries)) {
-      if (!/^[a-f0-9]{64}\.md$/u.test(filename) || !isPlainRecord(candidate)
-        || !hasExactKeys(candidate, ["key", "recordSha256"])) throw new Error("The semantic manifest has an invalid entry.");
-      const key = safeCode(candidate.key, 512);
-      const recordSha256 = parseSha256Hex(candidate.recordSha256);
-      if (key === null || recordSha256 === null || filename !== `${sha256Hex(key)}.md`) {
-        throw new Error("The semantic manifest entry identity is invalid.");
-      }
-      entries[filename] = { key, recordSha256 };
-    }
-    this.#manifest = semanticManifest(entries);
-  }
-
-  index(records: readonly KnowledgeGraphRecordV1[]): Promise<Readonly<{ indexed: number; v: 1 }>> {
-    if (records.length > 65_536) {
-      return Promise.reject(new RangeError("A semantic snapshot may contain at most 65,536 records."));
-    }
-    if (this.#closed) return Promise.reject(new Error("The semantic backend is closed."));
-    const snapshot = [...records];
-    const operation = this.#indexQueue.then(() => this.#indexSnapshot(snapshot));
-    this.#indexQueue = operation.then(() => undefined, () => undefined);
-    return operation;
-  }
-
-  async #indexSnapshot(records: readonly KnowledgeGraphRecordV1[]): Promise<Readonly<{ indexed: number; v: 1 }>> {
-    if (this.#closed) throw new Error("The semantic backend is closed.");
-    const documents = join(this.#cacheDirectory, "documents");
-    await mkdir(documents, { recursive: true });
-    await this.#loadManifest();
-    const entries: Record<string, { key: string; recordSha256: Sha256Hex }> = {};
-    for (const record of records) {
-      const filename = `${sha256Hex(record.key)}.md`;
-      entries[filename] = { key: record.key, recordSha256: record.recordSha256 };
-      const path = join(documents, filename);
-      const temporary = `${path}.${process.pid}.tmp`;
-      await writeFile(temporary, recordDocument(record), { encoding: "utf8", mode: 0o600 });
-      await rename(temporary, path);
-    }
-    const retained = new Set(Object.keys(entries));
-    for (const filename of await readdir(documents)) {
-      if (/^[a-f0-9]{64}\.md$/u.test(filename) && !retained.has(filename)) await unlink(join(documents, filename));
-    }
-    const nextManifest = semanticManifest(entries);
-    const store = await this.#open();
-    await store.update({ collections: ["oh"] });
-    await store.embed({ collection: "oh", model: OH_EMBEDDING_PROFILE_V1.model });
-    const manifestPath = join(this.#cacheDirectory, "manifest.json");
-    const temporaryManifest = `${manifestPath}.${process.pid}.tmp`;
-    await writeFile(temporaryManifest, canonicalJson(nextManifest), { encoding: "utf8", mode: 0o600 });
-    await rename(temporaryManifest, manifestPath);
-    this.#manifest = nextManifest;
-    return { indexed: records.length, v: 1 };
-  }
-
-  search(query: string, limit: number, authority: OhSqliteStore): Promise<readonly OhSemanticSearchResultV1[]> {
-    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
-      return Promise.reject(new RangeError("Semantic limit must be 1 through 100."));
-    }
-    if (this.#closed) return Promise.reject(new Error("The semantic backend is closed."));
-    const operation = this.#searchSnapshot(query, limit, authority);
-    this.#activeSearches.add(operation);
-    void operation.then(
-      () => { this.#activeSearches.delete(operation); },
-      () => { this.#activeSearches.delete(operation); },
-    );
-    return operation;
+    this.#boundary = makeSemanticBoundary(options);
   }
 
-  async #searchSnapshot(query: string, limit: number,
-    authority: OhSqliteStore): Promise<readonly OhSemanticSearchResultV1[]> {
-    const store = await this.#open();
-    const manifest = this.#manifest;
-    const results = parseQmdVectorResults(await store.searchVector(query,
-      { collection: "oh", limit: Math.min(100, limit * 3) }));
-    const output: OhSemanticSearchResultV1[] = [];
-    const seen = new Set<string>();
-    for (const result of results) {
-      const entry = manifest.entries[result.filename];
-      if (entry === undefined || result.title !== entry.key || seen.has(entry.key)) continue;
-      const current = authority.get(entry.key);
-      if (current === null || current.recordSha256 !== entry.recordSha256) continue;
-      const expectedDocument = recordDocument(current);
-      if (result.body !== expectedDocument || result.hash !== sha256Hex(expectedDocument)) continue;
-      seen.add(entry.key);
-      output.push({ key: entry.key, recordSha256: entry.recordSha256, score: result.score, v: 1 });
-      if (output.length === limit) break;
-    }
-    return output;
+  index(records: readonly KnowledgeGraphRecordV1[]): ReturnType<OhSemanticSearchBackendV1["index"]> {
+    return this.#boundary.index(records);
   }
 
-  async #finishClose(): Promise<void> {
-    await this.#indexQueue;
-    await Promise.allSettled([...this.#activeSearches]);
-    if (this.#store === null) return;
-    try {
-      const store = await this.#store;
-      await this.#closeStore(store);
-    } catch {
-      // Initialization failures are not close failures. A close initiated by
-      // late initialization is shared separately and must still be observed.
-      if (this.#storeClose !== null) await this.#storeClose;
-    }
+  search(query: string, limit: number, authority: OhSqliteStore): ReturnType<OhSemanticSearchBackendV1["search"]> {
+    return this.#boundary.search(query, limit, authority);
   }
 
   close(): Promise<void> {
-    this.#closed = true;
-    this.#closure ??= this.#finishClose();
-    return this.#closure;
+    return this.#boundary.close();
   }
 }

package/src/sqlite/port.ts

@@ -25,7 +25,7 @@ import {
   parseOhSyncBundleV1,
   parseOhSyncHeadRefV1,
   type OhSyncBundleV1,
-} from "../sync";
+} from "../sync-model";
 import type { OhSqliteDatabase } from "./driver";
 import {
   OhSqliteStore,

package/src/sync-libsql-program.ts

@@ -0,0 +1,170 @@
+import { Deferred, Effect, Exit, Option, Ref } from "effect";
+import { canonicalJson, parseSha256Hex, safeCode, utf8ByteLength } from "./canonical";
+import { OH_CONTRACT_MANIFEST_V1, parseOhContractManifestV1, type OhContractManifestV1 } from "./contract";
+import { OH_OPERATION_MAX_BYTES_V1, parseOhOperationV1, type OhOperationV1 } from "./operation";
+import { createOhSyncBundleV1, parseOhSyncBundleV1, OH_SYNC_BUNDLE_MAX_OPERATIONS_V1,
+  syncIngressBundleBudgetV1, type OhSyncHeadV1 } from "./sync-model";
+import { LibSqlSyncClient, syncInvalid, type SyncFailure, type SyncTransportService } from "./sync-platform";
+
+function invalid(message: string): SyncFailure {
+  return { _tag: "ValidationFailure", cause: new Error(message) };
+}
+
+function conflict(message: string): SyncFailure {
+  return { _tag: "SyncConflict", cause: new Error(message) };
+}
+
+function rowValue(row: Readonly<Record<string, unknown>> | readonly unknown[], key: string, index: number): unknown {
+  return Array.isArray(row) ? row[index] : (row as Readonly<Record<string, unknown>>)[key];
+}
+
+/** A shared initialization attempt retains its result for every admitted waiter. */
+export const makeLibSqlSyncTransport: Effect.Effect<SyncTransportService, never, LibSqlSyncClient> = Effect.gen(function* () {
+  const client = yield* LibSqlSyncClient;
+  const ready = yield* Ref.make<Option.Option<Deferred.Deferred<void, SyncFailure>>>(Option.none());
+  const setup = (manifest: OhContractManifestV1): Effect.Effect<void, SyncFailure> => Effect.gen(function* () {
+    if (parseOhContractManifestV1(manifest) === null) return yield* Effect.fail(invalid("Unsupported contract manifest."));
+    yield* client.batch([
+      { sql: `CREATE TABLE IF NOT EXISTS oh_sync_contracts (
+        contract_id TEXT PRIMARY KEY, contract_sha256 TEXT NOT NULL, manifest_json TEXT NOT NULL
+      ) STRICT` },
+      { sql: `CREATE TABLE IF NOT EXISTS oh_sync_operations (
+        space_id TEXT NOT NULL, sequence INTEGER NOT NULL, operation_sha256 TEXT NOT NULL UNIQUE,
+        operation_json TEXT NOT NULL, PRIMARY KEY(space_id, sequence)
+      ) STRICT` },
+      { sql: "INSERT INTO oh_sync_contracts(contract_id, contract_sha256, manifest_json) VALUES (?, ?, ?) ON CONFLICT(contract_id) DO NOTHING",
+        args: [manifest.contractId, manifest.contractSha256, canonicalJson(manifest)] },
+    ], "write");
+    const result = yield* client.execute({ sql: "SELECT contract_sha256, manifest_json FROM oh_sync_contracts WHERE contract_id = ?",
+      args: [manifest.contractId] });
+    const row = result.rows[0];
+    if (row === undefined || rowValue(row, "contract_sha256", 0) !== manifest.contractSha256
+      || rowValue(row, "manifest_json", 1) !== canonicalJson(manifest)) {
+      return yield* Effect.fail(invalid("Remote contract manifest mismatch."));
+    }
+  });
+
+  const ensure = (manifest = OH_CONTRACT_MANIFEST_V1): Effect.Effect<void, SyncFailure> => Effect.uninterruptible(
+    Effect.gen(function* () {
+      const candidate = yield* Deferred.make<void, SyncFailure>();
+      const selected = yield* Ref.modify(ready, (current) => Option.isSome(current)
+        ? [current.value, current] as const
+        : [candidate, Option.some(candidate)] as const);
+      if (selected !== candidate) return yield* Deferred.await(selected);
+      const result = yield* Effect.exit(setup(manifest));
+      // A failed shared attempt may be retried by a later call, while its
+      // admitted waiters all observe this exact failure, including defects.
+      if (Exit.isFailure(result)) yield* Ref.set(ready, Option.none());
+      yield* Deferred.done(candidate, result);
+      return yield* result;
+    }),
+  );
+
+  const head = (spaceId: string): Effect.Effect<OhSyncHeadV1, SyncFailure> => Effect.gen(function* () {
+    yield* ensure();
+    const result = yield* client.execute({ sql: `SELECT sequence, operation_sha256 FROM oh_sync_operations
+      WHERE space_id = ? ORDER BY sequence DESC LIMIT 1`, args: [spaceId] });
+    const row = result.rows[0];
+    if (row === undefined) return { operationSha256: null, sequence: 0, v: 1 };
+    const sequence = Number(rowValue(row, "sequence", 0));
+    const operationSha256 = parseSha256Hex(rowValue(row, "operation_sha256", 1));
+    if (!Number.isSafeInteger(sequence) || sequence < 1 || operationSha256 === null) {
+      return yield* Effect.fail(invalid("Invalid remote head."));
+    }
+    return { operationSha256, sequence, v: 1 };
+  });
+  return {
+    handshake: (manifest) => Effect.gen(function* () {
+      const parsed = parseOhContractManifestV1(manifest);
+      if (parsed === null) return yield* Effect.fail(invalid("Unsupported contract manifest."));
+      yield* ensure(parsed);
+    }),
+    head,
+    pull: (spaceId, afterSequence, limit) => Effect.gen(function* () {
+      const parsedSpaceId = safeCode(spaceId);
+      if (parsedSpaceId === null
+        || !Number.isSafeInteger(afterSequence) || afterSequence < 0 || Object.is(afterSequence, -0)
+        || !Number.isSafeInteger(limit) || limit < 1 || limit > OH_SYNC_BUNDLE_MAX_OPERATIONS_V1) {
+        return yield* Effect.fail(syncInvalid(new TypeError("Invalid sync pull request.")));
+      }
+      yield* ensure();
+      const bundleBudget = syncIngressBundleBudgetV1(parsedSpaceId);
+      const result = yield* client.execute({ sql: `SELECT operation_json FROM (
+          SELECT sequence, operation_json,
+            row_number() OVER (ORDER BY sequence) AS ordinal,
+            sum(length(CAST(operation_json AS BLOB))) OVER (
+              ORDER BY sequence ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+            ) AS cumulative_bytes
+          FROM (
+            SELECT sequence, operation_json FROM oh_sync_operations
+            WHERE space_id = ? AND sequence > ? ORDER BY sequence LIMIT ?
+          )
+        ) WHERE ordinal = 1 OR cumulative_bytes + ordinal - 1 <= ? ORDER BY sequence`,
+        args: [parsedSpaceId, afterSequence, limit,
+          bundleBudget.maximumBytes - bundleBudget.bytes] });
+      const rows = result.rows;
+      if (!Array.isArray(rows) || rows.length > limit) {
+        return yield* Effect.fail(invalid("Remote sync pull exceeded its requested row limit."));
+      }
+      const operations: OhOperationV1[] = [];
+      for (const row of rows) {
+        const json = rowValue(row, "operation_json", 0);
+        if (typeof json !== "string") return yield* Effect.fail(invalid("Invalid remote operation JSON."));
+        if (utf8ByteLength(json) > OH_OPERATION_MAX_BYTES_V1) {
+          return yield* Effect.fail(invalid("Remote operation JSON exceeds the canonical operation byte limit."));
+        }
+        const raw: unknown = yield* Effect.try({ try: () => JSON.parse(json) as unknown, catch: syncInvalid });
+        const operation = parseOhOperationV1(raw);
+        if (operation === null || canonicalJson(operation) !== json) return yield* Effect.fail(invalid("Invalid remote operation."));
+        operations.push(operation);
+      }
+      return yield* Effect.try({ try: () => createOhSyncBundleV1(parsedSpaceId, operations), catch: syncInvalid });
+    }),
+    push: (value) => Effect.gen(function* () {
+      yield* ensure();
+      const bundle = parseOhSyncBundleV1(value);
+      if (bundle === null) return yield* Effect.fail(invalid("Invalid outgoing sync bundle."));
+      if (bundle.operations.length === 0) return yield* head(bundle.spaceId);
+      const remote = yield* head(bundle.spaceId);
+      const first = bundle.operations[0];
+      const last = bundle.operations.at(-1);
+      if (first === undefined || last === undefined) return yield* Effect.fail(invalid("Invalid outgoing sync bundle."));
+      if (remote.sequence >= last.sequence) {
+        const result = yield* client.execute({ sql: `SELECT sequence, operation_sha256, operation_json
+          FROM oh_sync_operations WHERE space_id = ? AND sequence >= ? AND sequence <= ?
+          ORDER BY sequence LIMIT ?`, args: [bundle.spaceId, first.sequence, last.sequence,
+            bundle.operations.length] });
+        const rows = result.rows;
+        if (!Array.isArray(rows) || rows.length !== bundle.operations.length) {
+          return yield* Effect.fail(conflict("Sync conflict: remote history does not contain the exact pushed operations."));
+        }
+        for (let index = 0; index < bundle.operations.length; index += 1) {
+          const operation = bundle.operations[index];
+          const row = rows[index];
+          if (row === undefined || operation === undefined) {
+            return yield* Effect.fail(conflict("Sync conflict: remote history does not contain the exact pushed operations."));
+          }
+          const sequence = Number(rowValue(row, "sequence", 0));
+          const operationSha256 = parseSha256Hex(rowValue(row, "operation_sha256", 1));
+          const operationJson = rowValue(row, "operation_json", 2);
+          const expectedJson = canonicalJson(operation);
+          if (sequence !== operation.sequence || operationSha256 !== operation.operationSha256
+            || typeof operationJson !== "string"
+            || utf8ByteLength(operationJson) > OH_OPERATION_MAX_BYTES_V1
+            || operationJson !== expectedJson) {
+            return yield* Effect.fail(conflict("Sync conflict: remote history differs from the pushed operations."));
+          }
+        }
+        return { operationSha256: last.operationSha256, sequence: last.sequence, v: 1 };
+      }
+      if (first.sequence !== remote.sequence + 1 || first.parentOperationSha256 !== remote.operationSha256) {
+        return yield* Effect.fail(conflict("Sync conflict: pushed history does not extend the remote head."));
+      }
+      yield* client.batch(bundle.operations.map((operation) => ({
+        sql: "INSERT INTO oh_sync_operations(space_id, sequence, operation_sha256, operation_json) VALUES (?, ?, ?, ?)",
+        args: [bundle.spaceId, operation.sequence, operation.operationSha256, canonicalJson(operation)],
+      })), "write");
+      return { operationSha256: last.operationSha256, sequence: last.sequence, v: 1 };
+    }),
+  } satisfies SyncTransportService;
+});

package/src/sync-lifecycle.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+
+import { canonicalJson } from "./canonical";
+import { OH_CONTRACT_MANIFEST_V1 } from "./contract";
+import { OhSqliteStore } from "./sqlite/store";
+import { createLibSqlOperationSyncTransportV1, synchronizeOhStoreV1,
+  type LibSqlClientV1, type OhOperationSyncTransportV1 } from "./sync";
+
+function clientWithSetup(batch: LibSqlClientV1["batch"]): LibSqlClientV1 {
+  return {
+    batch,
+    execute: async (statement) => ({ rows: typeof statement !== "string"
+      && statement.sql.includes("SELECT contract_sha256, manifest_json")
+      ? [{ contract_sha256: OH_CONTRACT_MANIFEST_V1.contractSha256,
+        manifest_json: canonicalJson(OH_CONTRACT_MANIFEST_V1) }]
+      : [] }),
+  };
+}
+
+describe("sync Effect lifecycle compatibility", () => {
+  test("one failed initialization settles every admitted waiter before a later retry", async () => {
+    const gate = Promise.withResolvers<void>();
+    const failure = Object.freeze({ code: "synthetic setup refusal" });
+    let attempts = 0;
+    const transport = createLibSqlOperationSyncTransportV1(clientWithSetup(async () => {
+      attempts++;
+      if (attempts === 1) { await gate.promise; throw failure; }
+      return [];
+    }));
+    const calls = [transport.handshake(OH_CONTRACT_MANIFEST_V1), transport.head("default"), transport.pull("default", 0, 1)];
+    // Attach all rejection observers before releasing the shared attempt.
+    const outcomes = Promise.allSettled(calls);
+    expect(attempts).toBe(1);
+    gate.resolve();
+    for (const outcome of await outcomes) {
+      expect(outcome.status).toBe("rejected");
+      if (outcome.status === "rejected") expect(outcome.reason).toBe(failure);
+    }
+    expect(attempts).toBe(1);
+    expect(await transport.head("default")).toEqual({ operationSha256: null, sequence: 0, v: 1 });
+    await transport.handshake(OH_CONTRACT_MANIFEST_V1);
+    expect(attempts).toBe(2);
+  });
+
+  test("concurrent successful initialization is performed once", async () => {
+    const gate = Promise.withResolvers<void>();
+    let attempts = 0;
+    const transport = createLibSqlOperationSyncTransportV1(clientWithSetup(async () => {
+      attempts++;
+      await gate.promise;
+      return [];
+    }));
+    const ready = Promise.all(Array.from({ length: 20 }, () => transport.head("default")));
+    expect(attempts).toBe(1);
+    gate.resolve();
+    expect(await ready).toHaveLength(20);
+    expect(attempts).toBe(1);
+  });
+
+  test("the sync facade preserves non-Error transport rejection identity without retry", async () => {
+    const store = new OhSqliteStore({ path: ":memory:" });
+    const failure = Object.freeze({ code: "synthetic handshake rejection" });
+    let calls = 0;
+    const transport: OhOperationSyncTransportV1 = {
+      handshake: async () => { calls++; throw failure; },
+      head: async () => { throw new Error("unexpected head"); },
+      pull: async () => { throw new Error("unexpected pull"); },
+      push: async () => { throw new Error("unexpected push"); },
+    };
+    try {
+      await expect(synchronizeOhStoreV1(store, transport)).rejects.toBe(failure);
+      expect(calls).toBe(1);
+      expect(store.head().sequence).toBe(0);
+    } finally { store.close(); }
+  });
+
+  test("an eager adapter construction failure still returns a rejected Promise", async () => {
+    const store = new OhSqliteStore({ path: ":memory:" });
+    const descriptor = Object.getOwnPropertyDescriptor(store, "spaceId")!;
+    const failure = new Error("synthetic store getter");
+    Object.defineProperty(store, "spaceId", { configurable: true, get: () => { throw failure; } });
+    try {
+      const pending = synchronizeOhStoreV1(store, createLibSqlOperationSyncTransportV1(clientWithSetup(async () => [])));
+      expect(pending).toBeInstanceOf(Promise);
+      await expect(pending).rejects.toBe(failure);
+    } finally {
+      Object.defineProperty(store, "spaceId", descriptor);
+      store.close();
+    }
+  });
+
+  test("a defective shared setup response settles waiters and permits a later attempt", async () => {
+    const defect = new Error("synthetic response getter defect");
+    let attempts = 0;
+    const client = clientWithSetup(async () => { attempts++; return []; });
+    const execute = client.execute;
+    client.execute = async (statement) => {
+      if (attempts === 1) return { get rows(): never { throw defect; } };
+      return await execute(statement);
+    };
+    const transport = createLibSqlOperationSyncTransportV1(client);
+    const results = await Promise.allSettled([transport.head("default"), transport.handshake(OH_CONTRACT_MANIFEST_V1)]);
+    for (const result of results) {
+      expect(result.status).toBe("rejected");
+      if (result.status === "rejected") expect(result.reason).toBe(defect);
+    }
+    expect(await transport.head("default")).toMatchObject({ sequence: 0 });
+    expect(attempts).toBe(2);
+  });
+});