Carlos Florêncio
2.3 KiB
status, system, requirements, created, owners
| status | system | requirements | created | owners | ||
|---|---|---|---|---|---|---|
| current | tasks |
|
2026-08-28 |
|
Task plan write lifecycle System Design
Purpose and boundaries
This design defines the missing-task boundary for backward-compatible task-plan writes. It does not implement the broader task-documents migration.
Requirement mapping
| Requirement | Design section |
|---|---|
REQ-TASKS-DOCUMENTS-001 |
Transactional write and Error contract |
Components and responsibilities
internal/task/repository/sqlite.Repositoryowns the transaction and database error classification for SQLite and PostgreSQL.internal/task/service.PlanServiceowns operational logging and preserves typed repository errors.internal/task/planwsowns the shared WebSocket error contract for browser handlers and MCP handlers.
Transactional write
WritePlanRevision writes the plan head before it writes or merges a revision.
Both plan tables reference the task row with foreign keys.
If the head write reports a foreign-key violation, the repository returns the
shared ErrTaskNotFound sentinel. The transaction then rolls back. No plan head
or revision remains.
The repository uses internal/db.IsForeignKeyViolation for both supported
database dialects. It does not inspect a raw database error outside that helper.
Error contract
The plan service passes ErrTaskNotFound to its callers. It records the
expected rejection at debug level. Other write errors remain error-level
entries.
planws.CreateError and planws.UpdateError map ErrTaskNotFound to the
existing not_found WebSocket code. The response does not include a database
constraint message.
The browser and MCP surfaces use the same planws mapping. No request or
success payload changes.
Failure and recovery
A concurrent task deletion can occur after access validation and before the plan transaction. The foreign-key classification closes that race without a separate task existence query.
An unrelated database error keeps its wrapped diagnostic context. The service
records it at error level and the wire contract returns internal_error.
Test strategy
SQLite and PostgreSQL repository tests cover the sentinel and rollback. Service tests cover log severity. Shared contract tests cover browser and MCP mappings.