Files
kandev/docs/plans/workflow-session-targeting/task-05-persist-source-step-targets.md
T
2026-09-10 16:32:41 +01:00

119 lines
4.6 KiB
Markdown

---
id: "05-persist-source-step-targets"
title: "Persist source-step targets"
status: complete
wave: 5
depends_on:
- "04-prove-session-targeting"
plan: "plan.md"
requirements:
- REQ-TASKS-WORKFLOW-PROFILE-SESSIONS-001
- REQ-TASKS-WORKFLOW-PROFILE-SESSIONS-002
acceptance_criteria:
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.7
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.2
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.8
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.9
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.10
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.12
system_design:
- ../../specs/tasks/system-design/workflow-profile-session-lifecycle.md
---
# Task 05: Persist source-step targets
## Summary
Extend the working initial-target contract with direct source-step references
and durable source bindings. Initial provenance and entry retry storage remain
unchanged.
## In scope
- Add `kind: step` to backend/frontend/MCP target unions. Validate same workflow,
earlier position, direct profile override, no indirect target, and conditional
rule exclusion. Include incoming-reference validation for edit/reorder/delete.
- Portable `step_position`, template and duplication ID remapping, sync equality,
unresolved profile/source errors, and closed-kind rejection in earlier readers.
- Task-owned source-only `task_workflow_session_bindings` table. Add transactional
conditional upsert/load/cleanup, nullable session pointer, and logical profile.
- Aligned full/stub schema and template/bootstrap mappings where needed. Test
null legacy defaults without blindly changing ID-only helpers.
- Task/workflow/session deletion cleanup, stale-operation rejection, SQL guard,
required-store descriptor and fixed task adapter, replay and upgrade tests.
## Out of scope
- Replacing initial metadata with table rows.
- Runtime source selection and UI source choices.
## Acceptance
- REST/MCP create/update/clear preserve source references and reject invalid
sources without changing the workflow; initial contracts still pass.
- Export/import, template instantiation, duplication and sync remap references
correctly; readers cannot silently ignore unsupported target kinds.
- Bindings survive reopen, reject stale writes, retain profile after session
deletion, and clean up under task/workflow deletion on both databases.
## Verification
Use TDD; from the repository root:
```bash
rtk make -C apps/backend sqlguard
```
From `apps/backend`, use an isolated `KANDEV_TEST_POSTGRES_DSN`:
```bash
rtk go test ./internal/workflow/... ./internal/workflowsync/... ./config/workflows/... -count=1
rtk go test ./internal/mcp/server -run 'Test.*WorkflowStep' -count=1
rtk go test ./internal/mcp/handlers -run 'TestWorkflowStep.*Parity' -count=1
rtk go test -race ./internal/task/repository/sqlite -run 'TestWorkflowSessionBinding|TestPostgresWorkflowSessionBinding|TestWorkflowSessionTarget|TestPostgresWorkflowSessionTarget|Test.*DeleteWorkflow' -count=1
rtk go test -race ./internal/persistence/storeconformance -count=1
rtk go test ./internal/backendapp -run '^TestPostgresBootInitializesRepositories$' -count=1
```
Add explicit step-target payloads to schema/forwarding/event-parity tests.
Report PostgreSQL skips as missing evidence.
## Files likely touched
- Task 01's workflow model/controller/repository, MCP server/handler, and loader files
- `apps/backend/internal/task/repository/sqlite/workflow_session_bindings.go` and tests (new)
- `apps/backend/internal/task/repository/sqlite/{base_schema.go,base_migrations.go,workflow.go}`
- Task models/repository interfaces and session/task deletion paths
- `apps/backend/internal/persistence/{requiredstores,storeconformance}/`
- `apps/backend/AGENTS.md` for binding ownership
- `apps/web/lib/types/http.ts` and related workflow contracts
## Dependencies
Task 04 completes the initial slice. Task 01's metadata and version contract are
reused; do not recreate them.
## Risks
A duplicate/import can retain foreign source IDs. A reorder or deletion can
invalidate dependents. Profile removal and sync must validate the whole result.
Table cleanup must cover workspace reset as well as direct deletion.
## Inputs
- Design: Explicit recipient contract; Source-step bindings.
- Existing `RemapStepID`, `pull_from_step_position`, MCP parity tests.
- `workflow.go` is relevant for deletion; `builtin_workflow_step_rows.go`
is an ID lookup, not a target-value mapping.
## Parallelism
`sequential`
## Results
Implemented the source-step target variant, binding table, migrations, required
store inventory, cleanup, portable step-position remapping, and stale-operation
guards. Binding repository tests and task repository race tests passed; full
store conformance passed 290 tests.