# V2 Phase 3 Search Action Context Audit

Date: 2026-06-30

This note records Slice 3.5.3-h of the action_hint / next_action cleanup.

## Decision

- Keep `display_cache_governance` as a lightweight legacy cache-column governance check.
- Do not convert runtime schema-check into a full multi-table action semantics validator in this slice.
- Treat search documents as user-facing derived output, so contract search document generation must use the same full `ContractActionContext` as contract list, detail, and workspace responses.

## Why display_cache_governance stays lightweight

`display_cache_governance` is the pre-cleanup guard for retained legacy columns:

- `contracts.status_label`
- `contracts.status_tone`
- `contracts.next_action`
- `contracts.next_actions`

It should answer whether those legacy cache columns are consistent enough before a later cleanup step. It intentionally does not load review tasks, approval instances, approval steps, obligations, or other workflow tables.

Changing it into a full action semantics audit would change the meaning of `display_cache_consistency` and make schema-check depend on mutable workflow side effects. That belongs in a later explicit validator, not in the cache cleanup prestate.

## Implemented

- `ContractSearchRepository.upsert_contract_search_document(...)` now auto-loads `load_contract_action_context(session, row)` when callers do not pass an explicit context.
- Contract transition search sync now runs after formal approval facts and display cache have been updated.
- This ensures search summaries see pending approval steps instead of stale `action_hint`.
- Added regression coverage for search document generation:
  - search summary/search text follows `action_hint` after PATCH;
  - search summary switches to the structured approval-derived action after approval submission.
- Added a short code note documenting that `display_cache_governance` is intentionally lightweight.

## Not Changed

- No database columns were removed.
- No cleanup migration was added.
- `display_cache_governance` snapshot/backfill behavior remains based on the legacy cache-column prestate.
- API response compatibility for `next_action / next_actions` remains unchanged.

## Verification

```powershell
python -m compileall -q yuqei-contract-platform\services\contract-api\src\yuqei_contract_api
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py::test_search_document_generation_uses_contract_action_context -q
python -m pytest yuqei-contract-platform\services\contract-api\tests\test_contract_workflow.py yuqei-contract-platform\services\contract-api\tests\test_health.py yuqei-contract-platform\services\contract-api\tests\test_display_cache_governance.py -q
python -m alembic -c alembic.ini heads
```

Result:

- Compile passed.
- Contract workflow, runtime schema-check/health, and display cache governance regression passed.
- Alembic head remains `20260630_0022`.

## 2026-07-01 Superseded Note

The decision to keep `display_cache_governance` lightweight has been superseded by the 2026-07-01 smoke investigation.

Observed issue:

- `runtime/schema-check` reported `display_cache_consistency.mismatch_count=0`.
- Contract detail rendering still emitted `Contract display cache mismatch; derived value will be used`.

Root cause:

- Contract detail/list/workspace/search read paths derive `next_action/next_actions` from full `ContractActionContext`.
- The lightweight governance check only compared legacy columns with status-default derived values.

Updated decision:

- `display_cache_governance` now uses the same full action context needed by user-facing read paths.
- `runtime/schema-check` remains the cleanup prestate gate, but now checks the real display semantics instead of status defaults only.
- Heavy schema-check is no longer used as the Docker container healthcheck; container health uses `/api/v1/health`, while schema-check remains a smoke/CI quality gate.

Current evidence is recorded in:

- `project-docs/V2-phase3-display-cache-context-prestate-2026-07-01.md`