Contract Tests: enforce ADR-023 and ADR-019 invariants in CI

[insign]

Summary

Add an explicit contract-focused test suite that hard-fails when CodeWalk drifts from critical OpenCode lifecycle semantics, especially around prompt_async, optimistic message IDs, SSE reconciliation, and deferred config mutation.

This issue depends on the contract inventory produced in #26 and should treat that inventory as the baseline.

Why this exists

The highest-risk regressions in CodeWalk are not generic UI bugs; they are contract regressions where the client silently diverges from the server-authoritative lifecycle. ADR-023 already calls this out, and ADR-019 adds timing sensitivity around PATCH /config during active processing.

Known dangerous areas include:

• Optimistic message ID shape (local_user_*)
• Accidentally forwarding messageId in prompt_async
• Session state transitions that invent client-side meaning instead of following server events
• Merge/reconcile behavior that drops valid assistant responses
• Config mutation while the server is actively processing

Required references

• ADR-023 in ADR.md
• ADR-019 in ADR.md
• BEHAVIOR.md
• Resulting matrix from Contract Matrix: build OpenCode source-of-truth and capability inventory for CodeWalk #26

Current repo evidence to inspect

• lib/presentation/providers/chat_provider.dart
• lib/presentation/providers/chat_provider/chat_provider_message_merge_ops.dart
• lib/presentation/providers/chat_provider/chat_provider_realtime_ops.dart
• lib/presentation/providers/chat_provider/chat_provider_event_reducer_ops.dart
• lib/data/datasources/chat_remote_datasource.dart
• lib/data/datasources/app_remote_datasource.dart
• test/integration/opencode_server_integration_test.dart
• test/support/mock_opencode_server.dart
• test/unit/providers/chat_provider_*

Scope

Implement a dedicated contract test layer that validates at minimum:

1. prompt_async payload must not forward messageId
2. Optimistic user messages must use the local_user_<timestamp>_<seq> pattern
3. SSE/global event reconciliation must preserve valid assistant updates
4. Session status transitions must remain server-authoritative (idle, busy, etc.)
5. PATCH /config must not happen during active processing in ways forbidden by ADR-019
6. Slash-command routing must match the intended official endpoint usage (/command vs chat send path) once Contract Matrix: build OpenCode source-of-truth and capability inventory for CodeWalk #26 confirms the baseline
7. Realtime reducer logic must not resurrect reverted or abandoned branches after server-authoritative updates

Deliverables

• New contract-focused tests, ideally under a dedicated area such as test/contract/
• Expanded integration coverage if current mocks are insufficient
• Updated mock server behavior where existing fixtures encode outdated semantics
• Clear inline comments around the invariants being protected

Acceptance criteria

• A failing change to local_user_* or messageId forwarding causes CI failure.
• A failing change to config mutation timing causes CI failure.
• Reconcile/merge regressions that would drop a valid assistant response are covered.
• The test suite is discoverable and documented as the ADR-023 enforcement layer.
• Existing tests remain green.

Non-goals

• No feature redesign in this issue.
• No major UI work.
• No server changes.

Test commands

• make check
• Any narrower Dart/Flutter test command needed while iterating

Dependencies

• Depends on Contract Matrix: build OpenCode source-of-truth and capability inventory for CodeWalk #26.

Notes for the implementer

Prefer high-signal tests that lock behavior at the contract boundary over snapshotting random widget trees. The point is to make future drift expensive and obvious.

[insign]

Wave 1 completed for this issue.

Executed sequence:

1. implement the wave
2. run make check
3. create commit(s)
4. run reviewer loop until no accepted findings remain
5. cut a minor release
6. validate the release on at least one platform
7. close the completed issue(s)
8. move on to the next wave/issue

Artifacts delivered here:

• test/contract/opencode_contract_test.dart
• new ADR-023 / ADR-019 contract coverage for the highest-risk invariants

Release validation:

• v1.63.0
• Release workflow: https://github.com/verseles/codewalk/actions/runs/24707460025
• Verified platform: Build Linux (x64) success