@hraness/oh 0.4.1 → 0.4.2

package/src/semantic-model.ts

@@ -0,0 +1,142 @@
+import { canonicalJson, canonicalSha256, hasExactKeys, isPlainRecord, parseSha256Hex,
+  safeCode, sha256Hex, type Sha256Hex } from "./canonical";
+import { OH_GRAPH_LIMITS_V1, type KnowledgeGraphRecordV1 } from "./graph";
+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[]>;
+}
+
+export 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>;
+
+export type SemanticManifestV1 = Readonly<{
+  entries: Readonly<Record<string, Readonly<{ key: string; recordSha256: Sha256Hex }>>>;
+  profileSha256: Sha256Hex;
+  v: 1;
+}>;
+
+export 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;
+}>;
+
+export 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 };
+}
+
+export 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);
+}
+

package/src/semantic-platform.ts

@@ -0,0 +1,130 @@
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { Context, Effect, Layer } from "effect";
+
+import { canonicalJson, canonicalSha256, hasExactKeys, isPlainRecord, parseSha256Hex,
+  safeCode, sha256Hex, type Sha256Hex } from "./canonical";
+import type { KnowledgeGraphRecordV1 } from "./graph";
+import type { OhSqliteStore } from "./sqlite/store";
+import { OH_EMBEDDING_PROFILE_V1, recordDocument, semanticManifest,
+  type QmdStore, type QmdStoreFactoryV1, type SemanticManifestV1 } from "./semantic-model";
+
+export type SemanticFailure = Readonly<{
+  _tag: "FilesystemFailure" | "BackendFailure" | "ManifestFailure" | "ResultFailure" | "AuthorityFailure" | "Closed";
+  // Retained only for the existing Promise boundary; never log or serialize foreign causes.
+  cause: unknown;
+}>;
+
+export type SemanticOptions = Readonly<{
+  cacheDirectory: string;
+  databasePath?: string;
+  storeFactory?: QmdStoreFactoryV1;
+}>;
+
+export interface SemanticPlatformService {
+  readonly prepare: Effect.Effect<void, SemanticFailure>;
+  readonly loadManifest: Effect.Effect<SemanticManifestV1, SemanticFailure>;
+  readonly open: Effect.Effect<QmdStore, SemanticFailure>;
+  close(store: QmdStore): Effect.Effect<void, SemanticFailure>;
+  update(store: QmdStore): Effect.Effect<unknown, SemanticFailure>;
+  embed(store: QmdStore): Effect.Effect<unknown, SemanticFailure>;
+  search(store: QmdStore, query: string, limit: number): Effect.Effect<unknown, SemanticFailure>;
+  writeDocuments(records: readonly KnowledgeGraphRecordV1[]): Effect.Effect<SemanticManifestV1, SemanticFailure>;
+  publishManifest(manifest: SemanticManifestV1): Effect.Effect<void, SemanticFailure>;
+  readAuthority(authority: OhSqliteStore, key: string): Effect.Effect<KnowledgeGraphRecordV1 | null, SemanticFailure>;
+}
+
+export class SemanticPlatform extends Context.Tag("@hraness/oh/SemanticPlatform")<
+  SemanticPlatform, SemanticPlatformService
+>() {}
+
+function foreign<A>(tag: SemanticFailure["_tag"], operation: () => Promise<A>): Effect.Effect<A, SemanticFailure> {
+  return Effect.tryPromise({ try: operation, catch: (cause) => ({ _tag: tag, cause }) });
+}
+
+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);
+}
+
+function parseManifest(text: string): SemanticManifestV1 {
+  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 };
+  }
+  return semanticManifest(entries);
+}
+
+/** Foreign filesystem and optional QMD calls are confined to this adapter. */
+export function semanticPlatformLive(options: SemanticOptions): Layer.Layer<SemanticPlatform> {
+  const cacheDirectory = resolve(options.cacheDirectory);
+  const databasePath = resolve(options.databasePath ?? join(cacheDirectory, "qmd.sqlite"));
+  const documents = join(cacheDirectory, "documents");
+  const factory = options.storeFactory ?? defaultQmdStoreFactory;
+  return Layer.succeed(SemanticPlatform, {
+    prepare: foreign("FilesystemFailure", () => mkdir(documents, { recursive: true })).pipe(Effect.asVoid),
+    loadManifest: foreign("FilesystemFailure", async () => {
+      try { return await readFile(join(cacheDirectory, "manifest.json"), "utf8"); }
+      catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw error;
+      }
+    }).pipe(Effect.flatMap((text) => Effect.try({
+      try: () => text === null ? semanticManifest({}) : parseManifest(text),
+      catch: (cause): SemanticFailure => ({ _tag: "ManifestFailure", cause }),
+    }))),
+    open: foreign("BackendFailure", () => factory({ dbPath: databasePath, config: {
+      collections: { oh: { path: documents, pattern: "*.md" } },
+      models: { embed: OH_EMBEDDING_PROFILE_V1.model },
+    } })),
+    close: (store) => foreign("BackendFailure", () => store.close()),
+    update: (store) => foreign("BackendFailure", () => store.update({ collections: ["oh"] })),
+    embed: (store) => foreign("BackendFailure", () => store.embed({ collection: "oh", model: OH_EMBEDDING_PROFILE_V1.model })),
+    search: (store, query, limit) => foreign("BackendFailure", () => store.searchVector(query, { collection: "oh", limit })),
+    writeDocuments: (records) => foreign("FilesystemFailure", async () => {
+      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));
+      }
+      return semanticManifest(entries);
+    }),
+    publishManifest: (manifest) => foreign("FilesystemFailure", async () => {
+      const path = join(cacheDirectory, "manifest.json");
+      const temporary = `${path}.${process.pid}.tmp`;
+      await writeFile(temporary, canonicalJson(manifest), { encoding: "utf8", mode: 0o600 });
+      await rename(temporary, path);
+    }),
+    readAuthority: (authority, key) => Effect.try({
+      try: () => authority.get(key),
+      catch: (cause): SemanticFailure => ({ _tag: "AuthorityFailure", cause }),
+    }),
+  });
+}

package/src/semantic-program.ts

@@ -0,0 +1,113 @@
+import { Effect, Exit, FiberSet, Ref, Scope } from "effect";
+
+import { sha256Hex } from "./canonical";
+import type { KnowledgeGraphRecordV1 } from "./graph";
+import { parseQmdVectorResults, recordDocument, semanticManifest,
+  type OhSemanticSearchResultV1, type SemanticManifestV1 } from "./semantic-model";
+import { SemanticPlatform, type SemanticFailure } from "./semantic-platform";
+import type { OhSqliteStore } from "./sqlite/store";
+
+export interface SemanticLifecycle {
+  readonly closed: Ref.Ref<boolean>;
+  readonly operations: FiberSet.FiberSet<Exit.Exit<unknown, SemanticFailure>, never>;
+  readonly close: Effect.Effect<void, SemanticFailure>;
+  index(records: readonly KnowledgeGraphRecordV1[]): Effect.Effect<Readonly<{ indexed: number; v: 1 }>, SemanticFailure>;
+  search(query: string, limit: number, authority: OhSqliteStore): Effect.Effect<readonly OhSemanticSearchResultV1[], SemanticFailure>;
+}
+
+/** One owner scope holds the optional store until all admitted operations settle. */
+export const makeSemanticLifecycle: Effect.Effect<SemanticLifecycle, never, SemanticPlatform> = Effect.gen(function* () {
+  const platform = yield* SemanticPlatform;
+  const owner = yield* Scope.make();
+  const operations = yield* Scope.extend(FiberSet.make<Exit.Exit<unknown, SemanticFailure>, never>(), owner);
+  const closed = yield* Ref.make(false);
+  const manifest = yield* Ref.make<SemanticManifestV1>(semanticManifest({}));
+  const releaseResult = yield* Ref.make<Exit.Exit<void, SemanticFailure>>(Exit.void);
+  const indexing = yield* Effect.makeSemaphore(1);
+
+  const ensureOpen: Effect.Effect<void, SemanticFailure> = Effect.gen(function* () {
+    if (yield* Ref.get(closed)) {
+      return yield* Effect.fail({ _tag: "Closed", cause: new Error("The semantic backend is closed.") } satisfies SemanticFailure);
+    }
+  });
+  const loadManifest = yield* Effect.cached(platform.loadManifest.pipe(
+    Effect.flatMap((value) => Ref.set(manifest, value)),
+  ));
+  const initialize = yield* Effect.cached(Effect.gen(function* () {
+    yield* platform.prepare;
+    yield* loadManifest;
+    yield* ensureOpen;
+    // Acquisition and finalizer registration are uninterruptible as one unit.
+    return yield* Scope.extend(Effect.acquireRelease(
+      Effect.gen(function* () {
+        const store = yield* platform.open;
+        const release = yield* Effect.cached(platform.close(store));
+        return { store, release };
+      }),
+      ({ release }) => Effect.exit(release).pipe(Effect.flatMap((result) => Ref.set(releaseResult, result))),
+    ), owner);
+  }));
+
+  const open = Effect.gen(function* () {
+    yield* ensureOpen;
+    const acquired = yield* initialize;
+    if (yield* Ref.get(closed)) {
+      // A late store must close even though the operation that acquired it fails.
+      // The scope finalizer shares this cached release, including its exact error.
+      yield* acquired.release;
+      yield* ensureOpen;
+    }
+    return acquired.store;
+  });
+
+  function index(records: readonly KnowledgeGraphRecordV1[]): Effect.Effect<Readonly<{ indexed: number; v: 1 }>, SemanticFailure> {
+    return indexing.withPermits(1)(Effect.gen(function* () {
+      yield* ensureOpen;
+      yield* platform.prepare;
+      yield* loadManifest;
+      const next = yield* platform.writeDocuments(records);
+      const store = yield* open;
+      yield* platform.update(store);
+      yield* platform.embed(store);
+      yield* platform.publishManifest(next);
+      yield* Ref.set(manifest, next);
+      return { indexed: records.length, v: 1 };
+    }));
+  }
+
+  function search(query: string, limit: number,
+    authority: OhSqliteStore): Effect.Effect<readonly OhSemanticSearchResultV1[], SemanticFailure> {
+    return Effect.gen(function* () {
+      const store = yield* open;
+      const snapshot = yield* Ref.get(manifest);
+      const rawResults = yield* platform.search(store, query, Math.min(100, limit * 3));
+      const results = yield* Effect.try({
+        try: () => parseQmdVectorResults(rawResults),
+        catch: (cause): SemanticFailure => ({ _tag: "ResultFailure", cause }),
+      });
+      const output: OhSemanticSearchResultV1[] = [];
+      const seen = new Set<string>();
+      for (const result of results) {
+        const entry = snapshot.entries[result.filename];
+        if (entry === undefined || result.title !== entry.key || seen.has(entry.key)) continue;
+        const current = yield* platform.readAuthority(authority, 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;
+    });
+  }
+
+  const close = yield* Effect.cached(Effect.gen(function* () {
+    // A failed operation does not abort draining its siblings or poison close.
+    yield* FiberSet.awaitEmpty(operations);
+    yield* Scope.close(owner, Exit.void);
+    const result = yield* Ref.get(releaseResult);
+    return yield* result;
+  }));
+  return { closed, operations, close, index, search };
+});

package/src/semantic-runtime.ts

@@ -0,0 +1,53 @@
+import { Cause, Effect, Exit, Fiber, FiberSet, Option, Ref } from "effect";
+
+import type { OhSemanticSearchBackendV1 } from "./semantic-model";
+import { semanticPlatformLive, type SemanticFailure, type SemanticOptions } from "./semantic-platform";
+import { makeSemanticLifecycle } from "./semantic-program";
+
+type SemanticBoundary = Omit<OhSemanticSearchBackendV1, "profile">;
+
+/** The only asynchronous runner accepts an already closed, total boundary. */
+async function runClosed<A>(effect: Effect.Effect<Exit.Exit<A, SemanticFailure>, never, never>): Promise<A> {
+  const result = await Effect.runPromise(effect);
+  if (Exit.isSuccess(result)) return result.value;
+  const expected = Cause.failureOption(result.cause);
+  if (Option.isSome(expected)) throw expected.value.cause;
+  throw Cause.squash(result.cause);
+}
+
+export function makeSemanticBoundary(options: SemanticOptions): SemanticBoundary {
+  const lifecycle = Effect.runSync(makeSemanticLifecycle.pipe(Effect.provide(semanticPlatformLive(options))));
+  const start = Effect.runSync(FiberSet.runtime(lifecycle.operations)<never>());
+
+  function admitted<A>(operation: Effect.Effect<A, SemanticFailure, never>, immediate = true): Promise<A> {
+    // Register synchronously before returning to the caller, so immediate close
+    // cannot overtake an admitted operation before its fiber has started.
+    const fiber = start(Effect.exit(operation), { immediate });
+    return runClosed(Fiber.join(fiber));
+  }
+  function isClosed(): boolean {
+    return Effect.runSync(Ref.get(lifecycle.closed));
+  }
+  return {
+    index(records) {
+      if (records.length > 65_536) {
+        return Promise.reject(new RangeError("A semantic snapshot may contain at most 65,536 records."));
+      }
+      if (isClosed()) return Promise.reject(new Error("The semantic backend is closed."));
+      // Index snapshots have always entered an asynchronous FIFO queue. Keep
+      // same-turn close ahead of their first filesystem operation.
+      return admitted(lifecycle.index([...records]), false);
+    },
+    search(query, limit, authority) {
+      if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+        return Promise.reject(new RangeError("Semantic limit must be 1 through 100."));
+      }
+      if (isClosed()) return Promise.reject(new Error("The semantic backend is closed."));
+      return admitted(lifecycle.search(query, limit, authority));
+    },
+    close() {
+      Effect.runSync(Ref.set(lifecycle.closed, true));
+      return runClosed(Effect.exit(lifecycle.close));
+    },
+  };
+}

package/src/semantic.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -87,6 +87,120 @@ describe("local EmbeddingGemma profile", () => {
 });
 
 describe("QMD derived index confinement", () => {
+  test("same-turn close fences the first queued index before filesystem work", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-semantic-immediate-close-test-"));
+    roots.push(root);
+    let factoryCalls = 0;
+    const backend = new OhQmdSemanticBackendV1({ cacheDirectory: root, storeFactory: async () => {
+      factoryCalls += 1;
+      throw new Error("must not acquire");
+    } });
+    const indexing = backend.index([record("Ada")]);
+    const rejection = indexing.then(() => null, (error: unknown) => error);
+    await backend.close();
+    expect(await rejection).toMatchObject({ message: "The semantic backend is closed." });
+    expect(factoryCalls).toBe(0);
+    expect(await readdir(root)).toEqual([]);
+  });
+
+  test("closing before use never acquires a store and preserves validation precedence", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-semantic-unused-close-test-"));
+    roots.push(root);
+    let factoryCalls = 0;
+    const backend = new OhQmdSemanticBackendV1({ cacheDirectory: root, storeFactory: async () => {
+      factoryCalls += 1;
+      throw new Error("must not acquire");
+    } });
+    const authority = new OhSqliteStore({ path: ":memory:" });
+    await Promise.all([backend.close(), backend.close()]);
+    await expect(backend.search("late", 0, authority)).rejects.toBeInstanceOf(RangeError);
+    await expect(backend.search("late", 1, authority)).rejects.toThrow("closed");
+    await expect(backend.index([])).rejects.toThrow("closed");
+    expect(factoryCalls).toBe(0);
+    authority.close();
+  });
+
+  test("preserves the same late-acquisition close error for the caller and every close", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-semantic-late-close-failure-test-"));
+    roots.push(root);
+    const entered = deferred<void>();
+    const release = deferred<void>();
+    const failure = Object.freeze({ code: "CLOSE_FAILED", message: "foreign close failed" });
+    let closeCalls = 0;
+    const backend = new OhQmdSemanticBackendV1({ cacheDirectory: root, storeFactory: async () => {
+      entered.resolve();
+      await release.promise;
+      return {
+        close: async () => { closeCalls += 1; throw failure; },
+        embed: async () => ({}), searchVector: async () => [], update: async () => ({}),
+      };
+    } });
+    const authority = new OhSqliteStore({ path: ":memory:" });
+    const searching = backend.search("first", 1, authority);
+    await entered.promise;
+    const closing = backend.close();
+    const searchFailure = searching.then(() => null, (error: unknown) => error);
+    const closeFailure = closing.then(() => null, (error: unknown) => error);
+    release.resolve();
+    expect(await searchFailure).toBe(failure);
+    expect(await closeFailure).toBe(failure);
+    await expect(backend.close()).rejects.toBe(failure);
+    expect(closeCalls).toBe(1);
+    authority.close();
+  });
+
+  test("drains an active index, rejects the queued snapshot, and closes once after publication", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-semantic-queued-close-test-"));
+    roots.push(root);
+    const first = record("First edition");
+    const second = record("Second edition");
+    const entered = deferred<void>();
+    const release = deferred<void>();
+    let updateCalls = 0;
+    let closeCalls = 0;
+    const backend = new OhQmdSemanticBackendV1({ cacheDirectory: root, storeFactory: async () => ({
+      close: async () => { closeCalls += 1; },
+      update: async () => { updateCalls += 1; entered.resolve(); await release.promise; },
+      embed: async () => ({}), searchVector: async () => [],
+    }) });
+    const active = backend.index([first]);
+    await entered.promise;
+    const queued = backend.index([second]);
+    const queuedRejection = queued.then(() => null, (error: unknown) => error);
+    const closed = backend.close();
+    expect(closeCalls).toBe(0);
+    release.resolve();
+    await expect(active).resolves.toEqual({ indexed: 1, v: 1 });
+    expect(await queuedRejection).toMatchObject({ message: "The semantic backend is closed." });
+    await closed;
+    expect(updateCalls).toBe(1);
+    expect(closeCalls).toBe(1);
+    expect(await readFile(join(root, "manifest.json"), "utf8")).toBe(canonicalJson({
+      entries: { [`${sha256Hex(first.key)}.md`]: { key: first.key, recordSha256: first.recordSha256 } },
+      profileSha256: canonicalSha256(OH_EMBEDDING_PROFILE_V1), v: 1,
+    }));
+  });
+
+  test("a failed index releases the queue and preserves the original rejection object", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-semantic-failed-queue-test-"));
+    roots.push(root);
+    const failure = new TypeError("synthetic embedding failure");
+    const first = record("First edition");
+    const second = record("Second edition");
+    let embeds = 0;
+    const backend = new OhQmdSemanticBackendV1({ cacheDirectory: root, storeFactory: async () => ({
+      close: async () => {}, update: async () => ({}), searchVector: async () => [],
+      embed: async () => { embeds += 1; if (embeds === 1) throw failure; },
+    }) });
+    const failed = backend.index([first]);
+    const succeeded = backend.index([second]);
+    await expect(failed).rejects.toBe(failure);
+    await expect(succeeded).resolves.toEqual({ indexed: 1, v: 1 });
+    expect(embeds).toBe(2);
+    expect(await readFile(join(root, "manifest.json"), "utf8")).toContain(second.recordSha256);
+    await backend.close();
+  });
+
   test("closes idempotently after optional backend initialization fails", async () => {
     const root = await mkdtemp(join(tmpdir(), "oh-semantic-failed-open-test-"));
     roots.push(root);