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
//! # okf: the Open Knowledge Format, in pure Rust
//!
//! A dependency-free 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), a directory walker, and (in the binary) CLI
//! argument parsing. There are **no third-party dependencies**.
//!
//! ## Model
//!
//! - A [`Bundle`] is a directory tree of markdown files (§3).
//! - A [`Concept`] is one markdown [`Document`] = YAML [`Frontmatter`] + body
//! (§4).
//! - A [`ConceptId`] is a concept's path within the bundle, minus `.md` (§2).
//! - Concepts relate via markdown [`links`] (§6); the bundle exposes the
//! resulting graph and backlinks.
//! - `index.md` directory listings (§8) are generated by [`index`].
//! - `log.md` histories (§9) are parsed by [`log`].
//! - [`validate_bundle`] checks §11 conformance.
//!
//! ## 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` (§5.1) | [`provenance`] |
//! | Trust | `generated`, `verified` (§5.2), trust tiers (§5.3) | [`trust`] |
//! | Lifecycle | `status` (§5.4), `stale_after` (§5.5) | [`trust`] |
//! | Identity | the actor convention (§7) | [`actor`] |
//! | Attestation | `runtime`, `parameters`, `computation`, `executor`, `attester` (§10) | [`computation`] |
//! | Attribution | `[^label]` footnotes keyed to `sources[].id` (§5.1) | [`footnotes`] |
//!
//! Two v0.1 constructs are superseded (§13.1) 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::{Bundle, validate_bundle};
//!
//! let bundle = Bundle::load("./my_bundle")?;
//! println!("{} concepts", bundle.len());
//!
//! let report = validate_bundle(&bundle);
//! if report.is_conformant() {
//! println!("conformant OKF v0.2 bundle");
//! }
//! # Ok::<(), okf::BundleError>(())
//! ```
//!
//! Reading a concept's trust signals:
//!
//! ```
//! use okf::{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:ahormati, 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 (§5.2).
//! 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/knowledge-catalog/blob/main/okf/SPEC.md
// 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.
/// Compiles and runs the `README.md` examples as doctests.
///
/// `cfg(doctest)` means this item exists only while `cargo test` collects
/// doctests, so it never reaches the public API or the rendered documentation.
/// Without it the README's Rust blocks would be prose that nothing checks.
;
/// 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 (§12) with two documented supersessions
/// (§13.1), both of which this crate still reads, so a v0.1 bundle loads and
/// validates without special handling.
pub const SUPPORTED_OKF_VERSIONS: = ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use Document;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use Log;
pub use ;
pub use ;
pub use ;
pub use ;