@hraness/oh 0.2.3

package/src/schema.ts

@@ -0,0 +1,156 @@
+import {
+  boundedText,
+  canonicalJson,
+  canonicalSha256,
+  hasExactKeys,
+  isPlainRecord,
+  orderedUnique,
+  parseSha256Hex,
+  safeCode,
+  type JsonObject,
+  type Sha256Hex,
+} from "./canonical";
+import { parseKnowledgeSchemaRefV1, type KnowledgeSchemaRefV1 } from "./ontology";
+
+export const OH_SCHEMA_FORMAT_VERSION_V1 = 1 as const;
+export const OH_SCHEMA_KINDS_V1 = ["concept", "mapping", "predicate", "shape", "unit", "vocabulary"] as const;
+export type KnowledgeSchemaKindV1 = (typeof OH_SCHEMA_KINDS_V1)[number];
+
+export type KnowledgeLocalizedTextV1 = Readonly<{ language: string; text: string; v: 1 }>;
+
+export type KnowledgeSchemaRevisionInputV1 = Readonly<{
+  body: JsonObject;
+  code: string;
+  compatibility: "additive" | "breaking";
+  description: readonly KnowledgeLocalizedTextV1[];
+  kind: KnowledgeSchemaKindV1;
+  labels: readonly KnowledgeLocalizedTextV1[];
+  namespace: string;
+  previousSchemaSha256: Sha256Hex | null;
+  revision: number;
+  v: 1;
+}>;
+
+export type KnowledgeSchemaRevisionV1 = KnowledgeSchemaRevisionInputV1 & Readonly<{
+  schemaSha256: Sha256Hex;
+}>;
+
+export type KnowledgeVocabularyRevisionV1 = Readonly<{
+  namespace: string;
+  revision: number;
+  schemaRefs: readonly KnowledgeSchemaRefV1[];
+  v: 1;
+  vocabularySha256: Sha256Hex;
+}>;
+
+function parseLocalizedTexts(value: unknown): readonly KnowledgeLocalizedTextV1[] | null {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 128) return null;
+  const output: KnowledgeLocalizedTextV1[] = [];
+  for (const item of value) {
+    if (!isPlainRecord(item) || !hasExactKeys(item, ["language", "text", "v"]) || item.v !== 1) return null;
+    const language = typeof item.language === "string"
+        && /^(?:und|[a-z]{2,3}(?:-[a-z0-9]{2,8})*)$/u.test(item.language)
+      ? item.language : null;
+    const text = boundedText(item.text, 16_384);
+    if (language === null || text === null) return null;
+    output.push({ language, text, v: 1 });
+  }
+  return orderedUnique(output, canonicalJson) ? output : null;
+}
+
+function parseSchemaInput(value: unknown): KnowledgeSchemaRevisionInputV1 | null {
+  if (!isPlainRecord(value) || !hasExactKeys(value, ["body", "code", "compatibility", "description",
+    "kind", "labels", "namespace", "previousSchemaSha256", "revision", "v"]) || value.v !== 1
+    || !isPlainRecord(value.body)) return null;
+  try { canonicalJson(value.body); } catch { return null; }
+  const code = safeCode(value.code);
+  const namespace = safeCode(value.namespace);
+  const kind = OH_SCHEMA_KINDS_V1.find((candidate) => candidate === value.kind);
+  const labels = parseLocalizedTexts(value.labels);
+  const description = parseLocalizedTexts(value.description);
+  const previousSchemaSha256 = value.previousSchemaSha256 === null ? null : parseSha256Hex(value.previousSchemaSha256);
+  const revision = Number.isSafeInteger(value.revision) && (value.revision as number) > 0
+    ? value.revision as number : null;
+  const compatibility = value.compatibility === "additive" || value.compatibility === "breaking"
+    ? value.compatibility : null;
+  return code !== null && namespace !== null && kind !== undefined && labels !== null
+      && description !== null && (value.previousSchemaSha256 === null || previousSchemaSha256 !== null)
+      && revision !== null && compatibility !== null
+      && ((revision === 1) === (previousSchemaSha256 === null))
+      && (revision !== 1 || compatibility === "additive")
+    ? { body: value.body as JsonObject, code, compatibility, description, kind, labels,
+        namespace, previousSchemaSha256, revision, v: 1 }
+    : null;
+}
+
+export function createKnowledgeSchemaRevisionV1(input: KnowledgeSchemaRevisionInputV1): KnowledgeSchemaRevisionV1 {
+  const parsed = parseSchemaInput(input);
+  if (parsed === null) throw new TypeError("Invalid schema revision input.");
+  return { ...parsed, schemaSha256: canonicalSha256(parsed) };
+}
+
+export function parseKnowledgeSchemaRevisionV1(value: unknown): KnowledgeSchemaRevisionV1 | null {
+  if (!isPlainRecord(value) || !Object.hasOwn(value, "schemaSha256")) return null;
+  const schemaSha256 = parseSha256Hex(value.schemaSha256);
+  const { schemaSha256: _digest, ...input } = value;
+  const parsed = parseSchemaInput(input);
+  return schemaSha256 !== null && parsed !== null && canonicalSha256(parsed) === schemaSha256
+    ? { ...parsed, schemaSha256 } : null;
+}
+
+export function knowledgeSchemaRefV1(schema: KnowledgeSchemaRevisionV1): KnowledgeSchemaRefV1 {
+  return { code: schema.code, namespace: schema.namespace, revision: schema.revision,
+    schemaSha256: schema.schemaSha256, v: 1 };
+}
+
+function additiveBodyRetainsPrior(prior: JsonObject, next: JsonObject): boolean {
+  return Object.entries(prior).every(([key, value]) => Object.hasOwn(next, key)
+    && canonicalJson(next[key]) === canonicalJson(value));
+}
+
+/** Checks the immutable chain and the meaning of an additive evolution claim. */
+export function verifyKnowledgeSchemaEvolutionV1(
+  prior: KnowledgeSchemaRevisionV1,
+  next: KnowledgeSchemaRevisionV1,
+): Readonly<{ ok: true }> | Readonly<{ ok: false; reason: string }> {
+  if (parseKnowledgeSchemaRevisionV1(prior) === null || parseKnowledgeSchemaRevisionV1(next) === null) {
+    return { ok: false, reason: "invalid-schema" };
+  }
+  if (prior.namespace !== next.namespace || prior.code !== next.code || prior.kind !== next.kind) {
+    return { ok: false, reason: "identity-changed" };
+  }
+  if (next.revision !== prior.revision + 1 || next.previousSchemaSha256 !== prior.schemaSha256) {
+    return { ok: false, reason: "chain-broken" };
+  }
+  if (next.compatibility === "additive" && !additiveBodyRetainsPrior(prior.body, next.body)) {
+    return { ok: false, reason: "false-additive-claim" };
+  }
+  return { ok: true };
+}
+
+export function createKnowledgeVocabularyRevisionV1(input: Omit<KnowledgeVocabularyRevisionV1, "vocabularySha256">): KnowledgeVocabularyRevisionV1 {
+  const namespace = safeCode(input.namespace);
+  if (namespace === null || input.v !== 1 || !Number.isSafeInteger(input.revision) || input.revision < 1
+    || !Array.isArray(input.schemaRefs) || input.schemaRefs.length > 65_536) {
+    throw new TypeError("Invalid vocabulary revision input.");
+  }
+  const refs: KnowledgeSchemaRefV1[] = [];
+  for (const candidate of input.schemaRefs) {
+    const parsed = parseKnowledgeSchemaRefV1(candidate);
+    if (!parsed.ok || parsed.value.namespace !== namespace) throw new TypeError("Invalid vocabulary schema reference.");
+    refs.push(parsed.value);
+  }
+  if (!orderedUnique(refs, canonicalJson)) throw new TypeError("Vocabulary schema references must be ordered and unique.");
+  const payload = { namespace, revision: input.revision, schemaRefs: refs, v: 1 as const };
+  return { ...payload, vocabularySha256: canonicalSha256(payload) };
+}
+
+export function parseKnowledgeVocabularyRevisionV1(value: unknown): KnowledgeVocabularyRevisionV1 | null {
+  if (!isPlainRecord(value) || !hasExactKeys(value, ["namespace", "revision", "schemaRefs", "v", "vocabularySha256"])) return null;
+  const digest = parseSha256Hex(value.vocabularySha256);
+  try {
+    const created = createKnowledgeVocabularyRevisionV1({ namespace: value.namespace as string,
+      revision: value.revision as number, schemaRefs: value.schemaRefs as KnowledgeSchemaRefV1[], v: value.v as 1 });
+    return digest !== null && created.vocabularySha256 === digest ? { ...created, vocabularySha256: digest } : null;
+  } catch { return null; }
+}

package/src/sdk.ts

@@ -0,0 +1,96 @@
+import { opaqueId, type JsonValue } from "./canonical";
+import { createKnowledgeGraphRecordV1, type KnowledgeGraphRecordKindV1,
+  type KnowledgeGraphRecordV1 } from "./graph";
+import { searchOhV1, type OhSearchModeV1, type OhSearchResponseV1 } from "./search";
+import type { OhSemanticSearchBackendV1 } from "./semantic";
+import { OhSqliteStore, type OhHeadV1, type OhReplayVerificationV1 } from "./sqlite/store";
+import { synchronizeOhStoreV1, type OhOperationSyncTransportV1, type OhSyncResultV1 } from "./sync";
+import type { OhOperationV1 } from "./operation";
+
+export type OhOpenOptionsV1 = Readonly<{
+  databasePath?: string;
+  semanticBackend?: OhSemanticSearchBackendV1;
+  spaceId?: string;
+}>;
+
+export class Oh {
+  readonly store: OhSqliteStore;
+  readonly semanticBackend: OhSemanticSearchBackendV1 | undefined;
+  #closed = false;
+
+  private constructor(store: OhSqliteStore, semanticBackend?: OhSemanticSearchBackendV1) {
+    this.store = store;
+    this.semanticBackend = semanticBackend;
+  }
+
+  static open(options: OhOpenOptionsV1 = {}): Oh {
+    return new Oh(new OhSqliteStore({ path: options.databasePath ?? ".oh/oh.sqlite",
+      ...(options.spaceId === undefined ? {} : { spaceId: options.spaceId }) }),
+      options.semanticBackend);
+  }
+
+  head(): OhHeadV1 { return this.store.head(); }
+
+  put(input: Readonly<{
+    actorId?: string;
+    dependencies?: readonly string[];
+    expectedHead?: Pick<OhHeadV1, "generation" | "operationSha256">;
+    instant?: string;
+    key: string;
+    kind: KnowledgeGraphRecordKindV1;
+    operationId?: string;
+    value: JsonValue;
+  }>): OhOperationV1 {
+    const record = createKnowledgeGraphRecordV1({ dependencies: [...(input.dependencies ?? [])].sort(),
+      key: input.key, kind: input.kind, v: 1, value: input.value });
+    const head = this.store.head();
+    return this.store.commit({ actorId: input.actorId ?? "agent.local", changes: [{ kind: "put", record, v: 1 }],
+      expectedHead: input.expectedHead ?? head, ...(input.instant === undefined ? {} : { instant: input.instant }),
+      operationId: input.operationId ?? opaqueId("op_") });
+  }
+
+  tombstone(input: Readonly<{
+    actorId?: string;
+    expectedHead?: Pick<OhHeadV1, "generation" | "operationSha256">;
+    instant?: string;
+    key: string;
+    operationId?: string;
+  }>): OhOperationV1 {
+    const current = this.store.get(input.key);
+    if (current === null) throw new Error(`No record exists at ${input.key}.`);
+    const head = this.store.head();
+    return this.store.commit({ actorId: input.actorId ?? "agent.local",
+      changes: [{ key: input.key, kind: "tombstone", priorSha256: current.recordSha256, v: 1 }],
+      expectedHead: input.expectedHead ?? head, ...(input.instant === undefined ? {} : { instant: input.instant }),
+      operationId: input.operationId ?? opaqueId("op_") });
+  }
+
+  get(key: string): KnowledgeGraphRecordV1 | null { return this.store.get(key); }
+
+  list(options?: Parameters<OhSqliteStore["list"]>[0]): readonly KnowledgeGraphRecordV1[] {
+    return this.store.list(options);
+  }
+
+  async indexSemantic(): Promise<Readonly<{ indexed: number; v: 1 }>> {
+    if (this.semanticBackend === undefined) throw new Error("No local semantic backend is configured.");
+    return await this.semanticBackend.index(this.store.snapshotRecords());
+  }
+
+  async search(query: string, options: Readonly<{ limit?: number; mode?: OhSearchModeV1 }> = {}): Promise<OhSearchResponseV1> {
+    return await searchOhV1({ ...(this.semanticBackend === undefined ? {} : { backend: this.semanticBackend }),
+      ...(options.limit === undefined ? {} : { limit: options.limit }),
+      ...(options.mode === undefined ? {} : { mode: options.mode }), query, store: this.store });
+  }
+
+  async sync(transport: OhOperationSyncTransportV1, options?: Parameters<typeof synchronizeOhStoreV1>[2]): Promise<OhSyncResultV1> {
+    return await synchronizeOhStoreV1(this.store, transport, options);
+  }
+
+  verify(): OhReplayVerificationV1 { return this.store.verifyReplay(); }
+
+  async close(): Promise<void> {
+    if (this.#closed) return;
+    this.#closed = true;
+    try { await this.semanticBackend?.close(); } finally { this.store.close(); }
+  }
+}

package/src/search.ts

@@ -0,0 +1,66 @@
+import type { KnowledgeGraphRecordV1 } from "./graph";
+import type { OhSemanticSearchBackendV1 } from "./semantic";
+import type { OhSqliteStore } from "./sqlite/store";
+
+export type OhSearchModeV1 = "hybrid" | "keyword" | "semantic";
+export type OhSearchDiagnosticV1 = Readonly<{
+  code: "semantic-unavailable";
+  message: string;
+  v: 1;
+}>;
+export type OhSearchResultV1 = Readonly<{
+  evidence: readonly Readonly<{ lane: "keyword" | "semantic"; rank: number; score: number; v: 1 }>[];
+  record: KnowledgeGraphRecordV1;
+  score: number;
+  v: 1;
+}>;
+export type OhSearchResponseV1 = Readonly<{
+  diagnostics: readonly OhSearchDiagnosticV1[];
+  mode: OhSearchModeV1;
+  results: readonly OhSearchResultV1[];
+  v: 1;
+}>;
+
+export async function searchOhV1(input: Readonly<{
+  backend?: OhSemanticSearchBackendV1;
+  limit?: number;
+  mode?: OhSearchModeV1;
+  query: string;
+  store: OhSqliteStore;
+}>): Promise<OhSearchResponseV1> {
+  const limit = input.limit ?? 10;
+  const mode = input.mode ?? "keyword";
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new RangeError("Search limit must be 1 through 100.");
+  const keyword = mode === "semantic" ? [] : input.store.searchKeyword(input.query, Math.min(100, limit * 3));
+  let semantic: Awaited<ReturnType<OhSemanticSearchBackendV1["search"]>> = [];
+  const diagnostics: OhSearchDiagnosticV1[] = [];
+  if (mode !== "keyword") {
+    if (input.backend === undefined) {
+      diagnostics.push({ code: "semantic-unavailable", message: "No local semantic backend is configured.", v: 1 });
+    } else {
+      try { semantic = await input.backend.search(input.query, Math.min(100, limit * 3), input.store); }
+      catch (error) {
+        diagnostics.push({ code: "semantic-unavailable",
+          message: error instanceof Error ? error.message : "Local semantic search failed.", v: 1 });
+      }
+    }
+  }
+  const byKey = new Map<string, { evidence: OhSearchResultV1["evidence"][number][]; score: number }>();
+  const add = (key: string, lane: "keyword" | "semantic", rank: number, laneScore: number): void => {
+    const contribution = (lane === "keyword" ? 2 : 1) / (60 + rank);
+    const current = byKey.get(key) ?? { evidence: [], score: 0 };
+    current.evidence.push({ lane, rank, score: laneScore, v: 1 });
+    current.score += contribution;
+    byKey.set(key, current);
+  };
+  keyword.forEach((result, index) => add(result.key, "keyword", index + 1, result.score));
+  semantic.forEach((result, index) => add(result.key, "semantic", index + 1, result.score));
+  const results: OhSearchResultV1[] = [];
+  for (const [key, rank] of [...byKey.entries()].sort((left, right) => right[1].score - left[1].score || left[0].localeCompare(right[0]))) {
+    const record = input.store.get(key);
+    if (record === null) continue;
+    results.push({ evidence: rank.evidence, record, score: rank.score, v: 1 });
+    if (results.length === limit) break;
+  }
+  return { diagnostics, mode, results, v: 1 };
+}