Systems and subsystems

The submission writer and the experiment log

One function writes the TSV and refuses anything that would make it invalid: a wrong header, a duplicate file, a non-finite or out-of-range score, or an existing path. Every TSV gets a row in a tracked log with its validation score. A submitted file is never overwritten.

In plain words

The deliverable, the TSV, is a text file with a header and one row per test file, in the sponsor's order. The cheapest way to lose the weekend would be a malformed file, so the writer checks everything it can and reads the file back to confirm it. The log exists so that every number ever submitted can be traced to a file and a validation score; the project rule is that a submitted TSV is never renamed or overwritten.

What goes in and comes out

In: the ordered file ids and their scores. Out: <team>_predictions.tsv with header filename<TAB>cm-score, and a row appended to submissions/log.csv.

Where it lives

src/hearsay/submission.py: score_files, write_submission, append_log, preflight, and the accepted audio extensions.

Rules and where each is set

write_submission refuses, in order: an existing path, a length mismatch between ids and scores, an empty submission, duplicate ids, non-finite scores, scores outside [0, 1]; then it writes with exclusive-create and reads the file back to assert the header, order and exact values (submission.py, lines 73–110).
The log columns are timestamp, rung, validation_score, validation_score_clean_only, csv_path, notes; the clean-only column defaults to the validation score when no augmentation was used; the path is stored relative to the repository (submission.py, lines 29–31 and lines 113–133). The column named csv_path is a historical name for the submission path.
score_files never loses a row: a decode error, a scorer exception or a non-finite score yields the fallback score plus a flag (submission.py, lines 44–70).
The library's preflight scores silence and a chord twice and requires exact equality; the runner uses its own tolerant version.

Status

Built in the first hour and unchanged. The constant "always real" rollback TSV existed before any model did.

Numbers

The log is the source of truth on numbers where documents disagree (a project rule). The shipped TSV's row is timestamped 12:03 on Saturday; the file was sent at 12:30.

Known limits

The writer validates format, not content: a valid file with a bad ranking is still valid.

Tests that pin it

tests/test_audio_and_submission.py: one finite score per file in order, a scorer exception is survived, the exact TSV bytes, never overwrites, rejects a length mismatch, a duplicate, NaN, 1.5, −0.1 and an empty submission leaving no file behind, and the log row.

Sources

CLAUDE.md, "Conventions"; README, "Where each artifact lives".