@hraness/oh 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/oh",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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.2`. Its identical
+tarball and checksum are mirrored by the immutable GitHub Release `v0.3.2`.
 It requires Bun 1.3.14 or newer. The versioned contract is published at
 <https://oh.computer/spec/>.
 

package/spec/README.md

@@ -18,7 +18,8 @@ binds these versions:
 | SQLite schema | `2` |
 | Sync protocol | `oh.sync.v1` |
 | Local embedding profile | `1` |
-| Hosted semantic cache | `oh.cloudflare.embeddinggemma.v1` |
+| Hosted semantic cache V1 | `oh.cloudflare.embeddinggemma.v1` |
+| Hosted semantic cache V2 | `oh.semantic-cloud.v2` |
 | Projection semantics | `oh.projection.positive-datalog.v1` |
 | Composite memory | `experimental v1` |
 | Memory page | `oh.memory-page.v1` |
@@ -34,6 +35,7 @@ binds these versions:
 - [Sync protocol](v1/sync.md)
 - [Local embedding profile](v1/embedding.md)
 - [Hosted semantic cache](v1/semantic-cloud.md)
+- [Isolated hosted semantic cache V2](v2/semantic-cloud.md)
 - [Derived projections](v1/projection.md)
 - [Experimental composite agent memory](v1/memory.md)
 - [Memory pages and `.oh.md` interchange](v1/memory-page.md)
@@ -46,6 +48,11 @@ Machine-readable V1 artifacts:
 - [`embedding-profile.json`](v1/embedding-profile.json)
 - [`cloudflare-embedding-profile.json`](v1/cloudflare-embedding-profile.json)
 - [`cloudflare-embedding-renderer.json`](v1/cloudflare-embedding-renderer.json)
+- [`libsql-semantic-cache-schema-v1.sql`](v1/libsql-semantic-cache-schema-v1.sql)
+- [`libsql-semantic-digest-fixture-v1.json`](v1/libsql-semantic-digest-fixture-v1.json)
+- [`semantic-cloud V2 manifest`](v2/manifest.json)
+- [`libsql-semantic-cache-schema-v2.sql`](v2/libsql-semantic-cache-schema-v2.sql)
+- [`libsql-semantic-digest-fixture-v2.json`](v2/libsql-semantic-digest-fixture-v2.json)
 - [`contract.schema.json`](v1/contract.schema.json)
 - [`record.schema.json`](v1/record.schema.json)
 - [`schema-revision.schema.json`](v1/schema-revision.schema.json)

package/spec/manifest.json

@@ -25,9 +25,13 @@
         "specification": "./v1/projection.md"
       },
       "semanticCloud": {
+        "cacheSchema": "./v1/libsql-semantic-cache-schema-v1.sql",
+        "cacheSchemaSha256": "d9903735e900e08a8c49c9ad36ea8f277b1689117ef88b9a2c6b906456dfbace",
+        "digestFixture": "./v1/libsql-semantic-digest-fixture-v1.json",
         "profile": "./v1/cloudflare-embedding-profile.json",
         "renderer": "./v1/cloudflare-embedding-renderer.json",
-        "specification": "./v1/semantic-cloud.md"
+        "specification": "./v1/semantic-cloud.md",
+        "successor": "./v2/manifest.json"
       },
       "schemas": [
         "./v1/contract.schema.json",

package/spec/v1/libsql-semantic-cache-schema-v1.sql

@@ -0,0 +1,114 @@
+CREATE TABLE IF NOT EXISTS oh_semantic_schemas (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  schema_sha256 TEXT NOT NULL,
+  applied_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_vectors (
+  profile_sha256 TEXT NOT NULL,
+  renderer_sha256 TEXT NOT NULL,
+  input_sha256 TEXT NOT NULL,
+  vector_sha256 TEXT NOT NULL,
+  vector BLOB NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY(profile_sha256, renderer_sha256, input_sha256)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_generations (
+  authority_id TEXT NOT NULL,
+  generation INTEGER NOT NULL CHECK(generation >= 0),
+  authority_sha256 TEXT NOT NULL,
+  profile_sha256 TEXT NOT NULL,
+  renderer_sha256 TEXT NOT NULL,
+  membership_sha256 TEXT NOT NULL,
+  generation_sha256 TEXT NOT NULL UNIQUE,
+  document_count INTEGER NOT NULL CHECK(document_count >= 0),
+  chunk_count INTEGER NOT NULL CHECK(chunk_count >= 0),
+  created_at TEXT NOT NULL,
+  PRIMARY KEY(authority_id, generation)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_memberships (
+  authority_id TEXT NOT NULL,
+  generation INTEGER NOT NULL CHECK(generation >= 0),
+  generation_sha256 TEXT NOT NULL,
+  record_key TEXT NOT NULL,
+  record_sha256 TEXT NOT NULL,
+  ordinal INTEGER NOT NULL CHECK(ordinal >= 0),
+  input_sha256 TEXT NOT NULL,
+  PRIMARY KEY(authority_id, generation, record_key, ordinal)
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_heads (
+  authority_id TEXT PRIMARY KEY,
+  generation INTEGER NOT NULL CHECK(generation >= 0),
+  authority_sha256 TEXT NOT NULL,
+  profile_sha256 TEXT NOT NULL,
+  renderer_sha256 TEXT NOT NULL,
+  membership_sha256 TEXT NOT NULL,
+  generation_sha256 TEXT NOT NULL,
+  published_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_purges (
+  authority_id TEXT PRIMARY KEY,
+  purged_at TEXT NOT NULL
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS oh_semantic_memberships_generation
+  ON oh_semantic_memberships(authority_id, generation, record_key, ordinal);
+
+CREATE INDEX IF NOT EXISTS oh_semantic_memberships_input
+  ON oh_semantic_memberships(input_sha256);
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_vectors_no_update
+  BEFORE UPDATE ON oh_semantic_vectors
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic vectors are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_generations_no_update
+  BEFORE UPDATE ON oh_semantic_generations
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic generations are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_no_update
+  BEFORE UPDATE ON oh_semantic_memberships
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic memberships are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_generations_purge_guard
+  BEFORE INSERT ON oh_semantic_generations
+  WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic authority was purged'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_purge_guard
+  BEFORE INSERT ON oh_semantic_memberships
+  WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic authority was purged'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_published_guard
+  BEFORE INSERT ON oh_semantic_memberships
+  WHEN EXISTS (SELECT 1 FROM oh_semantic_heads
+    WHERE authority_id = NEW.authority_id AND generation = NEW.generation)
+    AND NOT EXISTS (SELECT 1 FROM oh_semantic_memberships
+      WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+        AND generation_sha256 = NEW.generation_sha256
+        AND record_key = NEW.record_key AND record_sha256 = NEW.record_sha256
+        AND ordinal = NEW.ordinal AND input_sha256 = NEW.input_sha256)
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic generation is published'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_heads_insert_purge_guard
+  BEFORE INSERT ON oh_semantic_heads
+  WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic authority was purged'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_heads_update_purge_guard
+  BEFORE UPDATE ON oh_semantic_heads
+  WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic authority was purged'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_purges_no_update
+  BEFORE UPDATE ON oh_semantic_purges
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic purge markers are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_purges_no_delete
+  BEFORE DELETE ON oh_semantic_purges
+  BEGIN SELECT RAISE(ABORT, 'Oh semantic purge markers are immutable'); END;

package/spec/v1/libsql-semantic-digest-fixture-v1.json

@@ -0,0 +1,13 @@
+{
+  "authorityId": "fixture:semantic-authority",
+  "authoritySha256": "d1eac8dd93ce6e04cb1316c670008250b98ec32cb0555f21d10b782ddffe03a7",
+  "content": "fixture body",
+  "generation": 7,
+  "generationSha256": "d2beeb0082da8ae3545ade90642a6366ecb209a673dbbbed350a6fec9b1157e3",
+  "inputSha256": "b2309e89dd3f903934c7b5f4a4c8c51d5323d84a66928a2f017dd871492ef294",
+  "membershipSha256": "34f1d2be0152f5626824a5b62ab75771ee906e3abf6b7159b3dfc348a23bdfbc",
+  "recordKey": "memory:fixture",
+  "recordSha256": "920d936e47e8f3cc5847017da5975ef73f8d84c04cb113880fb10575eeb614f9",
+  "title": "fixture title",
+  "v": 1
+}

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/spec/v2/libsql-semantic-cache-schema-v2.sql

@@ -0,0 +1,175 @@
+CREATE TABLE IF NOT EXISTS oh_semantic_schemas (
+  version INTEGER PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  schema_sha256 TEXT NOT NULL,
+  applied_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_isolations (
+    isolation_sha256 TEXT PRIMARY KEY,
+    authority_id TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_vectors (
+    isolation_sha256 TEXT NOT NULL,
+    profile_sha256 TEXT NOT NULL,
+    renderer_sha256 TEXT NOT NULL,
+    input_sha256 TEXT NOT NULL,
+    vector_sha256 TEXT NOT NULL,
+    vector BLOB NOT NULL,
+    created_at TEXT NOT NULL,
+    PRIMARY KEY(isolation_sha256, profile_sha256, renderer_sha256, input_sha256)
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_generations (
+    authority_id TEXT NOT NULL,
+    generation INTEGER NOT NULL CHECK(generation >= 0),
+    authority_sha256 TEXT NOT NULL,
+    isolation_sha256 TEXT NOT NULL,
+    profile_sha256 TEXT NOT NULL,
+    renderer_sha256 TEXT NOT NULL,
+    membership_sha256 TEXT NOT NULL,
+    generation_sha256 TEXT NOT NULL UNIQUE,
+    document_count INTEGER NOT NULL CHECK(document_count >= 0),
+    chunk_count INTEGER NOT NULL CHECK(chunk_count >= 0),
+    created_at TEXT NOT NULL,
+    PRIMARY KEY(authority_id, generation)
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_memberships (
+    authority_id TEXT NOT NULL,
+    generation INTEGER NOT NULL CHECK(generation >= 0),
+    generation_sha256 TEXT NOT NULL,
+    isolation_sha256 TEXT NOT NULL,
+    record_key TEXT NOT NULL,
+    record_sha256 TEXT NOT NULL,
+    ordinal INTEGER NOT NULL CHECK(ordinal >= 0),
+    input_sha256 TEXT NOT NULL,
+    PRIMARY KEY(authority_id, generation, record_key, ordinal)
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_heads (
+    authority_id TEXT PRIMARY KEY,
+    generation INTEGER NOT NULL CHECK(generation >= 0),
+    authority_sha256 TEXT NOT NULL,
+    isolation_sha256 TEXT NOT NULL,
+    profile_sha256 TEXT NOT NULL,
+    renderer_sha256 TEXT NOT NULL,
+    membership_sha256 TEXT NOT NULL,
+    generation_sha256 TEXT NOT NULL,
+    published_at TEXT NOT NULL
+  ) STRICT;
+
+CREATE TABLE IF NOT EXISTS oh_semantic_purges (
+    authority_id TEXT PRIMARY KEY,
+    isolation_sha256 TEXT NOT NULL,
+    profile_sha256 TEXT NOT NULL,
+    published_generation INTEGER CHECK(published_generation IS NULL OR published_generation >= 0),
+    published_generation_sha256 TEXT,
+    purged_at TEXT NOT NULL,
+    purge_marker_sha256 TEXT NOT NULL,
+    generation_count INTEGER NOT NULL CHECK(generation_count >= 0),
+    membership_count INTEGER NOT NULL CHECK(membership_count >= 0),
+    orphan_vector_count INTEGER NOT NULL CHECK(orphan_vector_count >= 0),
+    isolation_scope_count INTEGER NOT NULL CHECK(isolation_scope_count >= 0),
+    counts_recorded INTEGER NOT NULL CHECK(counts_recorded IN (0, 1))
+  ) STRICT;
+
+CREATE INDEX IF NOT EXISTS oh_semantic_isolations_authority
+    ON oh_semantic_isolations(authority_id, isolation_sha256);
+
+CREATE INDEX IF NOT EXISTS oh_semantic_memberships_generation
+    ON oh_semantic_memberships(authority_id, generation, record_key, ordinal);
+
+CREATE INDEX IF NOT EXISTS oh_semantic_memberships_input
+    ON oh_semantic_memberships(isolation_sha256, input_sha256);
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_isolations_no_update
+    BEFORE UPDATE ON oh_semantic_isolations
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic isolations are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_isolations_no_delete
+    BEFORE DELETE ON oh_semantic_isolations
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic isolations are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_isolations_purge_guard
+    BEFORE INSERT ON oh_semantic_isolations
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority was purged'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_vectors_no_update
+    BEFORE UPDATE ON oh_semantic_vectors
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic vectors are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_vectors_isolation_guard
+    BEFORE INSERT ON oh_semantic_vectors
+    WHEN NOT EXISTS (SELECT 1 FROM oh_semantic_isolations
+      WHERE isolation_sha256 = NEW.isolation_sha256)
+      OR EXISTS (SELECT 1 FROM oh_semantic_purges AS purge
+        JOIN oh_semantic_isolations AS isolation
+          ON isolation.authority_id = purge.authority_id
+        WHERE isolation.isolation_sha256 = NEW.isolation_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic vector isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_generations_no_update
+    BEFORE UPDATE ON oh_semantic_generations
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic generations are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_no_update
+    BEFORE UPDATE ON oh_semantic_memberships
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic memberships are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_generations_purge_guard
+    BEFORE INSERT ON oh_semantic_generations
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+      OR NOT EXISTS (SELECT 1 FROM oh_semantic_isolations
+        WHERE isolation_sha256 = NEW.isolation_sha256 AND authority_id = NEW.authority_id)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority or isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_purge_guard
+    BEFORE INSERT ON oh_semantic_memberships
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+      OR NOT EXISTS (SELECT 1 FROM oh_semantic_generations
+        WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+          AND generation_sha256 = NEW.generation_sha256
+          AND isolation_sha256 = NEW.isolation_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority or isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_memberships_published_guard
+    BEFORE INSERT ON oh_semantic_memberships
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_heads
+      WHERE authority_id = NEW.authority_id AND generation = NEW.generation)
+      AND NOT EXISTS (SELECT 1 FROM oh_semantic_memberships
+        WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+          AND generation_sha256 = NEW.generation_sha256
+          AND isolation_sha256 = NEW.isolation_sha256
+          AND record_key = NEW.record_key AND record_sha256 = NEW.record_sha256
+          AND ordinal = NEW.ordinal AND input_sha256 = NEW.input_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic generation is published'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_heads_insert_purge_guard
+    BEFORE INSERT ON oh_semantic_heads
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+      OR NOT EXISTS (SELECT 1 FROM oh_semantic_generations
+        WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+          AND generation_sha256 = NEW.generation_sha256
+          AND isolation_sha256 = NEW.isolation_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority or isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_heads_update_purge_guard
+    BEFORE UPDATE ON oh_semantic_heads
+    WHEN EXISTS (SELECT 1 FROM oh_semantic_purges WHERE authority_id = NEW.authority_id)
+      OR NOT EXISTS (SELECT 1 FROM oh_semantic_generations
+        WHERE authority_id = NEW.authority_id AND generation = NEW.generation
+          AND generation_sha256 = NEW.generation_sha256
+          AND isolation_sha256 = NEW.isolation_sha256)
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic authority or isolation is unavailable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_purges_no_update
+    BEFORE UPDATE ON oh_semantic_purges
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic purge markers are immutable'); END;
+
+CREATE TRIGGER IF NOT EXISTS oh_semantic_purges_no_delete
+    BEFORE DELETE ON oh_semantic_purges
+    BEGIN SELECT RAISE(ABORT, 'Oh semantic purge markers are immutable'); END;

package/spec/v2/libsql-semantic-digest-fixture-v2.json

@@ -0,0 +1,14 @@
+{
+  "authorityId": "fixture:semantic-authority",
+  "authoritySha256": "d1eac8dd93ce6e04cb1316c670008250b98ec32cb0555f21d10b782ddffe03a7",
+  "content": "fixture body",
+  "generation": 7,
+  "generationSha256": "5d848fcd482ca72781af87da7b2ff3f68cd5b9ef571495bc734a5a2582c719d1",
+  "inputSha256": "b2309e89dd3f903934c7b5f4a4c8c51d5323d84a66928a2f017dd871492ef294",
+  "isolationSha256": "217df103dc50da7d3ba2883d9c1cbad01014b2b9eb20e4f94f737291c583d9a5",
+  "membershipSha256": "73ec3fcf8af17d99e2ae84878329c834e044bb47ff08ecd0dca6a596504b26b8",
+  "recordKey": "memory:fixture",
+  "recordSha256": "920d936e47e8f3cc5847017da5975ef73f8d84c04cb113880fb10575eeb614f9",
+  "title": "fixture title",
+  "v": 2
+}

package/spec/v2/manifest.json

@@ -0,0 +1,11 @@
+{
+  "cacheSchema": "./libsql-semantic-cache-schema-v2.sql",
+  "cacheSchemaSha256": "679edfc3cb02dc768843976093f90d5879d53e84b797ac60d77956a634facae9",
+  "digestFixture": "./libsql-semantic-digest-fixture-v2.json",
+  "id": "oh.semantic-cloud.v2",
+  "legacyCacheSchema": "../v1/libsql-semantic-cache-schema-v1.sql",
+  "profile": "../v1/cloudflare-embedding-profile.json",
+  "renderer": "../v1/cloudflare-embedding-renderer.json",
+  "specification": "./semantic-cloud.md",
+  "v": 2
+}

package/spec/v2/semantic-cloud.md

@@ -0,0 +1,106 @@
+# Hosted semantic cache V2
+
+Hosted semantic-cache V2 is the isolated successor to the immutable
+[semantic-cache V1 contract](../v1/semantic-cloud.md). It keeps the same fixed
+Cloudflare EmbeddingGemma profile and renderer, but changes only the rebuildable
+libSQL cache protocol. It does not change an Oh graph, record, operation, local
+embedding, or provider contract.
+
+Applications use `bootstrapOhLibSqlSemanticCacheV2` and
+`openOhLibSqlSemanticCacheV2`. The parallel
+`bootstrapOhLibSqlSemanticCacheV1`, `openOhLibSqlSemanticCacheV1`, V1 types,
+V1 result values, and V1 digest preimages remain the released V1 behavior. V1
+and V2 use the same physical table names and therefore cannot be open in one
+database simultaneously. A V1 database can be upgraded to V2; a V2 database
+cannot be opened as V1 or downgraded.
+
+The host MUST quiesce V1 stage, publish, head, and search traffic before
+upgrade. An already-open V1 object is not a V2 runtime capability. Bootstrap
+does, however, arbitrate a racing V1 purge: a purge committed before transition
+custody is copied, while a purge that reaches the changed schema cannot report
+success.
+
+## Isolation and identity
+
+Every V2 authority reference and every stage, publish, head, search, receipt,
+and purge operation binds an `isolationSha256`. It is a validated opaque
+SHA-256 supplied by the host. Private hosts SHOULD derive it from their private
+authority handle, cache epoch, and exact cache profile. When omitted, Oh derives:
+
+```json
+{"authorityId":"<authority>","kind":"oh.semantic-authority-isolation.v2","v":2}
+```
+
+and hashes the canonical JSON. One isolation belongs immutably to one authority,
+while one authority may reserve multiple isolation epochs. The digest never
+enters renderer or provider text.
+
+Vector primary identity is
+`(isolation_sha256, profile_sha256, renderer_sha256, input_sha256)`.
+Generations, memberships, and published heads retain the isolation explicitly.
+The membership digest hashes a canonical
+`oh.semantic-membership.v2` envelope; the generation digest hashes an
+`oh.semantic-generation.v2` envelope. Consequently identical rendered text in
+different authorities or epochs is embedded and stored independently. Isolation
+prevents reuse and deletion coupling; it is not encryption and a database holder
+can still observe equal raw input digests or vector bytes.
+
+All public V2 values use `v: 2`. Provider and renderer values remain V1 because
+those fixed contracts did not change.
+
+## Published reads and purge custody
+
+`publishedHead` returns `null` for an isolation mismatch. Search checks the
+same isolation before sending a query to the provider and again while reading
+memberships. Publish requires the staged generation's exact isolation.
+
+`purgeAuthority` accepts the current published isolation, writes the permanent
+authority tombstone, deletes every generation and membership for the authority,
+and deletes every vector in every isolation reserved by it. A mismatched current
+isolation is a conflict and authorizes no deletion. The receipt records the
+first execution's counts and returns them unchanged on replay. It contains
+`purgeMarkerSha256`, the canonical
+`oh.semantic-purge-receipt.v2` `purgeReceiptSha256`, and zero
+`residualGenerations`, `residualMemberships`, and
+`residualScopedVectors`. `purgeReceipt` replays the same content-free proof
+without issuing deletes.
+
+## V1-to-V2 transition
+
+Bootstrap recognizes only the exact published V1 inventory or the exact V2
+inventory. An upgrade first starts one atomic write transaction that:
+
+1. creates `oh_semantic_v1_purge_transition`;
+2. copies every V1 authority tombstone into it with one database-side
+   `INSERT ... SELECT`;
+3. only after that copy, drops the unsafe globally deduplicated V1 derived rows;
+   and
+4. creates the V2 schema without a V2 schema marker.
+
+The copy has no lifetime tombstone cap and returns no unbounded row set to the
+host. A concurrent V1 purge either commits before this transaction and is copied,
+or runs afterward against a non-V1 schema and cannot report success. Concurrent
+V2 bootstraps converge on the one transition table.
+
+While the transition table exists, `openOhLibSqlSemanticCacheV2` fails closed.
+Bootstrap reads transition rows in fixed pages. Each page atomically creates the
+V2 isolation and receipt for every legacy tombstone and deletes a transition row
+only when the complete computed V2 custody record exists. A crash before a page
+commit changes nothing; a crash after commit can replay safely. Live V1 heads,
+generations, memberships, and vectors are deliberately invalidated because their
+global vector identity cannot be assigned a private owner after the fact.
+
+Finalization inserts the exact V2 schema marker only when the transition table
+is empty, then drops that table in the same transaction. Until that commit,
+neither a partially projected database nor a V2 runtime is accepted. Legacy
+receipts use `countsRecorded: false`; new V2 purges use
+`countsRecorded: true`.
+
+The exact standalone schemas are
+[revision 1](../v1/libsql-semantic-cache-schema-v1.sql) and
+[revision 2](libsql-semantic-cache-schema-v2.sql). Fixed
+[V1](../v1/libsql-semantic-digest-fixture-v1.json) and
+[V2](libsql-semantic-digest-fixture-v2.json) fixtures make the incompatible
+digest domains explicit. Hosted failure remains a
+missing derived retrieval lane and MUST NOT weaken exact graph or Datalog
+operations.

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.2" as const;
 
 type ParsedArguments = { options: Map<string, string[]>; positionals: string[] };
 type ValidatedInvocation = Readonly<{