Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
32 KiB
status, system, created, owners, requirements
| status | system | created | owners | requirements | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| draft | office | 2026-09-02 |
|
|
Step Entry Dispatch Convergence System Design
Implements
step-entry-dispatch-convergence.md
and the three requirement files separated from it, each of which governs more
than convergence and is stated once on its own:
step-entry-recovery-scan.md
(REQ-004),
step-entry-run-coalescing.md
(REQ-005), and
step-entry-fanout-reporting.md
(REQ-007). Builds on
step-entry-sequence-execution.md
and the legacy
workflow-on-enter-action-dispatch
spec, which is not edited.
Current shape
Two dispatchers execute a step's declared entry sequence for one arrival.
| Ledger dispatcher | Marker dispatcher | |
|---|---|---|
| Entry point | Repository.dispatchStepEntry after each writer's commit |
processOnEnter -> dispatchOnEnterActions |
| Executor | Engine.DispatchStepEntry |
dispatchEngineOwnedOnEnterAction |
| Kind list | sessionIndependentActionKinds |
case OnEnterClearDecisions, OnEnterQueueRunForEachParticipant |
| Entry identity | task_step_transitions row id (string) |
workflow_step_entries row id (int64) |
| Idempotency key input | ActionInput.EntryID |
ActionInput.OperationID = step_entry:<id>:<pos> |
| Claim | none | ClaimStepEntryMarker compare-and-set |
| Route coverage | every registered step-transition writer | on_turn_complete only (finalizeStepEnter passes entryID=0) |
clear_decisions and queue_run_for_each_participant appear in both kind
lists. On the on_turn_complete route both dispatchers run for the same
commit: updateTaskWithWorkflowStepAdmission allocates the
workflow_step_entries row, writes the ledger row, commits, then calls
dispatchStepEntry; applyEngineTransition then reads the allocated entry id
back through the result holder and calls launchProcessOnEnter. Because
idempotencyKey prefers EntryID and falls back to OperationID, the two
paths produce different keys for the same logical action, so neither the
idempotency window nor coalescing collapses the second run.
Three kinds were already reconciled - queue_run, run_code_review,
ensure_participant_seat are dispatched only by the ledger path, with a
comment in dispatchOnEnterActions saying so. The two kinds above were not.
Verified state
Measured on feature/fix-on-enter-dispatc-77a at 646ff0063, 2026-09-02.
These correct the inherited finding list, which predates the ledger dispatcher.
Already satisfied; no requirement below restates them:
- The
workflow-on-enter-action-dispatchAC-F1 stop rule is implemented:dispatchEngineOwnedOnEnterActionreturnsabandonfor a priorin_progressmarker anddispatchOnEnterActionsbreaks its loop. - The single-session duplicate-turn race no longer reproduces: five runs of
go test -race -count=3 -run 'TestProcessOnEnter_|TestProcessOnTurnComplete_Concurrent' ./internal/orchestrator/passed (previously 2 of 7 failed). A third signal,turnCompletionConsumedGeneration, closed it. - Participant de-duplication on
(role, agent_profile_id)is implemented inroleSeatsForFanOut. - Fan-out failure isolation is collect-and-continue, not abort-on-first-error.
Decision: the ledger dispatcher is the single owner
The ledger path becomes the owning dispatcher for every session-independent kind, including the two currently shared. The marker path stops executing them.
Chosen because the ledger path already satisfies AC-OFFICE-STEP-ENTRY-001.1 on
every route, while the marker path reaches only on_turn_complete. Moving
ownership the other way would mean re-wiring the four remaining routes onto the
result-holder mechanism, which is the work
step-entry-sequence-execution.md already did once.
The cost is that the ledger path holds no marker, so it does not satisfy
AC-OFFICE-STEP-ENTRY-DISPATCH-002.4 as it stands. The marker machinery is
therefore kept and moved, not deleted: workflow_step_entries,
workflow_step_entry_markers, ClaimStepEntryMarker,
CompleteStepEntryMarker, GetStepEntryMarkerState, and
ClearStepDecisionsAndCompleteMarker stay, and the ledger dispatcher claims
through them before executing a kind that requires durability.
This keeps one entry identity where there is one. For a step declaring at
least one marker-bearing kind, the workflow_step_entries row is the entry
identity for markers and idempotency keys on the three updateTaskTx sites
with a result holder; the other six still key off the ledger row id. For a
step declaring none, no entry is allocated
and its runs keep deriving their key from the
step-transition row id as they do today - the work step's
auto_start_agent-only sequence. idempotencyKey
therefore keeps both branches rather than collapsing to EntryID, and which
branch applies is read from the ownership declaration's marker-bearing column,
not from whether an entry row happens to exist
(AC-OFFICE-STEP-ENTRY-DISPATCH-002.8). Allocation already happens inside the
transition transaction whenever a result holder is attached; it becomes
unconditional for a step declaring at least one marker-bearing kind.
Ownership declaration
One exported table in internal/workflow/stepentry maps action kind to two
independent properties: its owning dispatcher, and whether it is
marker-bearing. Both Engine.DispatchStepEntry and
dispatchOnEnterActions read the
table; neither keeps a private list. This satisfies
AC-OFFICE-STEP-ENTRY-DISPATCH-002.1, and it is what makes 002.3's silent skip
safe - a kind with an owner elsewhere is not a discard.
Each column has its own seed, and they are different functions. The
ownership column is seeded from sessionIndependentActionKinds (five kinds);
the marker-bearing column is seeded from IsEngineOwnedOnEnter (two kinds).
IsEngineOwnedOnEnter reads like an ownership predicate because of its name,
but its doc comment and body are explicit that it reports what the marker
system dispatches, and it returns true for exactly clear_decisions and
queue_run_for_each_participant. Seeding ownership from it would silently drop
queue_run, run_code_review and ensure_participant_seat; seeding
marker-bearing from sessionIndependentActionKinds would promise a marker for
three kinds that have never carried one. Either substitution inverts the table.
This is the settled membership, and it is the set every criterion quantifying over marker-bearing positions reads:
| Action kind | Owning dispatcher | Marker-bearing |
|---|---|---|
clear_decisions |
ledger | yes |
queue_run_for_each_participant |
ledger | yes |
queue_run |
ledger | no |
run_code_review |
ledger | no |
ensure_participant_seat |
ledger | no |
enable_plan_mode |
marker | no |
auto_start_agent |
marker | no |
reset_agent_context |
marker | no |
set_session_mode |
marker | no |
configure_session |
marker | no |
configure_session is the tenth row, produced by neither seed and written in by
hand. CompileOnEnterAction has no case for it, so the engine has
no ActionKind for it and DispatchStepEntry can never reach it; only
processOnEnter executes it, inline before dispatchOnEnterActions. It is
marker-owned and not marker-bearing, like the other four session-shaped kinds.
Do not express that by adding it to sessionShapedActionKinds:
entrydispatch_test.go asserts both engine maps list only kinds
CompileOnEnterAction emits, so that edit fails the suite. The ownership table
is wider than either engine map: AC-OFFICE-STEP-ENTRY-DISPATCH-002.1 classifies
every kind either dispatcher can reach, not every kind the engine compiles.
Marker-bearing stays at exactly the two kinds that carry a marker today. This convergence moves ownership; it does not extend durability to kinds that never had it, which would be new work and is not required by AC-OFFICE-STEP-ENTRY-DISPATCH-002.4. The three ledger-owned kinds that are not marker-bearing keep deriving their idempotency key from the step-transition row id exactly as they do now, including inside a step that allocates an entry for some other position.
The two columns must stay separate because they genuinely differ. The shipped
office-default Review and Approval steps declare
[clear_decisions, ensure_participant_seat, queue_run_for_each_participant]:
after convergence the ledger dispatcher owns all three, but
ensure_participant_seat is executed without a marker. Reading marker-bearing
off the ownership column would make position 1 of every production entry a
position that can never hold a marker, and every rule quantifying over "the
entry's positions" would then be evaluating a set it can never satisfy.
Ordering within and across owners
Within one owner, the dispatcher walks the declared sequence in position order
and skips kinds it does not own, so relative order among the kinds it does own
is preserved - this is AC-OFFICE-STEP-ENTRY-DISPATCH-002.7, and it is what
guarantees a declared clear_decisions commits its delete before the fan-out
that follows it, both being ledger-owned after convergence.
That ordering alone is not enough, and the stop rule has to move with the
ownership. Engine.DispatchStepEntry is record-and-continue by contract - its
doc comment cites AC-OFFICE-STEP-ENTRY-001.4 and .6 - while the marker path
being retired breaks its loop on a failed or claim-lost action, which is AC-F1.
Verified state lists AC-F1 as already satisfied, but it is satisfied on the
path convergence retires, so moving ownership silently drops it. On the shipped
Review and Approval steps clear_decisions is position 0 and the fan-out is
position 2: without the stop rule a failed or claim-lost decision clear would be
recorded and the fan-out would still run, waking reviewers against decisions
that were never cleared, and quorum could then count a stale decision beside a
new one. That is the precise harm REQ-OFFICE-STEP-ENTRY-DISPATCH-002's Overview
exists to remove, so the ledger dispatcher abandons the remainder of an entry's
sequence when a marker-bearing position fails or loses its claim
(AC-OFFICE-STEP-ENTRY-DISPATCH-002.10). AC-OFFICE-STEP-ENTRY-001.4 admits this:
it continues-on-error "except where another acceptance criterion states
otherwise". The narrowing is deliberate and minimal - it is scoped to
marker-bearing positions, so a failing ensure_participant_seat still lets the
rest of the sequence run, exactly as record-and-continue intends.
Across owners there is no ordering guarantee and none is added. The ledger
dispatcher runs synchronously after tx.Commit(); the marker dispatcher runs on
the goroutine launchProcessOnEnter starts afterwards. Interleaving them would
mean making one wait on the other - either blocking the transition writer on a
goroutine or moving the marker path back inline - and both are larger changes
than this design carries. No shipped workflow declares a step whose entry
sequence mixes owners, so nothing in the tree depends on the guarantee that is
absent; the requirement's Out of scope states this as a known limit rather than
an oversight.
Task-scoped turn completion
turnCompletionLocks is re-keyed from session id to task id, and so is the
staleness decision. turnCompletionConsumedGeneration stays session-keyed -
it is not re-keyed, and it is not deleted; the paragraph below states why, and
AC-OFFICE-STEP-ENTRY-DISPATCH-003.2 requires exactly that split.
acquireTurnCompletionCriticalSection takes the task id it already has in
scope.
The generation guard's meaning changes with the key and must be restated:
keyed by session, it compared the caller's session snapshot UpdatedAt against
the last consumed one for that session. Keyed by task, a snapshot from session
B is not comparable to one recorded for session A. The guard therefore stores
the winning transition's identity for the task - the destination step id and
the commit time - and a caller is rejected when its own observed step already
differs from the task's current step. The step comparison already in the
critical section carries this; the generation map's role narrows to rejecting a
redelivery of the same session snapshot, which stays session-keyed inside a
task-keyed critical section rather than replacing it.
AC-OFFICE-STEP-ENTRY-DISPATCH-003.2 is satisfied by that split, and the AC now
states it explicitly: the staleness guard - the one deciding whether a
caller's observed step is still current - is task-keyed, and the retained
session-keyed map is the narrower redelivery check, which the criterion does
not govern. Both are required; neither substitutes for the other. Deleting
turnCompletionConsumedGeneration would lose same-session redelivery
de-duplication and is not what 003.2 asks for.
Both maps are in-process (sync.Map), so REQ-OFFICE-STEP-ENTRY-DISPATCH-003's
guarantee is scoped to one backend process, which the requirement's Out of
scope now states. No advisory or row lock is introduced.
processOnChildrenCompleted keeps lockChildCompletionOperation for its own
per-operation de-duplication and additionally takes the task lock before
reaching applyEngineTransition. Lock order is task lock first, then operation
lock, everywhere, so the two cannot deadlock.
allocateStepEntryIfPending computes entry_seq as SELECT COUNT(*) then
INSERT. Under the task lock of
AC-OFFICE-STEP-ENTRY-DISPATCH-003.1 two callers for one task cannot interleave
that read and write, so within a single backend process the race is closed by
serialization, not by the constraint. It is left as is rather than rewritten to
MAX(entry_seq)+1 because the UNIQUE(task_id, step_id, entry_seq) constraint
remains a correct backstop: a lost race surfaces as a failed transition, which
is the behavior AC-OFFICE-STEP-ENTRY-DISPATCH-008.3 asserts and
AC-OFFICE-STEP-ENTRY-DISPATCH-008.4's sibling test at the repository layer
covers. The constraint is defence in depth here, not the primary guarantee.
Startup recovery
Implements
step-entry-recovery-scan.md,
which states REQ-OFFICE-STEP-ENTRY-DISPATCH-004 in full. A single scan runs in
backend start, after the store opens and before the engine serves triggers,
alongside the existing startup recovery sweeps. Its selection is a join over
workflow_step_entries and its markers alone - no workflow declaration is
loaded, so an entry whose declaration is unreadable is still selected and still
reaches 004.3's unresolvable rule. It orders by
(task_id, step_id, entry_seq), applies the skip rules in
AC-OFFICE-STEP-ENTRY-DISPATCH-004.3, and re-dispatches what survives through
the same owning dispatcher a live arrival uses. Loading the declaration is
needed only to re-dispatch a surviving entry; a failure to load it there is
itself the unresolvable skip.
Because the scan runs before the engine serves triggers, an in_progress
marker cannot belong to a live dispatcher, so it is read as failed with no
lease and no wall-clock threshold. That is what makes the atomic-clear
rollback recoverable: ClearStepDecisionsAndCompleteMarker leaving the marker
in_progress proves the delete did not commit, and the entry is marked
terminal rather than re-run, per 004.5 and the legacy spec's AC-C2.
Every failure inside the scan is logged and skipped. The scan never blocks startup (004.2).
Reclaim: how a stranded position is re-executed
The scan cannot reuse the live-dispatch claim. ClaimStepEntryMarker is
INSERT-only: it returns claimed=false for any existing
(entry_id, position) row, whatever its state, and
CompleteStepEntryMarker only UPDATEs rows already in_progress. A scan built
on those two would abandon every entry it was written to rescue, satisfying
AC-OFFICE-STEP-ENTRY-DISPATCH-008.4 and failing 004.7. The two paths are
therefore distinct, per AC-OFFICE-STEP-ENTRY-DISPATCH-004.8:
- Live dispatch keeps
ClaimStepEntryMarkerunchanged. Losing to an existing row still means "do not execute", which is what 008.4 asserts. - Recovery adds
ReclaimStepEntryMarker(ctx, entryID, position, operationID, claimedAt) (bool, error), a state-predicated compare-and-set:UPDATE workflow_step_entry_markers SET state='in_progress', operation_id=?, claimed_at=?, error=NULL WHERE entry_id=? AND position=? AND state IN ('in_progress','failed'). It reportsreclaimedfrom the affected row count, so adoneorskippedrow is never taken over and a completed position is never executed twice. A position with no row at all is not stranded and takes the ordinaryClaimStepEntryMarkerinsert.
Reclaim is safe without a lease only because of the ordering guarantee: the scan runs before the engine serves triggers, so no in-process dispatcher can hold the row it supersedes. That ordering is load-bearing, not incidental.
Where terminality lives
workflow_step_entries has no state column and does not gain one: entry
terminality stays derived, per AC-OFFICE-STEP-ENTRY-DISPATCH-004.9, which avoids
an entry-level state that could disagree with its own markers. What it is
derived from changes.
It cannot be derived from the positions the step's declaration currently declares. Two cases break that reading, and both are live:
- A declaration can name a position that is not marker-bearing -
ensure_participant_seatat position 1 of the shipped Review and Approval steps - so "every declared position holds a terminal marker" is unsatisfiable for every production entry, and the scan would re-select them all at every process start, forever. AC-OFFICE-STEP-ENTRY-DISPATCH-004.3must retireunresolvableanddigest_changedentries, whose declaration is respectively unreadable and no longer shape-identical. Enumerating positions by re-reading the declaration is impossible in the first case and wrong in the second.
The entry row therefore stores its allocated position set: the ordered list of marker-bearing positions, computed once from the ownership declaration at allocation time and written inside the same transaction as the entry row.
r.migrate.Apply("workflow_step_entries.marker_positions",
`ALTER TABLE workflow_step_entries ADD COLUMN marker_positions TEXT NOT NULL DEFAULT ''`)
The value is the comma-separated ascending position list. "" is the legal
representation of "no marker-bearing positions"; BuildPendingAllocation
already declines to allocate in that case, so only a pre-existing row carries
it, and such a row reads as already terminal rather than as stranded work:
those rows predate the scan and have no marker to resume. BuildPendingAllocation
already computes this set to decide whether to allocate at all; it now returns
it, and the repository persists it.
A value that does not parse as a position list is not repaired: the entry is terminal by definition and one ERROR names it, per AC-OFFICE-STEP-ENTRY-DISPATCH-004.9. There is no position to resume and none to retire, so any other reading re-selects it at every process start forever - the same deadlock deriving from the declaration produced.
Terminality is then decidable from the store alone: an entry is non-terminal
exactly while some position in its stored marker_positions has no terminal
marker. No workflow declaration is loaded to answer the question, which is what
lets AC-OFFICE-STEP-ENTRY-DISPATCH-004.1 select an unresolvable entry at all,
and what lets 004.3 retire it by writing a terminal marker for each position in
that stored set.
The marker states become in_progress, done, failed, and a new
skipped - terminal, and distinct from both done (ran, succeeded) and
failed (enqueue attempted, did not succeed). Without the fourth value a
skipped position would have to lie in one direction or the other. 004.3 reads
the two alike only on a clear_decisions position, and apart everywhere else.
The reason is stored in a new nullable skip_reason column, added the way this
repository adds columns - r.migrate.Apply in
task/repository/sqlite/base_migrations.go, whose MigrateLogger swallows
"duplicate column name" so the call is replay-safe:
r.migrate.Apply("workflow_step_entry_markers.skip_reason",
`ALTER TABLE workflow_step_entry_markers ADD COLUMN skip_reason TEXT`)
CREATE TABLE IF NOT EXISTS alone would not add it to an existing database, so
the ALTER is required, not optional. Writing a skip needs to work from absent,
in_progress and failed alike, which neither existing method does, so the
scan uses SkipStepEntryMarker(ctx, entryID, position, kind, reason, at):
an upsert on (entry_id, position) setting state='skipped' and
skip_reason=?, guarded by WHERE state <> 'done' on the update branch. The
seven reason values are exactly 004.9's list.
Coalescing exclusion
Two halves, and only the first is in-memory. QueueRunRequest gains
EntryTriggered bool in both declarations - internal/runs/service and
internal/workflow/engine, which must stay identical per
AC-OFFICE-STEP-ENTRY-DISPATCH-005.3 - and the engine sets it for every run
enqueued by a step-entry action. shouldCoalesceRun returns false when it is
set, so an entry-triggered run never merges into an existing row.
That alone is not sufficient. CoalesceRun(ctx, agentInstanceID, reason, windowSecs, payload) takes neither the request nor its idempotency key, and
its subquery picks a pre-existing queued row as the merge target; the
comment-key exclusion it already has works only because
idempotency_key is a persisted column it can read back. A request-scoped
boolean is invisible to that subquery, so the flag must also be persisted on
the run row (AC-OFFICE-STEP-ENTRY-DISPATCH-005.2):
r.migrate.Apply("runs.entry_triggered",
`ALTER TABLE runs ADD COLUMN entry_triggered INTEGER NOT NULL DEFAULT 0`)
The runs DDL and its ALTER migrations are owned by the office repository
(office/repository/sqlite/base.go), which is where runs.outcome was added
the same way; runs/repository/sqlite/base.go says so explicitly. DEFAULT 0
gives every pre-existing row "not entry-triggered", which is the behaviour
005.2 requires and is also the safe direction: an old row stays a legal merge
target.
The insert path writes the column from the request, and CoalesceRun's
subquery gains AND entry_triggered = 0 so an entry-triggered queued row is
never chosen as a target either. Both directions are needed: the predicate
stops an entry run from being merged into something, the SQL stops it from
being merged onto.
The idempotency key is unchanged and the task-comment prefix is not reused, so idempotency suppression is unaffected (005.4).
Migrated columns are probed before use
Three columns are added by r.migrate.Apply:
workflow_step_entries.marker_positions,
workflow_step_entry_markers.skip_reason, and runs.entry_triggered.
The delivered marker_positions ALTER uses the task repository's required
migration logger. runMigrations checks Err() after this Apply, so an
unexpected failure returns from repository construction and prevents startup.
Existing rows receive ''. The skip_reason
and runs.entry_triggered migrations belong to deferred Tasks 04 and 08; define
their probe policy when those tasks land. SQL naming a missing column fails the
whole statement.
The table describes deferred readers; marker_positions still fails startup
before recovery when its required migration fails.
Deferred readers probe once at startup with the columnExists shape
runs.outcome already uses, then degrade explicitly:
| Column | Probe fails -> |
|---|---|
runs.entry_triggered |
one ERROR; CoalesceRun and the insert path fall back to pre-requirement coalescing, exclusion inactive (AC-...-005.6) |
workflow_step_entries.marker_positions |
one ERROR; the startup scan is skipped for that process start, entries left non-terminal for a later start (AC-...-004.11, 004.2) |
workflow_step_entry_markers.skip_reason |
shares the scan's probe; the scan cannot record a skip reason without it, so it is skipped under the same rule |
Other probe errors mean "column absent". Probing avoids issuing a statement that cannot succeed; an unknown answer gives no more license to issue it than a definite "no" does.
For deferred readers, degrading is chosen because their requirements treat the
scan and exclusion as improvements over today's behaviour. This does not
override the required marker_positions migration.
Diagnostics
The warning helper takes workflow id, step id, step name, and action type, and is called from all four discard points named in AC-OFFICE-STEP-ENTRY-DISPATCH-006.2. The fan-out callback gains a logger and emits per-participant ERROR records plus one INFO summary; it currently returns a joined error and logs nothing itself, which is why the summary cannot be produced by its caller.
engineOnEnterCallback returning a callback that fails with
ErrActionNotYetWired is replaced by an unwired check ahead of the claim, so an
unwired adapter produces the warning and no failed marker (006.4).
For a marker-bearing position the check does not stop there: it writes a
terminal skipped marker with reason adapter_unwired before returning. This
is required, not cosmetic. Terminality is derived from the allocated position
set (AC-OFFICE-STEP-ENTRY-DISPATCH-004.9), a position with no row at all is not
stranded and takes the ordinary insert on the next pass, and the unwired check
would fire again and again write nothing - so the entry would never become
terminal and the startup scan would re-select it at every process start,
forever. A skipped marker is terminal and is not a failed marker, so it
satisfies 006.4's prohibition rather than weakening it, and 004.9's reason field
tells an operator the adapter was absent rather than that the work ran. A
non-marker-bearing position keeps the warning-and-no-marker behaviour, because
it holds no position in the allocated set and so cannot strand an entry.
Enumeration order
roleSeatsForFanOut sorts by Position ASC, AgentProfileID ASC, and that
order is kept unchanged. AgentProfileID is already unique across the set
collapseByRoleAgent returns, so it is a valid final tiebreak and
AC-OFFICE-STEP-ENTRY-DISPATCH-007.7's unique-last-column rule is met without any
change.
An earlier draft moved the tiebreak to the participant row id; that is
withdrawn. review-participant-seats.md AC-OFFICE-REVIEW-SEATS-003.3 binds
this same fan-out to ascending position then ascending agent profile
identifier; that binding stands. The swap would have
violated that sibling contract wherever row-creation and agent-profile-id order
diverge, and the existing fixture is lexically pre-sorted so it would not have
caught the change - hence AC-OFFICE-STEP-ENTRY-DISPATCH-007.9's fixture whose
two orders disagree. Role is constant after filtering, so the legacy role ASC
leading key is not reintroduced.
Test seams
- The production-shape regression test needs both dispatchers wired.
review_participant_seats_acceptance_test.goalready builds that environment and is the place to assert an empty queue after the expected run. - The atomic-clear test needs a failure injected between delete and marker
completion.
dispatchClearDecisionsAtomiconly takes the atomic path for a concrete*workflowadapters.DecisionAdapter, so the seam has to be inside the repository method rather than a store double. - The task-scoped concurrency test needs two sessions on one task, which the existing single-session concurrency test does not build.
- The reclaim test must distinguish the two claim paths on the same row:
ClaimStepEntryMarkermust still returnclaimed=falseagainst anin_progressand afailedmarker (008.4), whileReclaimStepEntryMarkerreturnsreclaimed=truefor both andfalsefordoneandskipped. A test that only exercises the scan end-to-end cannot tell a working reclaim from a scan that silently found nothing to do. - The allocated position set needs a test that would fail if it were recomputed
from the declaration instead of read back: allocate an entry at a step whose
sequence declares a non-marker-bearing kind, then assert
marker_positionsomits that position and that the entry reaches terminality without it. A test over a step whose every kind is marker-bearing cannot tell the two implementations apart, and that is the shape the shipped Review step is not. - Retiring an
unresolvableentry needs a test that removes or corrupts the step declaration and asserts the scan still writes a terminal marker for every stored position. Without it a scan that quietly skips such entries looks identical to one with nothing to do. - The
skippedstate needs a test asserting a scan-skipped position is readable as neitherdonenorfailedafter restart, since that distinction is the whole point of the fourth value. - The coalescing test must cover the target direction, not only the incoming
one: a queued entry-triggered row must not be selected by
CoalesceRunfor a later ordinary request. Asserting only that an entry run does not coalesce passes against a service-side-only implementation, which is the half that is easy to ship by itself. - The stop rule (AC-OFFICE-STEP-ENTRY-DISPATCH-002.10) needs a test that fails
if it is removed: fail
clear_decisionsat position 0 of the shipped Review sequence and assert the position-2 fan-out enqueues nothing. Asserting only that the failure was recorded passes against a dispatcher that continued, which is exactly today's ledger behaviour. - The unwired-adapter case needs a test that a marker-bearing position reaches
a terminal
skippedmarker with reasonadapter_unwired, and that a second process start does not re-select the entry. Asserting only the warning passes against the no-marker implementation that strands the entry forever. - The window bound (AC-OFFICE-STEP-ENTRY-DISPATCH-004.12) needs an entry
allocated older than 24 hours: assert its unfinished positions are retired
idempotency_window_expiredwith an ERROR, and that no run is enqueued. A fixture inside the window cannot distinguish the bound from its absence. - The enumeration-order fixture must place two participants whose agent-profile-id order and row-creation order disagree (AC-OFFICE-STEP-ENTRY-DISPATCH-007.9). The existing fixture is lexically pre-sorted, so it passes under either tiebreak and would not have caught the row-id swap this design withdrew.
Risks
- Moving ownership changes idempotency keys. A run enqueued before the change and one enqueued after carry different keys for the same entry, so a deployment that lands mid-round can duplicate one round's runs once. Strictly better than duplicating every round; no migration is proposed.
- Allocation remains on the existing
on_turn_completeroute this round; manual moves, WIP promotion, and workflow switches are deferred to Task 04. - The task lock widens a critical section that currently admits concurrent sessions of one task. Turn completion already serializes per session; the change makes contention visible where it was previously silent corruption.
- Three ALTER migrations run on existing databases. The delivered
marker_positionsmigration is required; a failure stops startup after the finalErr()check. Deferred columns retain their future probe policy, with one ERROR for a failed probe. marker_positionsis a denormalized copy of what the ownership declaration would say at allocation time. That is deliberate - it is what makesunresolvabledecidable - but it means an entry allocated before a kind's marker-bearing property changes keeps the old set. The digest check in AC-OFFICE-STEP-ENTRY-DISPATCH-004.3 retires such an entry asdigest_changedrather than resuming it against a stale set.