knolo-core-rust

Compatibility status: legacy v1–v3 Rust reader/query profile plus the V5 read-only Knowledge Image verifier, deterministic migration foundation, and VQF-1 required object/event readers. The TypeScript runtime remains the V4 retrieval reference and canonical VQF encoder; this crate is a read-only V5 byte-contract implementation.

The shared implementation roadmap is ../../docs/ROADMAP.md.

Native Rust runtime support for Knolo .knolo packs.

V5 Knowledge Image foundation

The crate also exposes a dependency-free, read-only V5 verifier:

use knolo_core_rust::{inspect_knowledge_image, migrate_v4_to_v5};

let migration = migrate_v4_to_v5(&v4_bytes)?;
let verification = inspect_knowledge_image(&migration.image)?;
assert_eq!(verification.state_root, migration.state_root);

V5 uses deterministic CBOR, SHA-256 domain-separated roots, A/B superblocks, immutable object/event/commit segments, and fail-closed validation. The V4 reader and lexical query API remain compatible and unchanged. The crate also implements bounded V5 EQL v1 with deterministic plan_root and result_root values matching the TypeScript runtime.

Policy evaluation is also policy-root-bound and produces matching authorization roots. The crate exposes canonical authority-envelope roots and injected verifier callbacks; cryptographic algorithms and external identity resolution remain host responsibilities. Optional key IDs are included in canonical envelope payloads for rotation parity.

Required VQF-1 object and event segments are decoded with the same logical payload, identity, segment-root, and state-root checks as TypeScript. Native VQF encoding, lexical postings, and the optional query-index codec remain outside the portable Rust writer contract.

Native inspection consumers can use inspect_knowledge_runtime_v5 and inspect_knowledge_studio_management_v5 for the verified base diagnostics and KIP-0026 management snapshot. Their diagnostics and management roots match the shared TypeScript fixture; optional query, history, run, and replay panels stay host/runtime extensions until their native contracts are added.

use knolo_core_rust::{mount_knowledge_image, query_knowledge_image_v5};

let image = mount_knowledge_image(&v5_bytes)?;
let result = query_knowledge_image_v5(&image, "FROM chunk SEARCH \"retention\" LIMIT 20")?;
println!("{}", result.result_root);

Included in this initial release

• mount_pack_from_bytes(&[u8]) -> Pack
• query(&Pack, &str, QueryOptions) -> Vec<Hit>
• Pack parsing support for:
  • meta
  • lexicon
  • postings
  • blocks (legacy string array and v3 object array)

Example

use knolo_core_rust::{mount_pack_from_bytes, query, QueryOptions};

let bytes: Vec<u8> = std::fs::read("knowledge.knolo")?;
let pack = mount_pack_from_bytes(&bytes)?;

let hits = query(
    &pack,
    "react native bridge throttling",
    QueryOptions {
        top_k: 5,
        ..Default::default()
    },
);

for hit in hits {
    println!("{} => {}", hit.source.unwrap_or_default(), hit.score);
}
# Ok::<(), Box<dyn std::error::Error>>(())