@hraness/oh 0.4.1 → 0.4.2

package/dist/semantic-cloud.js

@@ -182,10 +182,6 @@ function sortUnique(values, key) {
   return sorted;
 }
 
-// src/semantic.ts
-import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-
 // src/graph.ts
 var OH_GRAPH_FORMAT_VERSION_V1 = 1;
 var OH_GRAPH_LIMITS_V1 = Object.freeze({
@@ -352,7 +348,7 @@ function graphRevisionSha256V1(input) {
   return canonicalSha256({ changes, operationId, parentGraphRevisionSha256, recordsSha256, revision, v: 1 });
 }
 
-// src/semantic.ts
+// src/semantic-model.ts
 var OH_EMBEDDING_PROFILE_V1 = Object.freeze({
   dimensions: 768,
   distance: "cosine",
@@ -384,261 +380,6 @@ function normalizeOhEmbeddingV1(vector) {
   }
   return normalized;
 }
-var qmdModuleSpecifier = "@tobilu/qmd";
-async function defaultQmdStoreFactory(options) {
-  let module;
-  try {
-    module = await import(qmdModuleSpecifier);
-  } catch {
-    throw new Error("Semantic search needs the optional @tobilu/qmd@2.5.3 package.");
-  }
-  const createStore = module.createStore;
-  if (typeof createStore !== "function")
-    throw new Error("The installed QMD package has no compatible createStore export.");
-  return await createStore(options);
-}
-function recordDocument(record) {
-  return `# ${record.key}
-
-kind: ${record.kind}
-
-${canonicalJson(record.value)}
-`;
-}
-var QMD_VECTOR_RESULT_KEYS = [
-  "body",
-  "bodyLength",
-  "chunkPos",
-  "collectionName",
-  "context",
-  "displayPath",
-  "docid",
-  "filepath",
-  "hash",
-  "modifiedAt",
-  "score",
-  "source",
-  "title"
-];
-function semanticManifest(entries) {
-  const immutableEntries = {};
-  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) {
-  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) {
-  if (!Array.isArray(value) || value.length > 100) {
-    throw new Error("QMD returned an invalid vector result batch.");
-  }
-  return value.map(parseQmdVectorResult).filter((result) => result !== null);
-}
-
-class OhQmdSemanticBackendV1 {
-  profile = OH_EMBEDDING_PROFILE_V1;
-  #cacheDirectory;
-  #databasePath;
-  #factory;
-  #manifest = semanticManifest({});
-  #manifestLoad = null;
-  #store = null;
-  #storeClose = null;
-  #closure = null;
-  #indexQueue = Promise.resolve();
-  #activeSearches = new Set;
-  #closed = false;
-  constructor(options) {
-    this.#cacheDirectory = resolve(options.cacheDirectory);
-    this.#databasePath = resolve(options.databasePath ?? join(this.#cacheDirectory, "qmd.sqlite"));
-    this.#factory = options.storeFactory ?? defaultQmdStoreFactory;
-  }
-  async#open() {
-    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() {
-    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) {
-    this.#storeClose ??= Promise.resolve().then(() => store.close());
-    return this.#storeClose;
-  }
-  #loadManifest() {
-    this.#manifestLoad ??= this.#readManifest();
-    return this.#manifestLoad;
-  }
-  async#readManifest() {
-    let text;
-    try {
-      text = await readFile(join(this.#cacheDirectory, "manifest.json"), "utf8");
-    } catch (error) {
-      if (error.code === "ENOENT")
-        return;
-      throw error;
-    }
-    let value;
-    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 > 65536)
-      throw new Error("The semantic manifest is incompatible or invalid.");
-    const entries = {};
-    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) {
-    if (records.length > 65536) {
-      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(() => {
-      return;
-    }, () => {
-      return;
-    });
-    return operation;
-  }
-  async#indexSnapshot(records) {
-    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 = {};
-    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: 384 });
-      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: 384 });
-    await rename(temporaryManifest, manifestPath);
-    this.#manifest = nextManifest;
-    return { indexed: records.length, v: 1 };
-  }
-  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 (this.#closed)
-      return Promise.reject(new Error("The semantic backend is closed."));
-    const operation = this.#searchSnapshot(query, limit, authority);
-    this.#activeSearches.add(operation);
-    operation.then(() => {
-      this.#activeSearches.delete(operation);
-    }, () => {
-      this.#activeSearches.delete(operation);
-    });
-    return operation;
-  }
-  async#searchSnapshot(query, limit, authority) {
-    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 = [];
-    const seen = new Set;
-    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;
-  }
-  async#finishClose() {
-    await this.#indexQueue;
-    await Promise.allSettled([...this.#activeSearches]);
-    if (this.#store === null)
-      return;
-    try {
-      const store = await this.#store;
-      await this.#closeStore(store);
-    } catch {
-      if (this.#storeClose !== null)
-        await this.#storeClose;
-    }
-  }
-  close() {
-    this.#closed = true;
-    this.#closure ??= this.#finishClose();
-    return this.#closure;
-  }
-}
 
 // src/cloudflare-embedding.ts
 var cloudflareEmbeddingProfilePayload = Object.freeze({

package/dist/semantic-model.d.ts

@@ -0,0 +1,75 @@
+import { type Sha256Hex } from "./canonical";
+import { type KnowledgeGraphRecordV1 } from "./graph";
+import type { OhSqliteStore } from "./sqlite/store";
+export declare const OH_EMBEDDING_PROFILE_V1: Readonly<{
+    readonly dimensions: 768;
+    readonly distance: "cosine";
+    readonly documentation: "https://ai.google.dev/gemma/docs/embeddinggemma";
+    readonly documentFormat: "title: {title} | text: {content}";
+    readonly engine: "@tobilu/qmd@2.5.3";
+    readonly model: "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
+    readonly normalization: "l2";
+    readonly queryFormat: "task: search result | query: {query}";
+    readonly v: 1;
+}>;
+export type OhEmbeddingProfileV1 = typeof OH_EMBEDDING_PROFILE_V1;
+export declare function formatOhEmbeddingQueryV1(query: string): string;
+export declare function formatOhEmbeddingDocumentV1(title: string, content: string): string;
+export declare function normalizeOhEmbeddingV1(vector: readonly number[]): readonly number[];
+export declare function cosineSimilarityV1(left: readonly number[], right: readonly number[]): number;
+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 declare function recordDocument(record: KnowledgeGraphRecordV1): string;
+type ParsedQmdVectorResult = Readonly<{
+    body: string;
+    filename: string;
+    hash: Sha256Hex;
+    score: number;
+    title: string;
+}>;
+export declare function semanticManifest(entries: Record<string, {
+    key: string;
+    recordSha256: Sha256Hex;
+}>): SemanticManifestV1;
+export declare function parseQmdVectorResults(value: unknown): readonly ParsedQmdVectorResult[];
+export {};
+//# sourceMappingURL=semantic-model.d.ts.map

package/dist/semantic-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-model.d.ts","sourceRoot":"","sources":["../src/semantic-model.ts"],"names":[],"mappings":"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"}

package/dist/semantic-platform.d.ts

@@ -0,0 +1,32 @@
+import { Context, Effect, Layer } from "effect";
+import type { KnowledgeGraphRecordV1 } from "./graph";
+import type { OhSqliteStore } from "./sqlite/store";
+import { type QmdStore, type QmdStoreFactoryV1, type SemanticManifestV1 } from "./semantic-model";
+export type SemanticFailure = Readonly<{
+    _tag: "FilesystemFailure" | "BackendFailure" | "ManifestFailure" | "ResultFailure" | "AuthorityFailure" | "Closed";
+    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>;
+}
+declare const SemanticPlatform_base: Context.TagClass<SemanticPlatform, "@hraness/oh/SemanticPlatform", SemanticPlatformService>;
+export declare class SemanticPlatform extends SemanticPlatform_base {
+}
+/** Foreign filesystem and optional QMD calls are confined to this adapter. */
+export declare function semanticPlatformLive(options: SemanticOptions): Layer.Layer<SemanticPlatform>;
+export {};
+//# sourceMappingURL=semantic-platform.d.ts.map

package/dist/semantic-platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-platform.d.ts","sourceRoot":"","sources":["../src/semantic-platform.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAIhD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,KAAK,QAAQ,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3F,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,IAAI,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,eAAe,GAAG,kBAAkB,GAAG,QAAQ,CAAC;IAEnH,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC,CAAC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACvD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IACxD,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAC7D,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACjE,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAChE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAC/F,cAAc,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,eAAe,CAAC,CAAC;IAC/G,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACpF,aAAa,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,sBAAsB,GAAG,IAAI,EAAE,eAAe,CAAC,CAAC;CACrH;;AAED,qBAAa,gBAAiB,SAAQ,qBAEnC;CAAG;AAsCN,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAoD5F"}

package/dist/semantic-program.d.ts

@@ -0,0 +1,18 @@
+import { Effect, Exit, FiberSet, Ref } from "effect";
+import type { KnowledgeGraphRecordV1 } from "./graph";
+import { type OhSemanticSearchResultV1 } 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 declare const makeSemanticLifecycle: Effect.Effect<SemanticLifecycle, never, SemanticPlatform>;
+//# sourceMappingURL=semantic-program.d.ts.map

package/dist/semantic-program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-program.d.ts","sourceRoot":"","sources":["../src/semantic-program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAS,MAAM,QAAQ,CAAC;AAG5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EACL,KAAK,wBAAwB,EAA2B,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,KAAK,CAAC,CAAC;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACrD,KAAK,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,CAAC,CAAA;KAAE,CAAC,EAAE,eAAe,CAAC,CAAC;IACvH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,wBAAwB,EAAE,EAAE,eAAe,CAAC,CAAC;CACrI;AAED,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE,gBAAgB,CA8F1F,CAAC"}

package/dist/semantic-runtime.d.ts

@@ -0,0 +1,6 @@
+import type { OhSemanticSearchBackendV1 } from "./semantic-model";
+import { type SemanticOptions } from "./semantic-platform";
+type SemanticBoundary = Omit<OhSemanticSearchBackendV1, "profile">;
+export declare function makeSemanticBoundary(options: SemanticOptions): SemanticBoundary;
+export {};
+//# sourceMappingURL=semantic-runtime.d.ts.map

package/dist/semantic-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-runtime.d.ts","sourceRoot":"","sources":["../src/semantic-runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGvG,KAAK,gBAAgB,GAAG,IAAI,CAAC,yBAAyB,EAAE,SAAS,CAAC,CAAC;AAWnE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,gBAAgB,CAmC/E"}

package/dist/semantic.d.ts

@@ -1,55 +1,8 @@
-import { type Sha256Hex } from "./canonical";
-import { type KnowledgeGraphRecordV1 } from "./graph";
+import type { KnowledgeGraphRecordV1 } from "./graph";
+import { type OhSemanticSearchBackendV1, type QmdStoreFactoryV1 } from "./semantic-model";
 import type { OhSqliteStore } from "./sqlite/store";
-export declare const OH_EMBEDDING_PROFILE_V1: Readonly<{
-    readonly dimensions: 768;
-    readonly distance: "cosine";
-    readonly documentation: "https://ai.google.dev/gemma/docs/embeddinggemma";
-    readonly documentFormat: "title: {title} | text: {content}";
-    readonly engine: "@tobilu/qmd@2.5.3";
-    readonly model: "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
-    readonly normalization: "l2";
-    readonly queryFormat: "task: search result | query: {query}";
-    readonly v: 1;
-}>;
-export type OhEmbeddingProfileV1 = typeof OH_EMBEDDING_PROFILE_V1;
-export declare function formatOhEmbeddingQueryV1(query: string): string;
-export declare function formatOhEmbeddingDocumentV1(title: string, content: string): string;
-export declare function normalizeOhEmbeddingV1(vector: readonly number[]): readonly number[];
-export declare function cosineSimilarityV1(left: readonly number[], right: readonly number[]): number;
-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>;
+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;
  * every returned hit is rejoined to its exact current record digest.
@@ -72,12 +25,8 @@ export declare class OhQmdSemanticBackendV1 implements OhSemanticSearchBackendV1
         databasePath?: string;
         storeFactory?: QmdStoreFactoryV1;
     }>);
-    index(records: readonly KnowledgeGraphRecordV1[]): Promise<Readonly<{
-        indexed: number;
-        v: 1;
-    }>>;
-    search(query: string, limit: number, authority: OhSqliteStore): Promise<readonly OhSemanticSearchResultV1[]>;
+    index(records: readonly KnowledgeGraphRecordV1[]): ReturnType<OhSemanticSearchBackendV1["index"]>;
+    search(query: string, limit: number, authority: OhSqliteStore): ReturnType<OhSemanticSearchBackendV1["search"]>;
     close(): Promise<void>;
 }
-export {};
 //# sourceMappingURL=semantic.d.ts.map

package/dist/semantic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../src/semantic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../src/semantic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAA2B,KAAK,yBAAyB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEnH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,2BAA2B,EAC/E,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,oBAAoB,EAAE,yBAAyB,EAC3D,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,yBAAyB;;IACtE,QAAQ,CAAC,OAAO;;;;;;;;;;OAA2B;gBAG/B,OAAO,EAAE,QAAQ,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,iBAAiB,CAAA;KAAE,CAAC;IAIlH,KAAK,CAAC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GAAG,UAAU,CAAC,yBAAyB,CAAC,OAAO,CAAC,CAAC;IAIjG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,UAAU,CAAC,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IAI/G,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvB"}