@hraness/oh 0.3.0 → 0.3.1

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.1
 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.1),
 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.1.tgz`](https://github.com/hraness/oh/releases/download/v0.3.1/hraness-oh-0.3.1.tgz)
 and
-[`SHA256SUMS`](https://github.com/hraness/oh/releases/download/v0.3.0/SHA256SUMS).
+[`SHA256SUMS`](https://github.com/hraness/oh/releases/download/v0.3.1/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.1"
   }
 }
 ```
@@ -567,9 +567,12 @@ const staged = await cache.stage({
   embeddingClient: embedder,
   generation: snapshot.head.generation,
 });
+const published = await cache.publishedHead({
+  authorityId: "thread:research/epoch:1",
+});
 await cache.publish({
   authorityId: "thread:research/epoch:1",
-  expectedPublishedGeneration: null,
+  expectedPublishedGeneration: published?.generation ?? null,
   generation: staged.generation,
 });
 ```
@@ -649,9 +652,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.1 from npm and use its packaged Oh Agent Skill. The
+exact npm tarball and SHA256SUMS are mirrored by the immutable v0.3.1 Release at
+https://github.com/hraness/oh/releases/tag/v0.3.1. 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.1";
 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.1";
 var KNOWN_OPTIONS = new Set([
   "actor",
   "after",

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":"AAAA,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAKL,KAAK,6BAA6B,EAEnC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,UAAU,CAAC;AAGlB,eAAO,MAAM,4BAA4B;;;;;;;EAOvC,CAAC;AAEH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,eAAe,GAAG,QAAQ,GAAG,oBAAoB,CAAC;gBAEhF,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAKjE;AAED,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,SAAS,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,SAAS,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,SAAS,CAAA;KAAE,CAAC,EAAE,CAAC;IACvE,CAAC,EAAE,CAAC,CAAC;CACN,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,SAAS,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,CAAC,CAAC;CACN,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,SAAS,CAAC;IAC5B,gBAAgB,EAAE,SAAS,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,CAAC;IACjB,CAAC,EAAE,CAAC,CAAC;CACN,CAAC,CAAC;AAEH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,SAAS,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,CAAC,EAAE,CAAC,CAAC;CACN,CAAC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,SAAS,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,SAAS,CAAC;IAC5B,gBAAgB,EAAE,SAAS,CAAC;IAC5B,aAAa,EAAE,SAAS,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,SAAS,CAAC;IAC1B,CAAC,EAAE,CAAC,CAAC;CACN,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,SAAS,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,CAAC,CAAC;CACN,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,EAAE,CAAC,CAAC;CACN,CAAC,CAAC;AAwOH,wBAAsB,gCAAgC,CACpD,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,QAAQ,CAAC;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAM,GAC7C,OAAO,CAAC,QAAQ,CAAC;IAAE,YAAY,EAAE,SAAS,CAAC;IAAC,aAAa,EAAE,CAAC,CAAC;IAAC,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC,CAkBxE;AAwXD,qBAAa,uBAAuB;;IAKlC,OAAO;IAKP,yEAAyE;WAC5D,IAAI,CAAC,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAS7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;;OAGG;IACG,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC;QAClC,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAgCxC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC;QAC1B,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,SAAS,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAC;QAC3C,eAAe,EAAE,6BAA6B,CAAC;QAC/C,UAAU,EAAE,MAAM,CAAC;QACnB,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAoH/B,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC;QAC5B,WAAW,EAAE,MAAM,CAAC;QACpB,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3C,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAgFjC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC;QAC3B,SAAS,EAAE,wBAAwB,CAAC;QACpC,eAAe,EAAE,6BAA6B,CAAC;QAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,CAAC,GAAG,OAAO,CAAC,SAAS,wBAAwB,EAAE,CAAC;IAkG3C,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC;QACnC,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC;CAyCtC;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,QAAQ,CAAC;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,CAAM,GAChD,OAAO,CAAC,uBAAuB,CAAC,CAElC"}

package/dist/semantic-cloud.js

@@ -1456,6 +1456,33 @@ class OhLibSqlSemanticCacheV1 {
     if (this.#closeClient)
       this.#client.close?.();
   }
+  async publishedHead(input) {
+    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) {
     this.#open();
     validateEmbeddingClient(input.embeddingClient);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/oh",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "open-source tools for agentic research",
   "type": "module",
   "license": "MIT",

package/skills/oh/SKILL.md

@@ -30,8 +30,8 @@ oh --help
 oh version
 ```
 
-The supported CLI is the exact npm release `@hraness/oh@0.3.0`. Its identical
-tarball and checksum are mirrored by the immutable GitHub Release `v0.3.0`.
+The supported CLI is the exact npm release `@hraness/oh@0.3.1`. Its identical
+tarball and checksum are mirrored by the immutable GitHub Release `v0.3.1`.
 It requires Bun 1.3.14 or newer. The versioned contract is published at
 <https://oh.computer/spec/>.
 

package/spec/v1/semantic-cloud.md

@@ -68,6 +68,15 @@ hit is rejoined to a caller-supplied current authority record digest. A stale
 head, changed authority digest, changed record digest, concurrent publish, or
 purge returns no stale authority.
 
+`publishedHead` returns the current compare-and-swap base or `null` for an
+absent or purged authority. Its bounded projection contains only the authority,
+generation, profile, renderer, membership, generation and publication
+identities already held by the cache; it exposes no vector, record body or
+formatted input. The read verifies that the pointer still matches its immutable
+generation and fails with an integrity error on divergence. A host can read the
+base, stage a later authoritative generation, and pass the returned generation
+to `publish` without keeping a second cache pointer elsewhere.
+
 `purgeAuthority` writes a permanent tombstone, removes the head, memberships,
 and staged generations, then deletes vectors no remaining authority uses. The
 tombstone prevents the same authority ID from being staged or published again.

package/src/cli.ts

@@ -9,7 +9,7 @@ import { Oh } from "./sdk";
 import { OH_SQLITE_SCHEMA_VERSION } from "./sqlite/migrations";
 import { createOhSyncBundleV1, parseOhSyncBundleV1 } from "./sync";
 
-export const OH_PACKAGE_VERSION = "0.3.0" as const;
+export const OH_PACKAGE_VERSION = "0.3.1" as const;
 
 type ParsedArguments = { options: Map<string, string[]>; positionals: string[] };
 type ValidatedInvocation = Readonly<{

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";
@@ -197,6 +213,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 +224,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 +253,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 +331,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 +396,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 +510,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;