feat: bind shadow recall profiles to V2 surface admission decisions (#186)

[ezutfen]

Closes #186 (ENG-RECALL-003B). Parent #160, epic #153. Depends on #158/#159/#160 (PRs #183/#182/#184, all merged).

Summary

Bind #160's governed/exploratory shadow recall packets to the exact #158 risk_aware_shadow_v1 per-surface decisions, instead of reconstructing candidate admission from review_status, disputed stay-kind logic, and the #159 Path-A projection. Shadow-only: no change to production recall serving authority, promotion authority, or CERTIFIED_SERVING_PROFILES.

Architecture

• Shared bulk V2 resolver (engram/admission_shadow.py:resolve_bulk_v2_decisions) — owned by the ENG-PROMOTION-003C — Replace the universal 72-hour gate with versioned risk-based admission profiles #158 module so the simulator, the operator simulate surfaces, and ENG-RECALL-003 — Separate relevance, utility, and epistemic trust in recall admission and ranking #160 recall cannot drift on "what is the effective V2 decision?". Evaluates the exact decision fresh for the whole window (bulk promotion support + bulk ENG-CLASSIFY-003 — Separate retention value from epistemic confidence and support versioned reassessment #157 selection via a new shared pure selection core + one latest-row lookup) and resolves the latest persisted V2 shadow row against it. Query count is constant at 7 regardless of window size; no provider calls; reads only.
• Exact surface mapping (RecallProfileSpec.v2_surface): governed → semantic_governed, exploratory → semantic_exploratory — never startup, never highest_admission_tier. Because the ENG-PROMOTION-003C — Replace the universal 72-hour gate with versioned risk-based admission profiles #158 policy's domain is live proposals (not_live → blocked on every surface), the candidate corpus windows are now the live-proposal SQL predicate (proposed AND valid_to IS NULL AND superseded_by IS NULL AND conflict IS DISTINCT FROM 'unresolved') applied before the bounded HNSW window; review_status='active' is no longer a positive admission source anywhere on the candidate path.
• Fail-closed resolution (current | missing | stale | mismatched | unsupported, canonical ENG-PROMOTION-003D — Persist promotion assessments and expose next-action state #159-style vocabulary): only current (row's decision_hash == fresh evaluation — the fresh evaluation is the verification, no projection pointer trusted) carries positive authority; each other status withholds with its own reason code (v2_decision_*). stale covers input-digest drift (state, effective ENG-CLASSIFY-003 — Separate retention value from epistemic confidence and support versioned reassessment #157 selection, content identity, time-window crossings).
• Surface gate (engram/recall_signals.py, recall-admission-v2): an item enters a candidate packet only when the exact surface decision is allow under a current resolution; withhold/review_required/blocked/unknown are consumed as-is. Recall-local rules (ENG-PROMOTION-003D — Persist promotion assessments and expose next-action state #159 blocked/strict-stale, lifecycle) remain withhold-only defense in depth — a V2 allow can never widen tenant/RLS/workspace/visibility boundaries; local-vs-V2 disagreements surface as bounded content-free admission_diagnostics (id, codes, resolution status, gates_disagree).
• Additive payload (recall-shadow-compare-v2): per-item admission.v2 binding block (assessment id, schema version, policy version + artifact digest, decision hash, resolution status, exact surface decision, risk/epistemic/retention state, effective ENG-CLASSIFY-003 — Separate retention value from epistemic confidence and support versioned reassessment #157 refs, window times, bounded code sets — identity and codes only, no content/provider output) plus per-packet diagnostics and a v2_resolution summary with per-status counts and query count.

Shadow-only boundary — confirmed unchanged

• CERTIFIED_SERVING_PROFILES remains {"legacy"} (test-pinned).
• POST /v1/recall remains legacy-only; requesting governed/exploratory still 422.
• Shadow comparison writes nothing: no recall_logs, no exposure counters, no promotion/review/evidence side effects, no shadow-current projections (test-pinned, incl. capture-disabled rollback reads).
• REVIEW_SCOPE + tenant_config.recall_profile_shadow_enabled still gate the surface; explicit workspace denial still yields no broader fallback.

Verification

• make check — lint + strict typecheck + root suite green (12 local failures are byte-identical to unmodified main in this environment: missing engram_client/engram_hooks workspace installs + subprocess tests crashing in the local AppImage python).
• make compose-ci — fully green: 3838 passed, 35 skipped, 0 failed against real PostgreSQL + pgvector under the non-owner app role.
• New/updated tests: golden parity matrix (ENG-PROMOTION-003C — Replace the universal 72-hour gate with versioned risk-based admission profiles #158 simulator ↔ resolver: identical decision hashes and surfaces across qualified-low / medium pre-post-72h / high-risk / absent / contested / governance-review / conflict states), age-only-changes-window, fail-closed matrix (missing/stale/mismatched/unsupported + input-digest drift + newest-row-wins), surface-mapping matrix, ENG-PROMOTION-003D — Persist promotion assessments and expose next-action state #159 defense-in-depth precedence, pre-LIMIT window starvation regression, cross-tenant FORCE-RLS invisibility, read-only proof, constant query count + no provider calls, deterministic-fixture latency recording, page-vs-item simulator parity, plus reworked unit contracts for the gate and profile registry.

Documentation

• ADR-160 supplement (§ V2-bound candidate admission): canonical authority, resolution table, fail-closed gate, unchanged boundary, remaining ENG-RECALL-003 — Separate relevance, utility, and epistemic trust in recall admission and ranking #160 slices and the fresh-ENG-CALIBRATION-001 — Labeled admission evaluation and shadow-rollout certification #162 certification gate.
• Progress comment on ENG-RECALL-003 — Separate relevance, utility, and epistemic trust in recall admission and ranking #160 (issue stays open).

Non-goals honored

No #161 corroboration lane, no evidence-root redesign, no positive-feedback admission, no #162 certification run, no production governed/exploratory rollout, no signal-aware expansion or final packing work. #161/#162 production enablement is not authorized by this PR.