# Offline text-artifact capture Version 1.0. **Development tooling; defaults are unfrozen.** Focused tests use temporary artificial text/reference fixtures. No actual study inputs, task answers, model outputs, ratings, or study captures are supplied. Existing research assets and utilities are unchanged. This implements the explicit text-deliverable capture step in [protocol ยง5 step 4](../03-experimental-protocol.md). Inspection found compatible raw-byte read/hash/exclusive-write helpers in [seal_runs.py](../run-sealing/seal_runs.py); the utility reuses those helpers without invoking sealing, assessment, or accounting. It does not discover files, compare candidates, choose an endpoint, summarize text, render a worker response, or strip boilerplate. ## Local usage Python 3.9+ and the standard library are sufficient, using the included project helpers. From this folder: ```sh python3 -B capture_text_artifact.py --source /worker/exported-deliverable.txt \ --run-id RUN_ID --condition-id CONDITION_ID --task-id TASK_ID \ --repetition-id REPETITION_ID --turn 3 --artifact-id ARTIFACT_ID \ --artifact-dir /staging/new-artifact-only \ --record-dir /coordinator/new-capture-record ``` All selection/identity arguments are explicit. Run, condition, task, repetition, and artifact identities must be nonempty UTF-8 strings without surrounding whitespace, control characters, or line separators. Interior spaces and Unicode identifiers are permitted; IDs never become filenames. Turn must be a positive integer, not a boolean. The caller maintains global uniqueness and consistency across captures; this tool does not discover or maintain a cross-run catalog. Optional `--expected-source-sha256` verifies a known lowercase SHA-256 before writing. No registry/guide is read to infer task versions or requirements. Both destinations must be **new, disjoint directories with existing parents**. Existing directories/files/symlinks, including empty directories and broken symlinks, are refused. The artifact directory contains only `artifact.txt`, copied from the selected file without modification. The separate coordinator directory contains `capture-record.json`. Source files are never modified, and no parent/source directory is searched for alternatives. Exit 0 reports the two paths and captured hash. Exit 2 reports a JSON validation/I/O error on stderr with no success output; an interruption returns 130. Missing/non-file sources, invalid UTF-8, malformed identities, expected-hash mismatches, and output collisions are rejected before creating directories. A zero-byte file is valid UTF-8 and is captured as empty, without claiming it completes the task. ## Byte preservation and semantic limits The source is read once as bytes, validated by UTF-8 decoding, and written as those same bytes. No decode/re-encode, newline conversion, Unicode normalization, heading removal, whitespace trimming, or appended newline occurs. UTF-8 BOMs, CRLF, tabs, quotes, and all text are preserved. Read-back bytes/hash must match before a success record can be published. **Callers must export the deliverable separately from diagnostics, progress prose, completion/self-assessment reports, tool traces, and private reasoning.** Explicit deliverable selection is the reversible development default. This capture utility does not heuristically extract an answer from a mixed worker transcript. If a caller labels a report or boilerplate-containing file as the deliverable, valid UTF-8 bytes are still copied unchanged. Byte validation cannot establish semantic purity, source legitimacy, correctness, successful task completion, or a compliant observation boundary. The record marks `semantic_purity_verified` false. The recorded source hash covers the bytes actually read, not a guarantee that the source path was immutable before or after capture. Supply a stable export and an expected hash when appropriate. The capture timestamp records this local operation, not worker-completion time, preregistration, or prior immutability. ## Coordinator record and handoff compatibility `capture-record.json` version 1.0 includes explicit run/turn/artifact identity; source path/hash/byte count; independently checked captured-file path/hash/byte count; timestamp; and declaration of the explicit-selection policy. This metadata is never inserted into `artifact.txt`. Keep the record out of model-facing/rater packets; folder naming/default permissions do not enforce confidentiality. Two nested records support existing interfaces without changing them: - `observation_artifact`: exactly `{artifact_id, sequence, path, sha256}`, using turn as sequence. The coordinator can supply it as current or earlier artifact metadata in the [observation assembler's manifest](../permitted-observations/README.md). The assembler reads only the captured text, not this capture record; its history/order/bounds checks still apply. - `sealing_record`: exactly `{record_id, kind, path, sha256}`, with `kind` = `artifact`. It can be added to a [run-sealing inventory](../run-sealing/README.md). The coordinator must still assign it to the correct run/attempt and **explicitly** select a final endpoint under the planned stopping/selection rule. Capturing a turn does not select it for final assessment; `final_endpoint_selected` remains false. Capture neither invokes these downstream tools nor changes live state. Absolute descriptor paths point only to the captured snapshot. The record does not claim the chosen IDs match an external run registry; that linkage remains explicit coordinator bookkeeping. ## Failed-write behavior and software checks Payload writing reuses the sealer's exclusive/fsynced byte writer. The coordinator success record is staged separately, fully written/flushed/read-back checked, and published through an atomic **no-overwrite hard link** only after payload validation. This is an unfrozen development publication default; unsupported hard-link filesystems fail without publishing a success record. Failed/corrupt payload writes, interrupted operations before publication, metadata-write failures, and publication failures leave no canonical `capture-record.json`. Partial new files/directories can remain; do not use them as a successful capture, and retry with fresh destinations. A pending temporary metadata file is not a success record. There is no claim of power-loss durability, confidentiality enforcement, or protection from later/adversarial filesystem edits. ```sh python3 -B -m unittest -v test_capture_text_artifact.py ``` Tests cover exact bytes/hashes, BOM/CRLF/Unicode/empty text, metadata separation, unchanged diagnostic-looking text, no alternative-file selection, invalid identities/sources/encoding, output refusal, partial/corrupt payload and metadata writes, failed publication, CLI status, and actual handoffs to the unchanged assembler and sealer using artificial fixtures. All fixture captures, assembled inputs, and archives are temporary and deleted. No model, experiment, API credit, production change, or submission is involved.