OKF as a Wrapper — Analysis of the Non-Replacement Role

Date: 2026-07-19 Inputs: C:\dev\MicroWebStacks\astro-huge-doc\plans\2026-07\19\okf-support\ (handoff.md, deep-research-report.md, survey.md, plan.md) Related:

1. Thesis

The Open Knowledge Format (Google Cloud, v0.1 draft, announced 12 June 2026) is designed, positioned, and actually used as a wrapper format: a portable, human-and-agent-readable last-mile layer that packages knowledge derived from authoritative systems, and points back to them. It is not designed to become the system of record, and every serious source — Google itself, first-party product integrations, third-party implementers, and critics — either states this explicitly or assumes it structurally.

The interesting question is therefore not whether OKF is a wrapper (the evidence below settles that), but whether the wrapping mechanics are good enough to keep fidelity to the authoritative sources — and what the wrapper should actually contain: a copy of the source's knowledge (snapshot), or a guide to using the source (interface). This distinction drives the whole analysis:

Snapshot wrapping — the bundle contains derived facts (schema dumps, data dictionaries, metric tables). Cheap to consume, but it drifts, and once an agent finds an answer in the bundle it stops consulting the source. This is the shadowing danger.

Interface wrapping — the bundle contains usage knowledge: what the source is, when to use it, how to invoke it (which MCP tool, which CLI, which API contract, which library), with pointers instead of payloads. This ages far slower and structurally cannot shadow the source, because the answer to any concrete question is still "go ask the source".

OKF supports both, its ecosystem today mostly builds snapshot wrappers (generators), and its base spec provides only weak fidelity machinery (a resource field, a # Citations convention, an ambiguous timestamp). The verdict in §8: OKF is well adapted as the format of the last-mile exchangeable doc — precisely because a "user guide for an authoritative tool" is itself a markdown how-to document, which is exactly what OKF standardizes — but the discipline of interface-first wrapping, drift control, and one-way authority has to be layered on top; the base spec does not enforce it.

2. References that state or assume the wrapper role

Grouped by who says it. Each entry states the wrapper-relevant claim, not a general description.

2.1 Google, as spec owner

2.2 Implementers (their architecture assumes wrapping)

2.3 Reviewers and critics (the wrapper's weak points)

Conclusion of §2: there is no reference, first-party or third-party, that positions OKF as a replacement for authoritative sources. The replacement risk is not in anyone's stated intent — it is an emergent operational failure mode (stale snapshot + trusting agent), which is exactly why the mechanics below matter.

3. How the wrapping actually works — mechanics

The de-facto lifecycle across Google's reference agent, okfgen, AWS Data Wiki, OKF Harness and Open Knowledge is:

generate  →  curate  →  validate  →  publish  →  ingest
(from source) (human)   (CI: shape    (static/    (Knowledge Catalog,
                         + drift)      /okf/, MCP)  agent runtimes)

The per-file wrapping contract is small:

---
type: dataset            # only REQUIRED field — the wrapper's facet
title: Customer Orders   # display only; identity is the file PATH
description: ...         # routing summary for progressive disclosure
resource: urn:bq:proj.ds.customer_orders   # ← back-pointer to authority
tags: [sales, pii]
timestamp: 2026-07-19T09:00:00Z            # derivation time (NOT validity)
---
# Definition
...prose, the wrapper's own contribution...

# Citations
- BigQuery table schema (system of record)   # ← authority list

Four mechanisms carry the wrapper role:

Path-based identity. The concept ID is the bundle-relative path, stable under title edits. This makes the bundle addressable without inventing a new global identifier scheme that would compete with the source's identifiers — the source keeps its URN/IRI in resource.

resource + # Citations as the authority tether. These are the only spec-level provisions for "the truth lives elsewhere". They are conventions, not enforced: a bundle with no citations is equally conformant. Fidelity is therefore a policy of the producing pipeline, not a property of the format.

Links as untyped relations. Markdown links express "related", never a formal claim. This is a feature for the wrapper role: the bundle cannot accidentally assert semantics (dependency, supersession, ownership) that only the authoritative system can state. The cost is that agents needing those semantics must go to the source (or to an RDF/SHACL profile layered above).

Permissive conformance. Unknown types, unknown fields, broken links must be tolerated. The bundle is designed to be consumable even when partially stale or partial — a cache semantics, not a contract semantics.

4. How the indexes work

The index layer is the part of OKF that deserves the most attention, because the index is the only content in the bundle that has no authoritative source — it is authored curation, and therefore the legitimate native content of the wrapper (everything else is derived and can drift; the index is the wrapper's own value-add).

index.md (reserved, per directory) — an authored progressive-disclosure listing: headings, one-line descriptions, ordered links to child concepts and sub-indexes. The root index.md carries the OKF version declaration. An agent reads the root index (~1 page), follows one branch, reads a sub-index, and only then loads a leaf concept. This is hierarchical routing: cost grows with path depth, not corpus size. Reserved files are not concept nodes — they are navigation, not knowledge.

log.md (reserved) — curated change history (creation/update/deprecation entries with dates and links). It answers "what changed in the bundle", which is exactly the drift-visibility question a wrapper needs; note it does not answer "what changed in the source" — that gap is the erd2okf drift-check's job.

Synthesized indexes — when no authored index exists, consumers (e.g. the Astro Huge Doc plan) synthesize one from filesystem hierarchy, titles, descriptions, types, tags — and must mark synthesized entries, preserving the distinction between authored curation and derived listing.

Routing layers above OKF — where the in-bundle index is not enough:

KCP knowledge.yaml: intent, trigger terms, loading priority, audience, dependencies, freshness, trust — a routing manifest separated from the documents. Best generated from the parsed OKF corpus with manual overrides only for non-inferable fields (survey's recommendation), otherwise the manifest itself becomes a second source that drifts.

llms.txt: flat public discovery front-door, generated from the bundle.

Derived machine indexes: /okf/index.json, /okf/graph.json, backlink tables (the Astro plan's relations table) — computed at collect time, never authored.

The pattern is consistent: one authored curation layer (index.md), everything else generated. That is the correct division of labor for a wrapper: humans curate routing and rationale; machines derive facts and inverses (backlinks, graphs, manifests) so they can be regenerated instead of maintained.

5. The non-destructive transition: what does the authoritative source become?

This is the user-facing core question. When a corpus gets wrapped in OKF, the source does not "become" anything — it stays exactly where it is. What changes is that the agent now needs a defined access modality to reach it from the wrapper doc. The wrapper doc's job is to name that modality precisely. Four modalities, with the fidelity mechanism of each:

Rules that make the transition smooth and non-destructive:

Additive adoption. OKF conformance = add type: frontmatter to existing markdown. No file moves, no format migration, no new store. Existing plain-markdown consumers keep working (tolerance rules). This is why the transition can be gradual per-document.

Generate snapshots, author interfaces. Anything that can be regenerated from a source (schemas, dictionaries, catalogs) must be generated and drift-checked in CI (erd2okf pattern). Anything hand-written should be interface knowledge (usage, rationale, routing) that has no upstream to drift from.

One-way authority. Edits to derived content flow back to the source (fix the schema, fix the wiki page), then regenerate — never patch the bundle in place. The bundle is staging/cache. This is the same lifecycle rule composable-context sets for .cache → memory → knowledge_base: staging, "not new source authority", with user-initiated promotion back to the authority.

Every leaf doc carries its tether. resource: filled, # Citations present, timestamp set at generation. A bundle-level convention (not in the base spec — add it as a local profile): a doc without resource or citations is either a genuine native doc (procedure, index, rationale) or a lint warning.

Freshness must be answerable. Since timestamp ≠ validity (KCP critique), add local fields where it matters: valid_until, generated_by, source_version/commit — the survey's graduated provenance model (basic → intermediate → PROV-O export). Show freshness in the consuming UI so a human can see staleness before the agent trusts it.

6. Keeping usage fidelity: user guide, API doc, or contract?

"How does the agent use the source correctly?" has three answers depending on what must stay faithful:

Faithful invocation → the source's own contract (OpenAPI operation, CLI --help, package types). Never transcribe these into the wrapper beyond a minimal example; link them. A transcribed contract is a stale contract.

Faithful selection (using the right source, at the right moment, for the right question) → this is genuine guide content and is the wrapper's proper job: intent, scope, when-not-to-use, alternatives, cost. No contract format expresses this; markdown prose does.

Faithful interpretation (what the results mean, caveats, business definitions) → also guide content, ideally with citations to where the definition is governed (policy page, metric owner).

So the fidelity architecture is: contracts stay native and linked; selection and interpretation knowledge is authored in the wrapper; invocation examples are minimal and tested (a CI job that actually runs the documented CLI/API example is the strongest freshness check available — it turns the user guide into a verified artifact, the same move erd2okf makes for schemas).

7. Is OKF adapted as the last-mile exchangeable doc format? Limits and alternatives

Limits (from spec, critics, and the research report)

No fidelity enforcement. resource/citations optional; nothing distinguishes a derived doc from a native one; conformance says nothing about truthfulness or freshness.

Timestamp ambiguity. File-change time, not validity window; no supersession semantics beyond a log.md convention.

No provenance model. Who/what generated this, from which source version — absent; needs local fields or PROV.

Untyped relations. Good for humility (§3.3), bad when the guide must state "X supersedes Y" machine-readably; needs the RDF/SHACL profile or local conventions.

Free-form body. Two conformant bundles can differ radically in quality; "user guide" has no required shape — # Schema/# Examples/# Citations are only suggestions, so exchangeability of structure is weaker than exchangeability of format.

No routing metadata. Intent/audience/priority/trigger-terms live in KCP, not OKF; a large bundle without a good authored index degrades to grep.

No composition/manifest story. Nothing specifies how bundles import or reference each other (cross-bundle links are an open question even in the handoff, §34) — directly relevant to composable-context.

Draft status. v0.1, single-vendor authored, no independent governance; implementers hedge (plan RK-3).

Alternatives, per concern (survey's layering, condensed)

None of these is "OKF but better" for the last-mile doc itself — each is better at a different layer, which is the strongest structural evidence that OKF's niche (portable human-authored markdown bundle) is real.

The counter-argument in OKF's favor — the user-guide point

The critique "don't wrap, just write a user guide for the authoritative tool" self-defeats into an argument for OKF: a user guide is a markdown how-to document with a title, a purpose, examples, and references. Give it type: guide, a resource: pointing at the tool, # Examples, # Citations — it is already an OKF concept document. A skill (SKILL.md) has the same shape. So the honest verdict is:

OKF is a reasonable standardization of exactly the artifact that the "alternative" proposes. The failure mode is not the format — it is filling the format with snapshot payloads instead of interface guidance. Wrap the interface, not the data: an OKF bundle whose leaves say "here is when and how to consult the source" is a durable last-mile layer; one whose leaves say "here is what the source contained on July 19th" is a stale shadow waiting to mislead an agent — unless regeneration and drift-CI make the snapshot effectively live.

What OKF adds over an unstandardized guide folder: portable identity (path-based), a facet (type), a routing layer (index.md), a history convention (log.md), tolerance rules that let heterogeneous consumers share one corpus, and a fast-growing lint/validate/publish/ingest toolchain. That is modest, but it is precisely the modesty that makes it adoptable — the survey's final judgement: OKF's strongest quality is "the unusually low distance between an ordinary documentation repository and an interoperable knowledge bundle".

8. Implications for composable-context

idea already contains the wrapper doctrine independently: "the better quality knowledge is the one that lives in its original authoring tools … memory and knowledge_base are for staging and not new source authority." OKF and composable-context are therefore solving the same problem one level apart — OKF standardizes the document format of the staged surface; composable-context defines the repository lifecycle and composition around it. Mapping:

Consequences:

OKF is a viable interchange profile for the knowledge side of a context repo — it costs one frontmatter field, and buys tool compatibility (validators, viewers, MCP servers, graph ingesters) for the composed surface.

The shadowing critique transfers fully. A composed context that flattens several repos' knowledge_bases is a wrapper-of-wrappers; every fidelity rule in §5 (tether, freshness, generate-don't-author snapshots, one-way promotion) applies at composition scope, and staleness now has two hops to hide in. The composition manifest should surface per-repo timestamp/version so the composed index can show freshness per branch.

OKF does not solve composition — no import semantics, no cross-bundle identity, no dedup/collision rules (the harborworks experiment's collision/scope problems remain composable-context's own to solve). Use OKF for the leaves and per-repo indexes; keep the manifest, flattening, and scoping logic in composable-context; optionally emit a generated KCP manifest for agent routing over the composed surface.

9. Recommendations

Adopt OKF as the format of last-mile and staged knowledge docs (knowledge_base, memory, guides, skills) — additively, via frontmatter only.

Enforce a local wrapper profile beyond base conformance: every derived doc must carry resource + # Citations + timestamp; add source_version and valid_until where staleness bites; lint this in CI.

Prefer interface wrapping. Leaves should teach selection, invocation pointers, and interpretation; snapshots only where a generator + drift-check exists (erd2okf pattern). Test documented invocation examples in CI where feasible.

Keep contracts native (OpenAPI/Avro/DCAT/Frictionless/package docs) and linked, never transcribed.

Treat index.md as the wrapper's real product — authored routing curation; generate everything else (backlinks, graphs, llms.txt, KCP manifest, JSON indexes) from the parsed corpus.

Keep authority one-way: bundle edits that correct facts flow back to the source and regenerate; the bundle is never write-authoritative. User-initiated promotion, per composable-context.

Depend only on OKF's stable core (type/title/description/tags/timestamp/resource, index.md/log.md, links-as-relations) and keep everything else in tolerated extra fields, so v0.x drift is absorbed (plan RK-3's hedge).

10. Full reference list

Spec owner (Google):

— non-replacement of Avro/Protobuf/OpenAPI; resource; # Citations; tolerance rules.

GoogleCloudPlatform/knowledge-catalog repo — reference producer (BigQuery → OKF + web enrichment), sample bundles, visualizer; "not an official Google product" disclaimer.

Google Cloud OKF announcement blog, 12 June 2026 — OKF as formalized LLM-wiki pattern; Knowledge Catalog ingests OKF.

Knowledge Catalog announcement, April 2026 — native aspect-type metadata model; OKF as ingest boundary.

BigQuery Conversational Analytics documentation — existing team wiki feeds Knowledge Catalog via OKF.

Andrej Karpathy, LLM Wiki gist (April 2026) — conceptual precursor: persistent derived wiki over sources.

Implementers:

okfgen (CKAN/Socrata/BigQuery/Firestore/docs/repos/DB → OKF); erd2okf drift-vs-conformance discussion; qsv describegpt OKF output.

KGLite (OKF → Cypher graph); NornicDB (OKF as source/exchange format); Graphify bridge proposal.

Kiso publisher (OKF → static site + llms.txt); WordPress Tick AI SEO / RankReady / Xagio (/okf/ endpoints, cron-synced, "not a ranking signal" disclaimers).

Open Knowledge, OKF Harness, okf-skills, okf CLI, okq, okf-gem, AKB, OpenKB — validation/runtime/authoring layers around OKF bundles.

Adjacent standards (the layers OKF must not replace):

Reviewers/critics:

July 2026 knowledge-centric information-systems vision paper — OKF/LLM-wiki as transition evidence, not endpoint.

July 2026 memory benchmarking paper — OKF memory improved retrieval precision, did not solve selection/session drift.

Local inputs:

MicroWebStacks\astro-huge-doc\plans\2026-07\19\okf-support\handoff.md — non-goals §4, source-authoritative rule §23, relation-inference limits §10.

...\okf-support\survey.md — layered-architecture verdicts and final judgement.

...\okf-support\deep-research-report.md — adoption evidence, toolchain, critiques, timeline.

...\okf-support\plan.md — OKF-native implementation stance, RK-3 spec-drift hedge.