Skip to content

Ticket #231: one native ingestion state value — verification ​

  • Date: 2026-11-12
  • Branch: ticket/231-native-ingestion-state
  • Spec: #231
  • ADRs: 0009, 0010
  • Unit gate: npm run verify (strict typecheck + full test suite)
  • Live gate: npm run test:live:native-first

State shape ​

src/v2/native-state.ts now owns one NativeSessionState per session in one map. The value owns enqueue order, pending inboxes, execution owner, answer-ordered execution turns, steered inboxes, the settled run id, the active turn, reordered execution starts, assistant-message mapping, text parts, live row checkpoints, the watchdog, and deferred child settlement. Delivery events stay in the durable turn timeline; the state value keeps no delivery map.

Mutations go through named transitions:

  • enqueue — host order, pending queue, reordered execution starts;
  • start / joinExecution — execution owner and participants;
  • resetExecution — clear a skipped or run-owned terminal's ownership;
  • answer — text parts and assistant-message identity;
  • steer — delivered-into-a-running-execution candidates;
  • settle — execution participants, per-turn memory, owner, and inbox slots;
  • reconcile — adoption re-queue and watchdog re-arm;
  • deleteTurn — per-turn release; clear — service-stop release.

The service keeps only nativeQueues (event serialization) and nativeReconcileRuns (coalesced reconcile) as async gates. The native subagent maps are a separate subsystem and are unchanged.

Maps removed ​

nativePendingInboxes, nativeInboxOrder, nativeExecutionOwner, nativeExecutionTurns, nativeSteeredInboxes, nativeRunSettled, nativeActiveTurn, nativePendingExecutions, nativeAssistantTurns, nativeText, nativeRows, nativeWatchdog, nativeDeferredSettlements, and nativeDelivery. Every former call site reads nativeState.peek(sessionID) or mutates through a transition.

Tests ​

src/v2/native-state.test.ts is the state-machine unit suite: a table case per host event family (session.inbox.enqueued, session.inbox.delivered, session.inbox.cancelled, session.text.started/delta/ended, session.retry.scheduled, session.execution.started, session.execution.succeeded/failed/interrupted, adoption, turn deletion, and service-stop clear). Those cases assert the state value directly.

Caller-observable behavior is asserted at the service seam by two ticket231 tables in src/v2/service.test.ts: session.execution.interrupted for user (cancelled) versus shutdown/inactivity (needs_you), and restart recovery for a transcript answer, an idle marker without an answer, and no terminal evidence. Each checks the durable task state, Work status, message rows, and row flags.

The existing #215–#229 native ingestion, retry, interruption, steering, adoption, watchdog, barrier, and restart suites pass unchanged. No behavior test was weakened.

Behavior notes ​

No observable behavior change. In-memory details differ only in lifetime:

  • an empty per-session value persists until service stop instead of individual maps deleting empty entries; no read path distinguishes the two;
  • service stop clears every native in-memory value and releases row/deferred timers in one pass;
  • the write-only delivery map was removed; delivery still appears in the durable session.inbox.delivered / session.inbox.delivery.changed events.

Review fixes ​

Two-axis review follow-up on ticket/231-253-review-fixes:

  • the state-machine table tests are labeled unit tests; service-seam tables cover interruption outcomes and restart recovery through task state and message rows;
  • deleteSession was removed; clear() releases row/deferred timers and drops the map in one pass;
  • the write-only delivery map was removed; delivery stays in the durable event timeline;
  • the empty start call became resetExecution, the two execution-join paths share joinExecution, clearNativeCheckpoint was inlined, and the session/watchdog and deferred walks share one entry source.

Gate results ​

  • npm run verify: strict typecheck passed; 1943 tests passed, 0 failed, 0 skipped after merging integration/native-ingestion-v7 (#253 added two, the review tables added six).
  • npm run test:live:native-first: main 66/66, restart 18/18, zero gaps and zero failures.

Released under the MIT License.