Omission candidates: classify the fields of single objects and entries of nested lists, not only top-level list entries (#3934)

[realmarcin]

Fixes #3934

What changes

replicate_structure.entry_omission_candidates (#3880) classified only the keyed entries of top-level lists of class-ranged slots. It skipped any slot holding one object. This PR adds nested_omission_candidates, the same receipt-backed reading one level further down:

• fields of objects: a field some replicates fill and others leave empty, in an object every replicate holds at that identity. This covers a slot holding one object (human_subject_research.irb_approval) and objects reached further down.
• entries of nested lists: an identified object entry of a list below the first level that some replicates carry and others do not (creators[*].affiliations[*]).

The walk goes down only by two kinds of step:

• a single-object step: a field of an object every replicate holds;
• a keyed-list step: an entry every replicate holds, identified by receipts._entry_key and its occurrence, the join the first level already uses. _entry_key strips the key's value and reads a resolver URL of a declared prefix as its CURIE. Nothing else is normalised, so a name in other words is another entry.

Nothing is read below a keyless entry, a node some replicate lacks, a value that is a list in one replicate and not in another (a list/object or list/scalar disagreement), or a commentary field.

A row is a candidate only when a holder's verified receipt path, resolved into its final record (resolve_verified), sits on the node or below it. Resolution follows the path by identity where the run left a phase-1 snapshot. Where it left none, the path is read as written (an index join). The path must be the node's own path in that replicate, so a receipt only counts through the same chain of entries. A receipt at another holder's path for the node credits nothing when its own replicate holds something else there.

scripts/arm_comparison.py adds the section "Receipt-backed omission candidates below the first level (#3934)". It also adds a _replicate_resolved helper that both entry sections now use, and rewords the top-level-only caveat. notes/arm_comparison.md is regenerated by the script (--no-figures).

Decisions the brief left open

1. Fields of keyed entries are included, not only fields of top-level single objects. The issue asks for every path whose chain is single/key. Rows carry basis (single / key, as in compare_nested) so the two kinds can be told apart.
2. String items of nested lists are counted (values), never classified. Their only identity is their exact text, and below the first level they are mostly prose. For example, version_access.versions_available holds "v1.1, published 2025-01-17, DOI …" in one v6 VOICE replicate and "1.1 (17 January 2025), doi:…" in another. By exact text, 775 of the 871 nested entry rows were such items, as were 47 of the 71 nested-entry candidates on the receipted arms. This mirrors the first level, which leaves the items of top-level lists of values unclassified. Whether such a list is filled at all is still a field row.
3. Credit on or below only. A receipt on the object or entry holding a node does not credit it. A receipt on a list covers only the list (A receipt on a list slot covers every entry beneath it #721). Measured effect: 17 rows (v6: 9 fields; v8: 5 nested entries and 3 fields).
4. Commentary fields are the receipts instrument's exempt keys less source_caveats: conforms_to_class, conforms_to_schema and notes. They are rows with status commentary. source_caveats is skipped at any depth. conforms_to and conforms_to_standard are not exempt, because they carry facts from the bundle (receipts.py). They are classified like any other field. On v5 agentic CM4AI, two conforms_to and two conforms_to_standard rows are such fields, held by rep3 only and unmeasured.

The top-level results did not move

• A test pins entry_omission_candidates' full output on a fixture that has structure below its first level. The pinned literal was produced by origin/main's module (bc1f41d). Since review round 1, the fixture also holds a string entry in a class-ranged top-level list, with a receipt on it (The first-level pin test omits the one input where the shared _keyed switch changes the first-level reading #4437). Main keys such an entry by its text and classifies it, and the branch still does.
• A corpus comparison ran origin/main's module against this branch's on the same records and resolved receipts. Across 24 arm × project groups and 2,854 first-level entry rows, the output was identical. Round 1 changed no code that computes a row or a count. It changed only a comment, docstrings and the new section's legend.
• A render from unmodified origin/main equals the committed note byte for byte, so main had not moved. Against it, the regenerated note changes one line (the caveat) and adds the new section. No existing row moves.

New rows per arm

Fields are shown as candidates / not / unmeasured / commentary; nested entries as candidates / not / unmeasured.

arm	fields in some replicates	nested entries	keyless / values
v4 API	73 (no receipts; 12 commentary)	0	0 / 163
v5 API	57 (no receipts; 17 commentary)	0	0 / 157
v5 agentic	97 (no receipts; 4 commentary)	46 (unmeasured)	0 / 160
v6 agentic	143: 50 / 89 / 0 / 4	38: 21 / 17 / 0	0 / 171
v7 API production	146: 10 / 89 / 0 / 47	0	0 / 83
v8 API production	75: 15 / 8 / 0 / 52	12: 3 / 9 / 0	0 / 95

Every v6 agentic group reads its receipt paths as written, because the agentic path leaves no phase-1 snapshot. Its verified snippets are all no_snapshot: 1,282 (AI_READI), 316 (CHORUS), 967 (CM4AI) and 727 (VOICE). So 50 of the 75 field candidates and 21 of the 24 nested-entry candidates rest on that index join. The v7 and v8 groups have no no_snapshot path: their paths were followed through the phase-1 snapshot (receipts.remap_path), as the #3880 table's basis column shows.

Both of the issue's examples are rows: human_subject_research.irb_approval (v4 CM4AI, unmeasured) and creators[*].affiliations[*] (v6 VOICE, a candidate that rep3 lacks). A corpus test pins both.

Tests

• tests/test_replicate_structure.py: 10 new unit tests, 2 new section tests and 1 new corpus test. Round 1 added 4 of the unit tests and 1 section test. It also changed _deep_group, DEEP_RESOLVED, the first-level pin and the shape-disagreement test. 64 non-corpus and 4 corpus tests pass.

• All eight test files that load the changed code: 420 passed in the non-corpus lane and 30 in the corpus lane.

• test_committed_comparison_matches_current_records: passes on the regenerated note.

• Mutation checks: Round 0 ran 12 mutations in an archive copy, and all 12 were caught. Round 1 ran 12 more in a git-archive copy of the round-1 commit, restoring each file from a pristine copy. All 12 were caught, each by exactly the tests expected:

  1. _status credits any holder's path (The chain test cannot fail for the case it names: "the node's index in another replicate" when that replicate also holds the node #4435): both new other-holder tests.
  2. A lone object is wrapped as a one-entry list (The shape-disagreement test cannot fail: its list/object pair has identical content below it #4436): the shape-disagreement, nested-rows and no-receipt tests.
  3. A one-entry list of an object is unwrapped (The shape-disagreement test cannot fail: its list/object pair has identical content below it #4436): the same three tests.
  4. The walk descends wherever any replicate holds a list, with no wrapping (The shape-disagreement test cannot fail: its list/object pair has identical content below it #4436): the shape-disagreement test.
  5. A lone scalar is wrapped as a one-entry list (The shape-disagreement test cannot fail: its list/object pair has identical content below it #4436): the shape-disagreement test.
  6. The first level reads only objects (objects_only=True, The first-level pin test omits the one input where the shared _keyed switch changes the first-level reading #4437): the first-level pin.
  7. Every conforms_to* field is commentary (The new section's note says every conforms_to_* field is commentary, but conforms_to_standard and conforms_to rows are classified as ordinary fields #4434): the exempt-keys test.
  8. source_caveats is not skipped below the first level (The new section's note says every conforms_to_* field is commentary, but conforms_to_standard and conforms_to rows are classified as ordinary fields #4434): the exempt-keys, nested-rows and no-receipt tests.
  9. The legend goes back to the hand-typed wildcard (The new section's note says every conforms_to_* field is commentary, but conforms_to_standard and conforms_to rows are classified as ordinary fields #4434): the legend test.
  10. The legend lists COMMENTARY_KEYS unfiltered (The new section's note says every conforms_to_* field is commentary, but conforms_to_standard and conforms_to rows are classified as ordinary fields #4434): the legend test.
  11. Nested entries are keyed by exact value (New note text calls a keyed identity "that key's exact value", but _entry_key reads a resolver URL as its CURIE and strips whitespace #4439): the identity test.
  12. The legend goes back to "exact value" (New note text calls a keyed identity "that key's exact value", but _entry_key reads a resolver URL as its CURIE and strips whitespace #4439): the legend test.

  The round-0 mutations were not rerun. Round 1 removed no assertion, and its fixture changes only add content.

No canary or model call was made.

Review round 1

All six findings are fixed in this PR. Commit 0f31845 has the code, docstring and test changes, and 293cdbe regenerates the note. Against the round-0 note, only the new section's legend line changed. No number moved.

• The new section's note says every conforms_to_* field is commentary, but conforms_to_standard and conforms_to rows are classified as ordinary fields #4434 (nit), fixed. The legend called every conforms_to_* field commentary, but the walk classifies conforms_to and conforms_to_standard. The legend now builds its skipped and commentary key lists from EXCLUDED_SLOTS and COMMENTARY_KEYS. Decision 4 above is corrected. The same shorthand predated this PR in the script's module docstring and the COMMENTARY_KEYS comment, and is corrected there too. Two new tests: a nested conforms_to_standard is a candidate beside a commentary conforms_to_class; and the legend names the computed keys and no wildcard.
• The chain test cannot fail for the case it names: "the node's index in another replicate" when that replicate also holds the node #4435 (minor), fixed. New nested and first-level tests cover a node held at different indices, where each holder's receipt sits at the other holder's path. Such a receipt credits nothing. Both tests fail under the issue's mutant. On the corpus this is the v6 agentic VOICE affiliation at creators[6] in rep1 and creators[8] in rep2.
• The shape-disagreement test cannot fail: its list/object pair has identical content below it #4436 (nit), fixed. In the shape-disagreement test, the list/object pair now differs below the shared identity, and a list/string pair is added. _deep_group's m gets the same change. A walk that reads through the disagreement now fails a test, whether it wraps an object, unwraps a one-entry list, iterates an object as a list or wraps a scalar (mutations 2 to 5).
• The first-level pin test omits the one input where the shared _keyed switch changes the first-level reading #4437 (nit), fixed. _deep_group gains the string entry S1 in a class-ranged top-level list, and the first-level pin was retaken from origin/main's module. Both main and the branch give value=S1 as a candidate.
• The docstring says receipt paths are resolved "by identity"; on the agentic arm, which supplies most candidates, they are an index join #4438 (nit), fixed. The docstring now says a receipt path is followed by identity only where the run left a phase-1 snapshot. Where it left none, the path is read as written (an index join). See the paragraph under the table above.
• New note text calls a keyed identity "that key's exact value", but _entry_key reads a resolver URL as its CURIE and strips whitespace #4439 (nit), fixed. The legend and the docstring now say a keyed identity is the key's value as receipts._entry_key reads it: stripped, and a resolver URL of a declared prefix read as its CURIE. A new test pins it. https://doi.org/…, doi:…, a padded value and an upper-case host are all one entry, but a DOI suffix in another case is a different entry.

Follow-ups filed

• Entry identity: one entity keyed by id in one replicate and by name in another reads as two missing entries #4396: one entity keyed by id in one replicate and by name in another reads as two missing entries.
• Nested omission reading: decide whether a receipt on the holding object or entry credits a field or nested entry #4397: decide whether a receipt on the holding object or entry credits a field or nested entry (the 17 rows of decision 3).
• Omission reading for the items of nested lists of values needs an identity other than exact text #4398: the items of nested lists of values need an identity other than exact text (decision 2).

Round 1 filed nothing new. #4435's verification noted that CLAUDE.md's "Two CI lanes" section is out of date, since every PR runs the corpus lane. #3863 already tracks that.

🤖 Generated with Claude Code