Crate okf_core

Expand description

§okf-core: the Open Knowledge Format, in pure Rust

A pure-Rust implementation of the Open Knowledge Format (OKF) v0.2, Google’s open, human- and agent-friendly format for representing knowledge as a directory of markdown files with YAML frontmatter.

OKF is intentionally minimal (“if you can cat a file, you can read OKF; if you can git clone a repo, you can ship it”), so this crate implements it with the standard library alone: its own YAML-subset parser, a markdown link scanner, and a directory walker. The companion okf crate re-exports this entire library and ships the okf command-line tool.

§Model

A Bundle is a directory tree of markdown files.
A Concept is one markdown Document = YAML Frontmatter + body.
A ConceptId is a concept’s path within the bundle, minus .md.
Concepts relate via markdown links; the bundle exposes the resulting graph and backlinks.
index.md directory listings are generated by index.
log.md histories are parsed by log.
Conformance checking and linting live in the companion okf-validator crate.

§What v0.2 adds

v0.2 makes provenance, trust, lifecycle, and attestation first-class. Every one of the new keys is optional, and absence is meaningful rather than invalid, so a v0.1 document is still a conformant v0.2 document.

Concern	Frontmatter	Module
Provenance	`sources`, `usage_window`	`provenance`
Trust	`generated`, `verified`, trust tiers	`trust`
Lifecycle	`status`, `stale_after`	`trust`
Identity	the actor convention	`actor`
Attestation	`runtime`, `parameters`, `computation`, `executor`, `attester`	`computation`
Attribution	`[^label]` footnotes keyed to `sources[].id`	`footnotes`

Two v0.1 constructs are superseded but still readable, since a v0.2 consumer is expected to handle v0.1 bundles: timestamp gives way to generated.at (see Frontmatter::content_changed_at), and the body # Citations list gives way to sources (see Document::citations).

§Example

use okf_core::{Bundle, ConceptId};

let bundle = Bundle::load("./my_bundle")?;
println!("{} concepts", bundle.len());

let id = ConceptId::parse("tables/orders")?;
for link in bundle.links_from(&id) {
    println!("{} -> {} (exists: {})", id, link.target, link.exists);
}

Reading a concept’s trust signals:

use okf_core::{Document, TrustTier};

let doc = Document::parse(
    "---\n\
     type: Metric\n\
     title: Revenue\n\
     status: stable\n\
     generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }\n\
     verified: { by: human:walter, at: 2026-06-25T09:00:00Z }\n\
     stale_after: 2026-12-31\n\
     ---\n\n\
)
.unwrap();

// A bare `verified` mapping counts as a one-element list.
assert_eq!(doc.frontmatter.verified().len(), 1);
assert_eq!(doc.frontmatter.trust_tier(), TrustTier::HumanReviewed);
assert_eq!(doc.frontmatter.status().to_string(), "stable");

Modules§

actor: The actor convention: who or what performed an action.
bundle: Loading and traversing an OKF bundle: a directory tree of markdown files.
computation: Attested Computation concepts.
concept_id: Concept identifiers and their mapping to/from file paths.
date: Calendar dates and ISO-8601 datetimes for the trust and lifecycle families.
diff: Bundle-level diff: an OKF-semantics diff between two Bundles.
document: The OKF concept document: YAML frontmatter + markdown body.
error: Error types for the crate.
fix: Automated remediation and migrations for OKF concepts, bundles, and logs.
footnotes: Markdown footnotes, the carrier for per-claim attribution.
frontmatter: Typed, order-preserving access to a concept’s YAML frontmatter.
index: Generation of index.md directory listings.
links: Markdown link extraction, classification, and path-valued fields.
log: Parsing, building, and updating log.md update histories.
markdown: Markdown scanning, link rewriting, heading extraction, and anchor slugs.
provenance: Provenance: the sources frontmatter family and per-claim attribution.
refactor: Knowledge refactoring, concept relocation, deletion, splitting, and merging.
scaffold: Scaffolding and initialization utilities for OKF bundles and concept documents.
trust: Trust and lifecycle frontmatter: generated, verified, status, and stale_after.
yaml: A small YAML subset parser used for OKF frontmatter.

Structs§

Actor: A parsed actor string, retaining the text exactly as written.
AttestedComputation: The contract of an Attested Computation concept: its top-level frontmatter plus the computation itself.
Attester: The deterministic check.
Attribution: A body claim attributed to a source, produced by joining footnote labels to sources[].id.
Bundle: A loaded OKF bundle.
BundleDiff: A bundle-level diff.
BundleFixReport: Remediation report for a whole bundle.
BundleInitOptions: Options for initializing a new OKF bundle.
Citation: A numbered entry under a legacy v0.1 # Citations heading.
Concept: A single concept within a bundle (one markdown document).
ConceptId: A concept identifier: an ordered list of path segments (e.g. ["tables", "users"] for tables/users).
ConceptIdError: Error returned when a concept-id segment is malformed.
ConceptOptions: Options for creating a new concept document.
Date: A proleptic-Gregorian calendar date (YYYY-MM-DD).
DateField: A frontmatter date field: the scalar exactly as written, plus its parse.
DateTime: An ISO-8601 datetime: a Date, an optional time of day, and an optional UTC offset.
DateTimeField: A frontmatter datetime field: the scalar exactly as written, plus its parse.
Document: A parsed OKF concept document.
Executor: How the computation is run.
FileFixReport: Remediation report for a single file.
FixOptions: Options controlling automated remediation and migration.
FootnoteDef: A [^label]: text definition line.
FootnoteRef: A [^label] reference in the body prose.
Frontmatter: A concept’s frontmatter: an ordered key/value mapping with typed accessors for the well-known OKF fields.
FrontmatterChange: Frontmatter key changes for a concept present in both bundles.
Generated: How the current content was produced: generated: { by, at }.
InlineComputation: A computation held in the body under # Computation.
Link: A markdown link found in a concept body.
Log: A parsed log.md.
LogDay: All entries recorded under a single date heading.
LogEntry: A single log bullet.
Mapping: An ordered YAML mapping (preserves insertion / source order, like the reference implementation which dumps with sort_keys=False).
MarkdownHeading: A parsed markdown heading.
MergeOptions: Options for merging one concept into another.
MergeReport: Summary report of a merge operation.
MoveOptions: Options for moving or renaming a concept.
MoveReport: Summary report of a move/rename operation.
Parameter: One typed, named hole an agent may fill.
ParseActorKindError: Error returned when a string cannot be parsed into an ActorKind.
ParseLinkKindError: Error returned when a string cannot be parsed into a LinkKind.
ParseTrustTierError: Error returned when a string cannot be parsed into a TrustTier.
Remediation: A single remediation action applied to a document or file.
RemoveOptions: Options for removing a concept.
RemoveReport: Summary report of a removal operation.
Rename: A rename detected by matching content hash between a removed and an added concept.
RenameSectionOptions: Options for renaming a section heading within a concept.
RenameSectionReport: Summary report of a section rename operation.
ResolvedLink: A cross-link from one concept to another, after resolution.
ResolvedSource: A sources entry resolved against the bundle.
Source: One entry in the sources list: a material the concept derives from.
SplitOptions: Options for splitting a concept section into a new concept.
SplitReport: Summary report of a split operation.
TrustChange: A trust tier or status change for a concept present in both bundles.
UsageWindow: The date/time range that frames usage_count.
Verification: A single verification event: { by, at }.

Enums§

ActorKind: The category an actor string falls into.
BundleError: Errors raised when loading or operating on a bundle on disk.
ComputationSource: Where the sanctioned computation lives.
DocumentError: Errors raised when parsing or validating a single OKF concept document.
LinkKind: How a link target is interpreted.
LinkRewriteAction: Action to perform on a detected markdown link during rewrite.
RefactorError: Error returned when a refactoring operation fails.
RemediationKind: What kind of remediation or migration was applied.
ResourceKind: What kind of thing a sources[].resource names.
Status: A concept’s lifecycle status. An absent key means Status::Stable.
TrustTier: A concept’s trust tier, derived from verified.
Value: A parsed YAML value.

Constants§

ATTESTED_COMPUTATION_TYPE: The type value that marks a concept as an Attested Computation.
KNOWN_FRONTMATTER_KEYS: Every frontmatter key the specification gives a meaning to, across all families. Anything else is a producer extension.
LEGACY_FRONTMATTER_KEYS: Keys v0.2 retired but consumers may still encounter in v0.1 documents. timestamp is superseded by generated.at.
OKF_VERSION: The OKF specification version this crate implements.
PREFERRED_KEY_ORDER: The key order the reference implementation writes documents in (its _PREFERRED_KEY_ORDER): identity first, then lifecycle, trust, and provenance.
RECOMMENDED_FRONTMATTER_KEYS: Keys a producer should fill in before publishing, in the order Document::missing_recommended reports them.
REQUIRED_FRONTMATTER_KEYS: The only frontmatter key OKF always requires: a concept carrying nothing but type is fully conformant.
RESERVED_FILENAMES: Reserved filenames with defined meaning at any level.
SUPPORTED_OKF_VERSIONS: Specification versions this crate can consume.

Functions§

append_log_entry: Appends an entry to log.md in the bundle root, creating the file if needed.
bundle_diff: Computes the OKF-semantics diff between two bundles.
compute_relative_path: Computes the relative markdown link path from from_concept to to_concept.
create_concept: Creates a new concept markdown file with proper frontmatter and heading.
default_author: Returns a default author actor string based on system user environment variables or "human:author".
extract_headings: Extracts all markdown headings in document order, ignoring headings inside fenced code blocks.
field_path_candidates: Normalizes a path-valued frontmatter field into the bundle-relative paths it might name, most likely first.
heading_slug: Derives a standard Markdown anchor slug from a heading text.
init_bundle: Initializes a new OKF bundle at root with index.md, log.md, and optionally an initial concept.
matches_heading: Checks whether a heading text matches a search query by title, slug, or normalized spacing.
merge_concepts: Merges source concept into target concept and deletes source.
move_concept: Moves or renames a concept, rewriting all incoming links and rebasing outgoing links.
parse_heading_line: Parses a single line as an ATX heading (# through ###### ).
rebase_relative_path: Rebases a relative file/resource path from old_dir to new_dir.
remediate_bundle: Remediates an entire bundle directory tree.
remediate_document: Remediates and migrates a single Document.
remediate_file: Remediates a single file on disk.
remediate_log: Remediates a parsed log.md file (consolidating duplicate date headings).
remove_concept: Safely removes a concept from the bundle.
rename_section: Renames a section heading within a concept and updates all internal and external anchor links.
rewrite_markdown_links: Rewrites inline markdown links in a document body using a callback function.
split_concept: Splits a section from an existing concept into a new concept.

Crate okf_core

Crate okf_core Copy item path

§okf-core: the Open Knowledge Format, in pure Rust

§Model

§What v0.2 adds

§Example

Modules§

Structs§

Enums§

Constants§

Functions§

Crate okf_core