paperspec/spec/12-package.md

12. The package

A document travels as a package: a folder named by its key, or the same folder zipped.

12.1 Files

Path	Required	Holds
MANIFEST.json	Yes	The manifest (12.3).
document.json	Yes	The document (2.2).
nodes.jsonl	Yes	Every node, in document order (3).
witnesses.json	Yes	Every witness, with its rights (2.3).
provenance.json	Yes	Tools and versions, backends, cached readings, stages and where each ran.
pages.jsonl	No	Every page of every witness (7.3).
locations.jsonl	No	Geometry per node and page (7.4).
references.jsonl	No	Parsed references and their resolution (10).
corrections.jsonl	No	Every correction, in order (11).
receipts.jsonl	No	Receipts and revocations, sorted by at and then id (8).
ids.jsonl	No	Retired IDs and legacy aliases (4.4).
suspects.jsonl	No	Unresolved suspects, sorted by id (5.7).
roster.json	No	The roster its receipts need (8.7).
assets/	No	Images and crops, as <sha256>.<extension>, present or listed only.
datasets/<id>/	No	Datasets (15).
derived/	No	Rebuildable renderings, never authoritative (12.7).

An optional JSON Lines file with no records is omitted. Every file is in the canonical form of 1.9.

12.2 Paths

Paths use /, are relative, have no empty, . or .. segment, no backslash and no NUL, and are already normalized. No two paths are the same once case-folded, so a package reads alike on every file system. A package folder carries no symbolic links, and a consumer refuses one that does, as it refuses a package whose files exceed its own size limit. In a zip, entries are UTF-8 named, sit under one top-level folder named by the key, are stored or deflated, carry no symbolic links, and are unique; a consumer refuses an archive that breaks any of these, or whose expanded size exceeds its own limit. It refuses in the same way (package.zip.entry) an archive it cannot read, such as one whose entries need a later version of the zip format than it implements, or whose deflated data does not inflate. A producer that wants byte-identical archives writes entries sorted by path, dated 1980-01-01 00:00, with no extra fields; fixtures/packages/tiny2026tiny-j4qm.sct.zip is such an archive.

12.3 The manifest

MANIFEST.json, scienting-package/1, is {format, doc, key, files}: the package format, scienting-doc/1, the document key, and every other file as {path, sha256, size}, sorted by the UTF-8 bytes of the path. An asset whose bytes stay in the asset store is listed with present: false; nothing else may be. The SHA-256 of MANIFEST.json pins the whole package.

12.4 Provenance

provenance.json holds tools ({name, version}), and optionally backends, readings (each cached reading's ID, witness, backend and SHA-256), stages (each stage's name, tool, input hashes, output hash, the processor where it ran, and the uses it ran under) and a session. Every stage that uses a model or an outside service records where it ran (14).

12.5 Text policies

Policy	Means
full	Every leaf keeps its content.
checks-only	Every leaf has withheld: true and no content; panels drop their figure text; references keep their resolution but no CSL; there are no corrections, suspects, datasets or derived files; and the hashing scheme is keyed: hmac-team between the team's machines and hkdf-pages outside the team (5.8).

A checks-only package is how a team shares its annotations on a paywalled paper without sharing the paper. Its text lives in the team's private asset store, and only key holders can check its values. fixtures/packages/hale2026harmonic-damb.checks-only is such an export of hale2026harmonic-damb to another machine of the team, under the team key in fixtures/keys/.

12.6 Assets

Assets are named by SHA-256, so every read is rehashed and a regenerated crop is a different asset. Bytes that live only in the asset store are listed in the manifest with present: false, with their size.

12.7 Derived files

derived/ holds what a pinned tool makes from the package. Each line of a derived file names a formula by node and run, the index of a math run among the node's runs, or null for an equation or equation line, and the tool ({name, version}) that made it.

Path	Lines	Schema
derived/mathml.jsonl	{node, run, tool, mathml}: the formula rendered as MathML.	mathml.schema.json
derived/math.jsonl	{node, run, tool, form, tree, symbols, complete, issues, label?}: the formula read in a math form (9.4).	math.schema.json

Nothing derived is content, and a consumer may delete and rebuild it; a validator does not recompute a derived file, since it does not run the tool, but checks its lines against their schema and that each names a formula of the package (doc.derived.node), and that a math line's formula is TeX and its complete and symbols agree with its tree (doc.derived.math). A derived file reads the text, so a checks-only package carries none (12.5). A correction can delete a formula, change it or move its run, so a producer that applies one rebuilds the derived files or leaves them out.

12.8 Media type and extension

A zipped package has the extension .sct.zip and the media type application/vnd.scienting.doc+zip.