Source: qa/db-review-Argon2.md
# QA Review: Database Integration & Cloud Model (`db-review-Argon2`)
- **Reviewer:** Argon2
- **Scope:** Fable2's integration of Astra4's working store (`neov2/db/README.md`, `neov2/db/CLOUD-MODEL.md`, `neov2/db/queries.sql`, `neov2/tools/{build_db.sh,load.py,store.py,q.py,export_ddb.py,review_status.py}`, `neov2/qa/review-status.tsv`).
- **Checkout & Worktree:** Clean checkout of `origin/master` in `/home/mma/repos/neochart-wt-argon2`.
```text
$ cd /home/mma/repos/neochart-wt-argon2 && git fetch origin master && git checkout -B argon2-dbreview origin/master && git status --short && git rev-parse HEAD
From https://github.com/lmctlhq/neochart
* branch master -> FETCH_HEAD
branch 'argon2-dbreview' set up to track 'origin/master'.
Switched to a new branch 'argon2-dbreview'
6bd95554f66af9b734970740923feef0322a4240
```
---
## Summary Verdict
**PASS** (with 4 concrete non-blocking observations documented below with exact command evidence):
1. **One-command build & idempotency (Checks 1 & 3):** `NEOV2_CORPUS=/home/mma/repos/neochart/neochartdocroot neov2/tools/build_db.sh` succeeds cleanly from scratch (298 CASE files, 176 proposals, 15 laws, 318 elements, 281 routes, 340 cases, 1,358 instances, 3,237 facts, 1,358 annotations, 271 proposal reviews, 124 case reviews) and a second consecutive run produces identical row counts across all 23 SQLite tables with zero duplicate rows in `review` (`271 == 271`) or `case_review` (`124 == 124`).
2. **Test suite (Check 2):** All 171 tests in `neov2/tools/tests` (`Ran 171 tests in 4.013s`, `OK (skipped=1)`) and all 8 tests in `neov2/variants/test_vtool.py` (`Ran 8 tests in 0.107s`, `OK`) pass.
3. **Quote fidelity (Check 4):** All 10 randomly sampled `fact` rows (`random.Random(42)` across 3,237 rows) match `source_text[start:end]` and `source_sha256` byte-for-byte.
4. **Named queries & hand SQL (Check 5):** All 13 named queries in `neov2/db/queries.sql` execute cleanly through `q.py`, and 3 independent hand SQL queries (`precision-by-source`, `route-coverage`, `review-coverage-by-author`) reproduce the exact numbers.
5. **DynamoDB JSONL export & size bounds (Check 6):** `export_ddb.py` writes 12,810 JSONL lines (12,809 base items + 1 manifest) and passes `roundtrip_counts()`. Every non-empty quote, opinion text, gloss, reason, and description field is externalized into a `*_ref` pointer (8,929 pointers total; 0 non-empty inline text fields; max item size is **2,927 UTF-8 bytes** vs the 380 KiB ceiling and 400 KiB DynamoDB limit).
- *Observation 1 (minor):* When a SQLite text column in `TEXT_COLUMNS` (`gloss`, `description`) contains an empty string `""` rather than `NULL`, `export_ddb.py` line 101 (`if not isinstance(value, str) or not value: continue`) leaves `"gloss":""` or `"description":""` inline on 1,258 items (0 bytes of text content, harmless, but could be stripped alongside `None`).
6. **Cloud model key analysis (Check 7):**
- `case -> instances` is answered in **1 Query** on base table `PK = CASE#<case_id>` (zero scans).
- `law -> elements -> routes -> cases` is answered **without a Scan** via 1 Query on `PK = LAW#<law_id>` (for law + elements + element-specific routes) + 1 Query on `PK = TAXONOMY#generic` + per-route Queries on `GSI4` (or per-element Queries on `GSI2`) + `BatchGetItem` on `PK = CASE#<case_id>, SK = CASE#<case_id>` (because `case.name`, `case.cite`, `case.court`, and `case.date` are not projected onto `instance` or `GSI6` `case_context` items).
- `element -> quotes` is answered **without a Scan** via `GSI1` / `PK = LAW#<law_id>` + `PK = ELEMENT#<element_id>` (`ANCHOR#`) + `GSI2` (`RULE#` and `STATUS#...#INSTANCE#`) + per-instance Queries on `PK = INSTANCE#<instance_id>` (`FACT#`) + `BatchGetItem` on `PK = CASE#<case_id>, SK = FACT#<fact_id>` + S3 range-reads.
- *Observation 2 (patterns that DO require a DynamoDB `Scan` under `export_ddb.py`):* See Section 7 for the 7 patterns/tables that lack a shared partition or GSI key in `export_ddb.py` (most notably: listing all 15 `law` rows without a hardcoded list; listing all 340 `case` rows including the 42 proposal-only cases absent from `GSI6`; finding unrouted instances where `route_id IS NULL`; grouping by `author` for `review-coverage-by-author`; reverse `fact -> instance` lookups; reverse `element -> constraint` lookups; and reading `proposal_batch` / `ingest_issue` / `mechanical_rejection`, where `export_ddb.py` line 92 puts the row hash in `PK = TABLE#<table>#<token>` so every row is its own partition).
7. **`review-status.tsv` vs QA reports (Check 8):** `python3 neov2/tools/review_status.py --check` reports `review-status.tsv is current`, and all 8 sampled rows across all 8 QA reports match the opened Markdown reports and git commit history.
---
## (1) One-Command Build & Table Counts
Command and exact output for first from-scratch build (`build_db.sh` + all 23 user tables in `sqlite_master`):
```text
$ cd /home/mma/repos/neochart-wt-argon2 && rm -f neov2/db/neov2.sqlite* && python3 neov2/tools/review_status.py --check && NEOV2_CORPUS=/home/mma/repos/neochart/neochartdocroot neov2/tools/build_db.sh && python3 -c '
import sqlite3
conn = sqlite3.connect("neov2/db/neov2.sqlite")
tables = [r[0] for r in conn.execute("SELECT name FROM sqlite_master WHERE type=\x27table\x27 AND name NOT LIKE \x27sqlite_%\x27 ORDER BY name")]
for t in tables:
n = conn.execute(f"SELECT count(*) FROM \"{t}\"").fetchone()[0]
print(f"{t}\t{n}")
'
review-status.tsv is current
TABLE ROWS
law 15
element 318
route 281
case 340
instance 1358
fact 3237
annotation 1358
review 271
case_review 124
proposal_batch 70
ingest_issue 0
mechanical_rejection 0
SOURCE STATUS CURRENT ANNOTATIONS
human-agent proposed 1182
llm-proposer accepted 75
llm-proposer proposed 20
llm-proposer rejected 6
matcher accepted 3
matcher rejected 72
Verified integrity/FKs and all imported quote slices; 298 CASE files, 176 proposals.
annotation 1358
case 340
case_context 298
case_review 124
constraint_element 74
element 318
element_anchor 387
fact 3237
ingest_issue 0
instance 1358
instance_fact 3237
law 15
law_claim 59
law_constraint 28
match_score 0
mechanical_rejection 0
proposal_batch 70
review 271
route 281
rule 465
schema_version 1
store_metadata 2
variant 886
```
---
## (2) Full Test Suite
### 2.1 Full `neov2/tools/tests` Discovery (171 Tests)
```text
$ cd /home/mma/repos/neochart-wt-argon2 && NEOV2_CORPUS=/home/mma/repos/neochart/neochartdocroot /home/mma/.cache/neov2/venv/bin/python -m unittest discover -s neov2/tools/tests -p "test_*.py" -v
test_absent_review_has_null_precision_and_recall (test_assist.AssistScoreTest.test_absent_review_has_null_precision_and_recall) ... ok
test_duplicate_judgment_and_variant_without_element_rejected (test_assist.AssistScoreTest.test_duplicate_judgment_and_variant_without_element_rejected) ... ok
...
test_export_keys_for_routes_reviews_and_route_instances (test_store_routes.StoreRoutes.test_export_keys_for_routes_reviews_and_route_instances) ... ok
test_named_queries_answer_route_and_review_questions (test_store_routes.StoreRoutes.test_named_queries_answer_route_and_review_questions) ... ok
test_routes_authors_and_reviews_are_in_the_store_and_rebuild_is_idempotent (test_store_routes.StoreRoutes.test_routes_authors_and_reviews_are_in_the_store_and_rebuild_is_idempotent) ... ok
----------------------------------------------------------------------
Ran 171 tests in 4.013s
OK (skipped=1)
```
### 2.2 Targeted Store, Query, Export, and Route-Taxonomy Suites
```text
$ cd /home/mma/repos/neochart-wt-argon2 && python3 -W ignore::ResourceWarning -m unittest discover -s neov2/tools/tests -p "test_store*.py" -v && python3 -W ignore::ResourceWarning -m unittest discover -s neov2/tools/tests -p "test_q.py" -v && python3 -W ignore::ResourceWarning -m unittest discover -s neov2/tools/tests -p "test_export_ddb.py" -v && python3 -W ignore::ResourceWarning -m unittest neov2/variants/test_vtool.py -v
test_bad_quote_does_not_replace_working_file (test_store.StoreTest.test_bad_quote_does_not_replace_working_file) ... ok
test_changed_proposal_requires_fresh_review (test_store.StoreTest.test_changed_proposal_requires_fresh_review) ... ok
test_concurrent_review_is_not_lost (test_store.StoreTest.test_concurrent_review_is_not_lost) ... ok
test_disagreement_and_later_review_not_overwritten (test_store.StoreTest.test_disagreement_and_later_review_not_overwritten) ... ok
test_duplicate_ids_and_invalid_role_fail (test_store.StoreTest.test_duplicate_ids_and_invalid_role_fail) ... ok
test_extension_table_and_view_survive_publish (test_store.StoreTest.test_extension_table_and_view_survive_publish) ... ok
test_future_round_and_abstention_are_idempotent (test_store.StoreTest.test_future_round_and_abstention_are_idempotent) ... ok
test_idempotent_and_manual_reviews_survive (test_store.StoreTest.test_idempotent_and_manual_reviews_survive) ... ok
test_mechanical_rejections_keep_hash_and_reason_not_invalid_quote (test_store.StoreTest.test_mechanical_rejections_keep_hash_and_reason_not_invalid_quote) ... ok
test_missing_review_label_is_not_presumed_rejection (test_store.StoreTest.test_missing_review_label_is_not_presumed_rejection) ... ok
test_pinned_complete_review_adapter_and_phase_history (test_store.StoreTest.test_pinned_complete_review_adapter_and_phase_history) ... ok
test_proposal_unknown_holding_and_variant_abstention (test_store.StoreTest.test_proposal_unknown_holding_and_variant_abstention) ... ok
test_round6_new_variant_is_proposed_and_partial_review_is_not_full_acceptance (test_store.StoreTest.test_round6_new_variant_is_proposed_and_partial_review_is_not_full_acceptance) ... ok
test_self_review_and_contradictory_accept_are_rejected (test_store.StoreTest.test_self_review_and_contradictory_accept_are_rejected) ... ok
test_upgrade_old_fact_constraint_preserves_rows (test_store.StoreTest.test_upgrade_old_fact_constraint_preserves_rows) ... ok
test_verdicts_are_transcribed_not_inferred (test_store_routes.ReviewStatusParser.test_verdicts_are_transcribed_not_inferred) ... ok
test_a_dropped_route_and_a_withdrawn_review_leave_the_store (test_store_routes.StoreRoutes.test_a_dropped_route_and_a_withdrawn_review_leave_the_store) ... ok
test_export_keys_for_routes_reviews_and_route_instances (test_store_routes.StoreRoutes.test_export_keys_for_routes_reviews_and_route_instances) ... ok
test_named_queries_answer_route_and_review_questions (test_store_routes.StoreRoutes.test_named_queries_answer_route_and_review_questions) ... ok
test_routes_authors_and_reviews_are_in_the_store_and_rebuild_is_idempotent (test_store_routes.StoreRoutes.test_routes_authors_and_reviews_are_in_the_store_and_rebuild_is_idempotent) ... ok
----------------------------------------------------------------------
Ran 20 tests in 0.326s
OK
test_cli_is_read_only_and_allowlisted (test_q.QueryTests.test_cli_is_read_only_and_allowlisted) ... ok
test_counts_and_evidence_are_distinct (test_q.QueryTests.test_counts_and_evidence_are_distinct) ... ok
test_disagreement_fields (test_q.QueryTests.test_disagreement_fields) ... ok
test_partial_reviewer_denominator_and_unknown_holding (test_q.QueryTests.test_partial_reviewer_denominator_and_unknown_holding) ... ok
test_precision_left_join_and_revision (test_q.QueryTests.test_precision_left_join_and_revision) ... ok
test_writable_uri_is_rejected_without_creating_database (test_q.QueryTests.test_writable_uri_is_rejected_without_creating_database) ... ok
----------------------------------------------------------------------
Ran 6 tests in 0.113s
OK
test_cli_failure_keeps_existing_output_and_key_bytes_are_enforced (test_export_ddb.ExportTests.test_cli_failure_keeps_existing_output_and_key_bytes_are_enforced) ... ok
test_missing_rows_and_duplicate_items_fail_roundtrip (test_export_ddb.ExportTests.test_missing_rows_and_duplicate_items_fail_roundtrip) ... ok
test_real_database_if_present (test_export_ddb.ExportTests.test_real_database_if_present) ... ok
test_roundtrip_counts (test_export_ddb.ExportTests.test_roundtrip_counts) ... ok
test_unicode_quotes_and_composite_keys (test_export_ddb.ExportTests.test_unicode_quotes_and_composite_keys) ... ok
----------------------------------------------------------------------
Ran 5 tests in 0.417s
OK
test_every_case_file_is_on_routes_and_every_route_is_on_its_menu (neov2.variants.test_vtool.Crosswalk.test_every_case_file_is_on_routes_and_every_route_is_on_its_menu) ... ok
test_every_frozen_label_resolves_to_exactly_one_route (neov2.variants.test_vtool.Crosswalk.test_every_frozen_label_resolves_to_exactly_one_route) ... ok
test_generic_routes_are_global_and_basis_is_not_a_route (neov2.variants.test_vtool.Crosswalk.test_generic_routes_are_global_and_basis_is_not_a_route) ... ok
test_kappa_arithmetic (neov2.variants.test_vtool.Crosswalk.test_kappa_arithmetic) ... ok
test_law_files_reference_routes_and_declare_no_variants (neov2.variants.test_vtool.Crosswalk.test_law_files_reference_routes_and_declare_no_variants) ... ok
test_proposer_menu_is_definitions_only_with_an_escape (neov2.variants.test_vtool.Crosswalk.test_proposer_menu_is_definitions_only_with_an_escape) ... ok
test_route_names_never_encode_outcome (neov2.variants.test_vtool.Crosswalk.test_route_names_never_encode_outcome) ... ok
test_single_entity_is_modelled_once (neov2.variants.test_vtool.Crosswalk.test_single_entity_is_modelled_once) ... ok
----------------------------------------------------------------------
Ran 8 tests in 0.107s
OK
```
---
## (3) Second Build Run (Idempotency & Review Uniqueness Check)
Running `build_db.sh` a second time over the existing `neov2/db/neov2.sqlite` produces the exact same row counts on every single table and zero duplicated rows in `review` or `case_review`:
```text
$ cd /home/mma/repos/neochart-wt-argon2 && NEOV2_CORPUS=/home/mma/repos/neochart/neochartdocroot neov2/tools/build_db.sh && python3 -c '
import sqlite3
conn = sqlite3.connect("neov2/db/neov2.sqlite")
tables = [r[0] for r in conn.execute("SELECT name FROM sqlite_master WHERE type=\x27table\x27 AND name NOT LIKE \x27sqlite_%\x27 ORDER BY name")]
for t in tables:
n = conn.execute(f"SELECT count(*) FROM \"{t}\"").fetchone()[0]
print(f"{t}\t{n}")
rev_total = conn.execute("SELECT count(*), count(DISTINCT id) FROM review").fetchone()
crev_total = conn.execute("SELECT count(*), count(DISTINCT case_id || \x27|\x27 || law_id || \x27|\x27 || seq) FROM case_review").fetchone()
print("review_total_vs_distinct_id:", rev_total)
print("case_review_total_vs_distinct_pk:", crev_total)
'
TABLE ROWS
law 15
element 318
route 281
case 340
instance 1358
fact 3237
annotation 1358
review 271
case_review 124
proposal_batch 70
ingest_issue 0
mechanical_rejection 0
SOURCE STATUS CURRENT ANNOTATIONS
human-agent proposed 1182
llm-proposer accepted 75
llm-proposer proposed 20
llm-proposer rejected 6
matcher accepted 3
matcher rejected 72
Verified integrity/FKs and all imported quote slices; 298 CASE files, 176 proposals.
annotation 1358
case 340
case_context 298
case_review 124
constraint_element 74
element 318
element_anchor 387
fact 3237
ingest_issue 0
instance 1358
instance_fact 3237
law 15
law_claim 59
law_constraint 28
match_score 0
mechanical_rejection 0
proposal_batch 70
review 271
route 281
rule 465
schema_version 1
store_metadata 2
variant 886
review_total_vs_distinct_id: (271, 271)
case_review_total_vs_distinct_pk: (124, 124)
```
---
## (4) Spot-Check of 10 Random `fact` Rows Against Corpus `text[start:end]`
Command and output verifying 10 random `fact` rows (`random.Random(42)` across all 3,237 `fact` rows) against the canonical IR corpus under `/home/mma/repos/neochart/neochartdocroot`:
```text
$ cd /home/mma/repos/neochart-wt-argon2 && python3 -c '
import hashlib, json, pathlib, random, sqlite3, sys
sys.path.insert(0, "neov2/tools")
import load
corpus = pathlib.Path("/home/mma/repos/neochart/neochartdocroot")
conn = sqlite3.connect("neov2/db/neov2.sqlite")
rows = conn.execute("SELECT id, case_id, kind, start, \"end\", source, source_sha256, quote FROM fact ORDER BY id").fetchall()
rng = random.Random(42)
sample = rng.sample(rows, 10)
print(f"Total fact rows: {len(rows)}; sampled 10 with random.Random(42):")
for idx, (fid, cid, kind, start, end, source, sha256_db, quote) in enumerate(sample, 1):
text = load.source_text(source, corpus)
sha256_actual = hashlib.sha256(text.encode("utf-8")).hexdigest()
sliced = text[start:end]
match = (sliced == quote) and (sha256_actual == sha256_db)
preview = repr(quote[:70] + ("..." if len(quote) > 70 else ""))
print(f"{idx}. id={fid} case_id={cid} kind={kind} span={start}..{end} len={len(quote)} source={source}")
print(f" sha256_match={sha256_actual == sha256_db} ({sha256_actual[:16]}...) slice_eq_quote={sliced == quote} quote={preview}")
assert match, f"Mismatch on {fid}"
print("ALL 10 RANDOM FACT ROWS VERIFIED BYTE-FOR-BYTE AGAINST CORPUS IR TEXT[start:end].")
'
Total fact rows: 3237; sampled 10 with random.Random(42):
1. id=fact:ann:cfa21ee78b9b891e0f8f4d5fd2cdc0e0896be3ce68e2bce8570039f5399aaf6c:5 case_id=/f3d/927/0108-01 kind=held span=29003..29143 len=140 source=docroot/ir/caselaw/f3d_927.jsonl#/f3d/927/0108-01
sha256_match=True (98fe49dd88fa8279...) slice_eq_quote=True quote='In sum, each of the injuries alleged in the SAC, except for the Sham M...'
2. id=fact:ann:29cd08049e6e6a137902dfc2c82157b1109df550768879ed066f1fdbae317fe2:0 case_id=/f3d/490/0575-01 kind=fact span=1336..1438 len=102 source=docroot/ir/caselaw/f3d_490.jsonl#/f3d/490/0575-01
sha256_match=True (d3f7952bc44164fe...) slice_eq_quote=True quote='The two street crews are components of the "Chicago Outfit," the linea...'
3. id=fact:ann:0b329858983a400ae5f9e4f39c76927deced9ad6a1f8725dc7b94b076c78ddfe:0 case_id=/us/572/0118-01 kind=held span=37567..37691 len=124 source=docroot/ir/caselaw/us_572.jsonl#/us/572/0118-01
sha256_match=True (925bbd2e7ac80af0...) slice_eq_quote=True quote='We assume without deciding that the communications alleged by Static C...'
4. id=fact:ann:edb2e8f86b577f6c97a31a9d59af654a10a754f9aca6c1d8a36688f26d1a6c53:0 case_id=/f3d/935/0527-01 kind=fact span=226..393 len=167 source=docroot/ir/caselaw/f3d_935.jsonl#/f3d/935/0527-01
sha256_match=True (abbba66e24a03cb0...) slice_eq_quote=True quote='The district court applied a two-level sentencing enhancement because ...'
5. id=fact:ann:616a78d1eaa73b05a118e93d827b2d751ae41db1c3c96f753b325ea69e421980:3 case_id=/f-supp-3d/351/0698-01 kind=fact span=18457..18590 len=133 source=docroot/ir/caselaw/f_supp_3d_351.jsonl#/f-supp-3d/351/0698-01
sha256_match=True (3fc0ce3b5b594533...) slice_eq_quote=True quote='The Dealers attempted to placate trueEX with minor business opportunit...'
6. id=fact:ann:585a29884162fe09c166fba67346870fb77489ceacaa751b135a8ee7f710f2f4:0 case_id=/f2d/628/1104-01 kind=fact span=15735..16070 len=335 source=docroot/ir/caselaw/f2d_628.jsonl#/f2d/628/1104-01
sha256_match=True (d2c865685b00f7d4...) slice_eq_quote=True quote='. The portion of the complaint which names Polk County reads as follow...'
7. id=fact:ann:50ee84f7d55044973b28e24084fcfe405d6d81463015d2561d76a1b720dbb458:2 case_id=/f-supp-3d/371/0407-01 kind=held span=22171..22321 len=150 source=docroot/ir/caselaw/f_supp_3d_371.jsonl#/f-supp-3d/371/0407-01
sha256_match=True (44719372de0b1641...) slice_eq_quote=True quote='The Court concludes that § 1981 does not extend to such conduct and is...'
8. id=fact:ann:357d47f00ed221e7bbd35707ea4819116ed67b32ad8d6ffa53f870ca8e14e8e0:2 case_id=/f-supp-3d/383/0343-01 kind=fact span=14488..14692 len=204 source=docroot/ir/caselaw/f_supp_3d_383.jsonl#/f-supp-3d/383/0343-01
sha256_match=True (8041a5a9c6e6a7d7...) slice_eq_quote=True quote='Furthermore, its statement that Durafacing is "a step above the rest" ...'
9. id=fact:ann:eb58895d12163817904767ded1976048c12d86219ac7257ce9df3550450c55b3:0 case_id=/f-supp-2d/367/1175-01 kind=held span=50200..50452 len=252 source=docroot/ir/caselaw/f_supp_2d_367.jsonl#/f-supp-2d/367/1175-01
sha256_match=True (a691ce28535a7c30...) slice_eq_quote=True quote='Mr. Dye failed to make any showing that the purported need for a polic...'
10. id=fact:ann:23fd5be6572b53245384d61d81314d1486489e6ec200264a812f6703420c7cc2:6 case_id=/f2d/829/0286-01 kind=held span=18164..18245 len=81 source=docroot/ir/caselaw/f2d_829.jsonl#/f2d/829/0286-01
sha256_match=True (86b85ab2b6819f0e...) slice_eq_quote=True quote='It is apparent in the instant case that the complaint does not satisfy...'
ALL 10 RANDOM FACT ROWS VERIFIED BYTE-FOR-BYTE AGAINST CORPUS IR TEXT[start:end].
```
---
## (5) Execution of All 13 Named Queries & Hand-SQL Sanity Checks
### 5.1 All 13 Named Queries via `q.py`
```text
$ cd /home/mma/repos/neochart-wt-argon2 && python3 neov2/tools/q.py --list && python3 -c '
import json, sqlite3, subprocess
db = "neov2/db/neov2.sqlite"
names = json.loads(subprocess.check_output(["python3", "neov2/tools/q.py", "--list"], text=True))
print(f"Named queries ({len(names)}): {names}")
for name in names:
cmd = ["python3", "neov2/tools/q.py", "--db", db, name]
if name == "review-disagreement":
out_final = json.loads(subprocess.check_output(cmd + ["--stage", "final"], text=True))
out_blind = json.loads(subprocess.check_output(cmd + ["--stage", "blind"], text=True))
print(f"QUERY {name} (stage=final): rows={len(out_final)} first={json.dumps(out_final[0]) if out_final else None}")
print(f"QUERY {name} (stage=blind): rows={len(out_blind)} first={json.dumps(out_blind[0]) if out_blind else None}")
else:
out = json.loads(subprocess.check_output(cmd, text=True))
print(f"QUERY {name}: rows={len(out)} first={json.dumps(out[0]) if out else None}")
'
["case-instances", "case-review-status", "element-quotes", "law-elements-variants", "precision-by-source", "review-coverage-by-author", "review-coverage-by-law", "review-disagreement", "route-catalogue", "route-coverage", "route-precision-by-review", "route-review-status", "route-support"]
Named queries (13): ['case-instances', 'case-review-status', 'element-quotes', 'law-elements-variants', 'precision-by-source', 'review-coverage-by-author', 'review-coverage-by-law', 'review-disagreement', 'route-catalogue', 'route-coverage', 'route-precision-by-review', 'route-review-status', 'route-support']
QUERY case-instances: rows=1358 first={"case_id": "/cl/10811625", "path": "/cl/10811625", "date": "2026-03-20", "court": "Supreme Court of the United States", "url": "catalog/cases/clus/volume_cl/10811625/index.html", "instance_id": "instance:ann:00e0dcad615c52b74a31d1f6e75f2ba72bcaf38099e5786a8bbc045e488566d9", "annotation_id": "ann:00e0dcad615c52b74a31d1f6e75f2ba72bcaf38099e5786a8bbc045e488566d9", "law_id": "42usc1983", "element_id": "42usc1983:person", "variant_id": "42usc1983:person:municipality/city-enforcing-ordinance", "holding": "satisfied", "holding_recorded": 1, "citation_role": "applied", "ruling_scope": "merits", "role_recorded": 1, "scope_recorded": 1, "proposed_role": null, "proposed_scope": null, "status": "proposed", "fact_id": "fact:ann:00e0dcad615c52b74a31d1f6e75f2ba72bcaf38099e5786a8bbc045e488566d9:0", "claim": "", "basis": "conceded", "opinion": null, "annotation_source": "human-agent", "author_alias": "Flash1", "model": "gemini-3.8-flash-high", "artifact_ref": "neov2/cases/42usc1983/cl-10811625-olivier-v-city-of-brandon.case"}
QUERY case-review-status: rows=298 first={"case_id": "/f-supp-2d/385/0740-01", "law_id": "15usc1", "name": "North Jackson Pharmacy, Inc. v. Caremark Rx, Inc.", "cite": "385 F. Supp. 2d 740 (2005)", "author": "Fable", "review_state": "reviewed-pass", "reviewer": "QA1", "verdict": "PASS", "qa_file": "neov2/qa/cases-v1-QA1.md", "content_changed_after_review": "no", "reviews": 2}
QUERY element-quotes: rows=4016 first={"element_id": "15usc1:agreement", "law_id": "15usc1", "evidence_kind": "fact", "evidence_id": "fact:ann:242280353758dc396fed22aa2f2be113fbc4e509819512856eec396e65ad8a59:1", "quote": "While the Plaintiffs sufficiently alleges that each of the Platforms acted to suppress or censor conservative content, they fail to show how the Platforms' purportedly parallel actions stem from a conspiracy. The Amended Complaint asserts that the Platforms are \"willing to lose revenue from conservative organizations and individuals like Freedom Watch.\" Am. Compl. 17. This willingness comes from a desire to \"further their leftist agenda.\" Id.", "start": 13085, "end": 13531, "source": "docroot/ir/caselaw/f_supp_3d_368.jsonl#/f-supp-3d/368/0030-01", "source_sha256": "bd4d3bb539dc2e85ba38dd93f92129e92f25fa179a14ab29a886dbb353cd8c8c", "instance_id": "instance:ann:242280353758dc396fed22aa2f2be113fbc4e509819512856eec396e65ad8a59", "case_id": "/f-supp-3d/368/0030-01", "annotation_id": "ann:242280353758dc396fed22aa2f2be113fbc4e509819512856eec396e65ad8a59", "annotation_source": "human-agent", "annotation_status": "proposed", "author_alias": "Flash1", "model": "gemini-3.8-flash-high", "protocol_hash": "89ef02cb040b8f8fc4c6142cd8ccb3999954f89201f1e54e9d350cabce3d53e5", "round_id": null, "artifact_ref": "neov2/cases/15usc1/f-supp-3d-368-30-freedom-watch-v-google.case", "content_hash": "2ebacd45430007cda77120da323dcbab4ae31ad0af5ace1caf6cd7993f63231b"}
QUERY law-elements-variants: rows=1204 first={"law_id": "15usc1", "citation": "15 U.S.C. \u00a7 1", "element_id": "15usc1:agreement", "parent_id": null, "element_name": "Concerted action (\"contract, combination ... or conspiracy\") between separate economic decisionmakers", "element_kind": "and", "variant_id": null, "variant_label": null, "variant_status": null, "variant_annotation_id": null, "variant_external_id": null, "element_instance_count": 32, "variant_instance_count": 5, "element_fact_count": 123, "variant_fact_count": 3}
QUERY precision-by-source: rows=5 first={"source": "human-agent", "unit": "case-instance", "round_id": null, "reviewer_alias": null, "accepted_count": 0, "reviewed_count": 0, "precision": null, "unreviewed_ratio": 1.0, "total_count": 1182, "element_reviewed_count": 0, "element_accepted_count": 0, "element_precision": null, "variant_reviewed_count": 0, "variant_accepted_count": 0, "variant_precision": null}
QUERY review-coverage-by-author: rows=6 first={"author": "Astra2", "case_files": 30, "reviewed_pass": 8, "reviewed_fix": 0, "reviewed_then_changed": 1, "unreviewed": 21}
QUERY review-coverage-by-law: rows=15 first={"law_id": "15usc1", "case_files": 24, "reviewed_pass": 3, "reviewed_fix": 0, "reviewed_then_changed": 9, "unreviewed": 12}
QUERY review-disagreement (stage=final): rows=1 first={"annotation_id": "ann:9f53da8f39262e3686de7372e5b89fd63795603c991887d3c292777a0c1f16d6", "external_id": "r5-006-05f3d17878ee", "source": "llm-proposer", "unit": "proposal", "round_id": "r5", "reviewer_a": "QA1", "verdict_a": "reject", "reviewer_b": "QA2", "verdict_b": "fix", "raw_disagreement": 1, "strict_accept_disagreement": 0}
QUERY review-disagreement (stage=blind): rows=1 first={"annotation_id": "ann:9f53da8f39262e3686de7372e5b89fd63795603c991887d3c292777a0c1f16d6", "external_id": "r5-006-05f3d17878ee", "source": "llm-proposer", "unit": "proposal", "round_id": "r5", "reviewer_a": "QA1", "verdict_a": "reject", "reviewer_b": "QA2", "verdict_b": "accept", "raw_disagreement": 1, "strict_accept_disagreement": 1}
QUERY route-catalogue: rows=437 first={"law_id": "15usc1", "element_id": "15usc1:agreement", "element_name": "Concerted action (\"contract, combination ... or conspiracy\") between separate economic decisionmakers", "route": "inference-from-conduct", "generic": 0, "route_status": "provisional", "law_referenced": 0, "definition": "Whether an agreement among competitors can be inferred from parallel or collective conduct, with or without plus factors (Twombly, Matsushita).", "blocks": 6, "instances": 6, "cases": 5, "satisfied": 1, "not_satisfied": 5, "patterns": 6}
QUERY route-coverage: rows=15 first={"law_id": "15usc1", "blocks": 105, "decided": 51, "instances": 45, "specific": 45, "generic": 6, "proposed": 0, "unrouted": 0, "coverage_pct": 100.0, "specific_pct": 88.2}
QUERY route-precision-by-review: rows=1 first={"source": "llm-proposer", "round_id": "r6", "reviewer_alias": "QA1", "reviewed": 48, "variant_accepted": 39, "variant_precision_pct": 81.3}
QUERY route-review-status: rows=2 first={"status": "accepted", "routes": 5, "blocks": 249, "instances": 152}
QUERY route-support: rows=5 first={"support": "0 cases", "routes": 35, "law_referenced": 34}
```
### 5.2 Sanity-Check of 3 Named Queries Against Independent Hand SQL
Checked `precision-by-source`, `route-coverage`, and `review-coverage-by-author` against independent SQL written directly against the base tables:
```text
=== precision-by-source via q.py ===
{'source': 'human-agent', 'unit': 'case-instance', 'round_id': None, 'reviewer_alias': None, 'accepted_count': 0, 'reviewed_count': 0, 'precision': None, 'unreviewed_ratio': 1.0, 'total_count': 1182, 'element_reviewed_count': 0, 'element_accepted_count': 0, 'element_precision': None, 'variant_reviewed_count': 0, 'variant_accepted_count': 0, 'variant_precision': None}
{'source': 'llm-proposer', 'unit': 'proposal', 'round_id': 'r5', 'reviewer_alias': 'QA1', 'accepted_count': 36, 'reviewed_count': 37, 'precision': 0.972972972972973, 'unreviewed_ratio': 0.0, 'total_count': 37, 'element_reviewed_count': 37, 'element_accepted_count': 36, 'element_precision': 0.972972972972973, 'variant_reviewed_count': 0, 'variant_accepted_count': 0, 'variant_precision': None}
{'source': 'llm-proposer', 'unit': 'proposal', 'round_id': 'r5', 'reviewer_alias': 'QA2', 'accepted_count': 36, 'reviewed_count': 37, 'precision': 0.972972972972973, 'unreviewed_ratio': 0.0, 'total_count': 37, 'element_reviewed_count': 37, 'element_accepted_count': 36, 'element_precision': 0.972972972972973, 'variant_reviewed_count': 0, 'variant_accepted_count': 0, 'variant_precision': None}
{'source': 'llm-proposer', 'unit': 'proposal', 'round_id': 'r6', 'reviewer_alias': 'QA1', 'accepted_count': 39, 'reviewed_count': 48, 'precision': 0.8125, 'unreviewed_ratio': 0.25, 'total_count': 64, 'element_reviewed_count': 48, 'element_accepted_count': 43, 'element_precision': 0.8958333333333334, 'variant_reviewed_count': 48, 'variant_accepted_count': 39, 'variant_precision': 0.8125}
{'source': 'matcher', 'unit': 'proposal', 'round_id': 'r4', 'reviewer_alias': 'QA1', 'accepted_count': 3, 'reviewed_count': 75, 'precision': 0.04, 'unreviewed_ratio': 0.0, 'total_count': 75, 'element_reviewed_count': 75, 'element_accepted_count': 3, 'element_precision': 0.04, 'variant_reviewed_count': 0, 'variant_accepted_count': 0, 'variant_precision': None}
=== precision-by-source via hand SQL ===
('human-agent', 'case-instance', None, None, 0, 0, 1182)
('llm-proposer', 'proposal', 'r5', 'QA1', 36, 37, 37)
('llm-proposer', 'proposal', 'r5', 'QA2', 36, 37, 37)
('llm-proposer', 'proposal', 'r6', None, 0, 0, 16)
('llm-proposer', 'proposal', 'r6', 'QA1', 39, 48, 48)
('matcher', 'proposal', 'r4', 'QA1', 3, 75, 75)
=== route-coverage via q.py (first 3) ===
{'law_id': '15usc1', 'blocks': 105, 'decided': 51, 'instances': 45, 'specific': 45, 'generic': 6, 'proposed': 0, 'unrouted': 0, 'coverage_pct': 100.0, 'specific_pct': 88.2}
{'law_id': '15usc1125', 'blocks': 40, 'decided': 33, 'instances': 26, 'specific': 23, 'generic': 10, 'proposed': 0, 'unrouted': 0, 'coverage_pct': 100.0, 'specific_pct': 69.7}
{'law_id': '15usc78j', 'blocks': 34, 'decided': 27, 'instances': 24, 'specific': 26, 'generic': 1, 'proposed': 0, 'unrouted': 0, 'coverage_pct': 100.0, 'specific_pct': 96.3}
=== route-coverage via hand SQL (substr(route_id,1,1)) ===
('15usc1', 105, 51, 45, 45, 6, 0)
('15usc1125', 40, 33, 26, 23, 10, 0)
('15usc78j', 34, 27, 24, 26, 1, 0)
=== review-coverage-by-author via q.py ===
{'author': 'Astra2', 'case_files': 30, 'reviewed_pass': 8, 'reviewed_fix': 0, 'reviewed_then_changed': 1, 'unreviewed': 21}
{'author': 'Astra4', 'case_files': 30, 'reviewed_pass': 8, 'reviewed_fix': 0, 'reviewed_then_changed': 1, 'unreviewed': 21}
{'author': 'Fable', 'case_files': 105, 'reviewed_pass': 10, 'reviewed_fix': 0, 'reviewed_then_changed': 42, 'unreviewed': 53}
{'author': 'Flash1', 'case_files': 34, 'reviewed_pass': 4, 'reviewed_fix': 0, 'reviewed_then_changed': 10, 'unreviewed': 20}
{'author': 'Flash2', 'case_files': 50, 'reviewed_pass': 1, 'reviewed_fix': 15, 'reviewed_then_changed': 0, 'unreviewed': 34}
{'author': 'Flash3', 'case_files': 49, 'reviewed_pass': 0, 'reviewed_fix': 0, 'reviewed_then_changed': 0, 'unreviewed': 49}
=== review-coverage-by-author via hand SQL ===
('Astra2', 30, 8, 0, 1, 21)
('Astra4', 30, 8, 0, 1, 21)
('Fable', 105, 10, 0, 42, 53)
('Flash1', 34, 4, 0, 10, 20)
('Flash2', 50, 1, 15, 0, 34)
('Flash3', 49, 0, 0, 0, 49)
```
---
## (6) DynamoDB JSONL Export, Round-Trip, Externalized Text & 400 KB Limit Check
Ran `export_ddb.py` and `roundtrip_counts()`, then audited every item and attribute in the resulting JSONL:
```text
$ python3 neov2/tools/export_ddb.py neov2/db/neov2.sqlite /tmp/argon2-neov2-items.jsonl && python3 -c '
import json, sys
sys.path.insert(0, "neov2/tools")
import export_ddb
path = "/tmp/argon2-neov2-items.jsonl"
with open(path, encoding="utf-8") as f:
lines = f.readlines()
counts = export_ddb.roundtrip_counts(lines)
print("roundtrip_counts passed! Table counts:", json.dumps(counts, sort_keys=True))
max_bytes = 0
max_item_key = None
ref_count = 0
for raw in lines:
b = len(raw.encode("utf-8"))
obj = json.loads(raw)
if b > max_bytes:
max_bytes = b
max_item_key = (obj["PK"], obj["SK"], obj["entity"])
for k in obj:
if k.endswith("_ref"):
ref_count += 1
print(f"Total JSONL lines: {len(lines)} (base items: {len(lines)-1}, manifest: 1)")
print(f"Max item UTF-8 bytes: {max_bytes} (< 400KB={max_bytes < 400*1024}, < 380KB={max_bytes < 380*1024}) on {max_item_key}")
print(f"Externalized *_ref pointers: {ref_count}")
'
roundtrip_counts passed! Table counts: {"annotation": 1358, "case": 340, "case_context": 298, "case_review": 124, "constraint_element": 74, "element": 318, "element_anchor": 387, "fact": 3237, "ingest_issue": 0, "instance": 1358, "instance_fact": 3237, "law": 15, "law_claim": 59, "law_constraint": 28, "match_score": 0, "mechanical_rejection": 0, "proposal_batch": 70, "review": 271, "route": 281, "rule": 465, "schema_version": 1, "store_metadata": 2, "variant": 886}
Total JSONL lines: 12810 (base items: 12809, manifest: 1)
Max item UTF-8 bytes: 2927 (< 400KB=True, < 380KB=True) on ('CASE#/us/569/0184-01', 'INSTANCE#instance:ann:b82e1595ac51dbfe99b4f501d5e422ab159de4f3c6d42ad16fabaaf58d31e7ca', 'instance')
Externalized *_ref pointers: 8929
```
Checking inline text attributes and maximum inline string lengths across all 12,810 JSONL items:
```text
$ cd /home/mma/repos/neochart-wt-argon2 && python3 -c '
import collections, sqlite3, sys
sys.path.insert(0, "neov2/tools")
import export_ddb
conn = sqlite3.connect("neov2/db/neov2.sqlite")
non_empty = []
empty_counts = collections.Counter()
max_str_by_col = collections.defaultdict(int)
for item in export_ddb.iter_items(conn):
for k, v in item.items():
if isinstance(v, str):
if len(v.encode("utf-8")) > max_str_by_col[(item.get("origin_table"), k)]:
max_str_by_col[(item.get("origin_table"), k)] = len(v.encode("utf-8"))
if k in {"quote", "verbatim_quote", "opinion_text", "full_text", "text", "xrefs", "gloss", "reason", "description", "content", "body"}:
if v == "":
empty_counts[(item.get("origin_table"), k)] += 1
else:
non_empty.append((item.get("origin_table"), k, len(str(v))))
print("Non-empty inline quote/opinion/gloss/reason/description fields:", len(non_empty))
print("Empty string (\"\") fields left in items:", dict(empty_counts))
print("Top 10 longest inline string attributes (table, col, max_utf8_bytes):")
for (tbl, col), b in sorted(max_str_by_col.items(), key=lambda x: -x[1])[:10]:
print(f" {tbl}.{col}: {b} bytes")
'
Non-empty inline quote/opinion/gloss/reason/description fields: 0
Empty string ("") fields left in items: {('element', 'gloss'): 38, ('instance', 'gloss'): 383, ('law_constraint', 'gloss'): 10, ('rule', 'gloss'): 5, ('variant', 'description'): 822}
Top 10 longest inline string attributes (table, col, max_utf8_bytes):
instance.subject: 520 bytes
case_context.posture: 461 bytes
proposal_batch.abstention_reason: 318 bytes
law_constraint.summary: 246 bytes
annotation.model: 242 bytes
route.definition: 242 bytes
variant.SK: 225 bytes
variant.origin_pk: 221 bytes
instance.variant_id: 217 bytes
variant.id: 217 bytes
```
---
## (7) Review of `CLOUD-MODEL.md` & Access Patterns (`Scan` vs `Query`/`BatchGetItem`)
### 7.1 Actual Emitted Key & GSI Structure (`export_ddb.py`)
```text
$ cd /home/mma/repos/neochart-wt-argon2 && python3 -c '
import collections, sqlite3, sys
sys.path.insert(0, "neov2/tools")
import export_ddb
conn = sqlite3.connect("neov2/db/neov2.sqlite")
by_table = collections.defaultdict(list)
gsi_by_table = collections.defaultdict(set)
for item in export_ddb.iter_items(conn):
t = item.get("origin_table")
if len(by_table[t]) < 2:
by_table[t].append((item["PK"], item["SK"]))
for k in item:
if k.startswith("GSI") and k.endswith("PK"):
gsi_by_table[t].add(k[:4])
for t in sorted(by_table, key=lambda x: str(x)):
print(f"Table {t!r:22} sample PK/SK={by_table[t][0]} GSIs={sorted(gsi_by_table[t])}")
'
Table None sample PK/SK=('EXPORT', 'MANIFEST') GSIs=[]
Table 'annotation' sample PK/SK=('ANNOTATION#ann:c17a57d830f51aefa87facd7a8fba195323d20d447d95fddf852a05278af21ec', 'ROW#annotation') GSIs=['GSI5']
Table 'case' sample PK/SK=('CASE#/f-supp-2d/385/0740-01', 'CASE#/f-supp-2d/385/0740-01') GSIs=[]
Table 'case_context' sample PK/SK=('CASE#/f-supp-2d/385/0740-01', 'CASE_CONTEXT#15usc1:/f-supp-2d/385/0740-01') GSIs=['GSI6']
Table 'case_review' sample PK/SK=('CASE#/f-supp-2d/385/0740-01', 'CASE_REVIEW#15usc1#000001#QA1') GSIs=['GSI6']
Table 'constraint_element' sample PK/SK=('CONSTRAINT#15usc1:plurality-distinct-from-reasonableness', 'ELEMENT#15usc1:agreement') GSIs=[]
Table 'element' sample PK/SK=('LAW#15usc1', 'ELEMENT#15usc1:agreement') GSIs=['GSI1']
Table 'element_anchor' sample PK/SK=('ELEMENT#15usc1:agreement', 'ANCHOR#15usc1:agreement:anchor:0') GSIs=[]
Table 'fact' sample PK/SK=('CASE#/f-supp-2d/385/0740-01', 'FACT#fact:ann:c17a57d830f51aefa87facd7a8fba195323d20d447d95fddf852a05278af21ec:0') GSIs=[]
Table 'instance' sample PK/SK=('CASE#/f-supp-2d/385/0740-01', 'INSTANCE#instance:ann:c17a57d830f51aefa87facd7a8fba195323d20d447d95fddf852a05278af21ec') GSIs=['GSI2', 'GSI4']
Table 'instance_fact' sample PK/SK=('INSTANCE#instance:ann:c17a57d830f51aefa87facd7a8fba195323d20d447d95fddf852a05278af21ec', 'FACT#fact:ann:c17a57d830f51aefa87facd7a8fba195323d20d447d95fddf852a05278af21ec:0') GSIs=[]
Table 'law' sample PK/SK=('LAW#15usc1', 'ROW#law') GSIs=[]
Table 'law_claim' sample PK/SK=('LAW#15usc1', 'LAW_CLAIM#15usc1:civil') GSIs=[]
Table 'law_constraint' sample PK/SK=('LAW#15usc1', 'LAW_CONSTRAINT#15usc1:plurality-distinct-from-reasonableness') GSIs=[]
Table 'proposal_batch' sample PK/SK=('TABLE#proposal_batch#edbb1655509d7c0e6c8b820ae08a2a05', 'ROW#proposal_batch#edbb1655509d7c0e6c8b820ae08a2a05') GSIs=[]
Table 'review' sample PK/SK=('ANNOTATION#ann:bfd2ba5a0a52cad688931389518424598cb554fb9d94274d8fde3cd319eecdc3', 'REVIEW#review:ac2cc5e47a86a85fe2a7da577f408e141401e79e7f43685fa6f1ce48f41ee667') GSIs=['GSI3']
Table 'route' sample PK/SK=('TAXONOMY#generic', 'ROUTE#_whole') GSIs=[]
Table 'rule' sample PK/SK=('LAW#15usc1', 'RULE#15usc1:agreement:rule:0') GSIs=['GSI2']
Table 'schema_version' sample PK/SK=('TABLE#schema_version#06d033ece6645de592db973644cf7357', 'ROW#schema_version#06d033ece6645de592db973644cf7357') GSIs=[]
Table 'store_metadata' sample PK/SK=('TABLE#store_metadata#743d8685df479dc2c2de48d8bbe813bb', 'ROW#store_metadata#743d8685df479dc2c2de48d8bbe813bb') GSIs=[]
Table 'variant' sample PK/SK=('ELEMENT#15usc1:restraint.per-se', 'VARIANT#15usc1:restraint.per-se:cooperative-or-novel-arrangement/ancillary-restraint-cooperative-buying-through-common-agent') GSIs=[]
```
### 7.2 Are the Three Core Presentation Patterns Answerable Without Scans?
1. **`law -> elements -> routes -> cases`**: **YES (no Scan required), via multi-step `Query` + `BatchGetItem`**:
- **Law $\rightarrow$ elements $\rightarrow$ element routes:** 1 `Query` on base table `PK = LAW#<law_id>` returns `ROW#law`, all `ELEMENT#<element_id>` items, and all element-specific `ELEMENT#<element_id>#ROUTE#<route_name>` items sorted directly beneath their parent element. Generic route definitions (`_whole`, `_pleading`, `_derivative`, `_procedural`, `_comparator`) require 1 `Query` on `PK = TAXONOMY#generic`.
- **Routes / elements $\rightarrow$ cases (instances):** Answering which cases/instances belong to each route of `<law_id>` requires either $R$ `Query` calls on **GSI4** (`GSI4PK = ROUTE#<route_id>`, with `GSI4SK begins_with ELEMENT#<element_id>#` for generic routes) or $E$ `Query` calls on **GSI2** (`GSI2PK = ELEMENT#<element_id>`, one per element of the law).
- **Case metadata (`name`, `cite`, `court`, `date`):** Neither `instance` items (on `GSI2`/`GSI4`) nor `case_context` items (on `GSI6PK = LAW#<law_id>`) include `case.name`, `case.cite`, `case.court`, or `case.date`—those fields exist only on the `case` item (`PK = CASE#<case_id>, SK = CASE#<case_id>`). Rendering case names/citations therefore requires a `BatchGetItem` on `PK = CASE#<case_id>, SK = CASE#<case_id>` for the distinct `case_id`s returned.
2. **`case -> instances`**: **YES (no Scan required), in 1 `Query`**:
- Base table `PK = CASE#<case_id>` with `SK begins_with INSTANCE#` (or an unfiltered `Query` on `PK = CASE#<case_id>` to fetch the `CASE#` header, `CASE_CONTEXT#`, `CASE_REVIEW#`, `INSTANCE#`, and `FACT#` items together in a single partition read).
3. **`element -> quotes`**: **YES (no Scan required), via `Query` fan-out + `BatchGetItem` + S3 range-reads**:
- **Statutory quotes:** `GSI1` (`GSI1PK = ELEMENT#<element_id>, GSI1SK = ROW#element`) or `PK = LAW#<law_id>, SK = ELEMENT#<element_id>` gives `verbatim_quote_ref`; 1 `Query` on base table `PK = ELEMENT#<element_id>` with `SK begins_with ANCHOR#` gives all `element_anchor` quote pointers.
- **Rule quotes & instances:** 1 `Query` on **GSI2** (`GSI2PK = ELEMENT#<element_id>`) returns all attached `RULE#<id>` items and all `STATUS#<status>#CASE#<case_id>#INSTANCE#<instance_id>` items.
- **Fact/held quotes for those instances:** Because `instance_fact` edges are keyed by `PK = INSTANCE#<instance_id>, SK = FACT#<fact_id>` and `fact` items are keyed by `PK = CASE#<case_id>, SK = FACT#<fact_id>`, fetching the `fact` items for $I$ instances of an element requires $I$ `Query` calls on `PK = INSTANCE#<instance_id>` followed by `BatchGetItem` on `(PK = CASE#<case_id>, SK = FACT#<fact_id>)` (or querying each distinct `PK = CASE#<case_id>`) and S3 byte/character range fetches on `quote_ref`.
### 7.3 Access Patterns & Named Queries That DO Require a `Scan`
Under the keys emitted by `export_ddb.py`, the following queries/patterns have no single partition key or GSI key and **would require a `Scan`** in DynamoDB:
1. **Enumerating all laws (`SELECT * FROM law`) without a hardcoded law list:** Each `law` item is in its own partition `PK = LAW#<law_id>, SK = ROW#law` with `GSIs = []`.
2. **Enumerating all 340 `case` items globally (or filtering cases by `court` / `date`):** `case` items have `PK = CASE#<case_id>, SK = CASE#<case_id>` with `GSIs = []`. Querying `GSI6` across all 15 laws only reaches the 298 authored `case_context` rows and misses the **42 proposal-only `case` rows** (`340 - 298 = 42`).
3. **Finding unrouted instances (`instance.route_id IS NULL`, as in `route-coverage.unrouted` or proposal instances):** `GSI4` (`GSI4PK = ROUTE#<route_id>`) is sparse (`if row.get("route_id"):`), so instances with `route_id IS NULL` (including all 176 proposal instances) cannot be found via `GSI4` and require either scanning or querying `GSI2` across all 318 elements.
4. **Author-grouped queries (`review-coverage-by-author` or listing annotations/cases by `author`):** Neither `case_context.author` nor `annotation.author_alias` is a partition/sort key in any GSI (`GSI3` indexes `reviewer_alias`; `GSI5` indexes `SOURCE#<source>#STATUS#<status>`).
5. **Reverse `fact -> instance` lookup (given a `fact_id`, find which `instance`s use it):** `instance_fact` is keyed only by `PK = INSTANCE#<instance_id>, SK = FACT#<fact_id>` (`GSIs = []`), with no inverse index on `FACT#<fact_id>`.
6. **Reverse `element -> law_constraint` lookup:** `constraint_element` is keyed only by `PK = CONSTRAINT#<constraint_id>, SK = ELEMENT#<element_id>` (`GSIs = []`), with no inverse index on `ELEMENT#<element_id>`.
7. **Reading `proposal_batch` (70 rows), `ingest_issue`, `mechanical_rejection`, `schema_version`, or `store_metadata`:** In `export_ddb.py` lines 91–92 (`return f"TABLE#{table}#{token}", f"ROW#{table}#{token}"`), the primary-key hash `token` is placed inside `PK` (`TABLE#proposal_batch#<token>`), giving every row its own distinct partition key with `GSIs = []`. Changing `PK` to `f"TABLE#{table}"` and `SK` to `f"ROW#{token}"` would allow `Query(PK = "TABLE#proposal_batch")` without a `Scan`.
---
## (8) Spot-Check of 8 Randomly Chosen Cases in `review-status.tsv` Against Opened QA Reports
Sampled 8 rows from `neov2/qa/review-status.tsv` (one from each of the 8 QA report files listed in `neov2/tools/review_status.py`), opened each QA report, and verified the exact line/table verdict and git commit history:
```text
$ cd /home/mma/repos/neochart-wt-argon2 && python3 -c "
import subprocess
rows_to_check = [
('neov2/qa/cases-QA1.md', 'neov2/cases/18usc1962/f2d-976-1016-midwest-grinding-v-spitz.case', 'FIX', 'yes'),
('neov2/qa/cases-QA2.md', 'neov2/cases/18usc1962/us-556-938-boyle-v-united-states.case', 'FIX', 'yes'),
('neov2/qa/cases-v1-QA1.md', 'neov2/cases/15usc1/us-550-544-bell-atlantic-v-twombly.case', 'PASS', 'no'),
('neov2/qa/wave2-cases-QA1.md', 'neov2/cases/15usc78j/us-564-135-janus-v-first-derivative.case', 'PASS', 'no'),
('neov2/qa/wave2-cases-QA2.md', 'neov2/cases/18usc1343/us-605-114-kousisis-v-us.case', 'FIX', 'yes'),
('neov2/qa/wave2-cases-QA2-crosscheck.md', 'neov2/cases/42usc1981/us-553-442-cbocs-west-v-humphries.case', 'FIX', 'yes'),
('neov2/qa/flash1-QA1.md', 'neov2/cases/42usc1983/f3d-935-804-us-v-town-of-colorado-city.case', 'PASS', 'no'),
('neov2/qa/flash2-QA1.md', 'neov2/cases/42usc2000e-2/f-supp-3d-357-95-martinelli-v-bancroft-chophouse.case', 'FIX', 'no'),
]
with open('neov2/qa/review-status.tsv') as f:
tsv_lines = [line.rstrip('\n').split('\t') for line in f]
for qa_file, case_file, exp_verdict, exp_changed in rows_to_check:
matches = [r for r in tsv_lines[1:] if r[5] == qa_file and r[6] == case_file]
assert len(matches) == 1
m = matches[0]
qa_commit = subprocess.check_output(['git', 'log', '-1', '--format=%h %s', '--', qa_file], text=True).strip()
case_commit = subprocess.check_output(['git', 'log', '-1', '--format=%h %s', '--', case_file], text=True).strip()
print('TSV row:', '\t'.join(m))
print(' report last commit:', qa_commit)
print(' case last commit: ', case_commit)
assert m[4] == exp_verdict and m[7] == exp_changed
print('All 8 sampled rows in review-status.tsv match the QA reports and git history.')
"
TSV row: /f2d/976/1016-01 18usc1962 Fable QA1 FIX neov2/qa/cases-QA1.md neov2/cases/18usc1962/f2d-976-1016-midwest-grinding-v-spitz.case yes
report last commit: b7471eb neov2 qa: review Fable case instances (QA1)
case last commit: 2f9de1c Make the variant route a checked field of every case annotation
TSV row: /us/556/0938-01 18usc1962 Fable QA2 FIX neov2/qa/cases-QA2.md neov2/cases/18usc1962/us-556-938-boyle-v-united-states.case yes
report last commit: 50e61b9 Review CASE annotations to surface QA2 labeling gaps
case last commit: 2f9de1c Make the variant route a checked field of every case annotation
TSV row: /us/550/0544-01 15usc1 Fable QA1 PASS neov2/qa/cases-v1-QA1.md neov2/cases/15usc1/us-550-544-bell-atlantic-v-twombly.case no
report last commit: ddd0bc1 neov2 qa: review CASE DSL v1 migration (QA1)
case last commit: 2f9de1c Make the variant route a checked field of every case annotation
TSV row: /us/564/0135-01 15usc78j Astra2 QA1 PASS neov2/qa/wave2-cases-QA1.md neov2/cases/15usc78j/us-564-135-janus-v-first-derivative.case no
report last commit: 4cac1ba neov2 qa: review wave-2 case instances (QA1)
case last commit: 2f9de1c Make the variant route a checked field of every case annotation
TSV row: /us/605/114 18usc1343 Fable QA2 FIX neov2/qa/wave2-cases-QA2.md neov2/cases/18usc1343/us-605-114-kousisis-v-us.case yes
report last commit: 92d79e7 Review wave-2 case instances and DSL-v2 claims
case last commit: 2f9de1c Make the variant route a checked field of every case annotation
TSV row: /us/553/0442-01 42usc1981 Astra2 QA2 FIX neov2/qa/wave2-cases-QA2-crosscheck.md neov2/cases/42usc1981/us-553-442-cbocs-west-v-humphries.case yes
report last commit: 6cb5052 Cross-check wave-2 QA case verdicts
case last commit: 2f9de1c Make the variant route a checked field of every case annotation
TSV row: /f3d/935/0804-01 42usc1983 Flash1 QA1 PASS neov2/qa/flash1-QA1.md neov2/cases/42usc1983/f3d-935-804-us-v-town-of-colorado-city.case no
report last commit: 1640aa7 QA1: audits of Flash1 new cases and Round-6 assisted extraction benchmark
case last commit: 79bf9ee neov2(42usc1983): fix all 12 Flash1 cases per QA1 audit and strict guards
TSV row: /f-supp-3d/357/0095-01 42usc2000e-2 Flash2 QA1 FIX neov2/qa/flash2-QA1.md neov2/cases/42usc2000e-2/f-supp-3d-357-95-martinelli-v-bancroft-chophouse.case no
report last commit: 4c9dd8b QA1: audit of Flash2 fixed cases under Fable2 strict guards
case last commit: 089e435 fix(42usc2000e-2): strict guard compliance, opinion spans, and fact extraction for Flash2 cases
All 8 sampled rows in review-status.tsv match the QA reports and git history.
```
Exact matching lines from the 8 opened QA reports:
1. **`neov2/qa/cases-QA1.md` (line 34):**
`| 4 | 18 U.S.C. § 1962 | Odd #3 (0-idx 4) | 18usc1962/f2d-976-1016-midwest-grinding-v-spitz.case | 7th Cir. | 1992 | **FIX** |`
2. **`neov2/qa/cases-QA2.md` (line 30):**
`- **FIX** — us-556-938-boyle-v-united-states.case (Boyle v. United States): enterprise : satisfied [proved] makes an evidence-sufficiency claim the Supreme Court did not decide.`
3. **`neov2/qa/cases-v1-QA1.md` (line 37):**
`| 8 | 15usc1/us-550-544-bell-atlantic-v-twombly.case | 15 U.S.C. § 1 | Fresh (QA1) | **PASS** | Rule 8 parallel conduct theories cleanly split; [cuts-against absent] verified. |`
4. **`neov2/qa/wave2-cases-QA1.md` (line 27):**
`| **15 U.S.C. § 78j** | [us-564-135-janus-v-first-derivative.case](...) | *Janus Capital Group v. First Derivative* (564 U.S. 135) | Rule 10b-5(b) maker attribution requires ultimate authority; adviser not maker | **PASS** |`
5. **`neov2/qa/wave2-cases-QA2.md` (line 22):**
`- **FIX —** [us-605-114-kousisis-v-us.case](../cases/18usc1343/us-605-114-kousisis-v-us.case) (Kousisis v. United States).`
6. **`neov2/qa/wave2-cases-QA2-crosscheck.md` (line 35):**
`| 42usc1981/us-553-442-cbocs-west-v-humphries.case | — | FIX | The separate remedies : not-reached block conflicts with its rule/gloss... |`
7. **`neov2/qa/flash1-QA1.md` (line 22):**
`| 3 | 42usc1983 | [f3d-935-804-us-v-town-of-colorado-city.case](...) | 935 F.3d 804 (2019), *United States v. Town of Colorado City* | Uncertain | **Proper Abstention**: ... | **PASS** |`
8. **`neov2/qa/flash2-QA1.md` (line 33):**
`| 13 | 42usc2000e-2 | [f-supp-3d-357-95-martinelli-v-bancroft-chophouse.case](...) | 357 F. Supp. 3d 95 (D. Mass. 2019), *Martinelli v. Bancroft Chophouse* | Hostile Environment / Constructive Discharge | **Header Court Error & Double Recital**: ... | **FIX** |`