feat(knowable-from): VART backend — Phase 3 reference impl

[AdaWorldAPI]

Summary

New optional feature vart-backend on ogar-knowable-from. Wires VartKnowableFromStore — a KnowableFromStore impl backed by AdaWorldAPI/vart (the versioned adaptive radix trie from the SurrealKV ecosystem). Closes PR #25's "reference backend" promise.

This is Phase 3 per docs/RDF-OWL-ALIGNMENT.md §10 — self-contained, no cross-session coordination needed.

Mechanism

pub struct VartKnowableFromStore {
    tree: Mutex<vart::art::Tree<vart::VariableSizeKey, u64>>,
}

// register(class_identity, _hint): advance version + insert_or_replace
let new_version = tree.version().saturating_add(1);
tree.insert_or_replace(&NULL_terminated(class_identity), new_version, new_version, 0)?;
Ok(new_version)

// knowable_from(class_identity): get at latest snapshot
tree.get(&NULL_terminated(class_identity), tree.version()).map(|(v, _, _)| v)

Why this matches the substrate's invariants

• NiblePath-shaped class_identity (e.g. ogit-erp/sale.order) is prefix-radix-indexed natively — same primitive bardioc PR feat: ogar-adapter-surrealql — emit wired, parse stub, knowable_from seam #18 / lance-graph PR #470 describe for inv.object_instance.
• Immutable / copy-on-write — every register produces a new logical version; readers at any prior version see the world-as-of-that-version (audit-as-version per ADR-008 / ADR-013).
• Append-only by construction — VART doesn't expose mutate-in-place semantics for past versions, so the registry log is forensically queryable.

NULL-termination for prefix safety

Per VART's variable-length-key discipline (src/lib.rs L42-48), class identities like ogit-op/Work and ogit-op/WorkPackage would address overlapping subtrees without NULL termination. The make_key helper appends \0 before constructing the VariableSizeKey. Verified by vart_prefix_keys_do_not_collide test.

Why schema_ddl_hint is discarded in v1

VART's value type is u64 to keep the trie homogeneous. The hint parameter is accepted for trait conformance and explicitly noted as discarded in v1 doc-comments. The surrealql-hint feature (PR #33) renders DDL at the helper layer (register_class_knowable_from), upstream of the backend — the self-describing-registry loop closes at the wrapper, not the backend. A future PR can wire a parallel Tree<VariableSizeKey, String> for hints if a real consumer needs them.

Tests (6 new; 10 prior → 16 total)

Test	Asserts
vart_empty_returns_none_and_version_zero	Empty trie, no entries
vart_register_returns_monotonic_versions	v1 < v2 < v3; first register lands at 1
vart_knowable_from_returns_latest_for_key	Lookup round-trips; unrelated class returns None
vart_re_register_same_class_advances_version	Upsert bumps the stamp (each register = new logical moment)
vart_prefix_keys_do_not_collide	NULL-term receipt — Work and WorkPackage get distinct stamps
vart_same_name_different_prefixes_do_not_collide	End-to-end through register_class_knowable_from — covers PR #31's canonical-identity P2 case against the real backend

Cargo + CI

• vart as optional = true behind vart-backend feature. Pinned to AdaWorldAPI/vart fork (git dep); zero runtime sub-deps per its Cargo.toml.
• CI: cargo test -p ogar-knowable-from --features vart-backend added — same crate-scoped pattern as the other feature-gated test steps.

Verification

$ cargo test --workspace                                     -> clean
$ cargo test -p ogar-knowable-from                           -> 10/10 (default)
$ cargo test -p ogar-knowable-from --features vart-backend   -> 16/16
$ cargo test -p ogar-knowable-from --features surrealql-hint -> 10/10
$ cargo check --workspace --all-targets                      -> clean

PII abort-guard (word-boundary): CLEAN.

Position in sequencing

Phase	Status
Phase 1 (#30) — RDF-OWL-ALIGNMENT doc	✅ merged
Phase 2a (#37) — ogar-adapter-ttl	✅ merged
Phase 2b (#38) — ogar-adapter-clickhouse-ddl	✅ merged
Phase 2c — ogar-from-osm-pbf	⏸ queued (gates on runtime D-OSM-3)
Phase 3 (this) — vart-backend	opens
Phase 4+ — ogar-pattern / ogar-actionable / ...	⏸ queued

https://claude.ai/code/session_01PBTGaPCSnnt6u3pjXpbLwY

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c2379c457c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Pin the VART git dependency to a stable revision

When vart-backend is enabled, this dependency is resolved from the remote repo's default branch because no rev, tag, or branch is specified, and this repository does not commit a Cargo.lock. That makes the new CI step and any downstream build using this feature non-reproducible: a future change in AdaWorldAPI/vart can break OGAR or silently change the backend semantics without any OGAR commit. Please pin this to the intended VART revision/tag, or vendor it through a locked workspace dependency.

Useful? React with 👍 / 👎.