4.0 KiB
id, title, status, wave, depends_on, plan, spec
| id | title | status | wave | depends_on | plan | spec | ||
|---|---|---|---|---|---|---|---|---|
| 03-ledger-schema-migration | Ledger schema and migration | done | 3 |
|
plan.md | ../../specs/tasks/requirements/workflow-task-step-transition-ledger.md |
Task 03: Ledger schema and migration
Create task_step_transitions idempotently on SQLite and Postgres, register its
contract, and prove the replay behaviour. No writer yet — this task ends with an
empty table that boots cleanly three times in a row.
Gated. Do not start until Slice 1 has shipped and been measured per the
spec's Gate between slices. Record the measurement (share of post-activation
turns carrying the stamp, and the resulting change in the 47.0 / 30.5 / 22.5
attribution split) in this task's ## Results before proceeding. If the
measurement is inconclusive, the recorded default is that Slice 2 proceeds as
specified — note that and continue.
Acceptance
task_step_transitionsexists with the spec's exact columns, both indexes, a cascade FK totasks, a set-null FK totask_sessions, and no FK toworkflowsorworkflow_steps.- A database created before this feature gains the table on boot; pre-existing tasks have no rows and nothing is backfilled.
- Running the migration runner twice more succeeds both times and changes nothing, on SQLite and on Postgres.
Verification
cd apps/backend && go test ./internal/task/repository/sqlite/... ./internal/telemetrycontract/... && KANDEV_TEST_POSTGRES_DSN="${KANDEV_TEST_POSTGRES_DSN}" go test -run 'Postgres|StepTransition' ./internal/task/repository/sqlite/... && make lint
Record in ## Results whether the Postgres leg ran or skipped.
Files likely touched
apps/backend/internal/task/repository/sqlite/base_schema.go— newinitStepTransitionsSchema, appended to theinitSchemastep list afterinitSessionSchemaand beforerunMigrationsapps/backend/internal/task/repository/sqlite/step_transitions_migration_test.go(new)apps/backend/internal/telemetrycontract/contract.go— registertask_step_transitionsat version 1 with its existence and stats queries
Dependencies
Tasks 01 and 02, plus the Slice 1 measurement gate.
Parallelism
sequential.
Inputs
- Spec,
task_step_transitions(new), Persistence guarantees, Migration and activation, and Scenarios → Migration and activation - Plan, Area 3
internal/workflow/repository/sqlite.go:88-96is the working precedent for the dialect-split monotonicid(INTEGER PRIMARY KEY AUTOINCREMENTon SQLite,BIGSERIAL PRIMARY KEYon Postgres). Copy that shape.- This is a new table, so
CREATE TABLE IF NOT EXISTSin the init block is correct and complete. The backend guide's "columns only viarunMigrations" rule applies to adding a column to an existing table and does not apply here. - Deliberately no FK to
workflow_stepsorworkflows. Steps get deleted, and the historical fact that a card was in a now-deleted step must survive that deletion. A reviewer may read the missing FK as an oversight; the DDL should carry a comment saying it is not. - Nothing is backfilled with a substituted value. Pre-activation state is absent, and absent is the correct reading.
- Model the test on
task_external_id_migration_test.go: seed a pre-migration row, run migrations, assert the pre-existing row is untouched and the new objects exist, then callNewWithDBtwice more and assert idempotence. - Use
internal/db'sIsDuplicateColumnError/IsAlreadyExistsErrorfor any replay classification, never local string matching (ADR 0027).
Output contract
Summary, files changed, tests run with counts, the Slice 1 gate measurement,
blockers, risks, and a status update to this file and plan.md in the same
conversation.
Results
See plan.md § Verification Results for the consolidated commands, outcomes, and decision record covering all six tasks (implemented and committed together).