okf-core 0.2.6

A pure-Rust implementation of the Open Knowledge Format (OKF) v0.2 specification: parser, model, validator, provenance/trust/attestation families, link graph, and index/log tooling.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

//! # okf-core: the Open Knowledge Format, in pure Rust
//!
//! A pure-Rust implementation of the [Open Knowledge Format (OKF)
//! v0.2][spec], 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](yaml), a
//! markdown [link scanner](links), 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`](https://docs.rs/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
//!
//! ```no_run
//! 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);
//! }
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! 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\
//!      # Definition\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");
//! ```
//!
//! [spec]: https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md

#![forbid(unsafe_code)]
#![warn(missing_docs)]
// Pedantic and nursery lints keep the published crate tidy; the few cases
// where a lint is genuinely wrong for this codebase are silenced inline with a
// justification.
#![warn(clippy::pedantic, clippy::nursery)]

pub mod actor;
pub mod bundle;
pub mod computation;
pub mod concept_id;
pub mod date;
pub mod diff;
pub mod document;
pub mod error;
pub mod fix;
pub mod footnotes;
pub mod frontmatter;
pub mod index;
pub mod links;
pub mod log;
pub mod markdown;
pub mod provenance;
pub mod refactor;
pub mod scaffold;
pub mod trust;
pub mod yaml;

/// The OKF specification version this crate implements.
pub const OKF_VERSION: &str = "0.2";

/// Specification versions this crate can consume.
///
/// v0.2 is a minor bump over v0.1 with two documented supersessions,
/// both of which this crate still reads, so a v0.1 bundle loads and
/// validates without special handling.
pub const SUPPORTED_OKF_VERSIONS: [&str; 2] = ["0.1", "0.2"];

#[doc(inline)]
pub use actor::{Actor, ActorKind, ParseActorKindError};
#[doc(inline)]
pub use bundle::{Bundle, Concept, RESERVED_FILENAMES, ResolvedLink, ResolvedSource};
#[doc(inline)]
pub use computation::{
    ATTESTED_COMPUTATION_TYPE, AttestedComputation, Attester, ComputationSource, Executor,
    InlineComputation, Parameter,
};
#[doc(inline)]
pub use concept_id::{ConceptId, ConceptIdError};
#[doc(inline)]
pub use date::{Date, DateField, DateTime, DateTimeField, normalize_iso_datetime};
#[doc(inline)]
pub use diff::{BundleDiff, FrontmatterChange, Rename, TrustChange, bundle_diff};
#[doc(inline)]
pub use document::Document;
#[doc(inline)]
pub use error::{BundleError, DocumentError};
#[doc(inline)]
pub use fix::{
    BundleFixReport, FileFixReport, FixOptions, Remediation, RemediationKind, remediate_bundle,
    remediate_document, remediate_file, remediate_log,
};
#[doc(inline)]
pub use footnotes::{FootnoteDef, FootnoteRef};
#[doc(inline)]
pub use frontmatter::{
    Frontmatter, KNOWN_FRONTMATTER_KEYS, LEGACY_FRONTMATTER_KEYS, PREFERRED_KEY_ORDER,
    RECOMMENDED_FRONTMATTER_KEYS, REQUIRED_FRONTMATTER_KEYS,
};
#[doc(inline)]
pub use links::{Citation, Link, LinkKind, ParseLinkKindError, field_path_candidates};
#[doc(inline)]
pub use log::{Log, LogDay, LogEntry, append_log_entry};
#[doc(inline)]
pub use markdown::{
    LinkRewriteAction, MarkdownHeading, extract_headings, heading_slug, matches_heading,
    parse_heading_line, rewrite_markdown_links,
};
#[doc(inline)]
pub use provenance::{Attribution, ResourceKind, Source, UsageWindow};
#[doc(inline)]
pub use refactor::{
    MergeOptions, MergeReport, MoveOptions, MoveReport, RefactorError, RemoveOptions, RemoveReport,
    RenameSectionOptions, RenameSectionReport, SplitOptions, SplitReport, compute_relative_path,
    merge_concepts, move_concept, rebase_relative_path, remove_concept, rename_section,
    split_concept,
};
#[doc(inline)]
pub use scaffold::{
    BundleInitOptions, ConceptOptions, create_concept, default_author, init_bundle,
};
#[doc(inline)]
pub use trust::{Generated, ParseTrustTierError, Status, TrustTier, Verification};
#[doc(inline)]
pub use yaml::{Mapping, Value};