Oh ontology
specification

Contract

Version 1 is identified by oh.ontology.v1. Its manifest pins ontology, graph, and schema versions together with the complete record-kind vocabulary and a SHA-256 digest of the canonical manifest bytes.

Ontology

The kernel separates identity, propositions, stances, evidence, context, inquiry, and projection. Graph envelopes and typed contract records enter through strict parsers fromunknown. Application values remain canonical JSON unless a consumer selects a registered codec.

• activity
• assertion
• context
• dependency-manifest
• edition
• entity
• evidence
• identity-operation
• inquiry
• inquiry-event
• review-decision
• rights-decision
• schema
• shape
• statement
• type-membership
• view
• vocabulary

Records and revisions

A record has one stable key, a closed kind, ordered unique dependencies, a JSON value, and a digest over its canonical preimage. A revision applies a nonempty ordered set of puts and tombstones against one parent. The resulting record references and their aggregate digest are part of the revision identity.

{
  "dependencies": ["entity:flywire"],
  "key": "statement:connectome-scope",
  "kind": "statement",
  "recordSha256": "<64 lowercase hex>",
  "v": 1,
  "value": { "...": "canonical JSON" }
}

Canonical JSON sorts object keys by UTF-16 code units, preserves array order, rejects non-finite numbers and unsupported values, and never normalizes user strings implicitly.

Local SQLite authority

One BEGIN IMMEDIATE transaction appends the operation, applies records and dependencies, advances the generation and graph head, updates full-text materialization, and adds the sync outbox row. Generation compare-and-swap prevents silent forks.

1. Validate contract, parent, dependencies, and canonical bytes.
2. Append one immutable operation and its ordered changes.
3. Advance the space generation and graph revision atomically.
4. Project the replaceable FTS index; semantic indexing is an explicit follow-up.

Operation-level sync

Sync exchanges bounded immutable operations, not database pages. Peers first compare contract manifests, then pull or push one contiguous sequence. Duplicate operations replay idempotently; stale heads and unknown contracts fail closed with explicit conflict errors.

The transport port is HTTP-friendly and compatible with a libSQL/Turso implementation, while the local store remains the source of truth. A separate promise-based adapter can instead use libSQL as the direct authority without importing Bun SQLite.

Semantic search

Oh publishes two separately digest-bound EmbeddingGemma views: a local QMD embeddinggemma-300M-Q8_0 profile, and an optional Cloudflare Workers AI profile with a direct libSQL cache. Both use 768-dimensional cosine vectors, but their outputs are not assumed interchangeable. Every hit rejoins the exact current authoritative record digest.

Semantic V2 data is a derived cache keyed by profile and exact renderer, host-controlled isolation, authority generation, and record digest. Isolation scopes vector reuse and purge without changing provider text. Keyword search stays available without a model; hosted failure never weakens exact graph or Datalog operations.

Derived projection

Typed positive rules derive recursive views from one exact graph head and content-addressed fact pack. Rule, query, input, and result identities use canonical bytes, while explicit work limits bound tuples, rounds, joins, and proof trees.

Projection rows always remain derived cache output. They do not become assertions, review decisions, or operation history until an application submits new records through its authority path.

Composite agent memory

One stable host-bound facade composes a separately governed working authority with one exact canonical head. Host-purposed named programs see lane-tagged facts, visible conflicts, exact physical authority and extractor digests, and bounded proofs without receiving store locators or canonical mutation handles. The additive V2 facade lets a host declare primitive query-body parameters and stable bounded pages. Its authenticated bearer cursors fail if the physical heads, program, bindings, or complete result change; a stable host key carries exact cursors across facade reconstruction. Explanation evidence shares one bounded cache and clock guard across canonical rollover.

Working nominations are verified dependency-closure proposals. The separate host control re-exports each proposal and adopts absent records through one compare-and-swap operation. A different canonical digest fails closed unless trusted host code names the exact logical key and exact reviewed prior digest; stale or partial replacement claims cannot write. Prospective snapshots over the lane limits also fail closed. It reconciles the physical head after the commit, so a replay cannot install an obsolete head. A derived result never promotes itself.

The stable memory-page profile carries bounded Markdown, explicit source observations, and host-attested provenance in an ordinary edition record. Its canonical.oh.md form is one self-contained record transport, not a second authority or embedding format.

Versioning and evolution

Package releases use semantic versions. Wire, graph, schema, SQLite, sync, and semantic profiles carry independent closed versions. A breaking byte or meaning change creates a new version; existing immutable preimages and migrations are never edited in place.