# Offline run sealing Version 1.0. **Development tooling, not experimental evidence.** Tests use temporary artificial files and metadata, not study outputs. No actual study archive, assessment packet, rating, or measured cost is supplied. Interfaces and defaults are unfrozen. Existing assets and utility behavior are unchanged. This implements the snapshot/archival step in [protocol ยง5](../03-experimental-protocol.md), before independent assessment. It archives exactly declared run records and the matching registered task/rubric references, with byte counts and SHA-256 hashes. The coordinator explicitly designates each endpoint. No newest-file, best-looking-artifact, hidden-score, or success heuristic selects an output. Sealing records a new snapshot event; it does **not** prove preregistration, completeness of the declared history, prior immutability, correct endpoint policy, or valid experimental conduct. ## Usage Python 3.9+ and the standard library are sufficient. Copy [inventory.template.json](inventory.template.json), fill the coordinator inventory, and choose a **new archive directory with an existing parent**: ```sh python3 -B seal_runs.py --inventory /coordinator/completed-inventory.json \ --output /coordinator/new-sealed-archive ``` `--registry` optionally selects a matching version 1.0 task registry; the default is the completed assessment kit's registry. Source record paths resolve relative to the input inventory (absolute paths also work). Registered reference paths resolve relative to their registry. Files must exist and be regular readable files; supplied expected hashes, when nonnull, must match. Source files and input inventories are never modified. No directory scanning discovers additional records, and no missing files are reconstructed. On successful exit 0, the tool reports the archive, packet-manifest and relocated-registry paths plus declared/assessable/unassessable run counts. Exit 2 means validation or I/O failure; interruption returns 130. Existing destinations, including empty directories and broken symlinks, are refused. No output is created on preflight failure. A write failure can retain an **unsealed partial archive** for coordinator inspection; rerun with a new destination rather than overwriting it. Future assessment preparation uses the existing builder, keeping distribution separate: ```sh python3 -B ../development-tasks/assessor-only/manual-assessment/build_assessment_packets.py \ --manifest /coordinator/new-sealed-archive/packet-build-manifest.json \ --registry /coordinator/new-sealed-archive/registry/task-registry.json \ --packets-dir /distribution/new-rater-packets \ --coordinator-dir /coordinator/new-packet-key ``` Do not distribute the archive itself. Its prompts, memory, configuration, attempts, usage and source paths are coordinator-only operational material. The packet builder copies only its allowed final-artifact/reference material and prepares separate keys. Folder naming and default filesystem permissions do not enforce confidentiality; storage/distribution access remains the coordinator's responsibility. ## Input inventory version 1.0 Root fields are exactly `input_inventory_version` (`"1.0"`), `batch_id`, `collection_completed` (boolean true), `independent_rater_ids`, `conditions`, `records`, and `runs`. Batch IDs are explicit strings. Two distinct rater identities and condition/repetition declarations follow the existing [coordinator contract](../development-tasks/assessor-only/manual-assessment/SCORING.md). `collection_completed` declares that collection of the listed records has ended, **not** that every attempt succeeded or all originally desired records are available. Unknown JSON fields and duplicate keys are rejected. `records` is a global file list. Each entry has exactly: | Field | Meaning | |---|---| | `record_id` | Unique nonempty string; also the artifact ID when this record is selected as an endpoint | | `kind` | `artifact`, `submitted_prompt`, `memory_snapshot`, `configuration`, `usage_ledger`, `usage_raw`, or `operational_record` | | `path` | Explicit source file path | | `sha256` | Optional expected lowercase SHA-256, or null to compute a snapshot hash without asserting a prior hash | Source paths must be unique. Share a single configuration/usage record ID across runs rather than duplicating the file under aliases. Every record must be referenced by at least one run. Artifact records belong to exactly one run; distinct files may have identical contents. Non-final artifacts, rejected responses, intermediate memory and raw operational files stay in the archive. The tool cannot detect undeclared omissions or identify semantic content from a filename. Each run has explicit `run_id`, `condition_id`, `task_id`, `task_version`, `rubric_version`, and `repetition_id`; `run_status`; `ended_at_utc`; `endpoint_selection`; `record_ids`; `record_availability`; and `attempts`. Run IDs and condition/task/repetition cells are unique. Task/rubric versions must match the registry, and conditions/repetitions must be declared. `run_status` is `completed`, `incomplete`, `failed`, or `cancelled`. End time is ISO 8601 UTC or null if unavailable, never a fabricated timestamp. `endpoint_selection` contains exactly `artifact_id` and a nonempty `basis` explaining the coordinator's endpoint policy. A nonnull ID must identify an artifact in this run's `record_ids`. Its bytes must be UTF-8 text for packet-builder compatibility; they are not transcoded or edited. The basis records a decision, not proof that it was prespecified. A completed run requires an endpoint. An incomplete/failed/cancelled run can designate its last available partial/incumbent artifact, or explicitly use null with a reason. Null endpoints are retained in `unassessable_runs`, with their identities/reasons, while the downstream manifest contains only explicitly designated deliverables. Original condition/repetition declarations remain, so scoring coverage holes remain visible. No minimum-score or missing-run imputation is performed. Version 1.0 requires at least one designated deliverable to emit a usable packet manifest; an all-no-deliverable inventory is rejected rather than producing an incompatible manifest or invented artifact. `record_availability` has exactly `artifacts`, `submitted_prompts`, `memory_snapshots`, `configuration`, `usage_records`, and `operational_records`, each with `state` and `note`. States are `available`, `partial`, `unavailable`, or `not_applicable`. Available/partial categories require matching file references; unavailable/not-applicable categories require none. Every state except available requires an explanation. This permits explicit missing usage or an arm with no memory without interpreting absence as zero usage or silently deleting a category. An archived unavailable configuration remains a reproducibility limitation; sealing does not cure it. Each run's nonempty `attempts` array contains exact fields `attempt_id`, `phase`, `role`, `status`, `retry_of`, `started_at_utc`, `ended_at_utc`, and `record_ids`. Attempt IDs are unique across the batch. Phase/role follow the resource ledger; status additionally permits `incomplete` alongside `succeeded`, `failed`, `cancelled`, and `unknown`. Record references must belong to the run and can be empty when no response was captured. Optional timestamps remain null when unavailable; present timestamps must be UTC, ordered, and not in the future. Retry links must exist, be acyclic, and retain run/phase/role. Incomplete attempts with no end time are preserved even after collection ends; they do not become successes or disappear from the inventory. ## Usage records and downstream contracts `usage_ledger` explicitly declares a [resource-ledger version 1.0](../resource-accounting/README.md) file. Its original bytes are archived; values are validated using the existing resource utility, with no accounting calculation, price inference, or filling unknowns. Ledger run IDs/cells must match exactly the runs referencing that file. Request IDs must identify declared attempts with matching run, phase, role, and retry link. A logical/content-incomplete attempt need not have the same status label as its transport request. Duplicate request IDs across reconciled usage-ledger records are rejected. Archive overlapping historical ledger snapshots as `usage_raw` instead: those are preserved byte-for-byte as opaque evidence, not asserted to be reconciled ledgers. A shared batch ledger can be referenced by all its runs without copying or charging it repeatedly. The emitted `packet-build-manifest.json` follows the existing builder's exact version 1.0 schema and references archived final artifacts by relative path/hash. Original task/rubric versions and run identities are retained. All emitted run seals use the actual snapshot completion time, not a backdated input timestamp. The self-contained `registry/task-registry.json` points to snapshotted public packets, guides, and conventions with unchanged content hashes; original inventory/registry bytes are also saved separately. These reference assets are an explicit consequence of selecting a registry, not inferred additional worker outputs. ## Commit and failure semantics The archive contains opaque-named record copies, original source-inventory/registry bytes, a relocated registry with verified references, and a versioned `archive-inventory.json` listing every declared record's kind, source provenance, **relative archive path**, byte count, and SHA-256. Original run statuses, endpoints, availability declarations, attempts, and unknown timestamps remain in that inventory. A detached `archive-inventory.sha256` covers its bytes. Neither file alone marks the batch sealed. The **only seal/commit record** is the final root `packet-build-manifest.json` with `batch_sealed: true`. Payloads and inventory are written exclusively, flushed, and validated, including all archive hashes and the relocated registry. The complete seal manifest is then staged in a temporary sibling file outside the archive, checked, and published with an atomic **no-overwrite hard link**. This is a reversible development publication default: unsupported hard-link filesystems fail without a committed seal; there is no unsafe fallback. Failed/interrupted copying, corrupted writes, staging failures, or failed publication leave no committed manifest. Partial archives are never overwritten. Temporary-sibling cleanup is best effort; a leftover temporary file is not the archive commit record. This guards the tool's process-level publication sequence, not power-loss durability, adversarial concurrent modification, authenticity, or later filesystem edits. Hashes can be recomputed after changes. The seal does not prove complete historical capture, frozen budgets/settings, prior immutability, or preregistration. Record these limits rather than treating a successful archive as experimental validation. ## Focused software checks ```sh python3 -B -m unittest -v test_seal_runs.py ``` Tests use temporary artificial reference files, text, prompts, configuration, memory, and all-unknown usage fixtures. They cover exact bytes/hashes, explicit endpoint choice, preservation of incomplete attempts, unavailable records, missing sources, identity/version/ledger failures, output collisions, corrupt/failed/interrupted writes, failed atomic publication, and an end-to-end handoff to the unchanged packet builder. Fixture archives/packets are deleted. No actual study archive, packet, rating, estimate, model run, experiment, API spending, production change, or submission is generated.