Kjell Tore Guttormsen 9d1f4b14ed test(fixtures): replace sector-specific example material with generic, fictitious examples — green

Every fixture, test document, tool example and document now uses an invented
kitchen-and-baking handbook series, written in this repository. The package's
behaviour is unchanged; src/ changes are comments and help text only.

- Generated fixtures are regenerated from their generators. Their structural
  counts are identical before and after: elements, images, rows, cells,
  headings, bookmarks and the witness inventory's per-document totals. The
  image-inbox and accounting documents are renamed kapittel-84-*.
- tools/okf_accounting_gate.py: the two options that named one real corpus
  each are replaced by a generic, repeatable --corpus PATH with no default.
  Row 5 compares the PDF pair alone. Gate verdict unchanged: RED rows 2, 3, 6.
- tools/okf_witness.py: the STS JSON reader for one publisher's delivery is
  removed, along with its three twins and five tests. The mutation harness
  loses W09.
- docs/: 13 dated reports that documented runs on a retired reference corpus
  are removed, and 40 are neutralized. Dead links are removed, and no new
  dangling path is introduced.
- The synthetic MCP-gate corpus and the residual probe words are neutral.

Valgt: keep the `okf quality --fasit` bar value (the measured fraction, one corpus) and
rewrite only its provenance, because the verdict stays unchanged and the
number names nothing.

Term check with the local list: 0 of 411 tracked files, 0 file names, 0 of
27 binary fixtures. Suite after git add: 2457 passed, 1 skipped. The base
tree had 2460 passed and 2 skipped; five tests went with the JSON reader and
four were added by the term check. ruff, ruff format and mypy --strict src/
are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-09-23 14:52:02 +02:00

4.8 KiB

Raw Blame History

Proposed SPEC § 6.4: `assets/`, the bytes a concept points at

Status: a proposal, raised from a consumer. Written in this repository because this repository implements the shape; the wording belongs upstream and _okf-canonical is not edited from here. Pinned commit read while writing: ad30107 (OKF v0.2).

Why it is needed

OKF v0.2 is silent about non-markdown files. § 3 says "A bundle is a directory tree of markdown files"; § 11's conformance list scopes every clause to .md files; § 6.3 makes references/ a convention for external material carried as concepts. So a picture is neither permitted nor forbidden — it is unaddressed, and a producer that carries one is guessing about where it goes and what a consumer may assume.

The need is not hypothetical. Measured on a Norwegian reference standard published both as a 701-page PDF and as a NISO-STS XML delivery: the process text is carried in full, and 12 Tabell N-N and 9 Figur N-N captions stand over nothing, because the publisher ships those tables as raster images in both deliveries. Section 84 says its classes "are given in table 84-2" and table 84-2 is a JPEG. A bundle built from that document reads as complete and is not.

The proposed wording

6.4 The assets/ convention

A bundle MAY carry non-markdown files that its concepts point at — images extracted from a source document, and anything else a concept embeds rather than describes. An assets/ directory at the bundle root conventionally holds them.

A concept points at an asset with a standard markdown image or link whose target is a path-valued reference under § 6.2 — the bundle-relative form (/assets/<name>) is recommended, for the same reason § 6.1 recommends it for links between concepts: it is stable when a concept moves within its subdirectory.

Asset file names are the producer's. A content-addressed name (for example a prefix of the file's SHA-256 followed by a readable remnant of the source's own name) is RECOMMENDED, because it makes the same bytes dropped twice one file and makes a rebuild of one corpus produce one bundle.

An asset is not a concept. It carries no frontmatter, it is not enumerated by § 8's index files, and § 11's conformance clauses do not apply to it — they are scoped to .md files, and this section does not widen them.

Consumers MUST NOT reject a bundle because it carries files they do not recognise, and MUST tolerate an asset pointer whose target is absent, for the same reason § 6.1 requires them to tolerate a broken link: the pointer may record that the source had a figure this bundle does not hold.

What it does NOT propose

No screening claim. Whether the bytes of an asset were examined is outside this section and outside the format. This library states it per run in log.md because its own gate is text-only; a picture is not text and did not pass it.
No required directory. assets/ is a convention, exactly as references/ is. A producer that puts its images elsewhere and points at them correctly is conformant.
No new frontmatter family. This library writes a count (images: N) on its own profiles, and that is a local key, not a proposal. § 11 already tells consumers not to reject a concept over an unknown key.

Conformance measured, not assumed

The claim "existing consumers do not break" is § 11 item 1 scoping to .md files, plus the consumer-side MUST NOTs. Measured on a bundle WITH assets/, built by okf build from the fixture inbox:

Surface	Result
`okf check` (17 rules)	`conformant: 17 rules over 4 excerpts and 2 withheld entries, 0 findings`, rc 0
`okf skill`	rc 0
`okf consume`	rc 0, 4 excerpts; the pointers travel with the excerpt text
`okf quality`	rc 3 — "nothing could be judged", because each file type has one document and the floor is five. No false `PASS`, no crash
guard 1.4.0 `okf.import_bundle`	6 of 6 concepts merged; the pointer blocks pass the gate as body text

The guard does not reject a bundle carrying binary files — it does not see them, because the importer walks .md. So no coordination message to llm-ingestion-pipeline-security is needed for this step.

The measurement that did NOT pass first time is in the report: Door C merged the concepts and wrote no assets/ at all, so every pointer in the imported bundle named a missing file. Fixed here, by the content-identity rule that door already owns. The run record is the 0.10.0 entry in CHANGELOG.md.

Route

Raised through portfolio-optimiser-commons, which owns the ingest-spec this library implements, and from there upstream. Not edited into _okf-canonical from here: that mirror is a read-only pin, and a spec change written by its implementer is not a spec change.

4.8 KiB Raw Blame History

Proposed SPEC § 6.4: assets/, the bytes a concept points at