kandev/docs/plans/workflow-session-targeting/task-05-persist-source-step-targets.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
05-persist-source-step-targets	Persist source-step targets	complete	5	04-prove-session-targeting	plan.md	REQ-TASKS-WORKFLOW-PROFILE-SESSIONS-001 REQ-TASKS-WORKFLOW-PROFILE-SESSIONS-002	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	../../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:

rtk make -C apps/backend sqlguard

From apps/backend, use an isolated KANDEV_TEST_POSTGRES_DSN:

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.