200 lines
10 KiB
Markdown
200 lines
10 KiB
Markdown
---
|
|
created: 2026-09-17
|
|
status: complete
|
|
requirements:
|
|
- REQ-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001
|
|
system_design:
|
|
- ../../specs/platform/system-design/bounded-task-status-delivery.md
|
|
legacy_specs: []
|
|
---
|
|
|
|
# Implementation Plan: Task-summary semantic equality
|
|
|
|
## Overview
|
|
|
|
Stop false compare-and-set exhaustion errors when a source event changes a
|
|
detail but leaves the bounded task summary unchanged. Align the projector's
|
|
in-memory equality with its existing persisted semantic JSON, then prove the
|
|
complete event-to-storage-to-publication path with a real SQLite repository.
|
|
One sequential work order owns the correction and its regression coverage.
|
|
|
|
## Evidence and confirmed root cause
|
|
|
|
Investigation baseline: checkout `f32eb3737`, 2026-09-17. Today's retained
|
|
backend files contained 31 `exhausted CAS retries refreshing pending task
|
|
status` warnings paired with `github.task_pr.updated` handler errors between
|
|
11:19 and 15:16 Lisbon time. At 15:16:47, the source changed review counts.
|
|
Read-only inspection of three affected task summaries found retained session
|
|
errors with omitted `recovery_actions` and `causes` fields. These database
|
|
reads describe inspection-time state, not a historical snapshot.
|
|
|
|
The deterministic cause is independent of concurrent writers:
|
|
|
|
1. `restoreSessionObservations` / `normalizeRebuildError` rebuild error
|
|
observations. `NormalizeRecoveryActionsForCategory` and
|
|
`NormalizeAgentErrorCauses` can produce non-nil zero-length slices.
|
|
2. `deriveActiveError` retains those slices. `cloneSummary` and database JSON
|
|
round trips omit them through `omitempty` and restore nil slices.
|
|
3. `TaskStatusSummary.SemanticEqual` uses `reflect.DeepEqual`, which treats
|
|
those in-memory representations as different.
|
|
4. A PR detail change, such as pending review count 1 to 2 while checks remain
|
|
failing, changes the keyed observation but not the aggregate summary.
|
|
5. The projector attempts a write. The repository correctly rejects it because
|
|
`SemanticJSON` is identical. Reload/rebase restores the same mismatch, so
|
|
all three retries fail and the handler returns an error.
|
|
|
|
A temporary test named `TestReproSummaryPRNoopWithRetainedError` drove
|
|
`Projector.HandleEvent` with a real SQLite repository and synthetic data. It
|
|
used one waiting primary session with an explicitly session-scoped retained
|
|
error and two PR events with checks `failure`, changing pending review count
|
|
from 1 to 2. The second event returned the exact exhaustion error. The before
|
|
and after stored JSON were identical and both revisions were 1. No competing
|
|
writer, running agent, external provider, or browser was involved.
|
|
|
|
The temporary reproduction was removed after investigation. Its permanent
|
|
success assertion belongs to Task 01's red phase. An initial fixture omitted
|
|
the error's session scope and therefore introduced a separate summary change;
|
|
the final fixture explicitly sets scope and session identity.
|
|
|
|
This establishes false errors for aggregate-preserving events, not a confirmed
|
|
loss of a meaningful PR status change. Existing projector tests missed it
|
|
because `projectorTestStore` rejects old revisions but accepts identical
|
|
semantic payloads with newer revisions, unlike the production repository.
|
|
|
|
## Requirement conformance and assumptions
|
|
|
|
Platform owns the bounded projection contract; Tasks and Integrations retain
|
|
the authoritative source records. This is an implementation defect under
|
|
[AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.2 and .3](../../specs/platform/requirements/bounded-task-status-delivery.md)
|
|
and the design's existing semantic-no-op and persistence guarantees. Reuse the
|
|
active requirement without adding a repair-specific requirement or new IDs.
|
|
|
|
The intended behavior is settled: unchanged projections succeed silently;
|
|
real changes preserve monotonic revisions and workspace-scoped publication.
|
|
No new product behavior, schema, ownership boundary, or ADR is needed. The
|
|
design clarifies the shared equality rule. The accepted
|
|
[summary boundary ADR](../../decisions/2026-08-01-separate-task-summary-session-stream-traffic.md)
|
|
and [activity ADR](../../decisions/2026-08-17-separate-task-activity-from-summary-freshness.md)
|
|
remain authoritative.
|
|
|
|
## Scope
|
|
|
|
### In scope
|
|
|
|
- Consistent equality for every valid bounded summary and its persisted form.
|
|
- Nil/empty error collections and JSON round-trip equivalence.
|
|
- Real SQLite projector regression, publication assertions, and faithful test
|
|
store no-op behavior.
|
|
- Preservation of genuine changes, validation failures, and contention errors.
|
|
|
|
### Out of scope
|
|
|
|
- Workflow import validation/input repair, task-deletion races, diff requests
|
|
during teardown, authentication settings, and agent-provider errors.
|
|
- Changes to error normalization throughout the model domain or error text.
|
|
- Retry-count increases, suppressing all CAS warnings, database rewrites,
|
|
schema migrations, new flags, and PR polling changes.
|
|
- Frontend layout, copy, interaction, and status precedence changes.
|
|
|
|
## Technical approach
|
|
|
|
In `apps/backend/internal/task/statussummary/model.go`, implement valid-value
|
|
equality using the canonical payload already provided by `SemanticJSON`.
|
|
Compare successful encodings with `bytes.Equal`; if either encoding fails,
|
|
return false so the projector continues into its existing validation/error
|
|
path. Do not equate two encoding failures by comparing nil byte slices.
|
|
This reuses the bounded persistence contract and automatically includes future
|
|
semantic fields. Do not change the JSON shape or broaden timestamp equivalence
|
|
beyond the existing serialized representation.
|
|
|
|
Keep `persistAndPublishLocked`, its reload/rebase behavior, and the repository
|
|
SQL contract intact unless the regression demonstrates a necessary local
|
|
adjustment. Correct `projectorTestStore.CompareAndUpdateTaskStatusSummary` in
|
|
`projector_test.go` to reject an unchanged workspace and semantic payload as
|
|
well as stale revisions. Do not relax unrelated test assertions to compensate.
|
|
|
|
Add focused model tests in `model_semantic_equality_test.go` and an integration
|
|
test in `internal/task/repository/sqlite/task_status_summary_projector_noop_test.go`.
|
|
Use the existing temporary-database helpers, synthetic identities, explicit
|
|
session error scope, fixed UTC times, and synchronous event handling.
|
|
The fixture must not open the developer's database or copy private log data.
|
|
|
|
## Tests
|
|
|
|
| Evidence | Acceptance mapping |
|
|
| --- | --- |
|
|
| `TestTaskStatusSummarySemanticEqualityMatchesPersistence`: nil/empty collections independently for active/task errors, JSON round trips, timestamp monotonic metadata, ignored revision/update time, and real semantic differences | AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.2 |
|
|
| `TestTaskStatusSummarySemanticEqualityRejectsInvalidValues`: invalid summaries cannot be classified as successful no-ops | AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.2 |
|
|
| `TestTaskStatusSummaryProjectorPRNoopWithRetainedError`: live and recreated projectors, real SQLite, unchanged payload/revision, zero extra publications, no exhaustion warning | AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.2, AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.3 |
|
|
| The real-change portion of `TestTaskStatusSummaryProjectorPRNoopWithRetainedError`: later aggregate change persists once and publishes the complete next revision while preserving error and unrelated fields | AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.2, AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.3 |
|
|
| Existing pending-authority and queue contention tests with the corrected test store | AC-PLATFORM-BOUNDED-TASK-STATUS-DELIVERY-001.2 |
|
|
|
|
## E2E evidence
|
|
|
|
The real-repository integration tests cover source event, normalization,
|
|
projection, SQL persistence/reload, and complete workspace-summary publication.
|
|
They exercise the shared payload consumed by desktop and mobile. No rendered
|
|
UI changes or new browser test are needed for this internal no-op correction.
|
|
|
|
## Work orders
|
|
|
|
- [x] [Task 01: Align semantic equality and prove persistence behavior](task-01-align-semantic-equality.md)
|
|
|
|
Execution is sequential. No subagents are authorized or required.
|
|
|
|
## Related implementation records
|
|
|
|
The linked packages `bounded-task-status-delivery` (implemented),
|
|
`session-stream-overload-isolation` (complete), `backend-runtime-state-ownership`
|
|
(completed), and `deleted-session-error-summary` (done) were inventoried.
|
|
This repair does not reopen their work orders or alter their E2E matrices;
|
|
their historical verification results remain unchanged.
|
|
|
|
## Verification results
|
|
|
|
Investigation: the final temporary regression failed as expected with three
|
|
CAS retries, identical persisted JSON, and unchanged revision 1:
|
|
|
|
```bash
|
|
(cd apps/backend && go test ./internal/task/repository/sqlite -run '^TestReproSummaryPRNoopWithRetainedError$' -count=1 -v)
|
|
```
|
|
|
|
Implementation and permanent regression verification passed on 2026-09-17:
|
|
|
|
```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.
|
|
```
|
|
|
|
The production equality path now uses the same canonical semantic JSON as the
|
|
repository. The SQLite projector regression proves no-op events keep the same
|
|
revision and publication count, recreated projectors converge, and a real PR
|
|
aggregate change advances once while preserving the retained error.
|
|
Design-package checks passed on 2026-09-17:
|
|
|
|
- `python3 scripts/list-docs.py validate`: 285 decisions and 986 specifications.
|
|
- `python3 scripts/lint-spec-files.py --all`: all specification files passed.
|
|
- `python3 scripts/lint-spec-files.test.py`: 36 tests passed.
|
|
- `git diff --check`: passed.
|
|
- `git status --short -- docs/plans/task-summary-semantic-equality`: confirmed
|
|
the new package is present and untracked; it contains this plan and Task 01.
|
|
|
|
The implementation is complete in Task 01. Commit and PR delivery evidence is
|
|
recorded outside this plan.
|
|
|
|
## Risks
|
|
|
|
- Comparing canonical JSON allocates bounded payloads; keep it on the existing
|
|
semantic-event path and do not introduce transcript or polling work.
|
|
- A faithful test store may expose pre-existing tests that rely on artificial
|
|
revision bumps. Preserve their behavioral intent and diagnose each failure.
|
|
- A no-op fix must not hide real field changes, invalid values, store failures,
|
|
or genuine contention exhaustion.
|
|
- The SQLite reproduction establishes this cause but does not prove every
|
|
historical CAS error had the same cause. No SQL changes are planned; if that
|
|
scope changes, add the repository-required PostgreSQL behavioral coverage.
|