@hraness/oh 0.3.0 → 0.3.2

package/src/libsql-semantic.test.ts

@@ -85,6 +85,22 @@ class InterleavingLibSqlClient extends SqliteCompatibleLibSqlClient {
   }
 }
 
+class PublishedHeadInterleavingLibSqlClient extends SqliteCompatibleLibSqlClient {
+  afterHeadRead: (() => Promise<void>) | null = null;
+
+  override async execute(statement: OhLibSqlStatementV1 | string): Promise<OhLibSqlResultV1> {
+    const result = await super.execute(statement);
+    const sql = typeof statement === "string" ? statement : statement.sql;
+    if (/FROM\s+oh_semantic_heads\s+WHERE\s+authority_id\s*=\s*\?/iu.test(sql)
+      && this.afterHeadRead !== null) {
+      const hook = this.afterHeadRead;
+      this.afterHeadRead = null;
+      await hook();
+    }
+    return result;
+  }
+}
+
 const instant1 = "2026-08-31T12:00:00.000Z";
 const instant2 = "2026-08-31T12:01:00.000Z";
 const instant3 = "2026-08-31T12:02:00.000Z";
@@ -131,7 +147,11 @@ function document(
 async function bootstrapped(): Promise<SqliteCompatibleLibSqlClient> {
   const client = new SqliteCompatibleLibSqlClient();
   expect(await bootstrapOhLibSqlSemanticCacheV1(client, { appliedAt: instant1 }))
-    .toMatchObject({ schemaVersion: 1, v: 1 });
+    .toEqual({
+      schemaSha256: "d9903735e900e08a8c49c9ad36ea8f277b1689117ef88b9a2c6b906456dfbace" as Sha256Hex,
+      schemaVersion: 1,
+      v: 1,
+    });
   return client;
 }
 
@@ -151,6 +171,51 @@ function authority(
 }
 
 describe("libSQL derived semantic cache", () => {
+  test("reproduces the fixed released V1 digest fixture", async () => {
+    const fixture = await Bun.file(new URL(
+      "../spec/v1/libsql-semantic-digest-fixture-v1.json",
+      import.meta.url,
+    )).json() as Readonly<{
+      authorityId: string;
+      authoritySha256: Sha256Hex;
+      content: string;
+      generation: number;
+      generationSha256: Sha256Hex;
+      inputSha256: Sha256Hex;
+      membershipSha256: Sha256Hex;
+      recordKey: string;
+      recordSha256: Sha256Hex;
+      title: string;
+      v: 1;
+    }>;
+    const client = await bootstrapped();
+    const cache = await openOhLibSqlSemanticCacheV1(client);
+    const calls: string[][] = [];
+    const staged = await cache.stage({
+      authorityId: fixture.authorityId,
+      authoritySha256: fixture.authoritySha256,
+      createdAt: instant1,
+      documents: [{
+        content: fixture.content,
+        key: fixture.recordKey,
+        recordSha256: fixture.recordSha256,
+        title: fixture.title,
+        v: fixture.v,
+      }],
+      embeddingClient: embeddingClient(calls),
+      generation: fixture.generation,
+    });
+    expect(staged).toMatchObject({
+      generationSha256: fixture.generationSha256,
+      membershipSha256: fixture.membershipSha256,
+      v: 1,
+    });
+    expect(calls).toHaveLength(1);
+    expect(sha256Hex(calls[0]?.[0] ?? "")).toBe(fixture.inputSha256);
+    await cache.close();
+    client.close();
+  });
+
   test("requires explicit bootstrap and refuses a partial or drifted schema", async () => {
     const empty = new SqliteCompatibleLibSqlClient();
     await expect(openOhLibSqlSemanticCacheV1(empty)).rejects.toMatchObject({
@@ -197,6 +262,7 @@ describe("libSQL derived semantic cache", () => {
       document("memory:two", "needle-beta"),
     ] as const;
     const firstAuthoritySha256 = digest("authority:first");
+    expect(await cache.publishedHead({ authorityId })).toBeNull();
     const first = await cache.stage({
       authorityId,
       authoritySha256: firstAuthoritySha256,
@@ -207,6 +273,7 @@ describe("libSQL derived semantic cache", () => {
     });
     expect(first).toMatchObject({ chunks: 2, documents: 2, embedded: 2, reused: 0 });
     expect(calls).toHaveLength(1);
+    expect(await cache.publishedHead({ authorityId })).toBeNull();
     expect(await cache.stage({
       authorityId,
       authoritySha256: firstAuthoritySha256,
@@ -235,6 +302,17 @@ describe("libSQL derived semantic cache", () => {
       generation: 1,
       publishedAt: instant1,
     })).toMatchObject({ published: true });
+    expect(await cache.publishedHead({ authorityId })).toEqual({
+      authorityId,
+      authoritySha256: firstAuthoritySha256,
+      generation: 1,
+      generationSha256: first.generationSha256,
+      membershipSha256: first.membershipSha256,
+      profileSha256: OH_CLOUDFLARE_EMBEDDING_PROFILE_V1.profileSha256,
+      publishedAt: instant1,
+      rendererSha256: expect.stringMatching(/^[a-f0-9]{64}$/u),
+      v: 1,
+    });
     expect(await cache.publish({
       authorityId,
       expectedPublishedGeneration: null,
@@ -302,6 +380,12 @@ describe("libSQL derived semantic cache", () => {
       generation: 2,
       publishedAt: instant2,
     })).toMatchObject({ published: true });
+    expect(await cache.publishedHead({ authorityId })).toMatchObject({
+      authoritySha256: secondAuthoritySha256,
+      generation: 2,
+      publishedAt: instant2,
+      v: 1,
+    });
     expect(await cache.search({
       authority: authority(authorityId, 1, firstAuthoritySha256, firstDocuments),
       embeddingClient: embedder,
@@ -361,6 +445,9 @@ describe("libSQL derived semantic cache", () => {
       embeddingClient: embedder,
       query: "needle-alpha",
     })).toEqual([]);
+    expect(await cache.publishedHead({
+      authorityId: "agent:session-a:epoch-1",
+    })).toBeNull();
 
     expect((await cache.purgeAuthority({
       authorityId: "agent:session-b:epoch-1",
@@ -472,6 +559,75 @@ describe("libSQL derived semantic cache", () => {
       embeddingClient: embedder,
       query: "needle-alpha",
     })).rejects.toBeInstanceOf(OhLibSqlSemanticError);
+    await expect(cache.publishedHead({ authorityId: "INVALID" }))
+      .rejects.toMatchObject({ code: "invalid-input" });
+    await cache.close();
+    client.close();
+  });
+
+  test("rejects a published pointer that diverges from its immutable generation", async () => {
+    const client = await bootstrapped();
+    const cache = await openOhLibSqlSemanticCacheV1(client);
+    const authorityId = "agent:published-head-integrity:epoch-1";
+    await cache.stage({
+      authorityId,
+      authoritySha256: digest("published-head-integrity"),
+      createdAt: instant1,
+      documents: [document("memory:one", "needle-alpha")],
+      embeddingClient: embeddingClient([]),
+      generation: 1,
+    });
+    await cache.publish({
+      authorityId,
+      expectedPublishedGeneration: null,
+      generation: 1,
+      publishedAt: instant1,
+    });
+    client.database.query(`UPDATE oh_semantic_heads SET authority_sha256 = ?
+      WHERE authority_id = ?`).run(digest("forged-head"), authorityId);
+    await expect(cache.publishedHead({ authorityId }))
+      .rejects.toMatchObject({ code: "integrity" });
+    await cache.close();
+    client.close();
+  });
+
+  test("does not return a head that changed during its bounded read", async () => {
+    const client = new PublishedHeadInterleavingLibSqlClient();
+    await bootstrapOhLibSqlSemanticCacheV1(client, { appliedAt: instant1 });
+    const cache = await openOhLibSqlSemanticCacheV1(client);
+    const authorityId = "agent:published-head-race:epoch-1";
+    const embedder = embeddingClient([]);
+    for (const generation of [1, 2] as const) {
+      await cache.stage({
+        authorityId,
+        authoritySha256: digest(`published-head-race:${generation}`),
+        createdAt: generation === 1 ? instant1 : instant2,
+        documents: [document(
+          `memory:${generation}`,
+          generation === 1 ? "needle-alpha" : "needle-beta",
+        )],
+        embeddingClient: embedder,
+        generation,
+      });
+    }
+    await cache.publish({
+      authorityId,
+      expectedPublishedGeneration: null,
+      generation: 1,
+      publishedAt: instant1,
+    });
+    client.afterHeadRead = async () => {
+      await cache.publish({
+        authorityId,
+        expectedPublishedGeneration: 1,
+        generation: 2,
+        publishedAt: instant2,
+      });
+    };
+    await expect(cache.publishedHead({ authorityId }))
+      .rejects.toMatchObject({ code: "conflict" });
+    expect(await cache.publishedHead({ authorityId }))
+      .toMatchObject({ generation: 2, publishedAt: instant2 });
     await cache.close();
     client.close();
   });

package/src/libsql-semantic.ts

@@ -79,6 +79,19 @@ export type OhSemanticPublishResultV1 = Readonly<{
   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;
@@ -749,6 +762,44 @@ export class OhLibSqlSemanticCacheV1 {
     if (this.#closeClient) this.#client.close?.();
   }
 
+  /**
+   * Reads the current compare-and-swap base without exposing cache rows or
+   * private source text. An absent or purged authority has no published head.
+   */
+  async publishedHead(input: Readonly<{
+    authorityId: string;
+  }>): Promise<OhSemanticPublishedHeadV1 | null> {
+    this.#open();
+    const authorityId = parseAuthorityId(input.authorityId);
+    if (await readPurge(this.#client, authorityId) !== null) return null;
+    const head = await readHead(this.#client, authorityId);
+    if (head === null) return null;
+    const generation = await readGeneration(this.#client, authorityId, head.generation);
+    if (generation === null || !headMatchesGeneration(head, generation)) {
+      if (await readPurge(this.#client, authorityId) !== null) return null;
+      throw new OhLibSqlSemanticError(
+        "integrity",
+        "The semantic published head does not match its immutable generation.",
+      );
+    }
+    if (await readPurge(this.#client, authorityId) !== null) return null;
+    const finalHead = await readHead(this.#client, authorityId);
+    if (finalHead === null) {
+      if (await readPurge(this.#client, authorityId) !== null) return null;
+      throw new OhLibSqlSemanticError(
+        "integrity",
+        "The semantic published head disappeared during its read.",
+      );
+    }
+    if (canonicalJson(finalHead) !== canonicalJson(head)) {
+      throw new OhLibSqlSemanticError(
+        "conflict",
+        "The semantic published head changed during its read.",
+      );
+    }
+    return Object.freeze({ ...head, v: 1 });
+  }
+
   async stage(input: Readonly<{
     authorityId: string;
     authoritySha256: Sha256Hex;

package/src/semantic-cloud.ts

@@ -1,2 +1,3 @@
 export * from "./cloudflare-embedding";
 export * from "./libsql-semantic";
+export * from "./libsql-semantic-v2";