Encode investigation source as contiguous plain-text code blocks

docs/investigation-code-blocks-v7.md

@@ -0,0 +1,62 @@
+# Investigation code blocks v7
+
+New project investigation contexts use `investigation_project_v7`. Existing
+requests keep v4/v5/v6 views and prompts. Only investigation requests change;
+archived case data, evidence IDs, controller gates, budgets and other phases do
+not change. No extra model call or semantic summary is introduced.
+
+## Plain code instead of per-line records
+
+Each shared file stores its metadata and origin once. Contiguous observed code
+is represented by blocks with `start_line` and `lines` containing plain text
+strings. Line numbers are inferred from start_line plus array offset. Shared
+`line_defaults` holds identical truncation flags once per file. Block attributes
+preserve different flags and their exact JSON types; missing flags remain missing.
+
+Source records are ordered by actual line number and typed content. Capture
+slices are remapped so their original item order and duplicates reconstruct
+exactly. Gaps start new blocks; no unread code is filled in. Contradictory records
+at one line remain separate and keep the existing conflicting_lines marker.
+Invalid/noninteger line records retain the previous encoding. Unknown file
+identity and different snapshots are handled as in v6.
+
+`shared_source_blocks_v1` references positions in the flattened blocks. These are
+record positions, not literal source line numbers. Fallback row tables remain
+available where they are smaller. The final choice is the smallest canonical
+view among block, consolidated and thin encodings. No request grows simply to
+introduce this encoding. All formats are described by the versioned prompt.
+
+`restore_blocks` rebuilds the original working view exactly, including filters,
+origins, boundaries, null/missing distinctions, truncation, order and actual text.
+Offline benchmarks test canonical JSON equality, including Unicode/escapes and
+contradictory observations. The measurement script now defaults to v7 and retains
+explicit `--target-version` choices for v5/v6 comparisons.
+
+## The actual request inspected by the user
+
+Comparison of the same late Bug 17 request, without display indentation:
+
+| Representation | User-message characters |
+|---|---:|
+| Original transmitted v4 | 206,560 |
+| v5 line tables | 91,210 |
+| v6 shared file/line tables | 89,817 |
+| v7 plain code blocks | 86,166 |
+
+This is a 58.29% reduction against the original, not merely the incremental
+reduction against the last already compressed version. Readable indented JSON
+shrinks from 9,210 to 4,255 display lines; display-line counts are not wire sizes.
+The actual shared code has 631 observed lines, represented by two blocks: 1-80
+and 90-640. Lines 81-89 were not read and are not invented. The remaining request
+contains case sources, hypothesis state, queries/evidence, interpretation, schema
+and other controller context. It is not all repeated source metadata.
+
+Across all 14 stored Bug 17 contexts, user text shrinks from 1,961,028 to 977,563
+characters (50.15%). Across the nine Bug 20 contexts it remains 549,750 versus
+563,131 originally (2.38%); that case has little code to consolidate. System
+instructions are included separately in the benchmark message totals.
+
+Fresh readable v7 examples were written outside the input package under the
+existing trial's request-inspection directory. They are offline reconstructions,
+not live requests. Actual provider token use and analysis quality remain to be
+checked in a future live run. No paid requests were used for this change.