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.mdand 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)
- 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.
- 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.
- 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.
- 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.
- Lossless round trip is the test: a library exported, imported into a fresh library and exported again gives the same bundle.
- 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.
- 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.
- 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.mdStep 14.1). - Owner answers 2026-11-08 (DECIDED): (a) a selection’s bundle is ONE root
Dataset,isPartOfnaming each folder touched; (b) ids arefichero: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. - 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_underinapi/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 fromgraph/,tables/entities.csv,reference/and the crate, with no placeholder and nowithheldcount 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 inannotations/,views/ortables/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 existingtest_holds_close_6320.pyandtest_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.jsonat its root (JSON-LD on the RO-Crate context plus the schema.org context the KG export already uses), the rootDatasetnaming the scope (its title, the catalogue’s description,license,datePublished, the Fichero version and the engine identity assdPublisher), oneFileorDatasetentity per part withencodingFormatandconformsTo(the IIIF, Web Annotation, CSVW, PROV-O, PAGE, ALTO, TEI profile URIs), andhasPartlisting 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_crateinexport_service.py, overiter_export_recordsand the page exporter, and it is reached as a KEPT EXPORT format (/export/kept, formatbundle, 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 inhasPart. Test:test_bundle_is_a_valid_ro_crate_6439.py(not yet written; the crate’s shape,hasPartequals the folder’s files, the validator), the existingtest_export_service.pyandtest_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’shttps://…/id/<kind>/…form assameAs, 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 inannotations/,tables/segments.csv,views/<page>.xmlandgraph/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 existingtest_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:wasAttributedToaprov:Person(the account, by its public name) or aprov:SoftwareAgent(the model by its card id<runtime>:<source>@<version>,source.model.card-id),prov:wasGeneratedByaprov:Activityfor the run (its recipe step, start and end, the settings that matter: temperature, prompt id, level), andprov:wasDerivedFromwhat it was made from (the rendition read, the earlier reading corrected, the teacher’s line); the source is the record’s attribution chain (_made_byinexport_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 inexporter.md’s design note). PROV travels ingraph/provenance.jsonldon a second named context (prov), referenced by id from every part, and as each W3C annotation’screatorandgenerator. 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 existingtest_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 ONEcsv-metadata.json(CSVW: each table’stableSchemawith typed columns,primaryKey,foreignKeysbetween the tables by the one id,aboutUrlthe 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 intables/catalogue.csvare one value. Acceptance:csv-metadata.jsonvalidates as CSVW;readings.csv’ssegment_idis a declared foreign key tosegments.csv; the Parquetsegmentsfile 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 existingtest_export_service.pyandtest_catalogue_sheet_rows.py.profile.catalogue.dublin-core-schema-org-and-iiif— [GAP] (#6439, addition (b); fitscatalogue.export-standards, #5365) each document’s catalogue entry is written once incatalogue/<document>.jsonldas Dublin Core terms (dcterms:title,creator,dateas EDTF,description,extent,language,rights,accessRights,isPartOf,identifier) and schema.org (ArchiveComponent/CreativeWorkwithholdingArchive,locationCreated,aboutfor 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’smetadata(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) andprovider, 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 fromcatalogue/<id>.jsonld, its manifest andtables/catalogue.csv; a restricted document is absent from all three and fromhasPart. 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 existingtest_catalogue_sheet_template.pyandtest_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 fromdatePublished; 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 andcsv-metadata.jsonagainst their JSON schemas kept on disk,source.format.schemas-on-disk, never fetched); every loss is DECLARED in the crate (afichero:losslist 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 existingtest_pagexml_round_trip.pyandtest_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 aSourcePageonce (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’sviews/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 existingtest_page_export_route.pyandtest_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, asrender_markdown_textwrites 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 existingtest_export_service.pyand 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 sameSourcePage: the page image as<image>(a relative path intoimages/or the IIIF Image API URL when by reference), the page’s pixel grid as theviewBox(formats.harness.pixel_grid); each region a<g>whoseidis 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),directionandwriting-modefrom the line’s direction,xml:langfrom 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’sdirection="rtl"; the file validates offline. Test:test_svg_view_6439.py(not yet written; the groups, the paths, the direction, validation), the existingtest_harness.pyandtest_right_to_left.py.profile.views.plain-text-and-duckdb— [GAP] (#6439) two conveniences, both derived and both declared as such in the crate (conformsTonone,fichero:derivedFromthe 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 ONEviews/library.duckdb, a DuckDB database whose tables aretables/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.duckdbhas asegmentstable withtables/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 existingtest_export_service.py.profile.views.levels-and-translations-have-a-place— [GAP] (#6439; withsource.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@resppointing 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 infichero/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 existingtest_tei.pyandtest_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 namefichero-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 adata/folder and asite.config.jsonalone, 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 templatesexport_eleventy_siterenders 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 isdata/+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; foldsiiif.publish.static, #3177) the site’sdata/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 andinfo.jsonper 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, andsite.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 isexport_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.jsonequals the bundle’s; every public image hastiles/<id>/info.jsonwithprofile: 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 existingtest_export_service.pyandtest_iiif_segments_as_annotations.py.profile.publish.pages-and-content— [GAP] (#6439, confirmation 1; withsite.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 ofgraph/, only those the bundle holds), DATES as attested (EDTF rendered in words) and PLACES on a MapLibre map fromreference/and the georeference files; every page shows its item’s RIGHTS and LICENCE (the catalogue’srights,accessRightsandlicense, 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, andprofile.private-never-leavesis 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 onlydata/andsite.config.jsonand 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 existingtest_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 (typefrom the document kind,title,authororarchiveandarchive_locationfrom the catalogue,issuedfrom the EDTF date,URLthe published id,accessedleft to the reader) built from the document’ssource_metadataand its catalogue entry by one mapping;CITATION.cffat the bundle’s root for the dataset (title, authors as the project’s people, version, date, licence, theidentifierswith 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 thansource_metadataa 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 (Highwirecitation_*, Dublin CoreDC.*) and a schema.org JSON-LD<script>fromcatalogue/, so Zotero and Google Scholar read it. Acceptance: a document’scitation/<id>.csl.jsonhas 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 hascitation_titleandDC.titlemeta 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 existingtest_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:Conceptper place withprefLabel, the attested forms asaltLabel,exactMatchto GeoNames, Wikidata or Pleiades where linked, the coordinates as WGS84geo: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 oneprefLabel, onealtLabeland oneexactMatch; 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 existingtest_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 plainhttpslink under the universal-link domain the app already claims (https://tubb.ca/apps/fichero/…, the pattern of the pairing link inFicheroApp.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; nofichero: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 onehttpslink 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 afichero: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; extendssource.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 (identifierandsameAs); 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 ofui/menus-and-commands.md, no chord) and Copy Reference (thefichero: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 assameAs; 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 existingtest_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 (handleOpenURLinFicheroApp.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 (RemoteClientPairingkeeps 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 existingtest_segments_matches_forwarding.pyandtest_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 (aAnnotationwith 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’sURLandCITATION.cff’sidentifiers(Part 3), the Word transcript’s page headings and the Markdown’s front matterurl, the catalogue workbook’s hidden link column, the Eleventy data folder’s pages; views with no place for it (PAGE, ALTO, plain text) carry thefichero: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 hasurl; the CSLURLequals the crate’ssameAs. Test:test_views_carry_the_link_6439.py(not yet written; the heading, the front matter, the CSL), the existingtest_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; withsource.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, itsmanifest()of teacher, counts, held-out and left-out lines and flags;line_pairs.write_line_pairs:pairs.jsonlwithlines/;yolo_set.export_region_set: labels per page) goes intotraining/<set>/as a nested RO-CrateDatasetwith a Croissant 1.0croissant.json:distributionnaming 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 astrain,validationandtestrecord sets; the same folder loads withdatasets.load_dataset()with no loader script (aREADME.mdwith 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 withdatasetsinto the same line count. Test:test_training_set_is_croissant_6439.py(not yet written; the record sets, the split, the load-back), the existingtest_kraken_training_set.pyandtest_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 markedrelease: noin 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 fromtraining/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 existingtest_set_excludes_flagged_lines.pyandtest_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 asmodels/<card id>/README.md, a Hugging Face model card: YAML front matter withlicense,base_model,datasets(the set’s id intraining/),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_hereandcer_publishednever 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:wasGeneratedBythe train job,prov:usedthe set,prov:wasDerivedFromthe base model. The weights are referenced (the Hugging Face repository or the file in the project) and copied intomodels/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 existingtest_models_live_in_the_project.pyandtest_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 thetraining/<set>/folder and themodels/<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 assameAs. Acceptance: the files pushed for the fixture’s set equal the bundle’straining/<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, thesameAs), the existingtest_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 withro-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, asimport-iiifis): 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, asmanifest_importkeeps 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 fromgraph/provenance.jsonld. The reading goes through the existing readers:formats.read_pagefor the views,iiif_importfor 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 existingtest_import_into_library.pyandtest_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 existingtest_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 (thesameAs/exactMatchto Wikidata, GeoNames, VIAF or Pleiades ingraph/andreference/, 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 ruleplan_alias_mergesalready 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 existingtest_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 existingtest_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,datePublishedand 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 existingtest_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/importand/import/persist), extended for BibLaTeX’s fields (datebesideyear,journaltitle,location,eventtitle,@online,@thesis, therelatedfamily) so nothing is dropped, and land as the bundle’scitation/part does (CSL JSON per work, the same mapping in reverse), so a.bibdropped alone, a.bibsidecar beside a folder (source.format.corpus-sidecars) and the bundle’scitation/all take one path; export is the derived BibTeX ofprofile.citation.cite-this-everywhere, and a.bibimported and exported again keeps every field and key. Acceptance: a BibLaTeX entry withdateandjournaltitleimports 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 existingtest_bibliography_importers_hardening.pyandtest_bibliography_sidecars.py.profile.round-trip.lossless— [GAP] (#6439, ruling 5; the second half ofprofile.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 fromdatePublishedand 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 existingtest_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 bindingtypst(thetypst-pyproject, Apache-2.0;typst.compile(source, output=…)withfont_pathsandroot), which carries the compiler inside its wheel, so it is provisioned exactly as pdfium is: one line infichero-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 withalt), PDF/UA-1 is an opt-in standard whose checks FAIL the compile for a non-compliant document (so the writer must supply everyaltand 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 andPROVENANCE.mdrow) 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 existingtest_export_word_include_images_6287.pyas the emitter pattern.profile.edition.is-a-view-of-the-bundle— [GAP] (#6440) the edition is ONE emitter beside Word (export_edition_pdfinexport_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 fromimages/(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 fromgraph/andreference/, the bibliography fromcitation/, the rights fromcatalogue/, the provenance fromgraph/provenance.jsonld— writes a Typst SOURCE FOLDER (edition.typ, the template,data/as the bundle’s JSON read with Typst’sjson(), 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 isprofile.private-never-leavesand no second filter exists. Acceptance: the fixture’s edition PDF holds every public page and no private one; deleting the bundle’sgraph/makes the index of entities empty and the compile still succeeds; the.typfolder 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 existingtest_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 nativefootnote()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 existingtest_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 percatalogue/) and closes with the INDEXES (entities by kind — persons, places, institutions — and dates, each entry with the folios and line numbers it appears on, fromgraph/and the mentions), the BIBLIOGRAPHY typeset by Typst’s native CSL support from the bundle’s citation data (the derived BibTeX ofcitation/as Typst’sbibliography()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, fromgraph/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 ofprofile.links.one-link-two-forms) as a Typstlink(), 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 analt(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 ( langandregionon Typst’stext()), 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.yamlandrecipe/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 thePIN_FORMS, place kind, settings, conditions) goes intorecipes/<id>/exactly as Share Recipe writes it (one writer:designer.share.export-is-the-whole-planIS the bundle’s recipe part), and is described ingraph/plans.jsonldas aprov:Plan(the recipe) whose steps areprov:Plans too, eachprov:wasInfluencedBythe model card it names, so a run’s activity can sayprov:hadPlan; the version is the recipe’s schema and content hash. Acceptance: the fixture’s recipe exports torecipes/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 existingtest_check_names_every_fault_5364.pyand 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 inrecipes/,graph/plans.jsonld,graph/provenance.jsonldortables/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 saysneeds: 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 existingtest_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 intograph/provenance.jsonldfollowing the Workflow Run RO-Crate profile (Process Run Crate for a step attempt, Workflow Run Crate for the run:CreateActions withinstrumentthe model card,objectthe pages and renditions read,resultthe readings and segments written,startTime,endTime,agent, the cost and the place it ran, fromWorkflowRunand the run account;prov:hadPlanthe 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 carriesprov:wasGeneratedByits 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-everythingmade concrete);tables/runsandtables/attemptsare 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 whoseobjectincludes the rendition read; two attempts of one step are two actions with oneisPartOf. 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 existingtest_jsonld_export.py.profile.models.card-for-every-model-used— [GAP] (#6439; extendsprofile.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 andlicense, the weights never copied for a model the project did not train (asameAsto 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 andruns_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 existingtest_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/projectandcheck_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 existingtest_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.
Step 3.5 — the site’s links to the app (#6439)
- 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.
Stage 4 — deep links into the app
Step 4.1 — one link in two forms for every kind, Copy Link and Copy Reference (#6439)
- 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).
Step 4.2 — opening a link: the one resolver, the landing per kind, the three library cases, the refusal (#6439)
- 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.
Step 4.3 — IIIF content state and the links in every view (#6439)
- 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
Step 7.4 — deep links, internal links, bookmarks, PDF/UA-1 and PDF/A (#6440)
- 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.