BRAN — a deterministic, offline retrieval CLI for OKF bundles, with selectable v0.1 and v0.2 profiles

[1wgrumph]

I've been building BRAN, a Rust CLI that consumes OKF bundles and answers the retrieval half of the problem: given a question, which documents are authoritative for it, and how do you hand a bounded set to a model without shipping the whole tree.

Retrieval is deterministic and fully offline. No embeddings, no vector store, no index to keep fresh. Ranking runs on declared OKF metadata plus paths and document bodies, so the same bundle and the same question always produce the same ranking. It runs standalone with no model and no account, or connected to one for answers with citations.

A query against a 45.9 MB repository narrowed the candidate sources to 40 KB with the owning file at rank 1, roughly a 1,175x reduction. That is one measurement on one corpus, not a benchmark.

Two profiles, reported independently. bran check <root> okf-v0.1 and okf-v0.2 are both selectable, alongside a stricter producer-side profile of my own. All three outcomes are computed on every run and reported separately, and only the selected profile controls the exit code:

{
  "selected_profile": "okf-v0.2",
  "selected_passed": true,
  "okf_compatibility": { "profile": "okf-v0.1", "status": "pass" },
  "okf_v0_2":          { "profile": "okf-v0.2", "status": "pass" },
  "bran_strict":       { "profile": "bran-strict", "status": "pass" }
}

That separation is deliberate, and it's the same point I raised in #212: a bundle can be OKF-conformant while a stricter local profile still reports diagnostics, and those two results answer different questions. Calling a profile warning "OKF nonconformance" is wrong, and so is letting a clean profile paper over a real OKF failure.

v0.2 support covers the optional families as shape-validated and preserved rather than required: sources/usage_window, generated/verified, status/stale_after, and the attested-computation fields. Both compatibility migrations are implemented, generated.at with fallback to legacy timestamp, and frontmatter sources with fallback to a body # Citations list. A bare verified: {by, at} mapping and a one-element verified list normalize identically. okf_version on a bundle-root index.md is accepted, and a newer or unknown declared version is consumed best-effort rather than rejected.

One design choice, and a limit I have not solved yet.

Ask a bundle "where is the zephyrite-collector configured and tested" when there is nothing named zephyrite-collector exists in it. The other words in that question, configured, collector, tested, match plenty of documents. My first implementation ranked on those leftovers and returned unrelated files with status: ok and no warning.

That is the dangerous shape, and it took me a while to see it. The caller cannot tell a good answer from a confidently wrong one, because both look identical: same status, same structure, same plausible-looking paths. Nothing in the response says "the one term you actually cared about matched nothing." An agent reads it as evidence and reasons about a component that does not exist.

So when an unmatched term is a compound identifier, BRAN now returns nothing and names the term:

{ "status": "ok", "source_rankings": [], "warnings": ["unmatched_query_terms: zephyrite-collector"] }

An agent recovers from "nothing found" easily. It cannot recover from confidently wrong context.

The limit: this triggers on compound identifiers, hyphenated or underscored, which are treated as a single high-specificity unit. A bare word inside a longer sentence still dilutes. where is the zephyrite collector configured and tested warns about zephyrite but still returns 32 ranked documents, because zephyrite alone is not distinguished from ordinary query vocabulary. I do not have a principled rule yet for deciding when a lone word is specific enough that its absence should suppress the whole result, and I would be interested in how others have drawn that line.

Rust, MIT/Apache-2.0, zero dependencies in the two core crates. Releases carry a Sigstore keyless signature and a provenance manifest.

Happy to answer anything about the ranking or the profile split.