Skip to content

Export — The Fichero profile of open standards — Design Spec (#6439)

Milestone: export-pipeline Manual: TBD — a section “Your work as open data”: what the bundle holds, which standard each part speaks, how to publish a site from it, and how to bring a bundle back in with nothing lost.

Design-led (Testing Constitution). The creative director owns this intent; tests enforce it; code makes them pass. Status: DRAFT (2026-11-08, written in parts as the owner thinks aloud; expect revisions). Builds on exporter.md (the one record stream and its emitters), public-site.md (the public archive site), ../source/iiif.md (IIIF in and out), ../source/formats-and-training.md (the one page harness, the round trips, the loss report), ../source/catalogue-export.md (the workbook), ../source/rights-and-access.md (what leaves out), ../source/synced-folder.md and the kept exports (#5485). Tags: [OK] built · [PARTIAL] exists in part · [GAP] designed, not built.

Intent

Fichero is the editor. The web is a static rendering. Everything a project knows — its images, segments, readings at every level, orders, notes, hands, claims, catalogue fields, rights, the models that read it and the runs that made each thing — leaves Fichero as ONE bundle that speaks open standards, and comes back in with nothing lost. Every other output (a site, a workbook, a BibTeX file, a Word transcript, a training set) is a VIEW derived from that bundle, never a parallel format with its own idea of the data.

The standards are the existing ones, used as published, never a dialect of our own: RO-Crate for the bundle, IIIF Presentation 3 and Image API 3 for images and their canvases, W3C Web Annotation for everything said about a canvas, RDF (JSON-LD, schema.org context) for the graph, PROV-O for who or what made each thing, CSVW and Parquet for the tables, Dublin Core and schema.org for the catalogue, CSL JSON / CITATION.cff / BibTeX for citation, SKOS for the reference lists, PAGE XML / ALTO / TEI / SVG / Markdown as page views, Croissant and model cards for training sets and models.

Rulings (owner, 2026-11-08, from #6439 and its comments)

  1. One bundle, many views. The bundle is the canonical exchange format. The existing BibTeX exporter, the catalogue workbooks, Word, Markdown and the Eleventy site are DERIVED VIEWS of it, not parallel formats: they read the same stream and the same ids.
  2. Order of writing: (1) bundle + round-trip, with tables and catalogue; (2) Markdown and the page views; (3) Publish, with citation data; (4) deep links; (5) training sets, Croissant, model cards; (6) import, with BibTeX/BibLaTeX import.
  3. Publish writes a DATA FOLDER and a SITE CONFIG for a website whose template, viewer and build live in their OWN open-source repository (own licence; Eleventy, Mirador or OpenSeadragon, MapLibre), buildable and viewable with no Fichero code or service; Fichero can push to a static host. Per-item rights and licence are shown; the open data bundle is downloadable from the site; deep links open the app only when it is installed, a plain link otherwise.
  4. No new API where one fits. Reuse the record stream, the page exporter, the IIIF routes, the KG RDF export, the catalogue columns, the kept exports and the format harness. Spec only, no code; not in the dev build.
  5. Lossless round trip is the test: a library exported, imported into a fresh library and exported again gives the same bundle.
  6. Private and public are respected throughout (confirmed 2026-11-08): per item, per reading, per entity; nothing private leaves, and a statement is public only if its sources are. The gate is the exporter’s existing one, applied once.
  7. The published site has entities, statements (subject, verb, object), dates, places, readings and translations (confirmed); GitHub Pages and Netlify are first-class targets, as is any folder.
  8. Recipes travel too (addition 3, 2026-11-08): the bundle exports and imports the project’s recipes — steps, settings, chains, the model per step — and its run records, as PROV-O plans and the Workflow Run RO-Crate profile, linked from each reading; never keys or secrets; model cards for every model USED, not only trained ones; an imported recipe arrives runnable-when-ready with a list of what is missing. The door is Share Recipe / Use a Recipe (recipe-designer.md Step 14.1).
  9. Owner answers 2026-11-08 (DECIDED): (a) a selection’s bundle is ONE root Dataset, isPartOf naming each folder touched; (b) ids are fichero: references only until Publish gives a base URL, and the crate then states both forms; (c) in the edition PDF, when standards conflict, PDF/A for archiving is the DEFAULT, tagged PDF is the default, PDF/UA-1 is opt-in; (d) the DATA licence is the user’s, per project and per item (the rights record, already specced); the site template repository’s name (fichero-site) and its licence stay PROVISIONAL until the owner creates the repository, and the template must work with ANY data licence.
  10. The edition PDF is typeset with Typst (#6440, RULED 2026-11-08): a Typst template generated from the bundle, deep links as Typst links, PDF/UA and PDF/A as Typst supports them, the Typst compiler shipped inside the app. The edition is a DERIVED VIEW of the bundle, never a parallel export; private never prints.

The profile, by layer (the map)

One row per layer: what is exported, the standard it speaks, the existing piece that produces it today, and the view derived from it. The bundle’s folder names are in the first column.

Bundle part Standard Produced today by Derived views
ro-crate-metadata.json RO-Crate 1.1 (JSON-LD, schema.org) nothing (the one new emitter, over iter_export_records) every view reads it for ids and parts
images/ the files, or IIIF Image API 3 URLs by reference the library’s originals and renditions; iiif.export.points-at-original the site’s tiles (level 0), thumbnails
iiif/ Presentation 3 manifests and collections GET /api/iiif/iiif/manifest/{document_id} (per document; folders not built) the site’s viewer, “Copy IIIF Link”
annotations/ W3C Web Annotation pages GET /api/iiif/iiif/lines/{document_id} (working pass’s lines; other readings, notes, claims not built) the site’s transcription beside the image
graph/ RDF: JSON-LD (schema.org context) + PROV-O GET /kg/export/rdf (entities, claims; no attribution today) person and place pages, SPARQL elsewhere
tables/ CSVW (CSV + csv-metadata.json) and Parquet export_parquet through DuckDB; the record stream’s columns the catalogue workbook, Excel, the HF dataset
catalogue/ Dublin Core terms + schema.org, and the IIIF manifest’s metadata, rights, requiredStatement the catalogue attributes and prototypes (catalogue.export.template-is-the-prototype); iiif.rights-travel the workbook’s rows, the site’s document pages
views/ PAGE XML, ALTO 4.4, TEI, SVG, Markdown, plain text; a DuckDB file page_export.export_page through the formats registry (SVG, Markdown-per-page and DuckDB not built) the synced folder, Word, “Export Page As”
citation/ CSL JSON, CITATION.cff, BibTeX/BibLaTeX bibliography/importers.py (write_bibtex, read_csl_json), POST /api/bibliography/export.bib cite-this-page, the site’s meta tags
reference/ SKOS (RDF) or CSL JSON the gazetteer and name list (../kg/project-gazetteer-and-names.md) the site’s search index
training/ Croissant (JSON-LD) + model cards training/kraken_set.py, training/line_pairs.py, recipes/cards.py (no Croissant, no card file) the HF dataset bundle (export.huggingface-dataset-ready-bundle)
fichero/ the choices and the id map (JSON) page_export.ExportChoices; fichero:segment/… references (SegmentReference, POST /api/locations/resolve) deep links, re-import matching

The kinds (one table, used by export and import)

Export (Part 1) and import (Part 6) cover IDENTICAL kinds: this table is the list both read (owner, 2026-11-08). A kind not in it is not in the bundle; a kind in it is exported, imported, matched and reported. Merge key is what import matches on, in order; yours wins says what happens when the library’s copy was set by a person: the incoming value is kept beside it, never over it.

Kind Id shape Bundle parts Merge key, in order Yours wins
project, folder fichero:folder/<library>/<id> crate root and Dataset parts, catalogue/ one id; the folder’s path under the root name and catalogue fields
document, page fichero:document/… iiif/ manifest and canvas, catalogue/, tables/documents, tables/pages, views/ one id; the IIIF canvas id kept from a by-reference import (iiif.round-trip); file checksum catalogue fields
image rendition fichero:rendition/… images/, the manifest’s painting annotation, tables/renditions (the edit chain, which one readers use) one id; checksum the readers’ rendition choice
segment (region, line, word, table cell) fichero:segment/… annotations/ targets, views/ zones, tables/segments one id; geometry equal to the pixel on the same canvas shape edited by a person
reading (every kind and LEVEL, incl. translation translation:<tag>) fichero:reading/… annotations/ bodies (one page per level), views/, tables/readings one id; same segment + level + text + maker a person’s reading at that level
reading order fichero:order/… annotations/ (an ordered page), tables/orders one id; same page + same sequence a person’s order
note, mark, editorial fact fichero:mark/… annotations/ (labelled pages), tables/marks one id always a person’s
hand, campaign fichero:hand/… reference/ (SKOS), graph/ one id; name name and notes
entity (person, place, organisation, concept) fichero:entity/… graph/, reference/, tables/entities AUTHORITY id first (Wikidata, GeoNames, VIAF, Pleiades: sameAs/exactMatch), then one id, then a name-only match as a PROPOSAL a confirmed entity, its forms
statement (claim: subject, verb, object, sources) fichero:claim/… graph/, tables/claims, tables/mentions one id; same subject + verb + object + source set a person’s statement or review
date (attested, EDTF) and place (georeference) on the segment, entity or catalogue value catalogue/, graph/, tables/, the georeference files (geo-out) with their carrier with their carrier
catalogue entry and prototype mapping with the document; fichero:prototype/… catalogue/, tables/catalogue, the manifest’s metadata the document’s id; the prototype’s id fields a person set
rights record fichero:rights/… the crate’s license, the manifest’s rights, tables/rights (public records only) one id; scope always (a record is never loosened by import)
reference lists (gazetteer, names, kinds, Tema) and bibliography fichero:concept/…, fichero:work/… reference/, citation/ authority id first, then one id, then label as a proposal a person’s label or match
training set fichero:set/… training/<set>/ one id; manifest checksum n/a (sets are not edited)
model and its card the card id <runtime>:<source>@<version> models/<id>/ the card id the project’s measured figures
recipe (steps, settings, chains, the model per step, prompts) fichero:recipe/<library>/<id>@<version> recipes/<id>/ (recipe.yaml, prompts, setup answers; never keys), graph/plans.jsonld (PROV plans) one id and version; a same-content recipe under another id is a proposal the project’s own edits to a shared recipe
run record (a recipe run, its steps, attempts, what each read and wrote, what it cost) fichero:run/… graph/provenance.jsonld (Workflow Run Crate profile), tables/runs, tables/attempts one id n/a (records are facts)
model card, for every model USED the card id <runtime>:<source>@<version> models/<id>/ (trained ones with weights referenced; used ones as the card alone) the card id the project’s measured figures
step, agent (PROV) the step’s id inside its run, the card id, the account graph/provenance.jsonld one id n/a

Declared losses are listed PER KIND in the crate (fichero:loss, from the formats’ LossReport and from the import’s report): what a format cannot hold, what the receiving library has no field for (kept as unrecognised, source.format.keeps-unrecognised), and what was left out as private.

Behaviors

Part 1 — the bundle and its round trip, with the tables and the catalogue (#6439, owner order (1) and addition (a), (b)).

  • profile.editor-not-the-web — [GAP] (#6439, ruling 1) Fichero is the editor and the only writer; everything outside it is a rendering of the bundle. Nothing on a published site, in a workbook or in a view writes back into the project except through an import (Part 6) or a community note for review (site.community-notes). Acceptance: no export surface carries a write-back URL to the engine; the site’s config names the bundle as read-only data. Test: test_profile_views_are_derived_6439.py (not yet written; every emitter reads the stream and the same ids, none holds a second model of a record).
  • profile.private-never-leaves — [GAP] (#6439, ruling 6) the bundle, and every view derived from it, carries ONLY what is public to the scope exported: the one filter in the record stream (source.format.rights-filtered-once) applies the exporter’s existing gate, the export routes’ reads check over every document named (assert_library_reads_every, documents_under in api/routes/ingest/export.py) and the rights record’s per-item answer (source.rights.record, source.rights.exports-leave-out), extended to readings and entities: a PRIVATE reading (a level, a person’s note-reading, a reading marked private) is not written to any part, not even as a count; a STATEMENT (claim) is written only when EVERY source it rests on is public, the rule the entity and claim reads already apply (source.rights.claims-with-only-denied-evidence-are-hidden), and a statement with one public and one private source goes out with the public evidence only; an ENTITY reachable only through private items (every mention, every statement private) is dropped from graph/, tables/entities.csv, reference/ and the crate, with no placeholder and no withheld count in the bundle. The site’s data folder (Part 3) is built from the bundle, so it can hold nothing the bundle does not. Acceptance (the fixture of Step 1.5): a private page leaves out its statement; an entity mentioned only on that page is absent from every part; a private reading never appears in annotations/, views/ or tables/readings.csv; the public statement with a private second source lists the public source alone. Test: test_bundle_keeps_private_in_6439.py (not yet written; the three absences and the one trimmed statement, by grep over every file of the bundle), the existing test_holds_close_6320.py and test_read_exports_check_the_body_ids_6320.py.
  • profile.bundle.is-an-ro-crate — [GAP] (#6439) a project, a folder or a selection exports as ONE bundle, a folder or its zip, that is a valid RO-Crate 1.1: ro-crate-metadata.json at its root (JSON-LD on the RO-Crate context plus the schema.org context the KG export already uses), the root Dataset naming the scope (its title, the catalogue’s description, license, datePublished, the Fichero version and the engine identity as sdPublisher), one File or Dataset entity per part with encodingFormat and conformsTo (the IIIF, Web Annotation, CSVW, PROV-O, PAGE, ALTO, TEI profile URIs), and hasPart listing every file written; nothing is in the folder that the crate does not describe, and nothing the crate describes is missing. The crate is written by ONE new emitter beside the others, export_ro_crate in export_service.py, over iter_export_records and the page exporter, and it is reached as a KEPT EXPORT format (/export/kept, format bundle, one folder per project, rewritten when the project changes) and as the one-shot “Export Bundle…” that keeps and writes once to a chosen folder; no new route. Acceptance: a project’s bundle validates with the RO-Crate validator and with the JSON-LD expand/compact isomorphism check the KG export already runs; every file in the folder is in hasPart. Test: test_bundle_is_a_valid_ro_crate_6439.py (not yet written; the crate’s shape, hasPart equals the folder’s files, the validator), the existing test_export_service.py and test_catalogue_workbook_kept.py.
  • profile.ids.one-id-everywhere — [GAP] (#6439) every thing in the bundle has ONE stable identifier used in every part: the segment reference as the app writes it (fichero:segment/<library>/<document>/<segment>, SegmentReference), and the same shape for documents, readings, orders, entities, claims, runs and people (fichero:<kind>/<library>/…); when the scope has a publish base URL (Part 3) the crate also states each id’s https://…/id/<kind>/… form as sameAs, so the site, the manifests, the annotations, the RDF and the tables all name the same thing by the same string; PAGE and ALTO carry the ids as today (source.sync.files-carry-ids). An id is never re-minted on export: exporting twice gives the same ids. Acceptance: a line’s id in annotations/, tables/segments.csv, views/<page>.xml and graph/ is one string; a resolve of it (POST /api/locations/resolve) lands on the live segment. Test: test_bundle_ids_are_one_string_6439.py (not yet written; the id of one segment read from four parts), the existing test_segment_references.py.
  • profile.provenance.prov-o-on-everything — [GAP] (#6439) every reading, segment, order, claim, catalogue value and image rendition in the bundle says who or what made it, in PROV-O: prov:wasAttributedTo a prov:Person (the account, by its public name) or a prov:SoftwareAgent (the model by its card id <runtime>:<source>@<version>, source.model.card-id), prov:wasGeneratedBy a prov:Activity for the run (its recipe step, start and end, the settings that matter: temperature, prompt id, level), and prov:wasDerivedFrom what it was made from (the rendition read, the earlier reading corrected, the teacher’s line); the source is the record’s attribution chain (_made_by in export_service.py, the readings’ created_by/read_from/run). The STORED value goes out under its own name and a derived value under a clearly separate one, never substituted (the ruled direction in exporter.md’s design note). PROV travels in graph/provenance.jsonld on a second named context (prov), referenced by id from every part, and as each W3C annotation’s creator and generator. Acceptance: a machine reading corrected by a person exports as two readings, the machine’s attributed to the model’s card id and generated by its run, the person’s attributed to the person and derived from the machine’s. Test: test_bundle_provenance_is_prov_o_6439.py (not yet written; the two readings and their three PROV relations; the stored value named as stored), the existing test_jsonld_export.py.
  • profile.tables.csvw-and-parquet — [GAP] (#6439, addition (a)) tables/ holds the record stream as TABLES twice over, the same rows and columns: one CSV per record type (documents, pages, segments, readings, orders, entities, claims, mentions, runs, catalogue) with ONE csv-metadata.json (CSVW: each table’s tableSchema with typed columns, primaryKey, foreignKeys between the tables by the one id, aboutUrl the id’s URL form), and the same tables as Parquet through the existing DuckDB writer (export.duckdb-parquet-not-pyarrow), one file per table, never PyArrow. The catalogue workbook (catalogue.export.*) and the Excel emitter are derived from these tables: their columns are the catalogue table’s columns under the prototype’s labels (catalogue.export.template-is-the-prototype), so a cell in the workbook and a cell in tables/catalogue.csv are one value. Acceptance: csv-metadata.json validates as CSVW; readings.csv’s segment_id is a declared foreign key to segments.csv; the Parquet segments file has the CSV’s rows; a workbook built from the same scope has the catalogue table’s values cell for cell. Test: test_bundle_tables_are_csvw_and_parquet_6439.py (not yet written; the schema, the keys, CSV equals Parquet, workbook equals table), the existing test_export_service.py and test_catalogue_sheet_rows.py.
  • profile.catalogue.dublin-core-schema-org-and-iiif — [GAP] (#6439, addition (b); fits catalogue.export-standards, #5365) each document’s catalogue entry is written once in catalogue/<document>.jsonld as Dublin Core terms (dcterms:title, creator, date as EDTF, description, extent, language, rights, accessRights, isPartOf, identifier) and schema.org (ArchiveComponent/CreativeWork with holdingArchive, locationCreated, about for the people and places by their graph ids), mapped from the catalogue attributes by their prototype’s declared mapping (the mapping is data on the prototype, never a switch in code); the SAME values appear as the IIIF manifest’s metadata (label and value pairs in the project’s languages), rights (a URI from the rights record, source.rights.record), requiredStatement (the attribution the archive asks for) and provider, so the manifest and the catalogue file never disagree. Restricted material is left out ONCE, in the record stream (source.format.rights-filtered-once, source.rights.exports-leave-out): a withheld document has no catalogue file, no manifest, no rows and no count anywhere in the bundle. Acceptance: a catalogued document’s title, date and rights read the same from catalogue/<id>.jsonld, its manifest and tables/catalogue.csv; a restricted document is absent from all three and from hasPart. Test: test_bundle_catalogue_is_dc_and_schema_org_6439.py (not yet written; the mapping from one prototype, the three places equal, the restricted document absent), the existing test_catalogue_sheet_template.py and test_iiif_by_reference.py.
  • profile.round-trip.export-twice-is-identical — [GAP] (#6439, ruling 5, the first half) exporting the same scope twice, with nothing changed between, gives two bundles that are byte-identical apart from datePublished; every kind in the kinds table is present with every record the scope has (the test counts per kind: segments, readings at each level, orders, entities, statements, catalogue entries, rights, reference concepts); every file validates against its schema or profile (the formats registry validates each page view as today, source.format.export-validated; the crate, the manifests, the annotation pages and csv-metadata.json against their JSON schemas kept on disk, source.format.schemas-on-disk, never fetched); every loss is DECLARED in the crate (a fichero:loss list per file from the formats’ LossReport, source.format.loss-report), never discovered. The second half, import of a bundle into a fresh library and re-export giving the same bundle, is Part 6 (profile.round-trip.lossless); the test file is written in Part 1 with this half and gains the second half there. Acceptance: two exports of a fixture library differ only in the date; a TEI view’s declared losses are listed in the crate beside the file. Test: test_bundle_round_trip_6439.py (not yet written; the two exports compared, every file validated offline, the losses listed), the existing test_pagexml_round_trip.py and test_export_validation.py.

Part 2 — the page views: Markdown, PAGE, ALTO, TEI, SVG, plain text, DuckDB (#6439, owner order (2)).

  • profile.views.every-view-is-a-page-export — [GAP] (#6439) views/ is written by the ONE page exporter and nothing else: each page becomes a SourcePage once (page_export.page_from_library, with the bundle’s choices: pass, order, reading kind and level, source.format.export-choices) and every format in the registry writes from it (formats.write_page: PAGE XML, ALTO 4.4, TEI, hOCR, YOLO today; SVG, Markdown and plain text join the registry below), one file per page per format, validated against its schema (source.format.export-validated), its losses declared (source.format.loss-report) and listed in the crate. The kept page exports and the synced folder (source.sync.out-is-the-exporters) are this same writer, so a kept bundle’s views/ IS the synced folder of its project; nothing renders a page twice. Acceptance: views/<page>.xml (PAGE) from the bundle is byte-identical to the kept PAGE export of the same page with the same choices; a format with no slot for a field lists the loss in the crate. Test: test_bundle_views_are_the_one_exporter_6439.py (not yet written; bundle view equals kept export; the loss listed), the existing test_page_export_route.py and test_export_validation.py.
  • profile.views.markdown-is-plain-and-round-trip-ready — [GAP] (#6439; the contract of #3176, narrowed) Markdown is PLAIN CommonMark a person can read and edit: one file per page and one per document (the pages as second-level headings, as render_markdown_text writes today: a line per line with the hard break, a line that begins like a heading or list escaped, never re-shaped), with a SHORT front matter — id, title, parent, order, pass, level, editable: [body] — and NO ids inside the text: the crate’s id map ties the file to its page and each body line, by its order in the file, to its segment, so an edited line comes back as a correction of that segment (Part 6) and a reordered or added line is said, not guessed. Markdown is a registered format (write and read) in the registry, so it is validated (front matter parses back to what was written, source.format.export-validated) and its loss report names what Markdown cannot hold (geometry, hands, marks, other readings). The Reader’s client-side “Export as Markdown” (export.app-wires-word-and-per-document-markdown-only) stays as the quick copy of the text on screen; the bundle’s Markdown is the engine’s. Acceptance: a page’s Markdown has its front matter and one body line per line in reading order; parsing the file back gives the same front matter and the same lines; the crate maps line 3 of the file to the third segment in that order. Test: test_bundle_markdown_is_plain_and_mapped_6439.py (not yet written; the front matter, the lines, the map, parse-back), the existing test_export_service.py and the kept Markdown test of #5502.
  • profile.views.svg-page — [GAP] (#6439; source.format.svg-out, #4946) each page is written as SVG from the same SourcePage: the page image as <image> (a relative path into images/ or the IIIF Image API URL when by reference), the page’s pixel grid as the viewBox (formats.harness.pixel_grid); each region a <g> whose id is its Fichero id with its polygon as <path>, each line inside it a <path> for its baseline and a <text> set along it with <textPath> (the counting reading at the chosen level), direction and writing-mode from the line’s direction, xml:lang from its language and script; a description segment gives <title> and <desc>. A write-only format in the registry (the registry allows a writer without a reader, FormatCannotRead), validated against the SVG 1.1 schema kept on disk, its losses declared (hands, marks, other readings). Acceptance: a page with two regions and five lines writes an SVG with two groups, five text paths along five baselines, the right-to-left line’s direction="rtl"; the file validates offline. Test: test_svg_view_6439.py (not yet written; the groups, the paths, the direction, validation), the existing test_harness.py and test_right_to_left.py.
  • profile.views.plain-text-and-duckdb — [GAP] (#6439) two conveniences, both derived and both declared as such in the crate (conformsTo none, fichero:derivedFrom the part they come from): plain text per page and per document, the page’s derived text in reading order with furniture left out, exactly the kept plain-text export (document_text), and ONE views/library.duckdb, a DuckDB database whose tables are tables/ loaded as written (the Parquet files read into tables of the same names through the managed connection, as the Parquet writer runs, never a second query of the library), read-only for analysis in DuckDB, Python or R. Neither is a source for import: Part 6 reads the crate, the tables and the views, never the text file or the database. Acceptance: views/library.duckdb has a segments table with tables/segments.parquet’s row count; the plain text of a page equals the kept plain-text export of it. Test: test_bundle_plain_text_and_duckdb_6439.py (not yet written; the row counts, the equality, the crate’s derived marks), the existing test_export_service.py.
  • profile.views.levels-and-translations-have-a-place — [GAP] (#6439; with source.editor.levels-section-and-working-text, #6429) every reading level and translation a segment has reaches the views where the format has a place for it, and is a declared loss where it has none: TEI carries the levels in <choice> (<orig> the as-written, <reg> regularised or modernised, <expan> expanded, each with @resp pointing at the PROV agent) and a translation as a parallel <text xml:lang> joined by @corresp; PAGE XML and ALTO hold one level per file, so the bundle writes one file per level asked, named with the level’s suffix, the working text’s file unsuffixed; Markdown and plain text write one file per level the same way; the annotations part (Part 1) carries every level as its own labelled annotation page already. The bundle’s default is the working text plus every level the scope has readings at; the choice is in fichero/choices.json. Acceptance: a line with as_written, modernised and a translation exports a TEI with a three-way <choice> and a parallel text, two PAGE files (working text, modernised), and the loss report of hOCR naming the levels it dropped. Test: test_bundle_levels_in_the_views_6439.py (not yet written; the TEI choice and parallel text, the files per level, the declared loss), the existing test_tei.py and test_reading_levels.py.

Part 3 — Publish: a static site from the bundle, with the citation and reference data (#6439, owner order (3), additions (c), (d) and 2, confirmations (1) and (2)). Folds public-site.md’s site behaviours (site.*) and iiif.publish.static (#3177); the Export → GitHub issues exporter.md section G lists (#3176–#3184, #508, #476) find their home here.

  • profile.publish.site-repo-is-separate-and-open — [GAP] (#6439, ruling 3) the website’s TEMPLATE, VIEWER and BUILD live in their OWN repository (provisional name fichero-site), under their own open licence (PROVISIONAL with the name, ruling 9d: the owner settles both when the repository is created; the template must work with any data licence, since the DATA licence is the user’s per project and per item), with Eleventy for the pages, OpenSeadragon with Annotorious for the page viewer (Mirador offered as the manifest viewer for a whole document), MapLibre for the maps, Pagefind or Lunr for the in-browser search, citeproc-js for the citation box; it builds and runs from a data/ folder and a site.config.json alone, with NO Fichero code, service, token or engine, and its README shows the build from the fixture bundle (Step 1.5) checked into that repo as its sample data. THIS repository keeps only the WRITER of the data folder and the config, the tile maker and the push (profile.publish.data-folder-is-the-bundle, profile.publish.push-targets); the Eleventy templates export_eleventy_site renders today (_eleventy_scaffold: .eleventy.js, package.json, netlify.toml, the page templates) move to the site repository and are removed here once it builds from the data folder. Acceptance: a checkout of the site repository with the fixture data builds on a machine with Node alone and shows the three pages, their transcriptions, the entities and the map; no file in it imports from or calls Fichero. Test: test_publish_writes_only_data_and_config_6439.py (not yet written; the writer’s output is data/ + site.config.json + the push manifest and nothing that is a template), the site repository’s own build test (not yet written there).
  • profile.publish.data-folder-is-the-bundle — [GAP] (#6439; folds iiif.publish.static, #3177) the site’s data/ IS the public bundle of Part 1, copied verbatim (the same crate, iiif/, annotations/, graph/, tables/, catalogue/, views/, citation/, reference/), so the site can hold nothing the bundle does not (profile.private-never-leaves), plus two things the site needs and the bundle does not: tiles/, IIIF Image API 3 LEVEL 0 static tiles and info.json per public image, made by the writer from the renditions the readers use (prep.renditions-mark-the-image-readers-use) so the viewer deep-zooms with no image server, and site.config.json: title, description, languages (Spanish first for a Spanish-language archive), the base URL, the viewer and map choices, the withholding thresholds already applied (site.living-withheld, stated so the site can say so), the bundle’s download path, the deep-link base (Part 4). The writer is export_eleventy_site’s request (POST /api/export/eleventy-site: output_path, target_id, recursive, site_title) narrowed to writing data and config, and the same writer runs as a kept export so the data folder stays current (site.kept-current: only touched files rewritten through the rewrite queue). Acceptance: data/ro-crate-metadata.json equals the bundle’s; every public image has tiles/<id>/info.json with profile: level0; the manifests’ image services point at the tiles’ URL under the base URL. Test: test_publish_data_folder_is_the_bundle_6439.py (not yet written; the copy equals the crate, the tiles’ info.json, the services rewritten), the existing test_export_service.py and test_iiif_segments_as_annotations.py.
  • profile.publish.pages-and-content — [GAP] (#6439, confirmation 1; with site.document-pages, site.person-and-place-pages, site.search-in-browser, site.show-not-tell, site.phone-and-slow-connection) the site renders, from the data folder alone: a page per document (its catalogue entry as fields, the page images in the viewer with the transcription beside them, a switch between the reading LEVELS and the TRANSLATIONS the bundle holds, the words where the readers disagree marked as the Reader marks them, source.disagree.lens), a page per ENTITY (its attested forms, the documents and passages that mention it), the STATEMENTS as subject, verb, object with their public sources linked (the claims of graph/, only those the bundle holds), DATES as attested (EDTF rendered in words) and PLACES on a MapLibre map from reference/ and the georeference files; every page shows its item’s RIGHTS and LICENCE (the catalogue’s rights, accessRights and license, the root dataset’s licence as the default) in one line with a link to the text, and a “Download the data” link to the bundle’s zip on the home page and to the document’s own part on each document page; search runs in the browser from an index built at build time; no AI-written prose anywhere (site.show-not-tell). Acceptance (the site repository’s test over the fixture data): the document page lists two levels and a translation to switch; the entity page names its two forms and one document; the statement shows its one public source and not the private one; the rights line reads the catalogue’s value; the download link resolves to the zip. Test: the site repository’s build test over the fixture (not yet written there); test_publish_config_names_what_the_site_shows_6439.py (not yet written; the config’s switches and the download path).
  • profile.publish.push-targets — [GAP] (#6439, confirmation 2; #3178, #3179) the data folder and config are published to one of four FIRST-CLASS targets, chosen per project: a plain FOLDER (the default; the person hosts it anywhere), a GIT REMOTE (the folder committed and pushed to a branch of the site’s repository, where the site repository’s own GitHub Actions workflow builds and deploys to GitHub Pages; the writer adds nothing but the data and config), GITHUB PAGES by that route, and NETLIFY (the same commit built by Netlify from the site repository, or a direct deploy of a built site through Netlify’s CLI when the person asks for a build on this Mac). Publishing is ONE job kind in Activity (publish-site, network lane) with the target in the project’s settings, run from Project › Publish… and on a schedule or when the kept data folder changed; credentials (a GitHub token from the device flow, a Netlify token) live in the engine’s secret store, never in the bundle, the data folder or the config, and profile.private-never-leaves is checked again on the files about to be pushed, so a private file can never travel; the push is audited (what, where, which commit) and its log is read in Activity. Acceptance: a folder target writes the data and config and nothing else; a git target commits only data/ and site.config.json and pushes to the named branch; a push with a private file in the folder is refused before any network call; the token is absent from every file written. Test: test_publish_push_targets_6439.py (not yet written; the four targets’ file sets, the refusal, the token absence, the audit row), the existing test_read_exports_check_the_body_ids_6320.py.
  • profile.citation.cite-this-everywhere — [GAP] (#6439, addition (c)) citation/ carries, for the project and for each public document, CSL JSON (type from the document kind, title, author or archive and archive_location from the catalogue, issued from the EDTF date, URL the published id, accessed left to the reader) built from the document’s source_metadata and its catalogue entry by one mapping; CITATION.cff at the bundle’s root for the dataset (title, authors as the project’s people, version, date, licence, the identifiers with the base URL); and BibTeX/BibLaTeX as DERIVED views of the same CSL JSON through the existing writer (write_bibtex, POST /api/bibliography/export.bib), which reads the CSL JSON rather than source_metadata a second time. On the site, each document and entity page has a “Cite this page” box rendered by citeproc-js from the CSL JSON in two styles (Chicago and APA, more in the site’s config) with Copy, and <head> carries the citation <meta> tags (Highwire citation_*, Dublin Core DC.*) and a schema.org JSON-LD <script> from catalogue/, so Zotero and Google Scholar read it. Acceptance: a document’s citation/<id>.csl.json has the catalogue’s title and date; the BibTeX entry for it is written from that CSL JSON with the same key; the fixture’s document page has citation_title and DC.title meta tags and the box renders Chicago. Test: test_bundle_citation_data_6439.py (not yet written; the CSL mapping, the cff, BibTeX from CSL), the existing test_routes_bibliography_resolve_export.py; the site repository’s meta-tag test (not yet written there).
  • profile.reference.skos-lists — [GAP] (#6439, addition (d)) reference/ carries the project’s reference lists as SKOS concept schemes in JSON-LD: the gazetteer (skos:Concept per place with prefLabel, the attested forms as altLabel, exactMatch to GeoNames, Wikidata or Pleiades where linked, the coordinates as WGS84 geo:lat/geo:long, ../kg/project-gazetteer-and-names.md), the name list (a concept per person with the attested forms), the document kinds and the Tema list (the catalogue’s editable subject list), and the hands; the project’s BIBLIOGRAPHY (the cited works, not the archive’s own documents) as CSL JSON beside them; every concept’s id is the one id (profile.ids.one-id-everywhere). The site’s search index and the entity pages read these; the catalogue’s Nombres and Lugares sheets (catalogue.export.authority-sheets-from-the-rows) are derived from them. Acceptance: a place with two attested forms and a GeoNames link exports as one concept with one prefLabel, one altLabel and one exactMatch; the Lugares sheet’s row for it has the same forms. Test: test_bundle_reference_lists_are_skos_6439.py (not yet written; the concept, the forms, the match, the sheet equality), the existing test_catalogue_sheet_rows.py.
  • profile.publish.site-links-open-the-app-if-installed — [GAP] (#6439, ruling 3; the app side is Part 4) every document, segment and entity page on the site carries a link to open it in Fichero that is a plain https link under the universal-link domain the app already claims (https://tubb.ca/apps/fichero/…, the pattern of the pairing link in FicheroApp.swift), so with the app installed it opens there and without it the SAME link lands on the site’s own page for that item; no fichero: scheme is written into the site, no “open in app” prompt is shown, and the link’s text says “Open in Fichero” only when the page detects nothing (it is the same link either way). Acceptance: the fixture’s document page has one https link per item under the domain; the link’s path resolves on the site itself. Test: the site repository’s link test over the fixture (not yet written there); test_publish_links_are_https_6439.py (not yet written; the writer puts the base and the domain in the config, never a fichero: URL in the data folder).

Part 4 — deep links into the app (#6439, owner order (4), ruling 3).

  • profile.links.one-link-two-forms — [GAP] (#6439; extends source.segment.citable, #4922) every thing in the bundle has ONE link in TWO forms that name the same id (profile.ids.one-id-everywhere): the app’s reference, fichero:<kind>/<library>/<document>/<id> for a segment as today (SegmentReference) and the same shape for a document, a page, a reading, an order, an entity, a claim and a run; and the UNIVERSAL form, https://tubb.ca/apps/fichero/open/<library>/<kind>/…, under the domain the pairing link already uses (#3791), the path mirroring the reference. The crate states both on every entity (identifier and sameAs); the site, the citations, the Word and Markdown views carry the https form; the app offers both: Copy Link (the https form, the default, on every selection’s context menu and Edit ▸, in the one command table of ui/menus-and-commands.md, no chord) and Copy Reference (the fichero: form, for MCP, the command line and notes). Acceptance: Copy Link on a selected line gives an https URL whose path ends in the line’s segment id; the crate’s entity for that line has the same URL as sameAs; the two forms parse to one reference. Test: DeepLinkFormsTests.swift (not yet written; the two forms for every kind parse to one reference; Copy Link’s string), test_bundle_links_name_the_one_id_6439.py (not yet written), the existing test_segments_matches_forwarding.py.
  • profile.links.open-resolves-through-the-one-resolver — [GAP] (#6439) opening either form (a click on the site with the app installed, a pasted link, a link in a note or a Word file) goes through the app’s one URL handler (handleOpenURL in FicheroApp.swift, which parses segment references today) and the ONE resolver (POST /api/locations/resolve, following forwarding notes so a split, merged or moved segment lands on its live parts, live_segment_ids, and a deleted one is said), then LANDS by kind: a segment selected on its page in the Reader and the Preview, a document on its first page, a page, a reading shown at its level, an order shown, an entity in the Inspector with its mentions, a claim with its evidence, a run in Activity; the library part is honoured first: an open library is used, a known library not open is opened after one question, a library this Mac does not have shows one sentence (“This library is not on this Mac”) with Open on the Web, the SAME https link in the browser, which lands on the site’s page (Part 3); nothing is downloaded or paired by a link (RemoteClientPairing keeps its own path). A restricted target resolves to a refusal in the engine’s words and reveals nothing about what it is (source.rights.citation-does-not-leak). Acceptance: a link to a line that was split since lands with both parts selected and a note saying so; a link to a library not here shows the sentence and the web button; a link to a restricted segment shows the refusal and not the page. Test: DeepLinkLandingTests.swift (not yet written; the landing per kind, the three library cases, the refusal), the existing test_segments_matches_forwarding.py and test_holds_close_6320.py.
  • profile.links.iiif-content-state-for-viewers — [GAP] (#6439; iiif.serve.content-state, #5327) Copy IIIF Link on a page, a region or a line gives a IIIF Content State (a Annotation with the canvas and the region as its target, encoded as the standard URL parameter) pointing at the bundle’s or the served manifest, so any viewer (Mirador, the Universal Viewer, the site’s own) opens on that region; the site’s viewer accepts the same content state on its document pages. Acceptance: Copy IIIF Link on a region gives a URL whose decoded content state targets the region’s canvas with its xywh; pasting it into the site’s document page opens the viewer on that region. Test: test_content_state_link_6439.py (not yet written; the encoding and the target), the site repository’s viewer test (not yet written there).
  • profile.links.derived-views-carry-the-link — [GAP] (#6439) every derived view that can hold a link holds the https form: CSL JSON’s URL and CITATION.cff’s identifiers (Part 3), the Word transcript’s page headings and the Markdown’s front matter url, the catalogue workbook’s hidden link column, the Eleventy data folder’s pages; views with no place for it (PAGE, ALTO, plain text) carry the fichero: id as today (source.sync.files-carry-ids) and the crate maps it. Acceptance: the Word transcript’s heading for a page links to that page’s https URL; the Markdown front matter has url; the CSL URL equals the crate’s sameAs. Test: test_views_carry_the_link_6439.py (not yet written; the heading, the front matter, the CSL), the existing test_export_word_transcript_options.py.

Part 5 — training sets, Croissant and model cards (#6439, owner order (5)).

  • profile.training.set-is-a-dataset-with-croissant — [GAP] (#6439; with source.train.self-describing, source.train.split-by-manuscript, source.train.rows-keep-context, #4947; export.huggingface-dataset-ready-bundle, #4069) a training set the project made (training.kraken_set.TrainingSet: PAGE XML and image per page, its manifest() of teacher, counts, held-out and left-out lines and flags; line_pairs.write_line_pairs: pairs.jsonl with lines/; yolo_set.export_region_set: labels per page) goes into training/<set>/ as a nested RO-Crate Dataset with a Croissant 1.0 croissant.json: distribution naming every file, recordSets for lines (fields: the line’s one id, its picture, its text at each level present, language, script, direction, hand, the maker and the checker as PROV ids, the manuscript), for pages and for regions, and the split by manuscript as train, validation and test record sets; the same folder loads with datasets.load_dataset() with no loader script (a README.md with the dataset-card YAML front matter, data/ as Parquet from the tables, the Croissant file beside) and is described in HTR-United’s terms in the card. Acceptance: the fixture’s set exports with a Croissant file that validates, a README whose front matter names the licence, languages and the split sizes, and loads back with datasets into the same line count. Test: test_training_set_is_croissant_6439.py (not yet written; the record sets, the split, the load-back), the existing test_kraken_training_set.py and test_line_pairs.py.
  • profile.training.only-what-may-train-and-leave — [GAP] (#6439; source.rights.model-use, source.rights.exports-leave-out, source.train.human-checked-by-default; the 2026-10-03 ruling that some material may train but never be released) a line enters a training set only when its rights record allows the model use asked (local, cloud, none) and, by default, only when a person checked it; a set LEAVES the project (the bundle, a Hugging Face push, a kept folder) only with the lines whose record allows RELEASE: a set holding lines that may train here but not be released is marked release: no in its crate and its manifest, is used by the trainer here as today, is left out of the bundle and the data folder, and its push is refused with the reason before any upload (hf_jobs, bakeoff_lines.push_private_dataset). Acceptance: a fixture line marked train-only trains the local set, is absent from training/ in the bundle, and the push of its set is refused naming the rule. Test: test_training_set_respects_release_6439.py (not yet written; in the set, out of the bundle, the refusal), the existing test_set_excludes_flagged_lines.py and test_hf_jobs_target.py.
  • profile.models.card-file-per-model — [GAP] (#6439; source.model.card-id, source.train.model-lineage) every model the project made (training.model_nodes: the Kraken readers, the vision LoRA students, the YOLO region finders, the spaCy name models) exports as models/<card id>/README.md, a Hugging Face model card: YAML front matter with license, base_model, datasets (the set’s id in training/), language, tags (the job kinds, the material, the scripts), metrics (the CER and WER measured here with the evaluation ids and the noise band, and the published CER apart, cer_measured_here and cer_published never mixed), and the seed card’s facts (recipes/assemble.Card: jobs, scripts, languages, material, licence, size, memory, where it runs) under their own names; a body that says what it was trained on, from which set and teacher, what it is for and where it fails, in the project’s words with NO fact the project did not record (the seed’s rule: an unstated fact is empty, never guessed). PROV ties the model to its training: prov:wasGeneratedBy the train job, prov:used the set, prov:wasDerivedFrom the base model. The weights are referenced (the Hugging Face repository or the file in the project) and copied into models/ only when the bundle is asked to carry them. Acceptance: a fine-tuned Kraken model exports a card whose front matter names its base, its set and its measured CER with the evaluation id, and whose body has no number the project did not measure. Test: test_model_card_file_6439.py (not yet written; the front matter from the node and the card, the body’s facts, the PROV triple), the existing test_models_live_in_the_project.py and test_a_new_card_keeps_the_old_evaluations_6138.py.
  • profile.training.hf-push-is-a-view — [GAP] (#6439) the Hugging Face pushes of a set and of a model (hf_jobs, the token from the keychain as today) upload the training/<set>/ folder and the models/<id>/ folder AS WRITTEN, so the repository on the Hub is a copy of the bundle’s part (its README is the card, its Croissant file drives the Hub’s dataset viewer) and never a second description composed for the push; the push records the repository id back on the set’s and the model’s crate entry as sameAs. Acceptance: the files pushed for the fixture’s set equal the bundle’s training/<set>/ byte for byte; the crate gains the repository id. Test: test_hf_push_uploads_the_bundle_part_6439.py (not yet written; the file set equality, the sameAs), the existing test_hf_jobs_target.py.

Part 6 — import, and the lossless round trip over the whole model (#6439, owner order (6), addition (e); owner 2026-11-08 on Part 6).

  • profile.import.bundle-merges-by-id — [GAP] (#6439) a bundle (a folder with ro-crate-metadata.json, or its zip) dropped on Fichero, chosen in File ▸ Import or named on the command line is recognised as a bundle by its crate (the same door as a package folder, source.format.package-folder, before any per-file guess) and imported as ONE job in Activity (import-bundle, as import-iiif is): every record of every kind in the kinds table is read from the crate and its parts and MATCHED BY ITS ONE ID into the receiving library, into the original (the ids land on the same things, source.format.reimport-recognised) or into a fresh library (the ids are kept as the records’ external ids, as manifest_import keeps them, so a second import of the same bundle is recognised and nothing is doubled); a match that is identical is skipped, a match that differs is changed or kept-beside (profile.import.yours-is-never-overwritten-silently), a record with no match is added with its provenance from graph/provenance.jsonld. The reading goes through the existing readers: formats.read_page for the views, iiif_import for the manifests and annotation pages, manifest_import’s API-driven creation for documents, entities and claims, the catalogue and rights through their actions; the bundle importer is one reader of the crate that hands each part to the reader that exists, no second path. Acceptance: the fixture bundle imported into an empty library gives the kinds table’s counts; imported again, every kind reports skipped and nothing is doubled. Test: test_bundle_import_merges_by_id_6439.py (not yet written; the counts per kind, the second import’s skips), the existing test_import_into_library.py and test_iiif_by_reference.py.
  • profile.import.dry-run-and-report-per-kind — [GAP] (#6439) an import is a DRY RUN first, by default: nothing is written until the person reads the REPORT and confirms. The report has one row per kind in the kinds table — would ADD, would CHANGE, would SKIP, each a count with the reasons behind it (identical; kept yours; private here; no field for it) — and, per kind, the DECLARED LOSSES: what the bundle said it lost when written (fichero:loss) and what this library cannot hold (kept as unrecognised, source.format.keeps-unrecognised, and said). The report is shown in the app (the import sheet), on the command line and over MCP from the same data, and is kept with the import’s audit entry so it can be read again. Acceptance: a dry run of the fixture against a library holding half of it reports the halves as skipped and added per kind, with one changed reading named; nothing is written until Confirm. Test: test_bundle_import_dry_run_report_6439.py (not yet written; the rows, the reasons, the losses, nothing written), the existing test_import_actions.py.
  • profile.import.entities-match-by-authority-first — [GAP] (#6439) an incoming entity, place or reference concept is matched BY AUTHORITY ID FIRST (the sameAs/exactMatch to Wikidata, GeoNames, VIAF or Pleiades in graph/ and reference/, against the library’s authority links), THEN by the one id, and only then by name — and a name-only match is a PROPOSAL in the report (“would merge: confirm”), never done by itself (the rule plan_alias_merges already keeps for alias lists); a confirmed proposal merges through the existing audited entity merge. Two incoming entities with different authority ids are never merged however alike their names. Acceptance: an incoming place with the library’s GeoNames id merges though its name differs; one with the same name and no authority id is a proposal; two with different Wikidata ids stay two. Test: test_bundle_import_entities_by_authority_6439.py (not yet written; the three cases), the existing test_import_into_library.py.
  • profile.import.yours-is-never-overwritten-silently — [GAP] (#6439) an item a person curated here (a reading a person wrote or corrected, an order a person set, a catalogue field a person typed, a confirmed entity, a reviewed statement, a mark, a rights record: the Yours wins column) is NEVER replaced by an incoming value: the incoming reading, order or statement is added BESIDE it with its own provenance and does not count; a catalogue field keeps the person’s value and the incoming one is listed under “kept yours” in the report; a rights record is never loosened by an import; the person chooses later in the Inspector as for any reading (Make This Count). Acceptance: a line the person corrected receives the bundle’s machine reading as a second, non-counting reading and the report says “kept yours: 1 reading”. Test: test_bundle_import_keeps_yours_6439.py (not yet written; the reading beside, the field kept, the record not loosened), the existing test_a_correction_counts.py.
  • profile.import.one-audited-batch-one-undo — [GAP] (#6439) the confirmed import is ONE audited set (every create, update and merge it performs under one audit id, safety.undo.a-set-is-undone-whole) with ONE ⌘Z that removes everything it added and restores everything it changed, including the entity merges it confirmed, and leaves what it skipped untouched; the audit entry names the bundle (its crate’s id, datePublished and checksum) and carries the report. Acceptance: ⌘Z after the fixture’s import returns the library to its previous counts per kind; the audit entry holds the report. Test: test_bundle_import_is_one_undo_6439.py (not yet written; the counts before, after and after undo), the existing test_import_actions.py.
  • profile.import.bibtex-and-biblatex — [GAP] (#6439, addition (e)) BibTeX and BibLaTeX files import through the existing bibliography reader (bibliography/importers.py: read_bibtex, read_any, POST /api/bibliography/import and /import/persist), extended for BibLaTeX’s fields (date beside year, journaltitle, location, eventtitle, @online, @thesis, the related family) so nothing is dropped, and land as the bundle’s citation/ part does (CSL JSON per work, the same mapping in reverse), so a .bib dropped alone, a .bib sidecar beside a folder (source.format.corpus-sidecars) and the bundle’s citation/ all take one path; export is the derived BibTeX of profile.citation.cite-this-everywhere, and a .bib imported and exported again keeps every field and key. Acceptance: a BibLaTeX entry with date and journaltitle imports with both; exported again it has the same key and fields. Test: test_biblatex_round_trip_6439.py (not yet written; the fields, the key, import-export equality), the existing test_bibliography_importers_hardening.py and test_bibliography_sidecars.py.
  • profile.round-trip.lossless — [GAP] (#6439, ruling 5; the second half of profile.round-trip.export-twice-is-identical) the CONFORMANCE TEST of the whole model: the fixture library (Step 1.5) is exported, imported into a FRESH library, and exported again; the two bundles are identical apart from datePublished and the library segment of every id (mapped once by the id map), for EVERY kind in the kinds table — pages and segments to the pixel, every reading at every level and translation with its maker, orders, marks, hands, ENTITIES with their forms and authority links, STATEMENTS with their sources, dates and places, catalogue entries, rights records, reference concepts, bibliography, the training set’s manifest, the RECIPES and their plans, the RUN RECORDS with every reading’s link to its attempt, and the model cards of every model used — and the only differences allowed are the declared losses, per kind, that the crate lists. The test is the same file as Part 1’s and runs in the gate. Acceptance: the diff of the two crates is empty after the id map and the date; the counts per kind are equal; the losses listed equal the differences found. Test: test_bundle_round_trip_6439.py (the Part 1 file, gaining this half), the existing test_pagexml_round_trip.py.

Part 7 — the edition PDF (#6440; folds export.pdf-document-export (#506) and source.format.pdf-out (#4946); ruling 8).

  • profile.edition.typeset-with-typst-inside-the-app — [GAP] (#6440, DECIDED) the edition is typeset by Typst, through the Python binding typst (the typst-py project, Apache-2.0; typst.compile(source, output=…) with font_paths and root), which carries the compiler inside its wheel, so it is provisioned exactly as pdfium is: one line in fichero-server/pyproject.toml’s requirements, packaged by briefcase into the engine, signed with the app, no user install and no network (everything the app needs ships inside); the version is PINNED (0.14 at writing, 2025-10-24; 0.15 was in its final testing) and its size recorded in the engine’s bundle-size table when measured (the wheel is tens of megabytes; the figure goes in the table, not here). What Typst gives, as of 0.14, stated honestly: PDFs are TAGGED by default (headings, paragraphs, lists, links, tables, figures with alt), PDF/UA-1 is an opt-in standard whose checks FAIL the compile for a non-compliant document (so the writer must supply every alt and every language tag), PDF/UA-2 is not supported, every PDF/A part is supported (A-1b, A-2b, A-2u, A-3b, A-3u, A-4) with the published incompatibility that PDF/UA-1 and PDF/A-4 cannot be asked together (DECIDED, ruling 9c: the default is tagged PDF with PDF/A-2b for archiving; PDF/UA-1 is opt-in and, when it conflicts with the PDF/A part asked, PDF/A wins and the conflict is said); shaping is Typst’s own (bidi and right-to-left text, Arabic and Hebrew joining, CJK horizontal text with CJK–Latin spacing; VERTICAL writing is not supported and is a declared loss), combining marks and the MUFI palaeographic range depend on the FONT, so the edition uses the engine’s bundled fonts (resources/fonts/: Junicode as the body and apparatus face, the Noto families for the scripts they cover, each with its OFL text and PROVENANCE.md row) and the writer checks every text run’s glyph coverage against them before compiling, listing a missing glyph as a declared loss rather than printing a box. Acceptance: the engine compiles the fixture’s edition with no Typst on the machine’s PATH; the PDF validates as PDF/UA-1 and PDF/A-2b with veraPDF in the gate; a right-to-left fixture line prints joined and ordered; a character no bundled font has is listed in the colophon’s losses. Test: test_edition_typst_inside_6439.py (not yet written; compile with PATH emptied, the two standards asked, the loss listed), the existing test_export_word_include_images_6287.py as the emitter pattern.
  • profile.edition.is-a-view-of-the-bundle — [GAP] (#6440) the edition is ONE emitter beside Word (export_edition_pdf in export_service.py) that reads the BUNDLE’S parts and nothing else — the pages and readings from the record stream and the page exporter at the chosen levels, the images from images/ (the renditions readers use), the apparatus from the marks and editorial facts the page exporter already carries (_editorial_facts_on, _marks_on_reading), the entities, dates and places from graph/ and reference/, the bibliography from citation/, the rights from catalogue/, the provenance from graph/provenance.jsonld — writes a Typst SOURCE FOLDER (edition.typ, the template, data/ as the bundle’s JSON read with Typst’s json(), the images, the fonts’ paths) and compiles it; the source folder is kept beside the PDF so a person can change the template and recompile; the emitter is reached as a kept-export format (edition-pdf, per document or per project) and from the Reader’s Export menu beside Word, no route of its own. Private never prints: the emitter reads only the public bundle, so the gate is profile.private-never-leaves and no second filter exists. Acceptance: the fixture’s edition PDF holds every public page and no private one; deleting the bundle’s graph/ makes the index of entities empty and the compile still succeeds; the .typ folder recompiles by hand to the same PDF. Test: test_edition_is_a_view_of_the_bundle_6439.py (not yet written; the parts read, the private page absent, the source folder recompiles), the existing test_export_word_transcript_options.py.
  • profile.edition.pages-facing-and-apparatus — [GAP] (#6440) the edition’s body is the scholar’s: a FACSIMILE page (the image at print resolution with its folio number, its IIIF link and its deep link) FACING its edited text, or the edited text FACING its translation when a translation level is in the bundle (facsimile, text and translation as three choices of layout per edition: facsimile–text, text–translation, facsimile–text–translation on a spread); the text at the chosen reading level with line numbers every five lines, the words where the readers disagree marked as the Reader marks them; the APPARATUS as footnotes in Typst’s native footnote() with the editorial facts (unclear, supplied, deleted in ⟦⟧ as the 2026-09-28 ruling has it, abbreviations expanded with the as-written form shown), the other readings as variants with their makers, and the person’s notes; a running head with the document’s title and the folio. Acceptance: a fixture page with one unclear span and one expanded abbreviation prints two footnotes with the right sigla; the translation layout prints the Spanish line facing its English; the disagreement mark appears on the one word below unanimous. Test: test_edition_body_and_apparatus_6439.py (not yet written; the footnotes, the facing layout, the mark), the existing test_abbreviation_markup.py.
  • profile.edition.front-and-back-matter — [GAP] (#6440) the edition opens with a title page (the project’s title, the archive, the editors as the project’s people, the date, the licence from the crate, the rights line per catalogue/) and closes with the INDEXES (entities by kind — persons, places, institutions — and dates, each entry with the folios and line numbers it appears on, from graph/ and the mentions), the BIBLIOGRAPHY typeset by Typst’s native CSL support from the bundle’s citation data (the derived BibTeX of citation/ as Typst’s bibliography() source, the style from the project’s choice, Chicago notes by default), a CITE THIS EDITION page (the CSL JSON of the edition itself, rendered in two styles, the DOI or URL when published), the RIGHTS page (the rights records that apply, the licence text), and a COLOPHON WITH PROVENANCE: which models read which pages under which runs, which people corrected and checked, when, from graph/provenance.jsonld, the bundle’s id and checksum, the Fichero and Typst versions, and the declared losses of this edition. Acceptance: the fixture’s index of persons lists the two forms of one person under one entry with its folios; the bibliography renders the one cited work in Chicago; the colophon names the fixture’s model and run. Test: test_edition_front_and_back_matter_6439.py (not yet written; the indexes, the bibliography, the colophon’s rows).
  • profile.edition.links-bookmarks-and-accessibility — [GAP] (#6440) every folio, line, entity and index entry carries its DEEP LINK (the https form of profile.links.one-link-two-forms) as a Typst link(), so a click in any PDF reader opens the app when installed and the site otherwise; internal links tie the apparatus to its line, the index entries to their folios and the facsimile to its text; the PDF OUTLINE (bookmarks) follows the edition’s structure (front matter, each document, each folio, the indexes, the bibliography, the colophon) from Typst’s headings; accessibility as PDF/UA-1 asks: every image with an alt (the page’s description segment when it has one, else “Facsimile of folio “), the logical reading order from the reading order, each text run tagged with its language and script (lang and region on Typst’s text()), the facing layout read text-then-translation, not column by column; the metadata (title, authors, language, keywords from the Tema list) in the PDF’s XMP as PDF/A requires. Acceptance: the fixture PDF’s outline has the folio bookmarks; the link on folio 2’s third line opens the line’s https URL; veraPDF reports no UA-1 violation; the facsimile’s alt text is the description segment’s text. Test: test_edition_links_and_ua_6439.py (not yet written; the outline, a link’s target, the alt text, veraPDF’s verdict), the site repository’s link test for the fallback (already named in Part 3).

Part 8 — recipes, runs and the models used (#6439 addition 3; ruling 8).

  • profile.recipes.travel-as-prov-plans — [GAP] (#6439; source.recipe.folder-format, source.recipe.data-not-code, designer.share.export-is-the-whole-plan) every recipe the project holds (recipe/recipe.yaml and recipe/setup.yaml, recipes/project.py; the prompts folder; the chains of image steps and reading levels; each step’s job, model pin in one of the PIN_FORMS, place kind, settings, conditions) goes into recipes/<id>/ exactly as Share Recipe writes it (one writer: designer.share.export-is-the-whole-plan IS the bundle’s recipe part), and is described in graph/plans.jsonld as a prov:Plan (the recipe) whose steps are prov:Plans too, each prov:wasInfluencedBy the model card it names, so a run’s activity can say prov:hadPlan; the version is the recipe’s schema and content hash. Acceptance: the fixture’s recipe exports to recipes/ byte-identical to Share Recipe’s file and to one plan with three step plans naming three card ids. Test: test_bundle_recipes_are_plans_6439.py (not yet written; the file equality, the plan and its steps), the existing test_check_names_every_fault_5364.py and the recipe export test Step 14.1 names.
  • profile.recipes.never-keys-or-secrets — [GAP] (#6439; designer.share.export-holds-nothing-private, source.recipe.never-holds-keys) no key, token, endpoint address, account name, cluster account, person’s path or private prompt leaves in recipes/, graph/plans.jsonld, graph/provenance.jsonld or tables/runs: the one scrubber Share Recipe uses runs on every recipe and run record the bundle writes, a cloud step names its provider and model and says needs: key, a cluster step names its place kind and never the account; the test seeds every such field and greps the whole bundle. Acceptance: a recipe with a cloud key set, a cluster account and an endpoint exports with none of the three strings anywhere in the bundle. Test: test_bundle_recipes_hold_no_secrets_6439.py (not yet written; the seeded fields, the grep over every file), the existing test_check_names_every_fault_5364.py.
  • profile.runs.workflow-run-crate-linked-from-each-reading — [GAP] (#6439) every recipe run and every step attempt goes into graph/provenance.jsonld following the Workflow Run RO-Crate profile (Process Run Crate for a step attempt, Workflow Run Crate for the run: CreateActions with instrument the model card, object the pages and renditions read, result the readings and segments written, startTime, endTime, agent, the cost and the place it ran, from WorkflowRun and the run account; prov:hadPlan the recipe’s plan), with the attempts of one step as SIBLING actions under the step, and EVERY reading, segment, order, statement and catalogue value in the bundle carries prov:wasGeneratedBy its step attempt’s id (so a reading says which run, step and model made it, and a person’s correction says which person and when, profile.provenance.prov-o-on-everything made concrete); tables/runs and tables/attempts are the same facts as rows. Acceptance: the fixture’s machine reading points at an action whose instrument is the Kraken card, whose plan is the recipe’s step, and whose object includes the rendition read; two attempts of one step are two actions with one isPartOf. Test: test_bundle_runs_are_a_workflow_run_crate_6439.py (not yet written; the action per attempt, the reading’s link, the siblings; validated against the profile’s JSON schema kept on disk), the existing test_jsonld_export.py.
  • profile.models.card-for-every-model-used — [GAP] (#6439; extends profile.models.card-file-per-model) models/ holds a card for EVERY model a run used, not only the trained ones: the seed cards (recipes/seed/cards.yaml) and the finder-added cards (discovery.installed_cards, the model store) for the readers, finders, correctors, embedders, name and date models and the cloud models the steps name, each as the Hugging Face model-card README of Part 5 with the card’s facts under their own names and license, the weights never copied for a model the project did not train (a sameAs to its published card instead), a cloud model’s card saying so with its provider; the plans and the runs point at these ids. Acceptance: a run with Kraken, a vision reader and a cloud corrector exports three cards, the cloud one with no weights and runs_on: cloud:<provider>. Test: test_bundle_cards_for_models_used_6439.py (not yet written; one card per model named by a plan or a run, the cloud card’s shape), the existing test_models_live_in_the_project.py.
  • profile.recipes.imported-runnable-when-ready — [GAP] (#6439; designer.share.import-checks-at-the-door, source.recipe.checked-at-every-door, source.recipe.check-names-every-fault) a bundle’s recipes import through Use a Recipe (Step 14.1: GET/PUT /api/recipes/project and check_recipe), never a second path: each arrives RUNNABLE WHEN READY with a LIST OF WHAT IS MISSING on this Mac, one plain sentence per fault from the existing check (a model not downloaded, offered for download with its size; a key not set for a cloud step, listed needs-a-key and never swapped; a reader or runtime not installed; a place kind this Mac has not configured), shown in the import report under the recipe’s row and in Set Up’s Ready page; the run records import as facts (the readings they made are linked to them) and are never re-run by an import (never rerun a model pass: same input and model reuse the imported result); a recipe identical to one the project has is skipped, one that differs is added beside as a new version. Acceptance: importing the fixture bundle on a Mac without the vision model lists “Qwen 2 VL 2B is not downloaded (1.5 GB): Download” under the recipe and the recipe is saved; Start is disabled until the download ends; the imported run’s readings count without any model running. Test: test_bundle_recipe_import_lists_missing_6439.py (not yet written; the sentences, the saved recipe, no run started), the existing test_check_names_every_fault_5364.py.

Build order

Stage 1 — the bundle and its round trip, tables and catalogue

Step 1.1 — the crate skeleton over the one stream, as a kept export (#6439)

  • Behaviours: profile.editor-not-the-web, profile.private-never-leaves, profile.bundle.is-an-ro-crate, profile.ids.one-id-everywhere
  • Tests: fichero-server/tests/unit/core/test_export_service.py, fichero-server/tests/unit/export/test_catalogue_workbook_kept.py, fichero-server/tests/unit/security/test_holds_close_6320.py, fichero-server/tests/unit/security/test_read_exports_check_the_body_ids_6320.py, test_bundle_keeps_private_in_6439.py (not yet written), test_bundle_is_a_valid_ro_crate_6439.py (not yet written), test_bundle_ids_are_one_string_6439.py (not yet written), test_profile_views_are_derived_6439.py (not yet written)
  • Depends on: none
  • Size: M

Engine only: the private gate first, in the stream, before any part is written; export_ro_crate beside the other emitters, writing the crate’s metadata, fichero/ids.json and fichero/choices.json (the pass, order and reading kind, source.format.export-choices) over iter_export_records; the format bundle registered with the kept exports so keep, write_now and the rewrite queue serve it; no route of its own. The crate validator and the JSON-LD isomorphism check run in the writer, as the KG export’s do.

Step 1.2 — provenance in PROV-O (#6439)

  • Behaviours: profile.provenance.prov-o-on-everything
  • Tests: fichero-server/tests/unit/kg/test_jsonld_export.py, test_bundle_provenance_is_prov_o_6439.py (not yet written)
  • Depends on: 1.1
  • Size: M

The second named JSON-LD context (prov) on the KG export, so GET /kg/export/rdf?context=prov and the crate’s graph/provenance.jsonld are one renderer; the attribution chain and the readings’ maker fields are its only sources.

Step 1.3 — tables as CSVW and Parquet, the workbook a derived view (#6439)

  • Behaviours: profile.tables.csvw-and-parquet
  • Tests: fichero-server/tests/unit/core/test_export_service.py, fichero-server/tests/unit/export/test_catalogue_sheet_rows.py, test_bundle_tables_are_csvw_and_parquet_6439.py (not yet written)
  • Depends on: 1.1
  • Size: M

The CSV writer over the same typed partitions the Parquet writer already has (_write_parquet_records), with csv-metadata.json from the partitions’ columns; the catalogue sheet’s columns read from the catalogue table rather than from the attributes a second time.

Step 1.4 — the catalogue as Dublin Core and schema.org, the same on the manifest, restricted left out once (#6439)

  • Behaviours: profile.catalogue.dublin-core-schema-org-and-iiif
  • Tests: fichero-server/tests/unit/export/test_catalogue_sheet_template.py, fichero-server/tests/unit/importers/test_iiif_by_reference.py, test_bundle_catalogue_is_dc_and_schema_org_6439.py (not yet written)
  • Depends on: 1.3
  • Size: M

The prototype gains a declared mapping (attribute → DC term, schema.org property, IIIF label), data not code; the manifest route reads its metadata, rights and requiredStatement from the same mapping; the rights filter stays where it is, in the stream.

Step 1.5 — export twice is identical, every file validated offline, losses declared (#6439)

  • Behaviours: profile.round-trip.export-twice-is-identical
  • Tests: fichero-server/tests/unit/formats/test_pagexml_round_trip.py, fichero-server/tests/unit/formats/test_export_validation.py, test_bundle_round_trip_6439.py (not yet written)
  • Depends on: 1.2, 1.4
  • Size: S

The JSON schemas for RO-Crate, Presentation 3, Web Annotation and CSVW vendored beside the XSDs (formats/schemas/, with their PROVENANCE.md rows); the fixture a small library with one restricted document, one corrected line and one catalogued folder, reused by every later part’s test.

Stage 2 — the page views

Step 2.1 — every view through the one page exporter, Markdown plain and mapped, plain text and the DuckDB file (#6439)

  • Behaviours: profile.views.every-view-is-a-page-export, profile.views.markdown-is-plain-and-round-trip-ready, profile.views.plain-text-and-duckdb
  • Tests: fichero-server/tests/unit/api/test_page_export_route.py, fichero-server/tests/unit/formats/test_export_validation.py, fichero-server/tests/unit/core/test_export_service.py, test_bundle_views_are_the_one_exporter_6439.py (not yet written), test_bundle_markdown_is_plain_and_mapped_6439.py (not yet written), test_bundle_plain_text_and_duckdb_6439.py (not yet written)
  • Depends on: 1.5
  • Size: M

Markdown and plain text move into the formats registry as writers (Markdown also a reader for its front matter and lines), so the kept exports, the synced folder and the bundle share one writer per format; the DuckDB file is the Parquet partitions attached through the managed connection.

Step 2.2 — the SVG page (#6439)

  • Behaviours: profile.views.svg-page
  • Tests: fichero-server/tests/unit/formats/test_harness.py, fichero-server/tests/unit/formats/test_right_to_left.py, test_svg_view_6439.py (not yet written)
  • Depends on: 2.1
  • Size: M

One new module in formats/ with one register() call, as the registry’s docstring prescribes; the SVG 1.1 schema vendored beside the others with its PROVENANCE.md row.

Step 2.3 — levels and translations in the views (#6439)

  • Behaviours: profile.views.levels-and-translations-have-a-place
  • Tests: fichero-server/tests/unit/formats/test_tei.py, fichero-server/tests/unit/api/test_reading_levels.py, test_bundle_levels_in_the_views_6439.py (not yet written)
  • Depends on: 2.1
  • Size: M

The TEI writer gains <choice> and the parallel text from the SourcePage’s readings by level (the page exporter already carries reading_level); the per-level file naming is the bundle writer’s, one loop over the levels asked.

Stage 3 — Publish, with the citation and reference data

Step 3.1 — the split: the data folder and config from the bundle, level 0 tiles, the site repository contract (#6439)

  • Behaviours: profile.publish.site-repo-is-separate-and-open, profile.publish.data-folder-is-the-bundle
  • Tests: fichero-server/tests/unit/core/test_export_service.py, fichero-server/tests/unit/api/test_iiif_segments_as_annotations.py, test_publish_writes_only_data_and_config_6439.py (not yet written), test_publish_data_folder_is_the_bundle_6439.py (not yet written)
  • Depends on: 2.3
  • Size: L

L because it has two halves in two repositories, kept as one step so the contract is written once: the writer here (the Eleventy request narrowed to data and config, the tile maker from the readers’ renditions, the kept-export wiring) and the site repository (its first commit: the templates moved out of _eleventy_scaffold, OpenSeadragon + Annotorious, MapLibre, the search index, the build from the fixture data). The site repository’s name and licence are provisional until the owner creates it (ruling 9d); the viewer choices are the spec’s recommendation.

Step 3.2 — citation and reference data in the bundle, BibTeX and the authority sheets as derived views (#6439)

  • Behaviours: profile.citation.cite-this-everywhere, profile.reference.skos-lists
  • Tests: fichero-server/tests/unit/api/test_routes_bibliography_resolve_export.py, fichero-server/tests/unit/export/test_catalogue_sheet_rows.py, test_bundle_citation_data_6439.py (not yet written), test_bundle_reference_lists_are_skos_6439.py (not yet written)
  • Depends on: 1.4
  • Size: M

The CSL mapping and the SKOS writer are two small renderers over the catalogue entry, source_metadata, the gazetteer and the name list; write_bibtex and the Nombres/Lugares sheets read their output rather than the library a second time.

Step 3.3 — what the site shows: documents with levels, entities, statements with public sources, dates, places, rights and licence, the download, the cite box (#6439)

  • Behaviours: profile.publish.pages-and-content
  • Tests: test_publish_config_names_what_the_site_shows_6439.py (not yet written); the site repository’s build test over the fixture (not yet written there)
  • Depends on: 3.1, 3.2
  • Size: L

Almost entirely in the site repository (templates and client scripts over the data folder); here only the config’s switches. Kept as one step because the pages are one design over one data folder; the site repository’s own build order splits it as it likes.

Step 3.4 — the four push targets as one audited job (#6439)

  • Behaviours: profile.publish.push-targets
  • Tests: fichero-server/tests/unit/security/test_read_exports_check_the_body_ids_6320.py, test_publish_push_targets_6439.py (not yet written)
  • Depends on: 3.1
  • Size: M

One job kind in Activity with the target as a project setting; the GitHub device flow and the Netlify token through the engine’s existing secret store; the private check run again on the files about to leave.

  • Behaviours: profile.publish.site-links-open-the-app-if-installed
  • Tests: test_publish_links_are_https_6439.py (not yet written); the site repository’s link test over the fixture (not yet written there)
  • Depends on: 3.3
  • Size: S

The config carries the base URL and the universal-link domain; the site writes the links; the app’s handling of them is Stage 4.

  • Behaviours: profile.links.one-link-two-forms
  • Tests: fichero-server/tests/unit/api/test_segments_matches_forwarding.py, DeepLinkFormsTests.swift (not yet written), test_bundle_links_name_the_one_id_6439.py (not yet written)
  • Depends on: 1.1
  • Size: M

SegmentReference generalised to the kinds (one parser, two printers); the crate writer states both forms; Copy Link joins the command table under the standard-chord rule (no chord).

  • Behaviours: profile.links.open-resolves-through-the-one-resolver
  • Tests: fichero-server/tests/unit/api/test_segments_matches_forwarding.py, fichero-server/tests/unit/security/test_holds_close_6320.py, DeepLinkLandingTests.swift (not yet written)
  • Depends on: 4.1
  • Size: M

The URL handler’s one branch for both forms; the resolver’s Location gains the kinds it lacks (entity and claim exist; reading, order and run join) as fields on the same model, no second route; the landing reuses InspectorPath.reveal and WindowState.revealSegments.

  • Behaviours: profile.links.iiif-content-state-for-viewers, profile.links.derived-views-carry-the-link
  • Tests: fichero-server/tests/unit/api/test_export_word_transcript_options.py, test_content_state_link_6439.py (not yet written), test_views_carry_the_link_6439.py (not yet written)
  • Depends on: 4.1, 3.2
  • Size: S

Stage 5 — training sets, Croissant, model cards

Step 5.1 — the set as a dataset with Croissant, loadable by datasets (#6439)

  • Behaviours: profile.training.set-is-a-dataset-with-croissant
  • Tests: fichero-server/tests/unit/training/test_kraken_training_set.py, fichero-server/tests/unit/training/test_line_pairs.py, test_training_set_is_croissant_6439.py (not yet written)
  • Depends on: 1.3
  • Size: M

The Croissant writer reads the set’s manifest and the lines’ tables; the split by manuscript is a field, not a copy; the Parquet partitions reuse Step 1.3’s writer.

Step 5.2 — what may train and what may leave (#6439)

  • Behaviours: profile.training.only-what-may-train-and-leave
  • Tests: fichero-server/tests/unit/training/test_set_excludes_flagged_lines.py, fichero-server/tests/unit/training/test_hf_jobs_target.py, test_training_set_respects_release_6439.py (not yet written)
  • Depends on: 5.1
  • Size: S

The rights record gains the release answer beside model use (one field on RightsRecord, rights.set audited as today); the set builder, the bundle writer and the push read it in one helper.

Step 5.3 — a model card file per model, PROV, the Hub push as a copy of the part (#6439)

  • Behaviours: profile.models.card-file-per-model, profile.training.hf-push-is-a-view
  • Tests: fichero-server/tests/unit/training/test_models_live_in_the_project.py, fichero-server/tests/unit/training/test_a_new_card_keeps_the_old_evaluations_6138.py, test_model_card_file_6439.py (not yet written), test_hf_push_uploads_the_bundle_part_6439.py (not yet written)
  • Depends on: 5.2, 1.2
  • Size: M

Stage 6 — import, and the round trip over the whole model

Step 6.1 — a bundle is recognised and merged by id through the existing readers (#6439)

  • Behaviours: profile.import.bundle-merges-by-id
  • Tests: fichero-server/tests/unit/formats/test_import_into_library.py, fichero-server/tests/unit/importers/test_iiif_by_reference.py, test_bundle_import_merges_by_id_6439.py (not yet written)
  • Depends on: 1.5, 2.3
  • Size: L

L and kept as one step because the matching by id is one rule applied to every kind in the table; splitting it by kind would write the rule several times. The crate reader hands each part to the reader that exists.

Step 6.2 — dry run and the report per kind, with declared losses (#6439)

  • Behaviours: profile.import.dry-run-and-report-per-kind
  • Tests: fichero-server/tests/unit/api/test_import_actions.py, test_bundle_import_dry_run_report_6439.py (not yet written)
  • Depends on: 6.1
  • Size: M

Step 6.3 — entities by authority first, yours never overwritten, one audited batch with one undo (#6439)

  • Behaviours: profile.import.entities-match-by-authority-first, profile.import.yours-is-never-overwritten-silently, profile.import.one-audited-batch-one-undo
  • Tests: fichero-server/tests/unit/formats/test_import_into_library.py, fichero-server/tests/unit/api/test_a_correction_counts.py, fichero-server/tests/unit/api/test_import_actions.py, test_bundle_import_entities_by_authority_6439.py (not yet written), test_bundle_import_keeps_yours_6439.py (not yet written), test_bundle_import_is_one_undo_6439.py (not yet written)
  • Depends on: 6.2
  • Size: M

Step 6.4 — BibTeX and BibLaTeX import on the one bibliography path (#6439)

  • Behaviours: profile.import.bibtex-and-biblatex
  • Tests: fichero-server/tests/unit/api/test_bibliography_importers_hardening.py, fichero-server/tests/unit/importers/test_bibliography_sidecars.py, test_biblatex_round_trip_6439.py (not yet written)
  • Depends on: 3.2
  • Size: S

Step 6.5 — the conformance test over the whole model (#6439)

  • Behaviours: profile.round-trip.lossless
  • Tests: fichero-server/tests/unit/formats/test_pagexml_round_trip.py, test_bundle_round_trip_6439.py (not yet written)
  • Depends on: 6.3, 6.4, 5.3, 4.3
  • Size: S

The Part 1 test file gains its second half; it runs in the gate and is the one proof the profile asks for. Stage 8 (later in this file) extends the same test to the recipes, the run records and the cards of the models used, in Step 8.3.

Stage 7 — the edition PDF (Typst)

Step 7.1 — Typst inside the engine, the edition emitter as a view of the bundle (#6440)

  • Behaviours: profile.edition.typeset-with-typst-inside-the-app, profile.edition.is-a-view-of-the-bundle
  • Tests: fichero-server/tests/unit/api/test_export_word_include_images_6287.py, fichero-server/tests/unit/api/test_export_word_transcript_options.py, test_edition_typst_inside_6439.py (not yet written), test_edition_is_a_view_of_the_bundle_6439.py (not yet written)
  • Depends on: 2.3, 4.1
  • Size: M

The typst wheel pinned in pyproject.toml with a comment like pdfium’s (signed with the app, no PATH lookup); the emitter writes the source folder and compiles; the kept-export format and the Reader’s Export menu entry; veraPDF added to the gate’s tools for the standards check (a Java tool, run in the gate only, never shipped).

Step 7.2 — the body: facsimile, facing text and translation, the apparatus (#6440)

  • Behaviours: profile.edition.pages-facing-and-apparatus
  • Tests: fichero-server/tests/unit/formats/test_abbreviation_markup.py, test_edition_body_and_apparatus_6439.py (not yet written)
  • Depends on: 7.1
  • Size: M

Step 7.3 — front and back matter: title, indexes, bibliography from CSL, cite this, rights, colophon with provenance (#6440)

  • Behaviours: profile.edition.front-and-back-matter
  • Tests: test_edition_front_and_back_matter_6439.py (not yet written)
  • Depends on: 7.2, 3.2
  • Size: M
  • Behaviours: profile.edition.links-bookmarks-and-accessibility
  • Tests: test_edition_links_and_ua_6439.py (not yet written)
  • Depends on: 7.3
  • Size: M

Stage 8 — recipes, runs and the models used

Step 8.1 — recipes as PROV plans through Share Recipe’s writer, nothing secret (#6439)

  • Behaviours: profile.recipes.travel-as-prov-plans, profile.recipes.never-keys-or-secrets
  • Tests: fichero-server/tests/unit/recipes/test_check_names_every_fault_5364.py, test_bundle_recipes_are_plans_6439.py (not yet written), test_bundle_recipes_hold_no_secrets_6439.py (not yet written)
  • Depends on: 1.2
  • Size: M

Waits for recipe-designer.md Step 14.1’s writer and scrubber (the bundle calls them; it does not re-implement them).

Step 8.2 — run records as a Workflow Run Crate, linked from every reading; a card for every model used (#6439)

  • Behaviours: profile.runs.workflow-run-crate-linked-from-each-reading, profile.models.card-for-every-model-used
  • Tests: fichero-server/tests/unit/kg/test_jsonld_export.py, fichero-server/tests/unit/training/test_models_live_in_the_project.py, test_bundle_runs_are_a_workflow_run_crate_6439.py (not yet written), test_bundle_cards_for_models_used_6439.py (not yet written)
  • Depends on: 8.1, 5.3
  • Size: M

Step 8.3 — imported recipes runnable when ready, with what is missing; runs imported as facts (#6439)

  • Behaviours: profile.recipes.imported-runnable-when-ready
  • Tests: fichero-server/tests/unit/recipes/test_check_names_every_fault_5364.py, test_bundle_recipe_import_lists_missing_6439.py (not yet written)
  • Depends on: 8.2, 6.3, 6.5
  • Size: M

The conformance test (test_bundle_round_trip_6439.py, Step 6.5) gains the recipes, the run records with every reading’s link and the cards of the models used; it is the same file.

Test matrix

Fixture (Step 1.5): a library of three pages with regions and lines, a machine reading corrected by a person, two reading levels, one order, two entities and a claim, a catalogued folder on a prototype with a declared mapping, a rights record restricting one page. Every Part’s test exports it.

Open questions

Both questions of the first draft were answered by the owner on 2026-11-08 and are recorded as ruling 9: one root Dataset with isPartOf per folder; fichero: ids only until Publish gives a base URL. None open.