feat(dialect): add okf target (Open Knowledge Format bundles)

[andrebaaij]

What and why

Adds okf as an emit-only target: Google Cloud's Open Knowledge Format, a vendor-neutral bundle of markdown concepts with YAML frontmatter. It gives semglot an output aimed at agents that read curated context as files rather than as a semantic-layer config.

The bundle is one type: Table concept per model under tables/, one type: Metric concept per metric under metrics/, notes.md for passthrough notes, and the reserved index.md in every directory. Relationships become markdown links between concepts, so the joins are part of the knowledge graph rather than prose only.

Emit-only by design. The spec prescribes no type taxonomy and carries meaning in free prose, so reading a bundle back into the IR would be a heuristic markdown scraper, not a parser. A test pins that okf does not register as a source.

The spec and the reference implementation disagree

SPEC.md requires exactly one frontmatter field, type. The reference implementation's OKFDocument.validate() requires type, title, description and timestamp to all be non-empty:

# okf/src/reference_agent/bundle/document.py
REQUIRED_FRONTMATTER_KEYS = ("type", "title", "description", "timestamp")

The reference implementation is what actually reads bundles, so this PR satisfies the stricter of the two. The first draft omitted timestamp on spec grounds, and all 13 concepts failed validation. What changed:

• timestamp is stamped, but never from a clock. It comes from a new profile timestamp field, falling back to the source's last commit date. The same checkout still produces a byte-identical bundle, so the goldens hold.
• Descriptions are synthesized when the IR has none. A metric falls back to its rendered definition, a table to "The <name> table."
• index.md is byte-identical to regenerate_indexes output, so their tooling is a no-op on our bundles instead of rewriting them.
• Links are directory-relative and body headings are #, matching the published ga4 bundle. The spec recommends absolute links for stability, but stability is moot for a generated bundle and relative is what the reference viewer resolves.

How this is tested against upstream

Three layers, since goldens happily pin a malformed bundle:

1. test/okf_conformance_test.go re-implements the reference rules in Go: frontmatter parses, required keys non-empty, every link resolves. Runs in CI with no extra toolchain. Mutation-checked, it fails when the timestamp is dropped.
2. test/okf_contract_test.py runs the real OKFDocument.validate() and regenerate_indexes() over the golden bundle. Not in CI (needs Python 3.11+ and a clone of upstream); setup is in the docstring.
3. reference_agent visualize renders the bundle as the reference viewer draws it.

All three pass against knowledge-catalog @ main as of 2026-07-20:

OK: test/models/ecommerce/dbt/okf validates against the OKF reference implementation
Wrote 13 concept(s), 24 edge(s), 23865 bytes → viz.html

The 24 edges are our generated links resolving in their viewer, for example metrics/aov -> tables/fct_orders.

Measures and data types are emitted as well. Without a # Measures section the bundle never names the aggregatable columns (order_net_booked, quantity); a reader would have had to reverse them out of a metric's definition SQL.

No IR changes were needed: ir.Model already carries everything OKF can express. dialect.Options gained a Timestamp field.

Checklist

• This PR is based on main (not stacked on another unmerged branch)
• If it changes emitted output, I regenerated goldens (UPDATE_GOLDEN=1 go test ./...) and reviewed the diff (don't bless output you haven't read)
• Docs updated if behavior or a dialect mapping changed (README.md, dialect/README.md)

🤖 Generated with Claude Code