Files
kandev/docs/specs/tasks/requirements/runner-switch-before-materialization-action.md
T
2026-09-13 15:25:16 +01:00

267 lines
17 KiB
Markdown

---
status: draft
system: tasks
created: 2026-09-07
owners:
- kandev
---
# Runner Switch Before Materialization Action Requirements
## Overview
The runner switch action itself: how a runner change is authorized, serialized,
applied, and refused. The mutability rule the action enforces is in
[Runner switch before materialization](runner-switch-before-materialization.md);
what a successful switch changes, and the surface a user drives it from, are in
[Runner switch before materialization effects](runner-switch-before-materialization-effects.md).
This file exists because the parts together exceed the requirement file-size
limit. The split is by layer, not by importance: every acceptance criterion
keeps the identifier it had when they were one document.
## Requirements
### REQ-TASKS-RUNNER-SWITCH-002: Runner switch action
**Intent:** Changing a task's runner is one authorized, atomic, retry-safe
operation that either moves the runner or explains precisely why it cannot,
and that never damages the rest of the task's metadata.
#### Acceptance criteria
- **AC-TASKS-RUNNER-SWITCH-002.1:** The system shall expose a task action named
`task.runner` accepting a payload with `id` naming the task and
`executor_profile_id` naming the target runner. The action name shall consist
of the task namespace plus exactly one further segment, so that the existing
authorization backstop for top-level task actions applies and promotes `id`
to the task identifier.
- **AC-TASKS-RUNNER-SWITCH-002.2:** The system shall authorize the caller against
the named task before evaluating either gate, at the position
AC-TASKS-RUNNER-SWITCH-002.17 fixes. This authorization shall run for every
caller on every transport, including the WebSocket gateway. The gateway-level
backstop is an additional layer for that one transport and shall never be the
only authorization for the operation: the service shall not vary its
authorization by the transport a request arrived on, and shall not depend on
being able to determine that transport.
- **AC-TASKS-RUNNER-SWITCH-002.3:** When the action executes, the system shall
re-evaluate every condition of AC-TASKS-RUNNER-SWITCH-001.3 inside a single
transaction that is serialized against session creation and task lifecycle
cleanup for the same task.
- **AC-TASKS-RUNNER-SWITCH-002.3a:** The serialization rule is general and is
stated once, because enumerating a subset of the conditions is what lets the
remainder race. **Every writer that can cause any condition of
AC-TASKS-RUNNER-SWITCH-001.3 to begin holding for a task, or that can change
which repository the compatibility gate of AC-TASKS-RUNNER-SWITCH-002.7
resolves against, shall take the same task-scoped lock the switch takes.** The
second clause is not a separate rule: a verdict computed against a repository
the task no longer has is as wrong as a gate condition that began holding
unobserved, and a writer that swaps a repository link in place changes no row
count, so the first clause alone would not reach it. No condition is exempt on
the ground that its row is reached through a session: none of the rows the gate
reads is keyed to a session, and a condition that is only observed rather than
serialized is not enforceable. The guarantee
AC-TASKS-RUNNER-SWITCH-002.13 gives for sessions shall hold identically for
every writer in scope: the switch commits first and the writer proceeds against
the new runner, or the writer commits first and the switch is refused with that
condition's code. A writer added later that can make a gate condition hold, or
can change the resolved repository, falls under this criterion without it being
amended.
- **AC-TASKS-RUNNER-SWITCH-002.3b:** The set of writers in scope for
AC-TASKS-RUNNER-SWITCH-002.3a is finite, is determined by audit rather than by
assumption, and shall be enumerated so the obligation is bounded and testable
rather than left for whoever implements it to discover. A writer satisfies the
rule in one of two ways, and the distinction is what bounds the work:
1. **Already satisfied, no change required** — the writer updates the task's own
row, and so takes that row's lock inherently, or takes the task-scoped lock
explicitly. Archiving the task, writing the task's host workspace path, and
writing the task's workspace mode are all writes to the task row. Session
creation and task environment creation take the task-scoped lock explicitly.
2. **Requires the lock to be added** — the writer writes a different table and
takes no task-scoped lock today. This capability shall bring each of these
under the same lock: the running-executor record write (condition 6); the
workspace source attachment that creates repository links and workspace
folder attachments (conditions 2, 3 and 7), which today takes the lock only
when it is also checking an expected parent and therefore takes none at all
for a task with no parent — the shape this capability most commonly serves;
the workspace group membership insert (condition 9), which is owned by the
office system rather than the task system; and the in-place update of an
existing task-repository link, which is in scope under the second clause of
AC-TASKS-RUNNER-SWITCH-002.3a.
Each writer in class 2 shall have its own acceptance evidence: a demonstration
that it and a concurrent switch produce one of the two outcomes
AC-TASKS-RUNNER-SWITCH-002.3a permits and never a third. For the three writers
that make a gate condition begin holding, those two outcomes are the ones that
criterion names: switch first and the writer proceeds against the new runner, or
writer first and the switch is refused with that condition's code. The in-place
link update has no condition code, because it makes no condition hold; its two
outcomes are that the switch commits first and the link update then applies, or
the link update commits first and the switch is refused as the retriable
`evaluation_unavailable` of AC-TASKS-RUNNER-SWITCH-002.7c. Both are outcomes the
closed vocabulary already contains; this criterion introduces none. A writer in class 1
shall have the same evidence, but needs no code change to produce it. An
implementation that changes no writer cannot satisfy this criterion, and one
that reports the rule as met without per-writer evidence has not met it.
- **AC-TASKS-RUNNER-SWITCH-002.4:** When a switch succeeds, the only task
metadata that changes shall be the stored executor profile identifier. Every
other metadata entry, including the agent profile identifier and any deferred
launch record, shall be unchanged afterwards.
- **AC-TASKS-RUNNER-SWITCH-002.5:** When a switch is rejected for any reason,
the system shall persist no change to the task.
- **AC-TASKS-RUNNER-SWITCH-002.6:** When a switch is rejected because the
mutability gate fails, the system shall return a typed conflict carrying the
same reason code, chosen by the same ordering, that
AC-TASKS-RUNNER-SWITCH-001.3 defines.
- **AC-TASKS-RUNNER-SWITCH-002.7:** When the mutability gate passes but the
target runner requires a git clone URL and the task's repository provides
none, the system shall reject the switch with the typed conflict
`target_cannot_materialize_repository`. This code shall never appear in the
projection defined by REQ-TASKS-RUNNER-SWITCH-001, because it describes the
target rather than the task.
- **AC-TASKS-RUNNER-SWITCH-002.7a:** Clone-URL resolution shall distinguish a
determinate answer from a failed lookup. A candidate that is absent, empty, or
whitespace-only supplies no URL and resolution continues to the next candidate.
Only an exhausted candidate list shall reject with
`target_cannot_materialize_repository`. A candidate that cannot be evaluated,
because the lookup errored or timed out, shall reject with
`evaluation_unavailable` per AC-TASKS-RUNNER-SWITCH-002.18. A transient failure
to read a repository's origin shall never be reported as a permanent statement
that the repository cannot be moved.
- **AC-TASKS-RUNNER-SWITCH-002.7b:** The compatibility gate shall not be
evaluated while the task row lock is held. The target profile's executor, its
clone-URL requirement, and any repository clone URL shall be resolved before
the transaction of AC-TASKS-RUNNER-SWITCH-002.3 opens, so no filesystem or
subprocess call occurs inside the locked section. Resolution shall be bounded
by a timeout; exceeding it is a failed lookup under
AC-TASKS-RUNNER-SWITCH-002.7a. What may be resolved early is only what the
filesystem or a subprocess is needed for; which repository the task has is a
task-scoped fact and is governed by AC-TASKS-RUNNER-SWITCH-002.7c, not by this
criterion. Resolving early does not move the decision: the
resolved result is applied at stage 6 of AC-TASKS-RUNNER-SWITCH-002.17, so a
task that fails the mutability gate reports that gate's code even when the
target is also incompatible.
- **AC-TASKS-RUNNER-SWITCH-002.7c:** A compatibility verdict is only valid for
the repository it was computed against, because it is resolved before the
transaction that validates which repository the task has. The system shall
record the identity of the repository the resolution used, and inside the
transaction, after the mutability gate has passed, shall confirm that the
task's single attached repository is still that same repository. This
confirmation shall compare both the repository identity and the link's
last-updated column, `task_repositories.updated_at`, against the values
observed at resolution time, so that a link mutated in place is detected even
though its identity column may not have moved. This confirmation is a
task-scoped read of two columns and involves no filesystem or subprocess call,
so it does not violate AC-TASKS-RUNNER-SWITCH-002.7b. It is a second line of
defence rather than the primary one: the writer that mutates the link is
itself in scope for AC-TASKS-RUNNER-SWITCH-002.3a, and the confirmation exists
so that a writer added outside that rule is still caught. When the repository has changed, the resolved
verdict shall be discarded and the request shall reject as
`evaluation_unavailable` under AC-TASKS-RUNNER-SWITCH-002.18, which is
retriable, rather than applying a verdict computed against a repository the
task no longer has. When the task does not have exactly one repository
attachment at resolution time, resolution shall be skipped and shall yield no
verdict; the request then reports `no_repository` or `multiple_repositories`
from the mutability gate at stage 5, and skipping shall never itself produce an
outcome. This keeps the ordering of AC-TASKS-RUNNER-SWITCH-002.17 intact: the
compatibility gate can only ever speak at stage 6.
- **AC-TASKS-RUNNER-SWITCH-002.8:** An identifier in this payload is **blank**
when it is absent, empty, or contains only whitespace. That single definition
governs every identifier the action accepts, so `id` and `executor_profile_id`
are judged by the same test and a whitespace-only value is never treated as a
value that could be looked up. When either identifier is blank the system shall
reject the request as invalid. A blank `executor_profile_id` shall never be
interpreted as clearing the task's runner, and a blank `id` shall be reported
as invalid rather than as not found.
- **AC-TASKS-RUNNER-SWITCH-002.9:** When the payload names a task that does not
exist, the system shall reject the request as not found, distinctly from every
conflict code.
- **AC-TASKS-RUNNER-SWITCH-002.10:** When the payload names an executor profile
that does not exist, or one whose executor is not available for use, the
system shall reject the request as invalid, distinctly from every conflict
code. An executor is available for use when it is not soft-deleted **and** its
status is active; failing either test makes it unavailable, and both produce
the same invalid outcome.
- **AC-TASKS-RUNNER-SWITCH-002.11:** When a switch names the executor profile
the task already stores, the system shall report success, shall leave the
stored value unchanged, and shall publish a task-updated event only when the
stored value actually changed. This success is reported only after both gates
have passed; naming the already-stored profile shall not bypass either. A task
that has since materialized therefore receives the gate's conflict code, not
success, even when the requested profile equals the stored one.
- **AC-TASKS-RUNNER-SWITCH-002.12:** When two switches for the same task run
concurrently, the system shall serialize them on the task. Both may succeed;
the stored runner afterwards shall be the one written by the transaction that
committed second, and no intermediate or blended metadata state shall be
observable.
- **AC-TASKS-RUNNER-SWITCH-002.13:** When a switch and a session creation for
the same task run concurrently, the system shall produce exactly one of two
outcomes: the switch commits first and the session is then prepared with the
new runner, or the session commits first and the switch is rejected with
`session_exists`. The system shall never leave a changed runner alongside a
session that was prepared under the previous runner.
- **AC-TASKS-RUNNER-SWITCH-002.14:** When a caller repeats the same switch after
an ambiguous failure, without supplying any idempotency token, and the task's
materialization state has not changed in between, the system shall reach the
same terminal state as a single successful call. The action assigns a value
rather than accumulating one, so retries need no deduplication key. When the
task did materialize in between, the repeat is refused by the gate per
AC-TASKS-RUNNER-SWITCH-002.11; the stored runner remains the one the first call
committed, so only the reported outcome differs.
- **AC-TASKS-RUNNER-SWITCH-002.15:** When a switch and an archive of the same
task run concurrently, the system shall serialize them: either the switch
commits before the archive, or the switch is rejected with `task_archived`. A
switch shall never commit against an archived task.
- **AC-TASKS-RUNNER-SWITCH-002.16:** The comparison in
AC-TASKS-RUNNER-SWITCH-002.11 shall be against the value the task stores, not
against the runner the task would otherwise resolve. Storing an explicit
executor profile on a task that previously stored none is a change even when
the named profile is the one the workspace default would have selected.
- **AC-TASKS-RUNNER-SWITCH-002.17:** When more than one rejection class applies
to the same request, the system shall report the outcome of the **first**
failing stage in exactly this order, so that a given request always produces
the same outcome regardless of implementation:
1. **Malformed request** (invalid): `id` or `executor_profile_id` blank in the
sense AC-TASKS-RUNNER-SWITCH-002.8 defines. Evaluated before any lookup, so
a blank identifier never reaches the not-found or target-invalid stages.
2. **Task not found** per AC-TASKS-RUNNER-SWITCH-002.9.
3. **Caller not authorized** per AC-TASKS-RUNNER-SWITCH-002.2, after existence
so the outcome matches the other top-level task actions.
4. **Target invalid** per AC-TASKS-RUNNER-SWITCH-002.10.
5. **Mutability gate** per AC-TASKS-RUNNER-SWITCH-002.6, itself ordered by
AC-TASKS-RUNNER-SWITCH-001.3.
6. **Compatibility gate** per AC-TASKS-RUNNER-SWITCH-002.7.
7. **Assignment**, including the no-op of AC-TASKS-RUNNER-SWITCH-002.11.
An evaluation failure under AC-TASKS-RUNNER-SWITCH-002.18 may arise at stages
2 and 4 through 7 and preempts the outcome of the stage where it occurs. Stage
7 is included because that criterion covers the write and the commit, not only
the reads: a request that passed every gate and then failed to commit reports
the retriable outcome rather than a success or a conflict.
- **AC-TASKS-RUNNER-SWITCH-002.18:** When the system cannot complete an
operation it needs in order to decide or to apply the request, the action shall
reject with a typed `evaluation_unavailable` outcome, distinct from every
mutability conflict code, from `target_cannot_materialize_repository`, and from
the invalid and not-found outcomes. It shall be marked retriable and shall
persist no change per AC-TASKS-RUNNER-SWITCH-002.5. **This covers writes and
not only reads:** a failure to acquire the task-scoped lock, a failure of the
metadata write, and a failure to commit the transaction all produce this
outcome, exactly as a failed read does. Naming only reads would leave the write
path with no outcome class at all, and the caller would receive something
outside the vocabulary AC-TASKS-RUNNER-SWITCH-004.4b is required to present.
Such a failure shall never be reported as a mutability conflict: a conflict
says the task is ineligible, a failed operation only that the system could not
complete it. A caller that receives it may repeat the request under
AC-TASKS-RUNNER-SWITCH-002.14, which is why this outcome and only this outcome
is retriable.
- **AC-TASKS-RUNNER-SWITCH-002.19:** A task-updated event for a runner change
shall carry the task's updated-at value from the committing transaction, and a
client shall ignore an event whose updated-at is older than the value it holds
for that task. Clients receiving two switches' events out of order shall
converge on the value written by the transaction that committed second, per
AC-TASKS-RUNNER-SWITCH-002.12. Ordered delivery is not required; a late event
must not overwrite a newer one.