Unclaimed Property Platform

DTD 5/5 verdict C (CONTINUE/WRAP/PIVOT -> PIVOT to packaging then wrap); Cody dissent (real
blocker is business/legal) folded in as a real DUA template, not dismissed.
- scripts/demo_tour.py: one-command narrated end-to-end tour (ingest 3 formats + reconcile ->
  masked search -> suppress/reinstate -> claim + outbox retry). VERIFIED runs /bin/zsh.
- Makefile: make demo / test / serve / install (one-command front door).
- README.md: rewritten — what works + proof table, 60-second demo, guardrails, repo map,
  and the real critical path up front.
- docs/04-data-use-agreement-template.md: the fill-in DUA + GTM sequence — the artifact that
  actually unblocks a real deployment (honors the dissent).
- MERGE: removed the orphan parallel NAUPA duplicate triad (naupa2_fixed/naupa3_xml/
  test_cycle3) — consolidated to the single pipeline-wired implementation. History retained.
Tests: 11/11 suites green after consolidation.

TK-10097

- FeedDefinition.expected_count (state control total; NAUPA trailer in prod); _reconcile()
  compares parsed (accepted+rejected) vs expected -> ok|short|over|unknown + delta.
- 'short' is the silent-truncation signal (a transfer that cut off looks 'successful' otherwise).
  Persisted on ingestion_batch (expected_count + reconciliation cols); batch_reconciliation() reads it.
- tests/test_cycle11_reconciliation.py: ok/short/over/unknown + persistence.
Tests: 11/11 suites green. All local/synthetic/$0.

TK-10097

- services/claims/outbox_worker.py: drains pending outbox_event -> StateAdapter with
  AT-LEAST-ONCE semantics + bounded retry. Transient fail -> stays pending (attempts++);
  exhausted -> 'failed' (claim NOT lost, stays SUBMITTING for ops); already-SUBMITTED ->
  treated as idempotent success (no retry loop).
- schema: outbox_event gains attempts + last_error; SqliteClaimRepository fetch_pending_outbox
  / mark_outbox / outbox_row.
- tests/test_cycle10_outbox_worker.py: transient-then-success, no-op re-drain, permanent-fail
  exhaustion. Now events are not just WRITTEN (Cycle 8) but reliably DELIVERED.
Tests: 10/10 suites green. All local/synthetic/$0.

TK-10097

- services/claims/sqlite_claim_repo.py implements ClaimRepository against claim_case/
  claim_event/outbox_event, sharing the SqliteRepository connection (one system-of-record).
- Closes the last 'runs only on a test fake' gap: the claim lifecycle now persists end-to-end
  and the C3 idempotency fix is proven against the REAL UNIQUE(claim_id, idempotency_key)
  constraint (duplicate -> sqlite3.IntegrityError), not an in-memory imitation.
- tests/test_cycle9_claims_persistence.py: full DRAFT->SUBMITTED_TO_STATE lifecycle, outbox,
  DB-level idempotency, state-only guard, illegal-transition rejection.
Tests: 9/9 suites green. All local/synthetic/$0.

TK-10097

- SqliteRepository.suppress_property/reinstate_property: flip search_document_state.is_suppressed
  so a record leaves/returns to anonymous search IMMEDIATELY (masked_search already filters it),
  while property + owner + version history are fully retained. Every action writes an immutable
  audit_event; audit_trail() reads it back. Unknown record -> False (no silent success).
- Closes the brief's near-real-time suppression requirement (privacy/fraud takedown) — the gap
  where nothing could pull a record from public search. State-authenticated in production.
- tests/test_cycle8_suppression.py: suppress->gone, data retained, audit written, reinstate->back.
Tests: 8/8 suites green. All local/synthetic/$0.

TK-10097

- normalize_search(): fully-collapsed alphanumeric key (spaces+punct removed) — CATHERINEONEIL.
- masked_search matches REPLACE(owner_name_normalized,' ','') LIKE collapsed-query, so 'Oneil'
  now finds "O'Neil" and 'Smith-Jones' variants match. Does NOT widen normalize_text (masks/
  blocking/phonetic unchanged). Empty-query guard (m2) preserved.
- tests/test_cycle7_recall.py proves the fix + no-regression.
Tests: 7/7 suites green. All local/synthetic/$0.

TK-10097

- services/ingestion/naupa3.py: namespace-tolerant XML parser via the lazy adapter registry
  (format_name naupa3_v1); same CanonicalProperty as CSV/NAUPA II.
- SECURITY: rejects any DOCTYPE/ENTITY document (XmlSecurityError) -> closes XXE /
  billion-laughs entity-expansion at the door before parsing. build_naupa3_xml helper for
  aligned fixtures (optional default xmlns to exercise namespace tolerance).
- tests/test_cycle6_naupa3.py: parity, namespace tolerance, XXE refusal, malformed-record
  reject, idempotency.
- Logged backlog: apostrophe/hyphen search RECALL (normalize_text collapses ' to space, so
  LIKE-search misses 'Oneil' for O'Neil; matching unaffected via phonetic key). Prod = OpenSearch analyzers.
Tests: 6/6 suites green. All local/synthetic/$0.

TK-10097

- services/common/rate_limit.py: SlidingWindowRateLimiter (injectable clock, per-key budgets,
  retry_after). Replaces the require_rate_limit_STUB masquerade — anti-enumeration is now real.
- services/search/service.py: SearchService composes validate -> rate-limit -> masked_search
  -> assert_public_safe (fail-closed) so every transport enforces identical privacy controls.
- services/search/run_local.py: dependency-free stdlib HTTP endpoint ($0). SMOKE-TESTED over
  real HTTP: 200 masked JSON, 400 empty-query, 429 after budget, /healthz. Single-threaded
  (SQLite is thread-bound; prod = Postgres pool).
- tests/test_cycle5_search.py: deterministic (injected clock) proof of masked results, real
  429 + window refill, empty-query rejection, per-client-key isolation.
Tests: 5/5 suites green. All local/synthetic/$0.

TK-10097

Product:
- NAUPA II fixed-width parser via lazy adapter registry (_get_parser); same CanonicalProperty
  as CSV so dedup/masking/search are format-agnostic. build_naupa2_line keeps fixtures aligned.
- tests/test_cycle3_naupa_and_blocking.py: NAUPA parity + idempotency + blocking-key bucketing.
Matching:
- blocking_keys fairness fix: empty-norm (CJK/Arabic) names now fall through to geo keys so
  they're never un-indexable; tests/test_cycle4_fairness.py asserts the coverage floor.
Claims:
- FIX regression from M1 refactor: complete_state_submission namespaced its transition key
  (:transition) so it no longer collides with queue's SUBMITTING event (C3-variant, caught
  by the Cycle-2 regression test).
Guardrails:
- scripts/pre-commit-tripwire.sh: blocks SSN-shaped strings + real-feed formats at commit.
Docs:
- docs/jurisdictions.json (machine-readable, 50+DC); docs/03 roadmap/budget.
- RECONCILED docs/03 revenue model from consumer finder-fees -> B2G government-paid, matching
  the thesis + brief (finder-fee model was explicitly excluded at launch). Fixed data/ -> docs/
  jurisdictions.json path (data/* is gitignored).
Tests: 4/4 suites green. All local/$0.

TK-10097

Cody+security-auditor+code-reviewer fan-out -> 4 criticals + crown-jewel privacy fix,
all fixed + regression-tested (tests/test_cycle2_hardening.py, 7/7 pass).

- Thesis + hard guardrails (no scraping, no real feeds, no autonomous contracting)
- 50-state + DC acquisition matrix (feed-first, records-request fallback, public handoff)
- Polyglot architecture + canonical schema (provenance/version non-destructive)
- Reference services: idempotent NAUPA/CSV ETL, Fellegi-Sunter matcher w/ phonetic key,
  masked FastAPI search, claim state-machine + transactional outbox
- Stdlib-only end-to-end smoke test (ingest idempotency + masking + matching) PASSES at $0

TK-10097