Delivery and cancellation

Delivery and response are two different observations. A request can be accepted by the session while the child is still working, and a response can time out while the child continues. Use the result fields instead of inferring delivery from the child state.

Status dimensions

WaitForResponse controls the caller’s observation. A waiting call drains the correlated response until completion, interruption, failure, or timeout. A background call returns the correlation identity and leaves the session-owned handback path responsible for completion.

Proof: delegate status types and delivery tests.

Acceptance boundary

The runtime reserves and appends a durable delegate intent before dispatching a native or foreign child. It registers the response tracker before enqueue. A caller cancellation before actor acceptance may retract queued work. Once the intent has crossed the acceptance boundary, the session owns it and the caller context cannot roll it back.

Native child turns may fold busy messages. Foreign or headless delivery uses NoFold and durable delivery phases. A queued result is not proof of a started turn; TurnStarted or TurnFoldedInto is the opening evidence used by restore.

Proof: intent and delivery phases, cancel command, and cancellation tests.

Cancellation command

The durable cancellation envelope is:

// package command
type CancelDelegateRequest struct {
	TargetCommandID uuid.UUID
	Ack             chan<- DelegateCancelResult
}

type DelegateCancelResult uint8

const (
	DelegateCancelNoop DelegateCancelResult = iota
	DelegateCancelQueued
	DelegateCancelActive
)

Validate requires a nonzero target and an acknowledgement channel. Noop means no cancellable request was found, Queued means the queued request was removed, and Active means cancellation reached an already admitted request. Active work is interrupted through the owning child/session path; cancellation does not forge a response terminal.

Proof: cancel command contract and cancel command tests.

Durable delivery state

event.DelegateDeliveryStateChanged records a request ID, target Loop ID, and one of these states:

Terminal delivery states suppress fallback. They survive restore and are validated against route, session, turn, and cancellation evidence.

%%{init: {"theme":"dark"}}%%
flowchart LR
    A[request] --> I[intent durable]
    I --> Q[accepted pending]
    Q --> S[turn started or folded]
    Q --> C{caller cancels}
    C -->|before acceptance| R[queued retracted]
    C -->|after acceptance| O[session-owned cancellation]
    S --> T[response terminal or background handback]
    I -. crash before opening .-> U[unknown after restore]

Proof: delivery state event and foreign delivery restore tests.

Typed failures

Use errors.As for *session.SessionError when durable intent or admission fails. The public kinds include SessionDelegateIntentAppendFailed, SessionDelegateAdmissionCommitFailed, SessionContextDone, and SessionLoopExited. Controller refusals are *sessionruntime.DelegateError with kinds such as DelegateInterruptPending, DelegateClosed, and DelegateNotOwned; their model-facing runtime selection message is bounded.

Proof: session error kinds and delegate refusal types.

Source and proof

• Delegate lifecycle and cancellation
• Delivery event
• Cancel command
• Delivery restore tests