OKF Platform — how the concept bundle works

OKF Platform — how the concept bundle works

Audience: engineers, agents (including ID-71 onboarding agents), and the product owner who need to understand what a Canonical OKF concept bundle is, how it is produced, and how a citation inside it resolves back to Platform records. Status: the first Platform bundle has shipped — repo canonical-okf-showcase (renamed from canonical-okf-platform at the S487 publish, bl-479), first commit 3f66483 (11/07/2026), 18 concepts ({132.15} done). Client bundles are future; VPS producer deploy ({132.35}) and the client ontology overlay ({132.34}) are still pending (see Producer operations and Ontology sync). Conformance wave (15/07/2026, canonical 9a795c5e): the producer now emits an OKF-v0.1-conformant bundle — log.md is SPEC §7 date-grouped (## YYYY-MM-DD, newest date first), every # Citations entry is a numbered real markdown link [n] [label](target) (§8), the bundle-root index.md carries a single-key okf_version: "0.1" frontmatter stamp (§11), and a hand-authored CONFORMANCE.md replaces the bundle’s root README.md as the agent-facing guide. This RESOLVES the former log.md-format and README §9.1 divergences (DR-019, amended 15/07/2026); the remaining deliberate divergences are the closed validator-enforced type taxonomy and the opaque canonical:// scheme (plus the machine-facing ontology.json artefact, documented in the bundle’s CONFORMANCE.md). The published bundle’s reserved files were hand-migrated the same day (root README.md removed, CONFORMANCE.md added), but its concept trailers keep the LEGACY citation format until the {132.35} BI-18 re-proof regenerates them. Stale-claim discipline: every mechanic below is pinned to a source module / spec / DR so future drift is traceable. If a citation no longer matches the code, the doc is stale — fix the doc, not the reader’s understanding.

---

What an OKF concept bundle is

An OKF concept bundle is a client-owned git repo of markdown concept files — a distilled map over the knowledge held in Canonical’s Platform database. It is a genuine OKF artefact (GoogleCloudPlatform knowledge-catalog SPEC.md v0.1), produced by the id-132 concept producer (scripts/cocoindex_pipeline/producer/) and consumed read-only by the /okf landing + graph viewer in the Canonical app.

The bundle is deliberately not a pipeline input — a separate consumption indexer reads it. The producer writes the bundle; nothing feeds it back in. The medium is a client-owned git repo (DR-016): the producer regenerates it, and approved human edits are re-applied as producer overrides, never as free-floating file mutations.

The five mechanics

#	Mechanic	One-line	Page
1	Bundle navigation contract	The file layout: index.md + log.md + ontology.json + concept directories; reserved filenames; the deliberate OKF-superset posture (DR-019).	Bundle navigation contract
2	canonical:// resolution	How a citation inside a concept points back to a Platform record — the citable-target set {source_documents, reference_items, concept}; q_a_pairs stays DB-internal.	canonical:// resolution
3	Ontology sync	The in-repo base controlled-vocabulary register + the (stubbed) client overlay → the per-bundle materialised ontology.json (DR-027).	Ontology sync
4	The semantic-linter gate	How the closed type/relation vocabularies gate BOTH extraction writes and concept writes; HARD-reject vs SOFT-WARN (id-133).	Semantic-linter gate
5	Producer operations	Run/trigger (DR-018), deploy posture, and the BI-17 provenance-minting model that makes every citation traceable to a row actually read.	Producer operations

How the five fit together

1. The producer walks the Platform L-records (source_documents, q_a_pairs, reference_items, and the derived extraction rows) and drafts one concept per knowledge grain via a two-pass Anthropic agent loop (Mechanic 5).
2. Every fact a concept asserts must be cited — and every citation must resolve through the canonical:// builders to a row the run actually read (Mechanics 2 + 5, the BI-17 provenance ledger).
3. Each concept is gated by the semantic linter before it is written to disk: closed type set, valid resource: scheme, closed entity/relation ontology (Mechanic 4).
4. The gated concepts are written into the bundle layout alongside a regenerated index.md, an appended log.md run block, and the materialised ontology.json (Mechanics 1 + 3).
5. The bundle is git-synced to the client-owned repo; approved human edits survive as producer overrides (DR-016).

Cross-references (platform-wide anchors)

These pages live under initiatives/core-product/knowledge-base-foundations/okf-platform/ because the five mechanics are producer- and bundle-specific even where they touch Platform-wide tables — keeping them one navigable set serves a reader (or ID-71 agent) landing here cold. The platform-wide anchors they lean on:

• Decision register — reference/decision-register.md (DR-016, DR-018, DR-019, DR-024, DR-027 are the load-bearing rulings for this set).
• Specs — specs/id-132-okf-concept-producer/ (PRODUCT/TECH/PLAN + OKF-LANDING.md), specs/id-133-ontology-three-layer-pass/TECH.md, specs/id-138-corpus-durable-home/SEED-CONTRACT.md.
• Platform context — reference/platform-context.md (four-DB topology, deploy hosts).
• Forward graph — OKF Forward Task Graph (S448) — the ID-132 / 133 / 135 / 138 sequencing this doc set is the reference substrate for.

Coordination boundaries

• Deploy-time ontology seeding is owned by {45.10} (first-client onboarding) — this set points to it as future work and does not author it.
• The client ontology overlay ({132.34}) and VPS producer deploy ({132.35}) are pending; where a mechanic depends on them, the page says so explicitly rather than describing a shipped state that does not yet exist.