Knolo Conformance Fixtures: When Two Runtimes Agree on the Bytes
How Knolo's open conformance fixtures let TypeScript, Rust and Python runtimes check the same Knowledge Image bytes, and what a matching root does not prove.
Knolo is an open-source, local-first Knowledge Image runtime and format, released under Apache-2.0 with @knolo/core on npm as the reference implementation. An open format only matters if more than one implementation can read it the same way. This note looks at how Knolo answers that today: shared conformance fixtures in the public repository, a published interoperability table, and a strict rule about what a matching root does and does not prove. It is grounded in the Knolo interoperability docs and the Knolo specifications page.
Why Knolo needs conformance, not just a spec
The specifications page describes the contract plainly: a V5 Knowledge Image is a bounded, content-addressed artifact with deterministic encodings, domain-separated SHA-256 roots, and a commit history, and V4 remains a supported compatibility path. It also says that numbered, adopted specification records do not exist yet; until they do, the working contract lives in public source and documentation.
That makes tests the practical meeting point. A prose description can be read two ways. A fixed set of bytes with an expected root cannot.
What the Knolo conformance fixtures contain
The conformance/ directory in the Knolo core repository on GitHub holds the shared set. Its README states that V4 retrieval conformance remains the compatibility baseline, with packs from a minimal v1 to a verified v4, deliberately corrupted packs (truncated, bad section digest), a query file, and expected output.
For V5, the fixtures are checked-in bytes, not generated test output. The minimal V5 image, a migrated legacy V1–V3 image, and a migrated V4 image with claims and agents each carry a published state root. TypeScript and Rust tests load those exact bytes and compare verification or migration output byte for byte. The Python verifier and query profile consumes the same image and checks the shared state, commit, plan, and result roots. Separate fixture sets cover VQF-1 decoding, composition, and Cortex.
The rule for adding a runtime is strict: a profile must not be marked equivalent until it consumes the same fixture set and produces the same result shape. Scores are compared within a declared tolerance; IDs, decisions, plan hashes, and rejection behavior must match exactly. Accepting a corrupted pack counts as a failure.
Which Knolo runtimes interoperate today
The Knolo interoperability page and the versions page publish the current table:
- TypeScript,
@knolo/core6.2.0: the reference for V4 retrieval and the full V5 surface, including composition and Cortex. - Rust,
knolo-core-rust5.5.1: V4 read, V5 verify and EQL, diagnostics roots, and VQF-1 object and event decoding. It does not encode VQF-1 or build lexical postings. - Python,
knolo5.5.1 on PyPI: read-only V5 verify and query, with older pack APIs preserved. - Internet Computer canister 5.5.1: a legacy pack profile.
The page is explicit about the edges: do not send a Cortex trace or a composition record to the Rust, Python, or canister runtimes and expect them to evaluate it. Verify those artifacts with the TypeScript packages or the CLI. Publishing a newer TypeScript line does not move the other runtimes' versions.
What a matching Knolo root proves
The interoperability page puts it in one sentence: a matching root across two implementations means those implementations agree on the bytes. It does not extend trust to a runtime that never implemented the contract.
Two consequences follow. First, agreement is scoped. Rust matching TypeScript on a V5 state root says nothing about features Rust does not implement. Second, agreement is not truth. Verification checks that bytes match the roots they declare, not that the knowledge inside is correct.
Knolo conformance and compatibility claims
This is where the open-technology record on knolo.org connects. The Knolo compatibility page says compatibility claims should point at versions, fixtures, and results, and that compatibility is not endorsement. The conformance directory is what makes that request concrete: an independent implementation can name the fixture set it passes and the version it passed with.
Status is still being built in public. The Knolo lifecycle page lists intended states (proposed, active, maintenance, deprecated, archived) but notes that no per-project matrix is published yet, and the Knolo KIPs index says no accepted standards have been published. Until those records exist, public source and fixtures are the working truth. Unpublished is better than invented.
Where to go next with Knolo
- Knolo on knolo.org: specifications, compatibility, lifecycle, and KIPs.
- Knolo on knolo.dev: developer docs, including verification.
- Knolo core repository on GitHub: the
conformance/fixtures and every runtime's source, under Apache-2.0. - Verify Knolo: the official Knolo domains.
Knolo is maintained by Hive AI. For an open Knowledge Image format, the fixtures are where the format is actually defined: the same bytes in, the same roots out, and a clear list of what each runtime has not implemented.
knolo · conformance · interoperability · open-source · knowledge-image
