Kjell Tore Guttormsen
2504011010
Placement settled by catalog's own reading of upstream at the pinned commit
3fcbb9f: SS8:509-510 and SS12:773-775 both put `okf_version` in a bundle-root
`index.md` frontmatter block, and SS12 calls it the only place frontmatter is
permitted in an index. Catalog's spec says the opposite about the same file;
that divergence is theirs against upstream, and we conform to upstream.
The value never touches a profile. `OKF_V0_2.index.root_frontmatter` names the
key; the caller supplies the value through a new keyword-only
`root_frontmatter_values` mapping. That keeps V4/V-A5 intact - `okf_version`'s
value tracks the upstream Google version and belongs to catalog (E1), so a
constant here would claim a decision we do not own and would have to be chased
on every upstream release. In the fixture the value is fixture DATA
(`okf-version.txt`), not a literal in our source.
Ordering comes from the policy, not the caller's mapping: a dict preserves
insertion order, so two callers passing the same keys would otherwise emit
different bytes. A key the policy does not name is refused fail-fast, before
any disk mutation. Omitting the argument emits no block at all - SS12 is a MAY
and none of upstream's four reference bundles declares the key.
The block is written only when the index is CREATED, so a re-run into an
existing bundle stays byte-identical (A-E5).
Raw-byte assertions rather than parsed ones, on the committed fixture as well
as on fresh runs: catalog measured that a quoted value fails their shape regex
with exit 1 and that a BOM hides the marker while still exiting 0.
`yaml.safe_load` returns "0.2" either way and strips a BOM first, so a parsed
assertion masks exactly those two defects. Asserting the frozen fixture catches
what a self-comparison cannot - regenerating from a broken emitter moves both
sides together.
A-E6 is now placement-explicit (promised catalog in
|
||
|---|---|---|
| .. | ||
| ingest-golden-file | ||
| ingest-golden-http | ||
| ingest-golden-okf-v0-2 | ||
| ingest-golden-sql | ||
| README.md | ||
Golden extractions (ingest-spec §11)
One directory per case, ingest-golden-{source type}/, each containing:
| Entry | Meaning |
|---|---|
manifest.json |
The manifest under test. |
fixture/ |
The source content (CSV catalogue, sqlite database, or mock payloads). |
ingested-at.txt |
The fixed timestamp, one line, §5 format. |
expected-bundle/ |
The expected materialized bundle, compared byte for byte. |
ingest-golden-file and ingest-golden-sql are the conformance MUSTs. The
http source type is an OPTIONAL extension point (spec §1); this repository
implements it, and ingest-golden-http exercises it against the mock payloads
in its fixture/ directory — the conformance suite never opens a socket and
runs without credentials (§11). For the sql case, the test sets the
OKF_GOLDEN_SQL_DB environment variable to the fixture database path; for the
http case, the injected mock transport serves fixture/{query path}.
The suite (tests/test_golden.py) re-materializes each case into a fresh
directory and compares the result against expected-bundle/ file by file,
byte for byte — the load-bearing golden-regression seam (§11).