[anth-volk]

Fixes #5

Summary

Adds docs/artifact-submissions.md, the contract for builds handing files to the collector. The collector's intake endpoints and worker framework (#12, stacked on this one) and the emitter's submission module (emitter#27) implement it.

• Two kinds. calibration-diagnostics (roles calibration_diagnostics, plus optional build_manifest, release_manifest and demographics: the files the calibration-tree publisher reads for a build today) and orrery-inputs (schema, execution_overlay, any number of upstream, and native evidence files that are never published).
• The emitter's roles. A table maps each bundle role emitter#27 sends (orrery_schema, execution_overlay, orrery_upstream, orrery_evidence and the four calibration roles) to the contract role it puts in files[].role. A second table maps emitter#22's earlier Orrery publication roles (PublicationFileRole: graph, schema, index, declaration, manifest, binding, summaries, upstream) for O7's re-submission of queued uploads: five of them become evidence, and graph has no contract role, because the collector projects its own Orrery artifact. That earlier path has no overlay file, which O7 has to obtain.
• Provenance: the run ID, the build (the attempt ID), the country, the release (or null for a staged build), and the Hugging Face repo, commit and folder holding the same bytes. Each field has a character set and length (build_id, release and each folder segment use the emitter interface's safe_identifier rule: 128 characters, no colon). Null fields are hashed as JSON null and are never left out. The commit is the one that added the folder.
• Identifiers are derived by the collector. The submission ID is a SHA-256 over the kind, provenance, licensed_data and the sorted inventory, so every request in the flow can be retried. The job ID also hashes a processing round, so a submission can be processed again. The digest of the files is files_sha256, which is a different value from the emitter receipt's inventory_sha256. files[].size is the emitter's bytes.
• Bytes never pass through the API. The API accepts bodies of at most 1 MiB and runs with 512 MiB of memory and a 30 s timeout, so files go to signed upload URLs for a private bucket. Each upload instruction lists every header its signature covers, Host included. Completion checks each object's size and recorded digest from storage metadata; the worker job recomputes every SHA-256.
• A collector without intake is recognisable. The token response states its scope. With intake switched off, the exchange for artifacts:submit and every submission path answer 404 with the code intake_not_enabled. A 404 means "unknown submission, create it again" only with the code submission_not_found. While intake is not available, the client keeps its files queued.
• Every answer is specified: the create, completion and status bodies (including each upload instruction's fields, headers and URL expiry), each collector answer with its code and what the client does, 429, the maintenance-mode 503 the collector returns on every path, other 5xx answers, and the storage service's answers to an upload (an expired URL, a signature mismatch, 412).
• Statuses: awaiting_upload, queued, processing, then one of succeeded, rejected or failed. A stored object with another size or SHA-256 rejects the submission at completion (stored_object_mismatch), because stored objects are never replaced.
• Attempts, dispatches and recovery: 3 attempts and 3 dispatches per processing round. A recovery run every 10 minutes fails a job whose lease expired after its third attempt, dispatches again one whose attempt or execution ended early, and fails one that would need a fourth dispatch. An operator can reprocess a final submission in a new round.
• Disclosure (decision D10, 2026-10-20): intake storage is private for every submission. Orrery outputs of licensed builds stay private until output clearance (D5). Calibration data derived from licensed data may be public. Native evidence is never published. licensed_data is required with no default.
• Credential scope: the exchange issues an artifacts:submit token only when asked; existing clients still get telemetry:write tokens, and neither scope works on the other's endpoints.

Review fixes (2026-10-20)

Docs only, so there is no red/green step for any of these commits.

Commit	Findings
397d555 Name the roles the emitter sends and the provenance syntax	roles named as emitter#27 sends them, with both mapping tables; provenance character sets, lengths, null handling and the adding commit; inventory_sha256 renamed files_sha256; size documented as the emitter's bytes
cc798fa Specify every answer, and how a client recognises a collector without intake	the token response's scope, intake_not_enabled and submission_not_found, the client rule to keep files queued; response bodies, upload instruction fields and headers (with Host), 429, 5xx and the maintenance-mode 503, storage answers; size and SHA-256 mismatches made final rejections
8e52d02 Reprocess submissions and recover jobs whose attempt ended without a result	processing rounds in the job ID, numbered dispatches, recovery and reprocessing
673df3d Keep only licensed Orrery outputs private, per decision D10	the disclosure rules and the changelog fragment

Testing

tools/bump-version.py --check passes: with this fragment, the next release is 0.4.0 (main is at 0.3.0). CI runs the full checks.

Merging

Don't merge before the collector deployment switch-over is verified. A merge to main creates a release, and after the switch-over it also deploys.

🤖 Generated with Claude Code