@hraness/oh 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/oh",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "open-source tools for agentic research",
   "type": "module",
   "license": "MIT",
@@ -68,6 +68,10 @@
       "types": "./dist/memory-page.d.ts",
       "import": "./dist/memory-page.js"
     },
+    "./memory": {
+      "types": "./dist/memory.d.ts",
+      "import": "./dist/memory.js"
+    },
     "./projection": {
       "types": "./dist/projection-public.d.ts",
       "import": "./dist/projection-public.js"

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.2`. Its identical
-tarball and checksum are mirrored by the immutable GitHub Release `v0.3.2`.
+The supported CLI is the exact npm release `@hraness/oh@0.4.0`. Its identical
+tarball and checksum are mirrored by the immutable GitHub Release `v0.4.0`.
 It requires Bun 1.3.14 or newer. The versioned contract is published at
 <https://oh.computer/spec/>.
 
@@ -168,14 +168,17 @@ and credential source. Never print credentials or embed them in records. Oh
 settles fast-forward histories only; preserve both logs when it reports a
 divergence.
 
-## Use composite memory only through host bindings
+## Use stable composite memory only through host bindings
 
-`@hraness/oh/experimental/memory` is an SDK-only surface. Do not let a model
-construct its options. Trusted application code must bind two distinct
-authority handles, exact binding digests, a pinned canonical head, working
-codecs, a working actor, domain extractor relation ownership and digests,
-host-purposed named rule/query programs, and named nomination routes before
-giving the returned object to an agent.
+`@hraness/oh/memory` is a stable SDK-only surface. Use
+`createOhMemoryAuthorityV1`, and do not let a model construct its options.
+Trusted application code must bind two distinct authority handles, exact
+binding digests, a pinned canonical head, working codecs, working and adoption
+actors, domain extractor relation ownership and digests, host-purposed named
+rule/query programs, and named nomination routes. Give only the returned
+`authority.agent` object to an agent; retain `authority.host` in trusted
+control-plane code. The old `@hraness/oh/experimental/memory` subpath is a
+compatibility alias, not the preferred import.
 
 The agent-facing object may call only `remember`, `query`, `explain`, and
 `nominate`. Never add a tool parameter for a database path or URL, authority,
@@ -186,18 +189,41 @@ as derived. A nomination may select only a host-registered route and is a
 prepared dependency-closure candidate for destination-owned review, not
 permission to write durable knowledge or import the working operation chain.
 
+Host adoption must pass the complete prepared nomination back through
+`authority.host.adoptNomination` with the exact canonical head it reviewed.
+The host control re-exports the closure from the bound working store, inserts
+absent records in one compare-and-swap operation, and treats equal digests as
+already present. A different digest fails closed unless trusted host code adds
+a bounded `replacements` claim with that exact logical key and exact reviewed
+prior record digest. Never derive that claim from model input or retry it
+against a new head. Missing, stale, wrong, duplicate, and absent-key claims
+abort every change. The host rejects a prospective canonical snapshot over
+8,192 records or 32 MiB, and reconciles the physical head after the commit so
+an idempotent replay cannot install an older head. Do not suppress its
+structured conflict evidence. Use `advanceCanonical` only for the same pin or
+an exact later head already proven by the bound canonical operation chain.
+Advance more than 16,384 operations in separate reviewed chunks.
+
 Use `createOhMemoryAgentV2` only when the host has registered primitive
 query-body parameters and fixed all projection, row, page, and page-byte
 limits. Expose only the exact bindings object, program ID, and continuation to
 the model. Do not expose parameter declarations, page size, or evaluator
 options as tool input. Follow `hasMore` until the continuation is `null`, and
-restart the named query after an integrity error; never combine pages across a
-working-head change. A V2 `query-limit` or `result-bytes` condition is a failed
-query, not a partial answer. Treat each continuation as a bearer cursor: pass
-it back unchanged only to the exact query and do not log or edit it. If the
-host reconstructs the facade or routes across replicas, it must provide the
-same private 32 through 64 byte `continuationKey` in host options; never expose
-that key as tool input. Keep row-level `proofsTruncated` evidence visible.
+restart the named query only after `OhMemoryContinuationError`; never combine
+pages across a working-head change. Store, projection, and extractor failures
+are not continuation failures and need their own handling. A V2 `query-limit`
+or `result-bytes` condition is a failed query, not a partial answer. Treat each
+continuation as a bearer cursor: pass it back unchanged only to the exact query
+and do not log or edit it. If the host reconstructs the facade or routes across
+replicas, it must provide the same private 32 through 64 byte
+`continuationKey` in host options; never expose that key as tool input. Keep
+row-level `proofsTruncated` evidence visible.
+Explanation capabilities share one 256-entry, 64 MiB cache and one clock guard
+across canonical rollover; do not build a second token router around the
+authority. Pass only plain JSON data to stable methods. Accessors, symbols,
+proxies, sparse arrays, and non-JSON values are rejected before execution.
+The detached-input walk caps depth, per-container breadth, total nodes, and
+canonical bytes before recursively cloning untrusted children.
 
 ## Keep memory pages model-neutral
 

package/spec/README.md

@@ -21,7 +21,7 @@ binds these versions:
 | 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` |
+| Composite memory | `stable V1 authority over V2 query` |
 | Memory page | `oh.memory-page.v1` |
 
 ## V1 documents
@@ -37,7 +37,7 @@ binds these versions:
 - [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)
+- [Composite agent memory](v1/memory.md)
 - [Memory pages and `.oh.md` interchange](v1/memory-page.md)
 - [Compatibility and migration](v1/migration.md)
 

package/spec/v1/memory.md

@@ -1,8 +1,9 @@
-# Experimental composite agent memory
+# Composite agent memory
 
-`@hraness/oh/experimental/memory` is the first consumer-facing composition of
-the stable store and projection contracts. It is experimental API, not a new
-ontology or a third storage authority.
+`@hraness/oh/memory` is the stable consumer-facing composition of the store and
+projection contracts. It is an application authority boundary, not a new
+ontology or a third storage authority. The former
+`@hraness/oh/experimental/memory` path remains an export-compatible alias.
 
 ## One kernel, two authorities
 
@@ -23,9 +24,13 @@ The host also binds the working actor, every named program's purpose, and every
 named nomination route. None of those authority-bearing labels comes from
 agent input.
 
-The returned object exposes only `remember`, `query`, `explain`, and
-`nominate`. It has no generic commit, store selection, path, sync, rule
-registration, canonical write, or purge operation.
+`createOhMemoryAuthorityV1` returns separate `agent` and `host` objects. The
+agent exposes only `remember`, `query`, `explain`, and `nominate`. It has no
+generic commit, store selection, path, sync, rule registration, canonical
+write, adoption, rollover, or purge operation. The host object exposes only
+serialized canonical-head rollover and reviewed nomination adoption. The
+lower-level V1 and V2 agent factories remain available for hosts that already
+own an equivalent control plane.
 
 `remember` accepts only an expected working head, semantic puts and tombstones,
 and an idempotency request ID. The facade supplies its host-bound actor, uses
@@ -70,9 +75,9 @@ silently canonical. Returned result, row, value, proof, source, and receipt
 graphs are detached and deeply immutable, so a caller cannot mutate bytes after
 their digest or explanation capability is issued.
 
-## Additive parameterized pagination (V2 experimental API)
+## Parameterized pagination (V2)
 
-`createOhMemoryAgentV2` is an additive experimental query surface. It does not
+`createOhMemoryAgentV2` is an additive query surface. It does not
 change a V1 request, result, digest preimage, factory, or type. Its `remember`
 and `nominate` methods continue to use the V1 semantic-bundle and nomination
 contracts. Only its `query` and `explain` envelopes use V2.
@@ -138,8 +143,15 @@ continuation and checks its program, binding, page-size, range, and alignment
 before reading the working store, invoking extractors, evaluating rules, or
 mapping proofs. Every valid continued call then rereads the current working
 head and rebuilds the projection. A head, source, result, or row-count change
-fails with an integrity error before proof mapping rather than mixing pages
-from two snapshots.
+fails before proof mapping rather than mixing pages from two snapshots.
+
+`OhMemoryContinuationError` is the exact public discriminator for a supplied
+cursor that cannot be decoded, authenticated, or rebound to the current exact
+identity. It extends `OhIntegrityError`, carries
+`code: "memory-continuation"`, and classifies `reason` as `encoding`,
+`authentication`, or `identity`. Store verification, projection evaluation,
+extractor, and other runtime failures retain their original error types; the
+facade does not relabel them as continuation failures.
 
 An outward result publishes `continuationSha256` beside the opaque token, or
 `null` beside `null` on the final page. `resultSha256` commits that deterministic
@@ -169,6 +181,110 @@ canonical store, import a derived tuple, grant rights, record a review, or turn
 a proposed assertion into reviewed knowledge. Destination-owned application
 code must perform those steps under its own policy and compare-and-swap head.
 
+## Stable host control
+
+`createOhMemoryAuthorityV1` wraps the V2 agent and binds a separate adoption
+actor. Both host methods accept `unknown`, require exact versioned envelopes,
+and execute serially. A model-facing adapter MUST receive only `authority.agent`;
+it MUST NOT receive `authority.host`, either physical store, or the authority
+factory options.
+
+`advanceCanonical` requires the current complete pinned head and a complete
+next head. An equal next head returns an immutable `unchanged` receipt. A later
+head is accepted only after the canonical change feed proves an uninterrupted
+path from the current pin and an exact bounded snapshot reproduces the complete
+next head. The returned `advanced` receipt binds the authority ID, binding
+digest, prior head, and new head. A stale expected head, earlier head, missing
+operation, fork, changed binding, malformed page, or snapshot mismatch fails
+without changing the pin. One call proves at most 16,384 operations and at most
+64 change-feed pages. The total operation bound is checked before the first
+fetch; hosts MUST advance a longer reachable history in reviewed chunks.
+
+Each query captures the current agent instance before its first asynchronous
+read. A rollover therefore cannot mix canonical snapshots into an in-flight
+query. All reconstructed agent generations share one explanation registry,
+byte accounting, wall-clock guard, and monotonic-clock guard. An existing
+explanation capability therefore continues to refer to its original result,
+while the 256-entry and 64 MiB eviction limits and expiry order remain global
+across rollover. Every reconstructed instance also uses the same private
+continuation key. A continuation issued before rollover still authenticates,
+then fails its exact memory-identity check if either source head changed.
+
+`adoptNomination` requires an exact expected canonical head and a parsed
+`OhMemoryNominationV1`. It verifies the host-registered nomination route,
+destination purpose, working authority ID, and binding digest. It then asks the
+actual bound working store to re-export the dependency closure at the
+nomination's exact source head and requires byte equality with the proposal.
+This prevents a detached, substituted, or stale capsule from becoming a write
+request merely because its own digest is valid.
+
+At the current canonical snapshot, an absent nominated record becomes a put and
+an equal record digest is already present. A different digest remains a strict
+conflict unless trusted host code supplies a `replacements` claim for that exact
+logical key and exact prior canonical record digest. A request may carry at most
+128 claims. Every claim has the exact keys `expectedPriorRecordSha256`, `key`,
+and `v`; keys must be unique and must name a record in the verified nomination.
+A missing, stale, or wrong claim for a record that still needs replacement is a
+conflict. A claim for an absent canonical key is also a conflict rather than
+permission to insert it. Every supplied claim is validated even when that key
+is already at its nominated digest. An exact replay checks such claims against
+the request's exact reviewed expected head, preserving idempotence without
+silently accepting an invented or stale extra claim. A claim conflict reported
+against an already-equal current record therefore carries equal canonical and
+nominated digests. With no invalid claim, the record remains eligible for the
+existing idempotent `already-present` reconciliation.
+
+Any blocking conflict aborts every insert and replacement. Otherwise adoption
+uses a deterministic operation ID derived from the host-bound adoption actor,
+canonical binding, nomination digest, and exact prior complete head. The head
+component preserves exact replay while allowing the same nomination to be
+reviewed and adopted again after a later canonical overwrite or tombstone.
+Before writing, it applies every
+changed nominated record to the pinned snapshot and rejects a result over 8,192
+records or 32 MiB. It then performs one compare-and-swap commit with no merge
+retry. Replacement claims are host-side admission evidence, not new operation
+fields: the existing operation binds the exact parent head and complete changed
+records, so the persisted V1 graph and operation bytes need no new shape. After
+the commit returns, the authority reads and proves the current physical head.
+It installs the returned head only when that is still the physical head; a
+reachable duplicate operation or later write is reconciled against the later
+exact snapshot. A stale expected head or already-ahead physical head may return
+`already-present` only when that current snapshot contains every nominated key
+at its exact nominated digest. This remains one compare-and-swap commit;
+reconciliation never retries it.
+
+A host may set `maximumCanonicalOperationBytes` when creating the authority.
+The SQLite commit constructs and hashes the exact operation, then rejects it
+before persistence when its canonical UTF-8 bytes exceed that bound. This lets
+an application guarantee that every admitted canonical operation fits its
+future encrypted transport without shrinking the separate working-memory
+limit. Exact idempotent replays remain subject to the same bound.
+The pre-effect refusal is an `OhOperationSizeError`, a `RangeError` subtype
+that exposes the exact operation bytes and configured maximum so a host can
+distinguish it from an ambiguous post-effect failure.
+
+An adoption conflict reports the expected and actual complete heads, total
+conflict count, whether the outward list was truncated, and at most 128 entries
+sorted by key. Each entry carries the nominated digest and the current
+canonical digest or `null` when the key is absent. `conflictsSha256` commits the
+complete sorted conflict set, including entries beyond the outward bound. The
+structured conflict is deeply immutable. Conflict handling and stale
+idempotency never overwrite a canonical record. The optional replacement path
+does not perform last-write-wins reconciliation: only the exact reviewed head
+and exact per-key prior digests authorize the single compare-and-swap.
+
+Every `unknown` request on the stable agent and host surfaces is recursively
+detached through enumerable data-property descriptors once at method entry.
+Accessors are never invoked; symbols, non-data properties, sparse arrays,
+non-JSON values, and proxies fail closed. Validation, canonical byte bounds,
+digests, and execution all consume that same frozen detached graph. Bound store
+responses are detached under the same rule before they are parsed or compared.
+Traversal admits at most 128 nested levels, 65,536 entries in one container,
+and 1,048,576 value nodes overall. It counts canonical UTF-8 bytes as it
+traverses and rejects an over-bound array before enumerating or cloning its
+entries; final canonical serialization must reproduce the incremental byte
+count.
+
 ## Memory pages and retrieval
 
 A memory page is an application profile for an ordinary `edition` record. Its
@@ -200,11 +316,13 @@ API boundary.
 The facade requests at most 8,192 records per lane, rejects a lane snapshot
 over 32 MiB, rejects a remember request over 8 MiB, bounds extractor
 invocations and emitted facts, limits the public result to 32 MiB, and retains
-at most 64 MiB of explanation evidence. A trusted store still constructs the
-snapshot before returning it, and a trusted synchronous fact extractor can
-consume time or temporary memory before it returns. Provider response limits,
-host storage quotas, callback review, isolation, deadlines, and cancellation
-remain application responsibilities.
+at most 64 MiB of explanation evidence across every canonical generation. The
+same record and byte ceilings are applied to a prospective adoption snapshot
+before its only compare-and-swap. A trusted store still constructs the snapshot
+before returning it, and a trusted synchronous fact extractor can consume time
+or temporary memory before it returns. Provider response limits, host storage
+quotas, callback review, isolation, deadlines, and cancellation remain
+application responsibilities.
 
 Suss is an optional differential evaluator behind the separate projection
 compatibility subpath. The memory facade uses the package-owned bounded

package/spec/v1/storage.md

@@ -50,7 +50,9 @@ application-profile digest, and declared capabilities. A supported runtime
 MUST reject a later attempt to open the same space under different binding
 bytes. A working profile disables operation replication and enables only
 host-controlled whole-space purge. A canonical profile cannot be purged by
-that API.
+that API. Its local SQLite authority may instead expose a canonical-only
+replication handle under host control; the promise-based agent store never
+carries that capability.
 
 Purge deletes the space head, complete operation history, current records,
 dependency and operation materializations, sync state, and derived keyword
@@ -78,10 +80,11 @@ before it is returned as current.
 
 ## Replay verification
 
-`oh verify` runs SQLite `integrity_check`, parses every canonical operation,
-replays the operation chain from an empty graph, recomputes record-set and graph
-revision digests, checks dependencies, compares the materialized records, and
-requires the reconstructed head to equal the stored head.
+`oh verify` runs SQLite `integrity_check` and `foreign_key_check`, parses every
+canonical operation, replays the operation chain from an empty graph,
+recomputes record-set and graph revision digests, checks dependencies, compares
+the materialized records, operation-record rows, search documents, and FTS rows,
+and requires the reconstructed head to equal the stored head.
 
 Backup and restore procedures SHOULD preserve the database and WAL atomically.
 An application SHOULD run replay verification after an untrusted transfer or

package/spec/v1/store.md

@@ -21,6 +21,26 @@ A historical read MUST fail if its sequence is absent or identifies a
 different operation digest. A change page MUST name its source cursor, pinned
 through-head, returned cursor, and whether more operations remain.
 
+A commit may declare `maximumOperationBytes`. The built-in SQLite and direct
+libSQL authorities measure the exact canonical operation before persistence,
+including on an exact operation-ID replay. Exceeding the host-declared bound
+throws `OhOperationSizeError`, a `RangeError` subtype carrying
+`operationBytes` and `maximumOperationBytes`; it never indicates an ambiguous
+post-effect failure. Its public `code` is `oh.operation-size.v1`, and
+`instanceof OhOperationSizeError` remains stable across separately bundled Oh
+entrypoints. Callers validating an unknown caught value may instead use
+`isOhOperationSizeError`; the guard requires a native error with immutable
+branded numeric fields, so copying the public fields onto a plain object is not
+sufficient.
+
+The core `OhConflictError`, `OhIntegrityError`, `OhDependencyError`, and
+`OhProfileError` classes likewise preserve `instanceof` identity across
+separately bundled Oh entrypoints. Their corresponding `isOhConflictError`,
+`isOhIntegrityError`, `isOhDependencyError`, and `isOhProfileError` guards
+require a native error with the immutable brand for that exact error family.
+A branded base class remains visible through an ordinary subclass, but a base
+instance MUST NOT satisfy an arbitrary subclass check.
+
 ## Semantic bundle ingress
 
 Model-facing code SHOULD use `OhSemanticBundleIngressV1` instead of generic

package/spec/v1/sync.md

@@ -25,11 +25,59 @@ interface OhOperationSyncTransportV1 {
 
 A bundle binds `oh.sync.v1`, the contract digest, one space ID, at most 1,000
 ordered operations, and its own digest. Operations MUST form one contiguous
-chain. An empty bundle is valid.
+chain. An empty bundle is valid. The complete canonical bundle is limited to
+64 MiB plus 4 KiB of envelope and operation-separator allowance, and to the
+equivalent finite JSON-node budget. Every operation, including its top-level
+strings, dependencies, and record values, consumes those shared limits; compact
+in-process graphs with repeated references do not multiply into unbounded
+detached data. `OH_SYNC_BUNDLE_MAX_BYTES_V1` exposes the canonical byte limit.
+
+The stock synchronizer selects the largest nonempty local prefix that fits
+these shared limits, even when the requested operation-count page is larger.
+The libSQL adapter applies the same cumulative canonical-byte predicate in its
+ordered remote query. A valid history larger than one bundle therefore advances
+in bounded pages instead of becoming permanently unsynchronizable. Host and
+offline exporters can request the same behavior with
+`createOhSyncBundleV1(spaceId, operations, { largestFittingPrefix: true })`.
 
 Parsing recomputes every operation digest and the bundle digest. Import also
 requires the bundle space to equal the selected local space and each operation
-to extend the exact local head.
+to extend the exact local head. The SQLite host replication handle applies a
+complete bundle in one `BEGIN IMMEDIATE` transaction. If any later operation
+fails semantic replay, no valid prefix is retained. An exact bundle already on
+the current authority chain is an idempotent replay.
+
+`parseOhSyncHeadV1` is the strict ingress for untrusted transport heads. It
+requires only `operationSha256`, `sequence`, and `v`, and enforces that sequence
+zero is the only null-digest head. `parseOhSyncHeadRefV1` applies the same
+descriptor-safe rules to an exact two-field host cursor. Both reject negative
+zero, accessors, proxies, and extra or hidden properties without invoking
+caller code. Bundle parsing checks exact envelopes and cheap collection limits
+before recursively detaching values; it rejects operations that parsing would
+otherwise normalize to different canonical JSON. Record-value detachment is
+limited to 128 nested levels, 1,048,576 traversed value nodes, and the graph
+record's 1 MiB canonical value ceiling. The parser also applies the 64 MiB
+canonical operation ceiling and an equivalent finite operation-node budget.
+Canonical string and container bytes are counted during traversal, and an
+array whose length cannot fit the remaining budget is rejected before its
+entries are enumerated or cloned. Shared object references consume the budget
+again for every canonical occurrence. Dependencies are preflighted under the
+same operation budget before any nested collection is cloned.
+
+## Host-controlled SQLite replication
+
+`createOhSqliteStoreAuthorityV1` keeps canonical replication on
+`authority.host.replication`; it is never a method on the agent-safe
+`OhStoreV1`. Working profiles receive no replication handle. The canonical
+handle exposes the exact binding, current head, pinned bundle export, and
+atomic bundle import.
+Import requires an exact strict head reference before parsing the bundle.
+
+Pinned export delegates to `changesSince(from, { limit, through })` and returns
+the page's exact `from`, `to`, `through`, and `hasMore` evidence with the
+canonical bundle. A writer that advances after `through` therefore cannot
+silently enlarge the exported interval. Applications SHOULD persist that
+bounded evidence before releasing local custody for network I/O.
 
 ## Settlement
 
@@ -42,9 +90,18 @@ compares heads:
 - Equal sequences with different digests, or any non-extending chain, are a
   conflict.
 
+A pull may not exceed the requested batch size. A page that reaches the
+observed remote sequence must end at that exact operation digest, and is
+rejected before import otherwise. A terminal pull or acknowledged terminal
+push settles in that same round after fresh local- and remote-head checks;
+callers do not need to reserve an extra observation round in `maximumRounds`.
+
 The synchronizer never performs last-write-wins merging. Divergent append-only
 histories remain intact for an explicit domain merge. Remote acknowledgments
-must equal the final pushed operation.
+must equal the final pushed operation. The stock synchronizer is convenient for
+simple transports and keeps the concrete store open while awaiting the network.
+Applications that journal uncertain effects SHOULD instead split capture,
+network exchange, and atomic import into separately revalidated host phases.
 
 ## libSQL and Turso seam
 
@@ -56,12 +113,24 @@ methods compatible with `@libsql/client`. It creates only:
 
 The application supplies the client, credentials, endpoint, access policy,
 retry policy, and backups. The adapter parameterizes values and verifies
-canonical operation JSON on pull. Semantic documents and vectors never cross
-this seam.
+canonical operation JSON on pull. Pull cursors are nonnegative, pull limits are
+1 through 1,000, a provider response may not exceed its requested row count,
+each raw operation JSON string is byte-bounded before parsing, and the ordered
+query returns only the largest prefix within the shared bundle byte ceiling.
+Semantic documents and vectors never cross this seam.
+
+Push retries are idempotent even if another writer has advanced the remote
+past the submitted tail. The adapter reads at most the submitted row count,
+requires every submitted sequence, digest, and canonical operation JSON to
+match the immutable remote rows, and acknowledges the submitted tail rather
+than the newer remote head. A missing or changed row fails closed.
 
 ## Offline transfer
 
 `oh sync export --after <sequence> --limit <count>` emits one canonical bundle.
-`oh sync import --file <path>` verifies and applies a bundle idempotently. A
-transfer process SHOULD preserve the exact bytes and SHOULD run `oh verify`
-after the final import.
+`oh sync import --file <path>` verifies and applies the complete bundle
+idempotently in one atomic import; an invalid later operation cannot leave a
+valid prefix behind. Before reading, the CLI requires a regular file no larger
+than the canonical bundle limit plus its one exported terminal LF, and checks
+the actual bytes again after the read. A transfer process SHOULD preserve the
+exact bytes and SHOULD run `oh verify` after the final import.

package/src/cli.test.ts

@@ -1,9 +1,15 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { existsSync } from "node:fs";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, truncate, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
+import { canonicalJson, canonicalSha256 } from "./canonical";
+import { createKnowledgeGraphRecordV1 } from "./graph";
+import { createOhOperationV1 } from "./operation";
+import { OhSqliteStore } from "./sqlite/store";
+import { createOhSyncBundleV1, OH_SYNC_BUNDLE_MAX_BYTES_V1 } from "./sync";
+
 const roots: string[] = [];
 const CLI_PATH = join(import.meta.dir, "cli.ts");
 const REPOSITORY_ROOT = join(import.meta.dir, "..");
@@ -100,4 +106,50 @@ describe("oh CLI", () => {
     expect((await run(["contract", "--db", database, "--space", "contract.test"], root)).code).toBe(0);
     expect(existsSync(database)).toBe(false);
   });
+
+  test("imports a sync bundle atomically when a later operation is invalid", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-cli-atomic-import-test-"));
+    roots.push(root);
+    const database = join(root, "target.sqlite");
+    const bundlePath = join(root, "hostile-bundle.json");
+    const source = new OhSqliteStore({ path: ":memory:" });
+    const entity = (key: string, name: string) => createKnowledgeGraphRecordV1({
+      dependencies: [], key, kind: "entity", v: 1, value: { name },
+    });
+    source.commit({ actorId: "agent.test", changes: [{ kind: "put",
+      record: entity("entity:first", "First"), v: 1 }], expectedHead: source.head(),
+    operationId: "op_first" });
+    source.commit({ actorId: "agent.test", changes: [{ kind: "put",
+      record: entity("entity:second", "Second"), v: 1 }], expectedHead: source.head(),
+    operationId: "op_second" });
+    const [first, second] = source.exportOperations();
+    if (first === undefined || second === undefined) throw new Error("Expected two operations.");
+    const { operationSha256: _operationSha256, ...payload } = second;
+    const hostileSecond = createOhOperationV1({ ...payload,
+      graphRevisionSha256: canonicalSha256("hostile graph revision"),
+      recordsSha256: canonicalSha256("hostile records") });
+    await writeFile(bundlePath,
+      canonicalJson(createOhSyncBundleV1(source.spaceId, [first, hostileSecond])), "utf8");
+    source.close();
+
+    const imported = await run(["sync", "import", "--db", database, "--file", bundlePath]);
+    expect(imported.code).toBe(1);
+    expect(imported.stderr).toContain("does not reproduce");
+    const verified = await run(["verify", "--db", database]);
+    expect(verified.code).toBe(0);
+    expect(JSON.parse(verified.stdout)).toMatchObject({ operations: 0, records: 0 });
+  });
+
+  test("rejects an oversized sparse sync bundle before opening the database", async () => {
+    const root = await mkdtemp(join(tmpdir(), "oh-cli-bounded-import-test-"));
+    roots.push(root);
+    const database = join(root, "target.sqlite");
+    const bundlePath = join(root, "oversized-bundle.json");
+    await writeFile(bundlePath, "", "utf8");
+    await truncate(bundlePath, OH_SYNC_BUNDLE_MAX_BYTES_V1 + 2);
+    const imported = await run(["sync", "import", "--db", database, "--file", bundlePath]);
+    expect(imported.code).toBe(1);
+    expect(imported.stderr).toContain("regular file of at most");
+    expect(existsSync(database)).toBe(false);
+  });
 });

package/src/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { readFile } from "node:fs/promises";
+import { lstat, readFile } from "node:fs/promises";
 
 import { canonicalJson, opaqueId, safeCode, type JsonValue } from "./canonical";
 import { OH_CONTRACT_MANIFEST_V1 } from "./contract";
@@ -7,9 +7,9 @@ import { OH_KNOWLEDGE_GRAPH_RECORD_KINDS_V1, createKnowledgeGraphRecordV1,
   type KnowledgeGraphRecordKindV1, type KnowledgeGraphRecordV1 } from "./graph";
 import { Oh } from "./sdk";
 import { OH_SQLITE_SCHEMA_VERSION } from "./sqlite/migrations";
-import { createOhSyncBundleV1, parseOhSyncBundleV1 } from "./sync";
+import { createOhSyncBundleV1, OH_SYNC_BUNDLE_MAX_BYTES_V1, parseOhSyncBundleV1 } from "./sync";
 
-export const OH_PACKAGE_VERSION = "0.3.2" as const;
+export const OH_PACKAGE_VERSION = "0.4.0" as const;
 
 type ParsedArguments = { options: Map<string, string[]>; positionals: string[] };
 type ValidatedInvocation = Readonly<{
@@ -174,7 +174,7 @@ async function validateInvocation(command: string, parsed: ParsedArguments): Pro
       assertAllowedOptions(parsed, [...GLOBAL_OPTIONS, "file"]);
       const file = one(parsed, "file");
       if (file === undefined) throw new TypeError("sync import needs --file.");
-      syncBundle = parseOhSyncBundleV1(JSON.parse(await readFile(file, "utf8")));
+      syncBundle = parseOhSyncBundleV1(await readSyncBundleFile(file));
       if (syncBundle === null) throw new TypeError("Invalid sync bundle.");
     } else {
       throw new TypeError("sync needs export or import.");
@@ -191,6 +191,21 @@ async function validateInvocation(command: string, parsed: ParsedArguments): Pro
 
 function print(value: unknown): void { process.stdout.write(`${canonicalJson(value)}\n`); }
 
+async function readSyncBundleFile(path: string): Promise<unknown> {
+  // `sync export` writes one terminal LF after the bounded canonical bundle.
+  const maximumFileBytes = OH_SYNC_BUNDLE_MAX_BYTES_V1 + 1;
+  const metadata = await lstat(path);
+  if (!metadata.isFile() || !Number.isSafeInteger(metadata.size)
+    || metadata.size > maximumFileBytes) {
+    throw new RangeError(`Sync bundle file must be a regular file of at most ${maximumFileBytes} bytes.`);
+  }
+  const contents = await readFile(path);
+  if (contents.byteLength > maximumFileBytes) {
+    throw new RangeError(`Sync bundle file must be at most ${maximumFileBytes} bytes.`);
+  }
+  return JSON.parse(contents.toString("utf8")) as unknown;
+}
+
 const HELP = `oh ${OH_PACKAGE_VERSION}
 
 Usage:
@@ -283,14 +298,25 @@ export async function runOhCli(arguments_: readonly string[]): Promise<number> {
       if (action === "export") {
         const after = integer(one(parsed, "after"), "after") ?? 0;
         const limit = integer(one(parsed, "limit"), "limit") ?? 1000;
-        print(createOhSyncBundleV1(oh.store.spaceId, oh.store.exportOperations(after, limit))); return 0;
+        print(createOhSyncBundleV1(oh.store.spaceId, oh.store.exportOperations(after, limit), {
+          largestFittingPrefix: true,
+        })); return 0;
       }
       if (action === "import") {
         const bundle = validated.syncBundle;
         if (bundle === null) throw new TypeError("Invalid prepared sync import command.");
-        let imported = 0;
-        for (const operation of bundle.operations) if (oh.store.importOperation(operation).imported) imported += 1;
-        print({ head: oh.head(), imported, v: 1 }); return 0;
+        const first = bundle.operations[0];
+        if (first === undefined) {
+          print({ head: oh.head(), imported: 0, v: 1 }); return 0;
+        }
+        const imported = oh.store.importOperations({
+          expectedHead: {
+            operationSha256: first.parentOperationSha256,
+            sequence: first.sequence - 1,
+          },
+          operations: bundle.operations,
+        });
+        print({ head: imported.head, imported: imported.imported, v: 1 }); return 0;
       }
       throw new TypeError("sync needs export or import.");
     }