# 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).


## OKF — spec + ADR follow-up

Documented the alignment rather than claiming compatibility:

- `docs/SPEC.md` §9.4 rewritten to match the code (was already stale — never
  documented `archived` or the old `meta.` keys). Now specifies reserved
  operational fields, bare OKF field names, `tags` as a YAML flow list, the
  `meta.` prefix for non-spec keys, and that the store block is stripped before
  serving. §8.1 notes arbitrary publisher metadata + reserved-key rejection.
  §13 Future Extensions adds OKF interop as a planned codec, not a conformance
  claim.
- `docs/adr/0002-okf-metadata-alignment.md` records the split-namespace
  decision and the integrity-boundary reasoning.

Framing decision (Fritz agreed): do **not** assert "OKF compatible / superset"
in normative spec text yet — it would overclaim. Accurate framing is two-layer:
a single demarkus document's **content model** is OKF-compatible (the doc
itself), but at the **system level** demarkus is a superset — it builds
versioning + hash chain + QUIC + capability auth + LOOKUP around an
OKF-compatible document. "The doc is OKF; we built more around it." Earn the
compatibility badge with the codec + a conformance check against OKF sample
bundles.


## Publisher metadata caps raised (10/512 → 50/1024)

Bumped while sizing for OKF producer-defined fields. Key insight: `MaxMetaBytes`
(sum of key+value lengths) is the **binding** limit, not key count — the 6 OKF
fields + importance already use ~7 keys / ~350 bytes, so you hit the byte wall
before the key wall. Doubling keys alone would have bought little.

Final: `MaxMetaKeys` 10→50, `MaxMetaBytes` 512→1024, `maxStoreFrontmatter`
1024→2048 (must cover 1024 bytes meta + operational fields + per-line
serialization overhead; worst case ~1.5 KB on disk). 50 keys is generous
headroom but harmless — the 1024-byte total still bounds real on-disk size.
Pre-1.0 is the cheap moment to right-size a wire limit. Constants in
`protocol.go` + `store.go`; both store and handler validation read the shared
constants. SPEC §9.4 updated. Boundary test now ties to `MaxMetaKeys+1` with
short keys so it isolates the key-count limit and won't rot on future bumps.