Milestone 7 of 8

Serialize, reload, and replay search

Save the index, statistics, analyses, results, excerpts, plots, and manifest; read them back separately; and reproduce the same ranked evidence.

An index is useful only when it can leave the current Python process and still mean the same thing. Save the inputs and evidence needed to check that claim.

Goal

Serialize the index and search evidence, reload it without changing order or values, and replay the search in a separate output tree.

Inputs

Use the validated source identity, tokenizer and search configuration, complete index, summaries, query analysis, contributions, ranked results, and excerpts. The replay must use saved configuration and source identity rather than hidden editor state.

Deliverables

Extend src/report.py and src/main.py to save:

  • output/inverted_index.json and document/term summaries;
  • output/query_analysis.jsonl, ranked_results.jsonl, score_contributions.csv, and result_excerpts.jsonl;
  • indexed-length, posting-count, candidate-count, and returned-result figures with exact plot data;
  • output/search_index_manifest.json; and
  • a replay agreement or mismatch record under output/replay/.

The manifest records source, tokenizer, configuration, artifact, and implementation identities. Replay must not overwrite the original output.

Checks

Read every JSON, JSONL, CSV, and plot-data artifact back. Check schemas, identities, deterministic key order, positions, counts, scores, contributions, rank, excerpts, and figure data. Replay into a distinct directory and compare the complete index and all downstream records.

Deliberately change one source identity, tokenizer version, query, ranking rule, or excerpt radius. The replay report must show the first mismatch while leaving the original artifacts unchanged. Check that a reloaded index still answers a repeated query exactly.

Workspace

Keep original artifacts under output/ and replay artifacts under output/replay/. Keep the manifest and search-index card at stable project paths. Do not put the replay output in the source corpus.

Hints

HintCompare in dependency order
Compare identity, source records, index, query analysis, contributions, results, excerpts, and figures in that order. A later mismatch may be a consequence of an earlier one.
HintPlots need records
A plot is reproducible only when its exact data and source identities are saved beside it.

Review

Open one original and replayed result with its contribution rows and excerpt. What exact agreement does replay establish for this configuration? What does it not establish about speed, meaning, or future corpora?

How to check your work

Checks compare manifest fields, read-back schemas, complete outputs, and the replay record with the fixtures. A mismatch remains visible; it is not repaired by silently rebuilding the source.