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 selects one pinned local QMD engine and theembeddinggemma-300M-Q8_0 model. The V1 profile publishes its 768-dimensional cosine contract. The concrete adapter confines QMD result identities, rejects non-finite scores, and rejoins every hit to current SQLite authority.

Semantic data is a derived cache keyed by profile and exact record digest. Keyword search stays available without a model, and results always rejoin the current authoritative record.

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 experimental 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.

Working nominations are verified dependency-closure proposals. Review and durable adoption remain destination-owned operations; a derived result never promotes itself.

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.