perf(server): finalizing a subagent reads only that child's records - #30875

Problem

When a delegated child thread finishes, the orchestrator needs that child's task and the transfers it sent back. To find them, it reads the parent's whole subagent list and every context transfer, and a parent can hold hundreds of tasks.

For the largest parent in a production-shaped database, the read decodes 239 subagent rows (442 KiB) and 239 transfers (232 KiB) to use one of each.

One finalize read seen in production coincided with a 3.85 s main-thread stall. The statement's own time was at most 21 ms, so the gain is in rows decoded, not in SQL time.

Change

• getThreadRecords gains two filters, subagentChildThreadIds and contextTransferSourceThreadIds.
  • A single id is matched by equality, so each read seeks the existing child-thread or source-thread index instead of walking the parent's rows. Several ids use the usual json_each list.
• Both parent reads on the finalize path ask for only the finishing child's rows: the one that finds the child's task, and the one that records its result, which also reads only that task's node and card. A delivery the result joins is read by id: its message and its other tasks. The result read no longer loads the parent's provider threads and turns, which it never used, or the parent's other nodes, cards and messages.
• The status a follow-up run mirrors onto its task reads only that task's node and card from the parent.
• A turn-item read filtered by node now seeks the node index, as the other id-filtered reads do. Before, it walked every card of the parent to return the task's one.
• perf(server): narrow delegated recovery reads to delivery records #29435 narrowed the delegated-recovery reads the same way; this is the finalize read, which it did not cover.

Server only; no client or contract change.

Scope and approval

No change to product behaviour, defaults, settings or contracts. The rows the finalize path uses are the same.

Overlap: #30873 adds the same three test helpers to ProjectionStore.test.ts and a paragraph at the same place in docs/internals/performance-regressions.md; whichever of the two lands second drops its copy on rebase.

Background and measurements: #31002 (context, not an approval request).

Verification

Failing first on main, with main's product code (8b44f42b1 for the first two tests, 9e8553853 for the third, b7a224c7d for the card-read plan check). Each fails by assertion:

• vp test run apps/server/src/orchestration-v2/ProjectionStore.test.ts -t "record reads narrow a parent to one child's tasks and transfers". It asserts that:

  • the narrowed rows equal the full read filtered in code, for one child and for several;
  • the subagent read searches orchestration_v2_projection_subagents_child_thread_idx (child_thread_id=?) and the transfer read searches orchestration_v2_projection_context_transfers_source_thread_status_idx (source_thread_id=?);
  • the task's card read searches orchestration_v2_projection_turn_items_node_ordinal_idx (node_id=?);
  • an empty filter returns nothing;
  • a sibling's undecodable rows do not fail the narrowed read, while the child's own still do;
  • the read is still correct without the indexes.

  On main the narrowed read returns all 4 tasks instead of the child's 2, and the card read walks every subagent card of the parent through orchestration_v2_projection_turn_items_thread_type_idx (thread_id=? AND type=?).

• vp test run apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts -t "finalizing a delegated child reads only that child's records from its parent": recovering a finished delegated child issues every parent subagent and transfer read narrowed to that child, and every parent node, card and message read narrowed to its task or to the delivery it joins (whose other tasks are read by id). The child's node and card still end completed, and the joined delivery's message still names those tasks. On main no read names the child.

• vp test run apps/server/src/orchestration-v2/DelegatedCompletionDelivery.test.ts -t "mirrors a follow-up's status reading only its task's node and card": when a held follow-up's status is mirrored onto its task, every parent node and card read names that task, and both still turn idle. On main those reads name no task.

With the change:

• 198/198 in ProjectionStore.test.ts, DelegatedCompletionDelivery.test.ts, Orchestrator.control-reads.test.ts and ThreadStop.test.ts, on main @ b7a224c7d.
• vp run check:changed against main @ b7a224c7d: format, lint, knip, graphql and typecheck pass; 6 test files, 153/153.
• vp test run apps/server/integration: 26 files, 355/355, and the provider replay fixtures (apps/server/src/orchestration-v2/testkit): 17 files, 248/248, on main @ b7a224c7d.
• A differential harness, run through the real store on an earlier server build, compared every (parent, child) pair's narrowed read with the full read filtered in code: 0 mismatches on four databases.

Related: #29435 (merged) narrowed the delegated-recovery reads the same way, and this is the finalize read it did not cover. #30582 (merged) does not touch this path. No open PR changes this read.

The parent read that finds the child's task at finalize, through the store, summed over every (parent, child) check. The result read and the follow-up status read, narrowed in follow-up commits, were not measured separately. The full and narrowed reads alternated per pair, measured locally on an earlier server build with the list form of the filter (before the equality seek):

Not checked

• A benchmark run. The numbers are local, on a loaded machine.
• The result read still loads every run of the parent, to find the task's run and the delivery's.
• The timings predate the equality seek, which also shortens the statement itself; they were not re-measured.

Made with Claude Opus 5.5 via Claude Code. Reviewed by GPT-6.1 Sol via Codex.

🤖 Generated with Claude Code