@hraness/oh 0.3.1 → 0.4.0

package/README.md

@@ -2,15 +2,49 @@
 
 [![skills.sh](https://skills.sh/b/hraness/oh)](https://skills.sh/hraness/oh)
 
-Oh is a local-first ontology kernel, SQLite store, CLI, TypeScript SDK, and
-Agent Skill for building durable, inspectable research graphs. It stores
-content-addressed records and an append-only operation log, checks every
-mutation against an explicit versioned contract, and keeps keyword and semantic
-indexes derived and replaceable.
+Turn a research question into an artifact whose sources, claims, citations,
+dependencies, and change history remain inspectable in one local SQLite file.
+Oh is the ontology kernel, store, CLI, TypeScript SDK, and Agent Skill behind
+that path. It stores content-addressed records and an append-only operation log,
+checks every mutation against an explicit versioned contract, and keeps keyword
+and semantic indexes derived and replaceable.
 
 [Website](https://oh.computer) · [Versioned specification](spec/README.md) ·
 [Agent Skill](skills/oh/SKILL.md)
 
+## From a question to an inspectable artifact
+
+Oh supplies a versioned graph envelope and a small ontology kernel. A research
+application can map familiar work onto explicit records without hiding meaning
+in a database convention:
+
+| Research object | Oh record kind | What becomes inspectable |
+| --- | --- | --- |
+| Question | `inquiry` | The question and its durable investigation trail. |
+| Source | `entity` | A stable identity for a paper, dataset, person, or system. |
+| Capture | `edition` | A bounded source edition or extract under an application profile. |
+| Claim | `statement` | The proposition, separate from who accepts it. |
+| Citation | `evidence` | How a passage, table, or observation bears on an assertion. |
+| Artifact | `view` | A derived brief or answer with addressable inputs. |
+
+An attributable `assertion` sits between a claim and the evidence that bears on
+it. A small review can therefore leave an inspectable path instead of one
+opaque answer:
+
+```text
+inquiry:primary-endpoint
+  → entity:trial-report
+  → edition:trial-report-v1
+  → statement:endpoint-12-weeks
+  → assertion:endpoint-12-weeks
+  → evidence:table-2
+  → view:review-brief
+```
+
+The [homepage trace](https://oh.computer/#trace) shows the exact CLI read and a
+schema-checked illustrative evidence record. It is a model of record custody,
+not a claim about a real study.
+
 ## Why Oh
 
 - **Make meaning explicit.** Every record declares a kind, stable logical key,
@@ -28,7 +62,7 @@ indexes derived and replaceable.
 - **Derive without silently asserting.** Positive recursive rules run against
   one exact graph head and fact-pack digest. Their tuples and bounded proofs
   are deterministic, disposable output rather than accepted graph records.
-- **Remember without conflating authority.** An experimental facade composes a
+- **Remember without conflating authority.** A stable host-bound facade composes a
   purgeable working authority with one pinned canonical head while preserving
   lane, conflict, record, and proof provenance.
 
@@ -40,16 +74,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.1
+bun add --global @hraness/oh@0.4.0
 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.1),
+[immutable GitHub Release](https://github.com/hraness/oh/releases/tag/v0.4.0),
 including the mirrored
-[`hraness-oh-0.3.1.tgz`](https://github.com/hraness/oh/releases/download/v0.3.1/hraness-oh-0.3.1.tgz)
+[`hraness-oh-0.4.0.tgz`](https://github.com/hraness/oh/releases/download/v0.4.0/hraness-oh-0.4.0.tgz)
 and
-[`SHA256SUMS`](https://github.com/hraness/oh/releases/download/v0.3.1/SHA256SUMS).
+[`SHA256SUMS`](https://github.com/hraness/oh/releases/download/v0.4.0/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 +141,7 @@ For a project dependency, pin the same immutable release in `package.json`:
 ```json
 {
   "dependencies": {
-    "@hraness/oh": "0.3.1"
+    "@hraness/oh": "0.4.0"
   }
 }
 ```
@@ -145,6 +179,13 @@ Pass the head you actually reviewed when concurrent writers matter. Do not
 retry `OhConflictError` blindly. Read the new head and records, reconcile the
 intended change, then submit a new operation.
 
+The core `OhConflictError`, `OhIntegrityError`, `OhDependencyError`, and
+`OhProfileError` classes keep their `instanceof` identity across separately
+bundled Oh entrypoints. Their matching `isOhConflictError`,
+`isOhIntegrityError`, `isOhDependencyError`, and `isOhProfileError` guards
+accept unknown caught values only when they are native, immutably branded Oh
+errors; copying a name or prototype onto a plain object is not enough.
+
 The root entrypoint exports canonical JSON, ontology, schema, graph, operation,
 store, and sync contracts. Use `@hraness/oh/store` for the runtime-neutral
 promise interface, `@hraness/oh/libsql` for a direct Node 24 or serverless
@@ -155,8 +196,9 @@ the local `Oh` facade, `@hraness/oh/sync` for transport seams,
 `@hraness/oh/semantic-cloud` for the Cloudflare EmbeddingGemma plus direct
 libSQL derived-cache adapter. Use the narrow stable `@hraness/oh/memory-page`
 entrypoint for model-neutral page records and `.oh.md` interchange. The
-`@hraness/oh/experimental/memory` subpath composes host-bound working and
-canonical stores behind a smaller agent-facing surface.
+stable `@hraness/oh/memory` subpath composes host-bound working and canonical
+stores behind separate agent and host-control surfaces. The former
+`@hraness/oh/experimental/memory` path remains as a compatibility alias.
 
 ## Open a scoped working store
 
@@ -219,19 +261,42 @@ only on `authority.host`; do not expose that object or raw database credentials
 through a model tool. Read the [store-port specification](spec/v1/store.md) for
 exact snapshot, change-feed, codec ingress, closure, and purge behavior.
 
+A Bun SQLite authority opened with the canonical profile instead exposes
+`authority.host.replication`. Its `exportBundle` result preserves the pinned
+change-feed `from`, `to`, `through`, and `hasMore` evidence; `importBundle`
+strictly parses and applies the complete bundle atomically. The capability is
+absent from `authority.store` and is `null` for working profiles. Long-running
+hosts can capture a bounded bundle, close local custody for network I/O, then
+reopen and revalidate before one atomic import.
+
 ## Compose working and canonical memory
 
-The experimental memory facade uses the same Oh kernel twice, not a separate
-memory database model. Trusted host code supplies two distinct physical store
-handles, their expected binding digests, one exact canonical head, sealed
-working codecs, digest-identified fact extractors, and a closed registry of
-named projection programs:
+The stable `@hraness/oh/memory` entrypoint uses the same Oh kernel twice, not a
+separate memory database model. Trusted host code supplies two distinct
+physical store handles, their expected binding digests, one exact canonical
+head, sealed working codecs, digest-identified fact extractors, and closed
+registries of named projection programs and nomination routes.
+
+Hosts that must fit canonical history into a narrower encrypted transport can
+set `maximumCanonicalOperationBytes`. The exact canonical operation is checked
+before its compare-and-swap persists; working-memory capacity is unaffected.
+This pre-effect refusal is an `OhOperationSizeError`, a `RangeError` subtype
+with the actual and configured canonical byte counts and the stable code
+`oh.operation-size.v1`. The class remains recognizable across Oh package
+entrypoints; `isOhOperationSizeError` is also exported for validating unknown
+caught values without accepting a plain object that merely copied those public
+fields.
+
+Use `createOhMemoryAuthorityV1` for an application integration. It returns an
+`agent` object with only `remember`, `query`, `explain`, and `nominate`, plus a
+separate `host` object for canonical-head rollover and reviewed adoption:
 
 ```ts
-import { createOhMemoryAgentV1 } from "@hraness/oh/experimental/memory";
+import { createOhMemoryAuthorityV1 } from "@hraness/oh/memory";
 
-const memory = await createOhMemoryAgentV1({
+const memory = await createOhMemoryAuthorityV1({
   actorId: "research.memory-agent",
+  adoptionActorId: "research.memory-reviewer",
   canonical: {
     authorityId: "project-reviewed",
     expectedBindingSha256: canonical.store.binding.bindingSha256,
@@ -242,12 +307,7 @@ const memory = await createOhMemoryAgentV1({
     destinationPurpose: "kb.review",
     nominationId: "knowledge-review",
   }],
-  programs: [{
-    programId: "project.dependencies",
-    purpose: "answer.research",
-    query,
-    rulePack,
-  }],
+  programs: [projectDependenciesProgramV2],
   working: {
     authorityId: "thread-working",
     codecs,
@@ -256,97 +316,79 @@ const memory = await createOhMemoryAgentV1({
   },
 });
 
-const result = await memory.query({
+const result = await memory.agent.query({
+  bindings: {},
+  continuation: null,
   programId: "project.dependencies",
-  v: 1,
+  v: 2,
 });
-```
 
-When the model must bind a small set of values and traverse a larger result,
-use the additive V2 factory. The host still owns the query and rules. It names
-only query-body variables as parameters and fixes every evaluation, row, page,
-and page-byte limit before exposing the agent object:
-
-```ts
-import { createOhMemoryAgentV2 } from "@hraness/oh/experimental/memory";
+const nomination = await memory.agent.nominate({
+  nominationId: "knowledge-review",
+  roots: ["edition:reviewed-summary"],
+  v: 1,
+});
+await memory.host.adoptNomination({
+  expectedCanonicalHead: result.identity.canonical.head,
+  nomination,
+  v: 1,
+});
 
-const memoryV2 = await createOhMemoryAgentV2({
-  actorId: "research.memory-agent",
-  canonical: {
-    authorityId: "project-reviewed",
-    expectedBindingSha256: canonical.store.binding.bindingSha256,
-    expectedHead: await canonical.store.head(),
-    store: canonical.store,
-  },
-  extractors: [valueChunkExtractor],
-  programs: [{
-    evaluation: {
-      maximumDerivedTuples: 8_192,
-      maximumProofDepth: 32,
-      maximumProofNodes: 1_024,
-      maximumResultBytes: 8 * 1024 * 1024,
-      maximumRounds: 64,
-      maximumTotalProofNodes: 16_384,
-      maximumWorkUnits: 1_000_000,
-    },
-    maximumPageBytes: 1024 * 1024,
-    maximumRows: 4_096,
-    pageSize: 128,
-    parameters: ["key", "lane"],
-    programId: "memory.value-chunks",
-    purpose: "answer.memory",
-    query: valueChunkQuery,
-    rulePack: valueChunkRules,
-    v: 2,
+// To replace an existing key, trusted host code must prove the reviewed
+// canonical digest. Omit replacements to retain strict insert-only adoption.
+await memory.host.adoptNomination({
+  expectedCanonicalHead: reviewedCanonicalHead,
+  nomination: revisedNomination,
+  replacements: [{
+    expectedPriorRecordSha256: reviewedRecord.recordSha256,
+    key: reviewedRecord.key,
+    v: 1,
   }],
-  working: {
-    authorityId: "thread-working",
-    codecs,
-    expectedBindingSha256: working.store.binding.bindingSha256,
-    store: working.store,
-  },
+  v: 1,
 });
-
-let continuation: string | null = null;
-do {
-  const page = await memoryV2.query({
-    bindings: { key: "entity:research", lane: "working" },
-    continuation,
-    programId: "memory.value-chunks",
-    v: 2,
-  });
-  continuation = page.continuation;
-} while (continuation !== null);
 ```
 
-V2 evaluates one complete bounded result before paging it. Any projection row
-or byte truncation returns no page. A continuation is an authenticated bearer
-cursor that binds its offset to the exact physical heads, program, bindings,
-projection result, page size, and row count, so a working-head change fails
-instead of mixing snapshots. Pass it back only to the same exact named query;
-do not synthesize, edit, or log it.
-
-The factory generates a random continuation key by default, which makes a
-cursor valid only for that agent instance. If the host reconstructs agents or
-routes queries across replicas, pass the same host-owned 32 through 64 byte
-`Uint8Array` as `continuationKey`. The factory clones it; key rotation
-invalidates outstanding cursors. The result publishes a deterministic
-`continuationSha256` separately, and `resultSha256` commits that digest rather
-than the opaque key-dependent token.
-
-The returned object has only `remember`, `query`, `explain`, and `nominate`.
-The host fixes the working actor, each program purpose, and every nomination
-destination before exposing those methods. `remember` accepts an idempotency
-request plus semantic changes and returns a locator-free working-lane receipt;
-it does not accept caller-supplied actor or time claims. The object cannot
-select a store, install a rule, write canonical knowledge, sync, or purge.
-Query identity binds both exact physical lanes and all projection policy;
-conflicting same-key records remain visible. Explanation requires a bounded,
-short-lived opaque capability bound to the exact result. Nomination chooses
-only a host-registered route and creates a verified working dependency-closure
-proposal; it never promotes it. Read the
-[experimental memory specification](spec/v1/memory.md) for the complete
-authority and lifecycle boundary.
+`adoptNomination` parses the complete proposal, checks its host-selected route
+and working authority, and re-exports the closure from the exact nominated
+working head. An absent record is inserted, an equal digest is already present,
+and a different digest fails closed by default. Trusted host code can authorize
+an intentional replacement only by naming the logical key and its exact
+reviewed prior digest in a bounded `replacements` list. Missing, stale, wrong,
+duplicate, or absent-key claims fail without a partial write. Every supplied
+claim is checked, including claims for keys already at their nominated digest;
+an exact replay validates those claims against its exact reviewed head. The
+inserts and authorized replacements share one compare-and-swap operation; the existing
+parent-head and record-change bytes carry the transition without a new persisted
+format. Before that commit, the authority proves that the prospective canonical
+snapshot stays within 8,192 records and 32 MiB. After it, the authority re-reads
+the physical head, so a reachable duplicate operation or a later writer cannot
+make it install an obsolete intermediate head. A stale expected head succeeds
+only when the current physical snapshot contains every nominated digest exactly.
+
+`advanceCanonical` moves the facade's pin only from its current exact head to
+the same head or a proven descendant in the bound canonical operation chain.
+One call proves at most 16,384 operations over at most 64 bounded pages; callers
+must advance longer histories in reviewed chunks. Host mutations are
+serialized. A query already in flight keeps the immutable pin it captured,
+existing explanation capabilities survive rollover in one shared 64 MiB cache,
+and an old continuation fails when the memory identity changes.
+
+Every stable method snapshots unknown JSON input through data-property
+descriptors before validation. Accessors, symbols, proxies, sparse arrays, and
+non-JSON values fail closed, and execution uses only the detached bytes. The
+snapshot walk is capped at 128 levels, 65,536 entries per container, and
+1,048,576 total nodes, and counts canonical bytes before it clones each child.
+
+V2 evaluates one complete bounded result before paging it. Agent input may bind
+only host-declared primitive query-body parameters; it cannot choose sources,
+rules, purpose, page size, or evaluation limits. Pass an issued continuation
+back unchanged only to the same named query and do not log it. Catch
+`OhMemoryContinuationError` when a supplied cursor needs to be restarted; its
+`reason` distinguishes encoding, authentication, and exact-identity failures.
+Other store and projection failures keep their original types. The compatibility
+alias `@hraness/oh/experimental/memory` remains available, but new integrations
+should use `@hraness/oh/memory`. Read the [memory specification](spec/v1/memory.md)
+for the complete authority, conflict, pagination, and lifecycle boundary.
 
 ## Use a memory page or `.oh.md` file
 
@@ -528,18 +570,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,43 +595,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: "thread:research/epoch:1",
+  authorityId,
+  isolationSha256,
 });
 await cache.publish({
-  authorityId: "thread:research/epoch:1",
+  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
 
@@ -615,10 +674,18 @@ try {
 
 The consumer owns credentials, client construction, retry policy, and remote
 availability. The transport handshakes before exchanging data and refuses a
-different contract or a non-fast-forward history.
+different contract or a non-fast-forward history. Canonical bundles share one
+64 MiB plus 4 KiB byte/node budget across at most 1,000 operations. If a retry
+finds that another writer has advanced beyond its submitted tail, the libSQL
+adapter acknowledges that tail only after every submitted sequence, digest,
+and canonical operation still matches the bounded remote row range. Histories
+larger than one bundle advance through the largest fitting operation prefix in
+each direction.
 
 For offline transfer, `oh sync export` writes a bounded bundle to stdout and
-`oh sync import --file <path>` verifies and imports it idempotently.
+`oh sync import --file <path>` verifies and imports it idempotently in one
+atomic transaction. Import refuses non-regular or oversized bundle files before
+opening the local authority.
 
 ## Boundaries and limitations
 
@@ -652,9 +719,9 @@ keep remote sync explicit.
 You can also give an agent this prompt:
 
 ```text
-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
+Install @hraness/oh@0.4.0 from npm and use its packaged Oh Agent Skill. The
+exact npm tarball and SHA256SUMS are mirrored by the immutable v0.4.0 Release at
+https://github.com/hraness/oh/releases/tag/v0.4.0. 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.1";
+export declare const OH_PACKAGE_VERSION: "0.4.0";
 export declare function runOhCli(arguments_: readonly string[]): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAWA,eAAO,MAAM,kBAAkB,EAAG,OAAgB,CAAC;AA0MnD,wBAAsB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuF7E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAWA,eAAO,MAAM,kBAAkB,EAAG,OAAgB,CAAC;AAyNnD,wBAAsB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkG7E"}