# Journal — 2026-06-22

## OKF (Google Open Knowledge Format) alignment — step 1: store frontmatter

Google published OKF v0.1 (2026-06-12): an org-knowledge format that is
near-identical to demarkus's own model — directory bundles of markdown,
cross-link relationship graph, `index.md` hubs, path-minus-`.md` as concept
identity. Spec: github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

### The one real seam

OKF carries metadata **in-body** as YAML frontmatter (required `type`;
recommended `title`/`description`/`resource`/`tags` (a YAML list)/`timestamp`).
demarkus carries metadata **out-of-band** and treats a body that opens with
`---` as literal content. So syntactically identical (`---` frontmatter), but
different data model: in demarkus the on-disk `---` block is a store-owned
envelope (`version`/`previous-hash`/`archived` + publisher data), it is
**stripped before serving**, and the catalog reads only the publisher keys.
Naively publishing a raw OKF file double-wraps the frontmatter and the OKF
`type`/`tags` never reach the catalog.

### Decision — split namespace in store frontmatter (`protocol/store/store.go`)

Pre-1.0, so changed the storage format. Promote the recognized OKF field names
to **bare** frontmatter; keep everything else namespaced:

- Recognized OKF keys (`type`,`title`,`description`,`resource`,`tags`,`timestamp`)
  → written bare. `tags` serialized as a YAML flow list `[a, b]` to match spec.
- Non-spec publisher keys (`importance`, custom) → keep the `meta.` prefix.
- Store-operational (`version`,`previous-hash`,`archived`) → bare, unchanged.

### The non-obvious why

The `meta.` prefix was not decoration — it was the **integrity boundary** that
stopped a publisher from supplying `archived: true` / `version: 999` and forging
store state (`extractMetadata` read only `meta.*`). Dropping it for the OKF
fields means that boundary now has to be enforced by name: added a
`reservedMetaKeys` denylist (`validateMeta` rejects them) and `extractMetadata`
excludes them. Keeping arbitrary publisher keys under `meta.` preserves the
boundary for the open-ended set — only a closed, known set of OKF names goes
bare.

Key property that kept the change contained: the **in-memory metadata map stays
bare-keyed**, so catalog/handler/filter were untouched. Only `buildVersionFile`
(write) and `extractMetadata` (read) changed. `tags` round-trips list↔csv, so
the map contract (`"a,b"`) is unchanged.

Back-compat: `extractMetadata` still reads old `meta.tags`/`meta.type` writes —
live `soul.demarkus.io` data and existing immutable versions keep working.

### What this does NOT do

Vocabulary alignment only. The frontmatter is still **stripped before serving**
and the store's `versions/` layout is not an OKF bundle tree — so demarkus does
not yet serve or ingest OKF bundles. That is the next layer: an import/export
codec (and possibly server-native bundle serving). Because the stored field
names are now the literal OKF names, that codec is 1:1 rather than a translation
table.

Open scoping question parked: import-only vs round-trip codec vs server-native
content-negotiated bundle serving; and where it lives (`tools/demarkus-okf` CLI
vs `client/okf` package).