@hraness/oh 0.3.0 → 0.3.2

package/README.md

@@ -40,16 +40,16 @@ direct libSQL authority also support Node 24 serverless runtimes. Install the
 exact current release from npm:
 
 ```sh
-bun add --global @hraness/oh@0.3.0
+bun add --global @hraness/oh@0.3.2
 oh --help
 ```
 
 The identical package bytes and their checksum are available from the
-[immutable GitHub Release](https://github.com/hraness/oh/releases/tag/v0.3.0),
+[immutable GitHub Release](https://github.com/hraness/oh/releases/tag/v0.3.2),
 including the mirrored
-[`hraness-oh-0.3.0.tgz`](https://github.com/hraness/oh/releases/download/v0.3.0/hraness-oh-0.3.0.tgz)
+[`hraness-oh-0.3.2.tgz`](https://github.com/hraness/oh/releases/download/v0.3.2/hraness-oh-0.3.2.tgz)
 and
-[`SHA256SUMS`](https://github.com/hraness/oh/releases/download/v0.3.0/SHA256SUMS).
+[`SHA256SUMS`](https://github.com/hraness/oh/releases/download/v0.3.2/SHA256SUMS).
 
 Oh writes to `.oh/oh.sqlite` and the `default` space unless you select another
 path or space. Keep `.oh/` out of source control.
@@ -107,7 +107,7 @@ For a project dependency, pin the same immutable release in `package.json`:
 ```json
 {
   "dependencies": {
-    "@hraness/oh": "0.3.0"
+    "@hraness/oh": "0.3.2"
   }
 }
 ```
@@ -528,18 +528,24 @@ is absent.
 
 ## Add a hosted semantic cache
 
-The hosted adapter uses the same source-record principle with a distinct,
+The hosted V2 adapter uses the same source-record principle with a distinct,
 profile-bound cache. It sends bounded inputs to Cloudflare Workers AI's
 EmbeddingGemma model and stores only float32 vectors, input digests, record
 digests, immutable generation membership, and a published pointer in direct
 libSQL. It stores no title, body, record JSON, or query text.
 
+Every cache call also binds an isolation SHA-256. The helper below derives a
+safe authority-specific default. A private multi-tenant host should instead
+derive an opaque digest from its private authority handle, cache epoch, and
+profile identity, then pass that same digest to every cache operation.
+
 ```ts
 import { createClient } from "@libsql/client";
 import {
   OhCloudflareEmbeddingClientV1,
-  bootstrapOhLibSqlSemanticCacheV1,
-  openOhLibSqlSemanticCacheV1,
+  bootstrapOhLibSqlSemanticCacheV2,
+  deriveOhSemanticIsolationSha256V2,
+  openOhLibSqlSemanticCacheV2,
 } from "@hraness/oh/semantic-cloud";
 
 // Deploy once with a short-lived schema credential.
@@ -547,40 +553,54 @@ const schemaClient = createClient({
   authToken: process.env.OH_SEMANTIC_SCHEMA_TOKEN!,
   url: process.env.OH_SEMANTIC_DATABASE_URL!,
 });
-await bootstrapOhLibSqlSemanticCacheV1(schemaClient);
+await bootstrapOhLibSqlSemanticCacheV2(schemaClient);
 schemaClient.close();
 
 const client = createClient({
   authToken: process.env.OH_SEMANTIC_RUNTIME_TOKEN!,
   url: process.env.OH_SEMANTIC_DATABASE_URL!,
 });
-const cache = await openOhLibSqlSemanticCacheV1(client, { closeClient: true });
+const cache = await openOhLibSqlSemanticCacheV2(client, { closeClient: true });
 const embedder = new OhCloudflareEmbeddingClientV1({
   accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
   apiToken: process.env.CLOUDFLARE_WORKERS_AI_TOKEN!,
 });
+const authorityId = "thread:research/epoch:1";
+const isolationSha256 = deriveOhSemanticIsolationSha256V2(authorityId);
 
 const staged = await cache.stage({
-  authorityId: "thread:research/epoch:1",
+  authorityId,
   authoritySha256: snapshot.head.recordsSha256,
   documents,
   embeddingClient: embedder,
   generation: snapshot.head.generation,
+  isolationSha256,
+});
+const published = await cache.publishedHead({
+  authorityId,
+  isolationSha256,
 });
 await cache.publish({
-  authorityId: "thread:research/epoch:1",
-  expectedPublishedGeneration: null,
+  authorityId,
+  expectedPublishedGeneration: published?.generation ?? null,
   generation: staged.generation,
+  isolationSha256,
 });
 ```
 
 Search requires the exact current authority generation and record digests, and
 returns nothing from a stale or concurrently replaced head. Purge writes a
-permanent authority tombstone before deleting memberships and unused vectors.
-The same authority ID cannot be resurrected; allocate a new epoch for a new
-lifetime. Hosted failure is a missing convenience lane, never permission to
-weaken exact graph or Datalog operations. Read the
-[hosted semantic-cache specification](spec/v1/semantic-cloud.md).
+permanent authority tombstone before deleting memberships and every vector in
+that authority's reserved isolation scopes. Its immutable marker and receipt
+make retries return the same first-run counts while proving zero residual cache
+rows. Distinct authority or cache-epoch isolation digests never reuse a vector,
+and the digest never enters provider text. The same authority ID cannot be
+resurrected; allocate a new epoch for a new lifetime. Hosted failure is a
+missing convenience lane, never permission to weaken exact graph or Datalog
+operations. Read the
+[isolated hosted semantic-cache V2 specification](spec/v2/semantic-cloud.md).
+The released V1 API and digests remain available unchanged for compatibility;
+V1 and V2 cannot open the same semantic database simultaneously.
 
 ## Sync through libSQL or Turso
 
@@ -649,9 +669,9 @@ keep remote sync explicit.
 You can also give an agent this prompt:
 
 ```text
-Install @hraness/oh@0.3.0 from npm and use its packaged Oh Agent Skill. The
-exact npm tarball and SHA256SUMS are mirrored by the immutable v0.3.0 Release at
-https://github.com/hraness/oh/releases/tag/v0.3.0. Verify the CLI with
+Install @hraness/oh@0.3.2 from npm and use its packaged Oh Agent Skill. The
+exact npm tarball and SHA256SUMS are mirrored by the immutable v0.3.2 Release at
+https://github.com/hraness/oh/releases/tag/v0.3.2. Verify the CLI with
 `oh --help` and `oh version`.
 Do not create or modify an Oh database until I name its path and ask you to.
 ```

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
 #!/usr/bin/env bun
-export declare const OH_PACKAGE_VERSION: "0.3.0";
+export declare const OH_PACKAGE_VERSION: "0.3.2";
 export declare function runOhCli(arguments_: readonly string[]): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -3144,7 +3144,7 @@ class Oh {
 
 // src/cli.ts
 import { readFile } from "fs/promises";
-var OH_PACKAGE_VERSION = "0.3.0";
+var OH_PACKAGE_VERSION = "0.3.2";
 var KNOWN_OPTIONS = new Set([
   "actor",
   "after",

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

@@ -0,0 +1,160 @@
+import { type Sha256Hex } from "./canonical";
+import { type OhCloudflareEmbeddingClientV1 } from "./cloudflare-embedding";
+import type { OhLibSqlClientV1 } from "./libsql";
+export declare const OH_LIBSQL_SEMANTIC_LIMITS_V2: Readonly<{
+    chunksPerDocument: 64;
+    chunksPerGeneration: 4096;
+    documentsPerGeneration: 512;
+    embeddingBatch: 16;
+    searchLimit: 100;
+    searchPage: 128;
+}>;
+export declare class OhLibSqlSemanticV2Error extends Error {
+    readonly code: "conflict" | "integrity" | "invalid-input" | "purged" | "schema-unavailable";
+    constructor(code: OhLibSqlSemanticV2Error["code"], message: string);
+}
+export type OhSemanticAuthorityRefV2 = Readonly<{
+    authorityId: string;
+    authoritySha256: Sha256Hex;
+    generation: number;
+    /** Defaults to an authority-specific isolation when omitted. */
+    isolationSha256?: Sha256Hex;
+    records: readonly Readonly<{
+        key: string;
+        recordSha256: Sha256Hex;
+    }>[];
+    v: 2;
+}>;
+export type OhSemanticDocumentV2 = Readonly<{
+    content: string;
+    key: string;
+    recordSha256: Sha256Hex;
+    title: string;
+    v: 2;
+}>;
+export type OhSemanticStageResultV2 = Readonly<{
+    authorityId: string;
+    chunks: number;
+    documents: number;
+    embedded: number;
+    generation: number;
+    generationSha256: Sha256Hex;
+    isolationSha256: Sha256Hex;
+    membershipSha256: Sha256Hex;
+    reused: number;
+    status: "staged";
+    v: 2;
+}>;
+export type OhSemanticPublishResultV2 = Readonly<{
+    authorityId: string;
+    generation: number;
+    generationSha256: Sha256Hex;
+    isolationSha256: Sha256Hex;
+    published: boolean;
+    v: 2;
+}>;
+/** The exact, currently published cache pointer for one semantic authority. */
+export type OhSemanticPublishedHeadV2 = Readonly<{
+    authorityId: string;
+    authoritySha256: Sha256Hex;
+    generation: number;
+    generationSha256: Sha256Hex;
+    isolationSha256: Sha256Hex;
+    membershipSha256: Sha256Hex;
+    profileSha256: Sha256Hex;
+    publishedAt: string;
+    rendererSha256: Sha256Hex;
+    v: 2;
+}>;
+export type OhSemanticSearchResultV2 = Readonly<{
+    chunkOrdinal: number;
+    key: string;
+    recordSha256: Sha256Hex;
+    score: number;
+    v: 2;
+}>;
+export type OhSemanticPurgeResultV2 = Readonly<{
+    authorityId: string;
+    countsRecorded: boolean;
+    generations: number;
+    isolationScopes: number;
+    isolationSha256: Sha256Hex;
+    memberships: number;
+    orphanVectors: number;
+    profileSha256: Sha256Hex;
+    publishedGeneration: number | null;
+    publishedGenerationSha256: Sha256Hex | null;
+    purgeMarkerSha256: Sha256Hex;
+    purgeReceiptSha256: Sha256Hex;
+    purgedAt: string;
+    residualGenerations: 0;
+    residualMemberships: 0;
+    residualScopedVectors: 0;
+    v: 2;
+}>;
+/**
+ * Derives the private-by-default cache scope used when a host does not supply
+ * its own epoch/profile isolation digest.
+ */
+export declare function deriveOhSemanticIsolationSha256V2(authorityId: string): Sha256Hex;
+export declare function bootstrapOhLibSqlSemanticCacheV2(client: OhLibSqlClientV1, options?: Readonly<{
+    appliedAt?: string;
+}>): Promise<Readonly<{
+    schemaSha256: Sha256Hex;
+    schemaVersion: 2;
+    v: 2;
+}>>;
+export declare class OhLibSqlSemanticCacheV2 {
+    #private;
+    private constructor();
+    /** @internal Public callers should use `openOhLibSqlSemanticCacheV2`. */
+    static open(client: OhLibSqlClientV1, closeClient: boolean): Promise<OhLibSqlSemanticCacheV2>;
+    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;
+        isolationSha256?: Sha256Hex;
+    }>): Promise<OhSemanticPublishedHeadV2 | null>;
+    stage(input: Readonly<{
+        authorityId: string;
+        authoritySha256: Sha256Hex;
+        createdAt?: string;
+        documents: readonly OhSemanticDocumentV2[];
+        embeddingClient: OhCloudflareEmbeddingClientV1;
+        generation: number;
+        isolationSha256?: Sha256Hex;
+        maximumChunksPerDocument?: number;
+        signal?: AbortSignal;
+    }>): Promise<OhSemanticStageResultV2>;
+    publish(input: Readonly<{
+        authorityId: string;
+        expectedPublishedGeneration: number | null;
+        generation: number;
+        isolationSha256?: Sha256Hex;
+        publishedAt?: string;
+    }>): Promise<OhSemanticPublishResultV2>;
+    search(input: Readonly<{
+        authority: OhSemanticAuthorityRefV2;
+        embeddingClient: OhCloudflareEmbeddingClientV1;
+        limit?: number;
+        query: string;
+        signal?: AbortSignal;
+    }>): Promise<readonly OhSemanticSearchResultV2[]>;
+    /** Reads the immutable, content-free receipt for a completed purge. */
+    purgeReceipt(input: Readonly<{
+        authorityId: string;
+        isolationSha256?: Sha256Hex;
+    }>): Promise<OhSemanticPurgeResultV2 | null>;
+    purgeAuthority(input: Readonly<{
+        authorityId: string;
+        isolationSha256?: Sha256Hex;
+        purgedAt?: string;
+    }>): Promise<OhSemanticPurgeResultV2>;
+}
+export declare function openOhLibSqlSemanticCacheV2(client: OhLibSqlClientV1, options?: Readonly<{
+    closeClient?: boolean;
+}>): Promise<OhLibSqlSemanticCacheV2>;
+//# sourceMappingURL=libsql-semantic-v2.d.ts.map

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

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

package/dist/libsql-semantic.d.ts

@@ -49,6 +49,18 @@ export type OhSemanticPublishResultV1 = Readonly<{
     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;
@@ -77,6 +89,13 @@ export declare class OhLibSqlSemanticCacheV1 {
     /** @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;

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

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

package/dist/semantic-cloud.d.ts

@@ -1,3 +1,4 @@
 export * from "./cloudflare-embedding";
 export * from "./libsql-semantic";
+export * from "./libsql-semantic-v2";
 //# sourceMappingURL=semantic-cloud.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"semantic-cloud.d.ts","sourceRoot":"","sources":["../src/semantic-cloud.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"semantic-cloud.d.ts","sourceRoot":"","sources":["../src/semantic-cloud.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}