Kjell Tore Guttormsen
9d1f4b14ed
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>
95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
# 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.
|