@hraness/oh 0.2.7 → 0.3.1

package/dist/libsql-semantic.d.ts

@@ -0,0 +1,130 @@
+import { type Sha256Hex } from "./canonical";
+import { type OhCloudflareEmbeddingClientV1 } from "./cloudflare-embedding";
+import type { OhLibSqlClientV1 } from "./libsql";
+export declare const OH_LIBSQL_SEMANTIC_LIMITS_V1: Readonly<{
+    chunksPerDocument: 64;
+    chunksPerGeneration: 4096;
+    documentsPerGeneration: 512;
+    embeddingBatch: 16;
+    searchLimit: 100;
+    searchPage: 128;
+}>;
+export declare class OhLibSqlSemanticError extends Error {
+    readonly code: "conflict" | "integrity" | "invalid-input" | "purged" | "schema-unavailable";
+    constructor(code: OhLibSqlSemanticError["code"], message: string);
+}
+export type OhSemanticAuthorityRefV1 = Readonly<{
+    authorityId: string;
+    authoritySha256: Sha256Hex;
+    generation: number;
+    records: readonly Readonly<{
+        key: string;
+        recordSha256: Sha256Hex;
+    }>[];
+    v: 1;
+}>;
+export type OhSemanticDocumentV1 = Readonly<{
+    content: string;
+    key: string;
+    recordSha256: Sha256Hex;
+    title: string;
+    v: 1;
+}>;
+export type OhSemanticStageResultV1 = Readonly<{
+    authorityId: string;
+    chunks: number;
+    documents: number;
+    embedded: number;
+    generation: number;
+    generationSha256: Sha256Hex;
+    membershipSha256: Sha256Hex;
+    reused: number;
+    status: "staged";
+    v: 1;
+}>;
+export type OhSemanticPublishResultV1 = Readonly<{
+    authorityId: string;
+    generation: number;
+    generationSha256: Sha256Hex;
+    published: boolean;
+    v: 1;
+}>;
+/** The exact, currently published cache pointer for one semantic authority. */
+export type OhSemanticPublishedHeadV1 = Readonly<{
+    authorityId: string;
+    authoritySha256: Sha256Hex;
+    generation: number;
+    generationSha256: Sha256Hex;
+    membershipSha256: Sha256Hex;
+    profileSha256: Sha256Hex;
+    publishedAt: string;
+    rendererSha256: Sha256Hex;
+    v: 1;
+}>;
+export type OhSemanticSearchResultV1 = Readonly<{
+    chunkOrdinal: number;
+    key: string;
+    recordSha256: Sha256Hex;
+    score: number;
+    v: 1;
+}>;
+export type OhSemanticPurgeResultV1 = Readonly<{
+    authorityId: string;
+    generations: number;
+    memberships: number;
+    orphanVectors: number;
+    purgedAt: string;
+    v: 1;
+}>;
+export declare function bootstrapOhLibSqlSemanticCacheV1(client: OhLibSqlClientV1, options?: Readonly<{
+    appliedAt?: string;
+}>): Promise<Readonly<{
+    schemaSha256: Sha256Hex;
+    schemaVersion: 1;
+    v: 1;
+}>>;
+export declare class OhLibSqlSemanticCacheV1 {
+    #private;
+    private constructor();
+    /** @internal Public callers should use `openOhLibSqlSemanticCacheV1`. */
+    static open(client: OhLibSqlClientV1, closeClient: boolean): Promise<OhLibSqlSemanticCacheV1>;
+    close(): Promise<void>;
+    /**
+     * Reads the current compare-and-swap base without exposing cache rows or
+     * private source text. An absent or purged authority has no published head.
+     */
+    publishedHead(input: Readonly<{
+        authorityId: string;
+    }>): Promise<OhSemanticPublishedHeadV1 | null>;
+    stage(input: Readonly<{
+        authorityId: string;
+        authoritySha256: Sha256Hex;
+        createdAt?: string;
+        documents: readonly OhSemanticDocumentV1[];
+        embeddingClient: OhCloudflareEmbeddingClientV1;
+        generation: number;
+        maximumChunksPerDocument?: number;
+        signal?: AbortSignal;
+    }>): Promise<OhSemanticStageResultV1>;
+    publish(input: Readonly<{
+        authorityId: string;
+        expectedPublishedGeneration: number | null;
+        generation: number;
+        publishedAt?: string;
+    }>): Promise<OhSemanticPublishResultV1>;
+    search(input: Readonly<{
+        authority: OhSemanticAuthorityRefV1;
+        embeddingClient: OhCloudflareEmbeddingClientV1;
+        limit?: number;
+        query: string;
+        signal?: AbortSignal;
+    }>): Promise<readonly OhSemanticSearchResultV1[]>;
+    purgeAuthority(input: Readonly<{
+        authorityId: string;
+        purgedAt?: string;
+    }>): Promise<OhSemanticPurgeResultV1>;
+}
+export declare function openOhLibSqlSemanticCacheV1(client: OhLibSqlClientV1, options?: Readonly<{
+    closeClient?: boolean;
+}>): Promise<OhLibSqlSemanticCacheV1>;
+//# sourceMappingURL=libsql-semantic.d.ts.map

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

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

package/dist/libsql.js

@@ -60,17 +60,27 @@ function encodeCanonical(value, path, ancestors) {
   ancestors.add(value);
   try {
     if (Array.isArray(value)) {
-      const encoded = [];
-      for (let index = 0;index < value.length; index += 1) {
-        if (!Object.hasOwn(value, index)) {
-          throw new OhValidationError("sparse-array", `${path}[${index}]`, "must not contain holes");
-        }
-        encoded.push(encodeCanonical(value[index], `${path}[${index}]`, ancestors));
+      const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+      const length = lengthDescriptor?.value;
+      if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0) {
+        throw new OhValidationError("non-json-property", path, "array has an invalid length descriptor");
       }
-      const extraKeys = Reflect.ownKeys(value).filter((key) => key !== "length" && (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(key) || Number(key) >= value.length));
-      if (extraKeys.length > 0) {
+      const ownKeys2 = Reflect.ownKeys(value);
+      if (!ownKeys2.includes("length") || ownKeys2.some((key) => key !== "length" && (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(key) || Number(key) >= length))) {
         throw new OhValidationError("non-json-property", path, "array has non-index properties");
       }
+      const elements = [];
+      for (let index = 0;index < length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (descriptor === undefined) {
+          throw new OhValidationError("sparse-array", `${path}[${index}]`, "must not contain holes");
+        }
+        if (!descriptor.enumerable || descriptor.get !== undefined || descriptor.set !== undefined) {
+          throw new OhValidationError("non-json-property", `${path}[${index}]`, "must be an enumerable data property");
+        }
+        elements.push(descriptor.value);
+      }
+      const encoded = elements.map((element, index) => encodeCanonical(element, `${path}[${index}]`, ancestors));
       return `[${encoded.join(",")}]`;
     }
     if (!isPlainRecord(value)) {
@@ -80,19 +90,21 @@ function encodeCanonical(value, path, ancestors) {
     if (ownKeys.some((key) => typeof key !== "string")) {
       throw new OhValidationError("non-json-property", path, "object has a symbol property");
     }
+    const entries = [];
     const keys = ownKeys;
     for (const key of keys) {
       const descriptor = Object.getOwnPropertyDescriptor(value, key);
       if (descriptor === undefined || !descriptor.enumerable || descriptor.get !== undefined || descriptor.set !== undefined) {
         throw new OhValidationError("non-json-property", `${path}.${key}`, "must be an enumerable data property");
       }
+      entries.push([key, descriptor.value]);
     }
-    keys.sort();
-    const entries = keys.map((key) => {
+    entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+    const encodedEntries = entries.map(([key, entryValue]) => {
       assertUnicodeScalarString(key, `${path}.<key>`);
-      return `${JSON.stringify(key)}:${encodeCanonical(value[key], `${path}.${key}`, ancestors)}`;
+      return `${JSON.stringify(key)}:${encodeCanonical(entryValue, `${path}.${key}`, ancestors)}`;
     });
-    return `{${entries.join(",")}}`;
+    return `{${encodedEntries.join(",")}}`;
   } finally {
     ancestors.delete(value);
   }
@@ -140,6 +152,21 @@ function canonicalNow() {
 function safeCode(value, maximumLength = 128) {
   return typeof value === "string" && value.length <= maximumLength && /^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$/u.test(value) ? value : null;
 }
+function boundedText(value, maximumBytes = 64 * 1024) {
+  if (typeof value !== "string" || value.length === 0 || value.normalize("NFC") !== value || utf8ByteLength(value) > maximumBytes)
+    return null;
+  try {
+    assertUnicodeScalarString(value, "$text");
+  } catch {
+    return null;
+  }
+  for (const character of value) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code <= 8 || code >= 11 && code <= 12 || code >= 14 && code <= 31 || code >= 127 && code <= 159)
+      return null;
+  }
+  return value;
+}
 function orderedUnique(values, key) {
   return values.every((value, index) => index === 0 || key(values[index - 1]) < key(value));
 }
@@ -183,17 +210,70 @@ var OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1 = [
   "view",
   "vocabulary"
 ];
+var KNOWLEDGE_GRAPH_RECORD_KEYS_V1 = [
+  "dependencies",
+  "key",
+  "kind",
+  "recordSha256",
+  "v",
+  "value"
+];
+function exactKnowledgeGraphRecordEnvelopeV1(value) {
+  try {
+    if (!isPlainRecord(value))
+      return null;
+    const ownKeys = Reflect.ownKeys(value);
+    if (ownKeys.length !== KNOWLEDGE_GRAPH_RECORD_KEYS_V1.length || ownKeys.some((key) => typeof key !== "string") || KNOWLEDGE_GRAPH_RECORD_KEYS_V1.some((key) => !ownKeys.includes(key)))
+      return null;
+    const detached = {};
+    for (const key of KNOWLEDGE_GRAPH_RECORD_KEYS_V1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor === undefined || !descriptor.enumerable || descriptor.get !== undefined || descriptor.set !== undefined)
+        return null;
+      detached[key] = descriptor.value;
+    }
+    return detached;
+  } catch {
+    return null;
+  }
+}
+function exactGraphDependenciesV1(value) {
+  try {
+    if (!Array.isArray(value))
+      return null;
+    const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+    const length = lengthDescriptor?.value;
+    if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0 || length > OH_GRAPH_LIMITS_V1.dependenciesPerRecord)
+      return null;
+    const ownKeys = Reflect.ownKeys(value);
+    if (ownKeys.length !== length + 1 || !ownKeys.includes("length") || ownKeys.some((key) => key !== "length" && (typeof key !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(key) || Number(key) >= length)))
+      return null;
+    const detached = [];
+    for (let index = 0;index < length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (descriptor === undefined || !descriptor.enumerable || descriptor.get !== undefined || descriptor.set !== undefined)
+        return null;
+      detached.push(descriptor.value);
+    }
+    return detached;
+  } catch {
+    return null;
+  }
+}
 function recordKey(value) {
   return typeof value === "string" && value.length <= 512 && /^[a-z][a-z0-9]*(?:[._:/-][a-z0-9]+)*$/u.test(value) ? value : null;
 }
 function createKnowledgeGraphRecordV1(input) {
-  if (!isPlainRecord(input) || !hasExactKeys(input, ["dependencies", "key", "kind", "v", "value"]) || input.v !== 1 || !Array.isArray(input.dependencies))
+  if (!isPlainRecord(input) || !hasExactKeys(input, ["dependencies", "key", "kind", "v", "value"]) || input.v !== 1)
     throw new TypeError("Invalid graph record input.");
+  const dependencyInput = exactGraphDependenciesV1(input.dependencies);
+  if (dependencyInput === null)
+    throw new TypeError("Invalid graph record dependencies.");
   const key = recordKey(input.key);
   const kind = OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1.find((candidate) => candidate === input.kind);
-  if (key === null || kind === undefined || input.dependencies.length > OH_GRAPH_LIMITS_V1.dependenciesPerRecord)
+  if (key === null || kind === undefined)
     throw new TypeError("Invalid graph record identity.");
-  const dependencies = input.dependencies.map(recordKey);
+  const dependencies = dependencyInput.map(recordKey);
   if (dependencies.some((dependency) => dependency === null) || !orderedUnique(dependencies, String) || dependencies.includes(key)) {
     throw new TypeError("Graph dependencies must be ordered, unique, and non-reflexive.");
   }
@@ -205,10 +285,17 @@ function createKnowledgeGraphRecordV1(input) {
   return { ...payload, recordSha256: canonicalSha256(payload) };
 }
 function parseKnowledgeGraphRecordV1(value) {
-  if (!isPlainRecord(value) || !Object.hasOwn(value, "recordSha256"))
+  const envelope = exactKnowledgeGraphRecordEnvelopeV1(value);
+  if (envelope === null)
     return null;
-  const recordSha256 = parseSha256Hex(value.recordSha256);
-  const { recordSha256: _digest, ...input } = value;
+  const recordSha256 = parseSha256Hex(envelope.recordSha256);
+  const input = {
+    dependencies: envelope.dependencies,
+    key: envelope.key,
+    kind: envelope.kind,
+    v: envelope.v,
+    value: envelope.value
+  };
   try {
     const created = createKnowledgeGraphRecordV1(input);
     return recordSha256 !== null && created.recordSha256 === recordSha256 ? { ...created, recordSha256 } : null;

package/dist/memory-page.d.ts

@@ -0,0 +1,2 @@
+export * from "./memory-pages";
+//# sourceMappingURL=memory-page.d.ts.map

package/dist/memory-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-page.d.ts","sourceRoot":"","sources":["../src/memory-page.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}