kandev/docs/plans/task-summary-semantic-equality/task-01-align-semantic-equality.md

---
id: "01-align-semantic-equality"
title: "Align semantic equality and prove persistence behavior"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
  - REQ-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001
acceptance_criteria:
  - AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.2
  - AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.3
system_design:
  - ../../specs/platform/system-design/bounded-task-status-delivery.md
---

# Task 01: Align semantic equality and prove persistence behavior

## Summary

Make valid summary equality agree with persisted canonical JSON. Prove that a
PR detail change with an unchanged aggregate and a retained session error is
a successful no-op, while a later real change still persists and publishes.

## In scope

- Add model and real-SQLite regression tests before production edits.
- Replace representation-sensitive equality with successful canonical-payload
  comparison, preserving the existing validation/error path.
- Match the test store's rejection semantics to the production repository.
- Record red/green command results and update the plan/work-order status.

## Out of scope

All exclusions in [the plan](plan.md#scope), especially repository SQL changes,
global normalization changes, UI work, log-level suppression, and retry tuning.

## Acceptance

1. Every tested valid summary compares equal to its canonical JSON round trip,
   including nil/empty error actions and causes. Metadata-only differences
   are equal; real semantic differences are unequal. Failed encodings are
   never accepted as equality.
2. Against real SQLite, both live and recreated projectors process an
   aggregate-preserving PR change with no handler error, exhaustion warning,
   revision change, or extra summary publication. Preserve unrelated fields.
3. A subsequent true aggregate change advances exactly one revision and
   publishes exactly one complete replacement with task/workspace identity.
   Existing store-error and contention behavior stays observable and bounded.

## TDD sequence and regression construction

1. Mark this work order `in_progress`. Add
   `TestTaskStatusSummaryProjectorPRNoopWithRetainedError` using
   `newTaskStatusSummaryTestRepo` and `seedTaskForStatusSummary`.
2. Configure `LoadSessionObservations` with one primary waiting session,
   `ErrorsObserved: true`, and an error with `Scope: "session"`, matching
   `SessionID`, fixed UTC `OccurredAt`, stamp, and preview. Leave optional
   collections absent so production normalization creates the relevant shape.
3. Call `Projector.HandleEvent` with `GitHubTaskPRUpdated`, fixed task/workspace
   and repository identity, one open PR, `checks_state: "failure"`, and
   `pending_review_count: 1`. Load the first summary, then send count 2.
   The unchanged `failure` aggregate must succeed; current code instead returns
   `exhausted CAS retries ... after 3 attempts`. Assert payload and revision
   as well as event counts. Capture the projector logger for the warning check.
4. Include a recreated-projector case using the same temporary repository and
   authoritative session/PR loaders. Keep loader keys aligned with event keys.
   Register bus/logger/database cleanup immediately. No sleeps are needed.
5. Add model cases named in the plan. Independently exercise empty actions and
   empty causes in both `ActiveError` and `TaskError`, plus valid populated
   changes, removal, queue count, Git/PR state, and last activity changes.
6. Implement canonical equality and faithful fake-store semantics. Never
   return equality when either `SemanticJSON` call fails. Do not swallow CAS
   exhaustion or increase its attempt count.
7. In `TestTaskStatusSummaryProjectorPRNoopWithRetainedError`, after the
   no-op cases, change aggregate status to a distinct state, assert one
   write/event, then replay and assert no extra event. Verify the retained
   error and complete replacement survive. Run the targeted packages and
   record results.

## Verification

Run from the repository root. The first command is the red test before the
production edit and must be rerun green afterward. The second covers every
changed suite and the existing contention regressions.

```bash
(cd apps/backend && go test ./internal/task/repository/sqlite -run '^TestTaskStatusSummaryProjectorPRNoopWithRetainedError$' -count=1 -v)
(cd apps/backend && go test -race ./internal/task/statussummary ./internal/task/repository/sqlite -count=1)
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
git diff --check
git status --short -- docs/plans/task-summary-semantic-equality
```

Do not claim PostgreSQL was exercised by the SQLite suite. There is no SQL or
dialect change in this scope; if one becomes necessary, reconcile the package
and add the required real PostgreSQL check before implementing it.

## Files likely touched

- `apps/backend/internal/task/statussummary/model.go`
- `apps/backend/internal/task/statussummary/model_semantic_equality_test.go` (new)
- `apps/backend/internal/task/statussummary/projector_test.go` (test-store helper)
- `apps/backend/internal/task/repository/sqlite/task_status_summary_projector_noop_test.go` (new)
- This work order and `plan.md` (status and results).

Read-only integration points: `projector.go`, `projector_events.go`,
`projector_derive.go`, `rebuild.go`, and `repository/sqlite/task_status_summary.go`.

## Dependencies

None.

## Risks

Invalid data must reach existing validation rather than being hidden by failed
serialization. The revised fake store can reveal tests that previously assumed
every higher revision was accepted. Diagnose those assumptions rather than
weakening the persistence contract.

## Parallelism

`sequential`

## Inputs

- [Plan and reproduction evidence](plan.md).
- [Requirements](../../specs/platform/requirements/bounded-task-status-delivery.md), AC .2 and .3.
- [Design](../../specs/platform/system-design/bounded-task-status-delivery.md), derivation and persistence guarantees.
- Existing `model_test.go`, `projector_pending_authority_test.go`,
  `projector_queued_test.go`, and `task_status_summary_test.go` patterns.
- `.agents/skills/tdd/references/backend-tests.md`.

## Results

Implemented on 2026-09-17.

- `TaskStatusSummary.SemanticEqual` compares successful canonical semantic JSON
  encodings and rejects invalid summaries as equal.
- The projector test store now models both production rejection conditions:
  stale revisions and unchanged workspace/semantic payloads.
- Added model coverage for nil/empty omitted collections, metadata-only changes,
  real semantic changes, JSON round trips, and invalid values.
- Added a real SQLite projector regression covering live and recreated no-op PR
  updates and one true aggregate change.

Verification passed:

```text
(cd apps/backend && go test ./internal/task/statussummary ./internal/task/repository/sqlite \
  -run 'TestTaskStatusSummarySemanticEquality|TestTaskStatusSummaryProjectorPRNoopWithRetainedError' -count=1)
  2 packages passed.

(cd apps/backend && go test -race ./internal/task/statussummary ./internal/task/repository/sqlite -count=1)
  2 packages passed.

python3 scripts/list-docs.py validate
  Validated 285 decisions and 986 specifications.

python3 scripts/lint-spec-files.py --all
  All specification files passed.

git diff --check
  passed.
```