Module okf 

Open Knowledge Format (OKF) rendering for lean-ctx project knowledge.

OKF (Google Cloud, June 2026) formalises the “LLM-wiki” pattern: a directory of Markdown files, one concept per file, each with a small YAML frontmatter block (only type is mandatory) and a Markdown body; concepts link to each other with ordinary Markdown links, and reserved index.md / log.md files provide progressive disclosure and history. It is vendor-neutral, human- and agent-readable, and git-diffable — the portable, no-lock-in counterpart to the signed ctxpkg bundle.

This module renders a KnowledgeSnapshot to an OKF bundle and parses a bundle back into facts + relations. Both directions go through that shared snapshot, so OKF and ctxpkg can never disagree on what the project’s knowledge is.

Determinism (#498)

Every byte of the export is a pure function of the snapshot: frontmatter keys are emitted in a fixed order (reserved OKF keys first, then sorted leanctx_*), file slugs are stable, relation lines are sorted, and no now() or counter ever reaches the output. Two exports of the same snapshot are byte-identical, which keeps provider prompt-caching effective.

Lossless round-trip

lean-ctx-specific fields ride along as producer-owned leanctx_* keys (OKF §reserves only a small set and lets producers add their own), so an export -> import cycle reconstructs the same facts, archetypes, and relations. Foreign bundles that carry only type import as plain facts rather than failing.

Structs

OkfEdge

A relation parsed from a concept’s ## Relations section.

OkfImport

The result of parsing an OKF directory back into lean-ctx structures.

Functions

from_okf_dir

Parses an OKF directory into facts, patterns, and relations. Lenient by design: files without a type (or without frontmatter) are skipped rather than failing the whole import; use lint_okf_bundle to surface those.

lint_okf_bundle

Non-fatal conformance checks. Returns warnings only — OKF’s own tooling treats these as advisory, and a partially-malformed bundle should still import what it can.

to_okf_bundle

Renders a snapshot to a deterministic OKF bundle (path -> contents). Only current facts become concepts; superseded history stays in ctxpkg.

write_okf_bundle

Writes a bundle to dir, creating category subdirectories as needed.

Type Aliases

OkfBundle

A rendered OKF bundle: relative file path -> file contents. A BTreeMap so iteration (and thus writing) is deterministic.