feat: bind served shadow recall evidence fields to exact V2/#157 state (#188)

[ezutfen]

Closes #188 (ENG-RECALL-003C — parent #160, epic #153)

Summary

Admitted governed/exploratory shadow items now present the exact risk_aware_shadow_v1 V2/#157 fresh evaluation state that authorized admission — closing the gap where admission.v2.fresh.epistemic_state = "supported" while item.epistemic_state = "unknown" for the same admitted item.

• build_v2_evidence_fields (engram/recall_signals.py): one pure function projecting the already-bound RecallAdmissionDecision.v2 into the served evidence block. No second ENG-CLASSIFY-003 — Separate retention value from epistemic confidence and support versioned reassessment #157 selection, no per-item memory_assessments query, no second V2 evaluation, no provider call — structurally (synchronous, no session parameter) and mechanically (counters pinned by tests).
• Top-level epistemic_state mirrors evidence.epistemic_state exactly; the item-local review/conflict/verification heuristic now serves only non-V2 local profiles (none registered).
• Warnings derive from the canonical V2 state + independently true lifecycle marks: evidence_unknown / evidence_contested / evidence_insufficient / risk_high / risk_unknown (with _WARNING_TEXT mirrors). Impossible admitted combinations (non-current resolution, non-allow surface, not_applicable epistemic) fail closed via V2EvidenceContractError.
• Unchanged: ranking (compute_signal_rank_score, utility weights), ordering, budgets, corpus eligibility, ENG-PROMOTION-003D — Persist promotion assessments and expose next-action state #159 local-withhold precedence, CERTIFIED_SERVING_PROFILES == {"legacy"}, legacy packet shape (byte-for-byte; new test pins no evidence/warning_codes keys on legacy items), MCP surface, shadow read-only behavior. No selection_status added to the V2 contract; no ENG-EVIDENCE-001 — Evidence-root-aware corroboration and usefulness lane #161/ENG-CALIBRATION-001 — Labeled admission evaluation and shadow-rollout certification #162/Context Ledger work.

Representative before/after (governed-admitted qualified proposal)

Field	Before (#187)	After (#188)
admission.v2.fresh.epistemic_state	supported	supported
epistemic_state (top level)	unknown ← mismatch	supported
warning_codes	["unreviewed", "evidence_unknown"]	["unreviewed"]
evidence block	—	{source: v2_fresh_evaluation, …, epistemic_state: supported, risk_state: low, retention_state: retain, …}

Warning matrix (test-pinned)

V2 fresh state	Served	Warning code
epistemic supported	mirrored	none
epistemic unknown	mirrored	evidence_unknown
epistemic contested	mirrored	evidence_contested
epistemic insufficient_evidence	mirrored	evidence_insufficient
epistemic not_applicable	fail closed	V2EvidenceContractError
risk high	mirrored	risk_high
risk unknown	mirrored	risk_unknown
risk low/medium	mirrored	none

Lifecycle marks (unreviewed, admission_assessment_stale, admission_legacy_import) remain where independently true (pinned with the canonical state in the stale-#159-binding test).

Proof highlights

• Identity invariant: unit tests assert every evidence.* == admission.v2.fresh.* field-by-field from the shared binding; DB tests re-verify against the real resolver path (test_served_evidence_state_is_the_exact_v2_fresh_evaluation — supported/unknown/contested/insufficient/high-risk/absent fixtures across both profiles).
• Projection, not recomputation: evidence built after admission from decision.v2; evaluation core runs exactly once per item per packet, bulk resolver once per packet (monkeypatch counters); standalone resolver query_count equals the packets' reported count; mutable item fields (confidence/trust/importance/counters/age/verification) cannot move evidence.* with the decision held fixed.
• Read-only: recall logs, exposure counters unchanged under the shadow compare with evidence present.
• Fail-closed: missing/stale/mismatched/unsupported stay withheld, diagnostic v2 identity intact, no served evidence block.
• Legacy: byte-for-byte — pre-existing legacy pins pass unchanged plus new additive-key pins.

Tests

• tests/test_recall_signals.py: +10 unit tests (canonical serialization, warning matrix, local-derivation boundary, fail-closed, no-IO signature proofs).
• tests/test_recall_profile_semantic.py: evidence matrix integration test (real resolver), no-duplicate-evaluation/IO proof, read-only proof; pre-issue mismatch pins updated to the canonical contract.
• sdk/engram-client/tests/test_models.py: RecallResponse accepts structured evidence blocks; unknown/null states stay structured, never numeric.

Results

• Focused: test_recall_signals.py 50 passed; test_recall_profile_semantic.py + test_recall_v2_admission.py + test_recall_profiles.py 108 passed; SDK model tests 8 passed.
• make check: lint + mypy --strict (engram 95 files, evals, SDK, MCP, hooks) clean; root suite failures are environment-only (no ENGRAM_DATABASE_URL in that shell) and byte-identical to unmodified main (diffed FAILED/ERROR lists).
• make compose-ci: passed — 3861 passed, 35 skipped against PostgreSQL 16 + pgvector under the non-owner app role (migrations, FORCE RLS, root/SDK/MCP/hooks suites).
• Production remains legacy-only; no ENG-CALIBRATION-001 — Labeled admission evaluation and shadow-rollout certification #162 certification, ENG-EVIDENCE-001 — Evidence-root-aware corroboration and usefulness lane #161 corroboration, or Context Ledger behavior enabled. ADR-160 carries the ENG-RECALL-003C — Bind served shadow recall evidence fields to exact V2/#157 state #188 supplement.

Remaining #160 slices (after this issue)

#157 enrichment on non-V2 paths (startup), signal-aware graph/tunnel expansion, diversity/root-redundancy + conflict-preserving packing, demonstrated-usefulness feedback, semantic Context Ledger receipts (packet is now receipt-ready), dogfood/exposure-concentration evaluation on the shadow surface (incl. keeping the V2 row corpus fresh), fresh #162 certification + default cutover.