The best way to control Claude Code, Codex and more from any computer or phone
perf(server): message ordinals are read through an index, not a scan (#30873)
Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Navid Nadali committed
Nov 15, 2026 at 02:32 UTC
a62bc8156daf35a5473e8774b9082eb76911e134
8 files changed
+285
-15
apps/server/src/orchestration-v2/Orchestrator.control-reads.test.ts
+3
-1
@@ -2671,7 +2671,9 @@ it.effect("queued-message commands read a long thread's history without walking
2671
if (
2672
(detail.includes("TEMP B-TREE FOR GROUP BY") && query.includes("json_each")) ||
2673
(/^SEARCH .*(node|turn_item).* \(thread_id=\?\)$/.test(detail) &&
2674
- !detail.includes("USING COVERING INDEX")) ||
2674
+ !detail.includes("USING COVERING INDEX") &&
2675
+ // That full ordering pass, through an index that holds only message items.
2676
+ !(detail.includes("message_ordinal_idx") && !query.includes("json_each"))) ||
2677
// Every active run in the environment, not only this thread's.
2678
/^SEARCH .*runs.* \(status=\?\)$/.test(detail) ||
2679
// A status-filtered read that fetches every typed row to check its status.
apps/server/src/orchestration-v2/ProjectionStore.test.ts
+188
-11
@@ -1311,17 +1311,8 @@ it.effect("record reads filter notification sources without dropping matching me
1311
.pipe(Effect.withTracer(tracer));
1312
assert.lengthOf(userMessages.messages, 3);
1313
const ordinalLookup = statements.find((statement) => statement.includes("MIN(ordinal)"));
1314
- assert.isDefined(ordinalLookup);
1315
- const sql = yield* SqlClient.SqlClient;
1316
- const plan = (yield* sql.unsafe<{ readonly detail: string }>(
1317
- `EXPLAIN QUERY PLAN ${ordinalLookup}`,
1318
- [threadId, "[]"],
1319
- )).map((row) => row.detail);
1320
- // User-only reads must stay on a type-bounded index instead of scanning every turn item.
1321
- assert.isTrue(
1322
- plan.some((detail) => /turn_items_(user_message|thread_type)_idx/.test(detail)),
1323
- plan.join("\n"),
1324
- );
1314
+ // User-only reads must seek the message-ordinal index instead of scanning every turn item.
1315
+ yield* assertReadsThroughMessageOrdinalIndex(ordinalLookup, ["thread_id=?", "<expr>=?"]);
1316
// With every user item loaded, the items give the order and the lookup does not run.
1317
const withItems = traceSqlStatements();
1318
const ordered = yield* store
@@ -2613,6 +2604,192 @@ const subagentRecordsSelectById = Effect.gen(function* () {
2604
assert.deepEqual(yield* read([]), []);
2605
});
2606
2607
+const recordsAt = (second: number) => DateTime.makeUnsafe(Date.UTC(2026, 0, 1, 0, 0, second));
2608
+const recordsThreadCreated = (threadId: ThreadId) =>
2609
+ ({
2610
+ id: EventId.make(`event:${threadId}:created`),
2611
+ type: "thread.created",
2612
+ threadId,
2613
+ providerInstanceId,
2614
+ occurredAt: recordsAt(0),
2615
+ payload: {
2616
+ createdBy: "user",
2617
+ creationSource: "web",
2618
+ id: threadId,
2619
+ projectId: ProjectId.make("project:records"),
2620
+ title: threadId,
2621
+ providerInstanceId,
2622
+ modelSelection,
2623
+ runtimeMode: "full-access",
2624
+ interactionMode: "default",
2625
+ branch: null,
2626
+ worktreePath: null,
2627
+ activeProviderThreadId: null,
2628
+ lineage: { parentThreadId: null, relationshipToParent: null, rootThreadId: threadId },
2629
+ forkedFrom: null,
2630
+ createdAt: recordsAt(0),
2631
+ updatedAt: recordsAt(0),
2632
+ archivedAt: null,
2633
+ settledOverride: null,
2634
+ settledAt: null,
2635
+ lastVisitedAt: null,
2636
+ deletedAt: null,
2637
+ },
2638
+ }) as never;
2639
+
2640
+const queryPlan = Effect.fn("queryPlan")(function* (statement: string | undefined) {
2641
+ assert.isDefined(statement);
2642
+ const sql = yield* SqlClient.SqlClient;
2643
+ const rows = yield* sql.unsafe<{ readonly detail: string }>(`EXPLAIN QUERY PLAN ${statement}`);
2644
+ return rows.map((row) => row.detail);
2645
+});
2646
+
2647
+// SQLite's plan wording changes between versions, so only the index search, the keys it seeks
2648
+// and the absence of a temporary B-tree are pinned.
2649
+const assertReadsThroughMessageOrdinalIndex = Effect.fn("assertReadsThroughMessageOrdinalIndex")(
2650
+ function* (statement: string | undefined, keys: ReadonlyArray<string>) {
2651
+ const plan = yield* queryPlan(statement);
2652
+ const search = plan.find((detail) =>
2653
+ detail.includes("orchestration_v2_projection_turn_items_message_ordinal_idx"),
2654
+ );
2655
+ assert.isDefined(search, plan.join("\n"));
2656
+ for (const key of keys) assert.include(search, key);
2657
+ assert.isFalse(
2658
+ plan.some((detail) => detail.includes("TEMP B-TREE")),
2659
+ plan.join("\n"),
2660
+ );
2661
+ },
2662
+);
2663
+
2664
+// Each message's first item orders it, not the stored message order (the assistant reply is stored
2665
+// first); the message-ordinal statement reads those ordinals through migration 94's index.
2666
+const messageOrdinalsReadThroughTheirIndex = Effect.gen(function* () {
2667
+ const store = yield* ProjectionStore.ProjectionStoreV2;
2668
+ const threadId = ThreadId.make("thread:message-ordinals");
2669
+ yield* store.apply(recordsThreadCreated(threadId));
2670
+ const conversation = (name: string, firstOrdinal: number) => {
2671
+ const runId = RunId.make(`run:${name}`);
2672
+ const nodeId = NodeId.make(`node:${name}:root`);
2673
+ const user = MessageId.make(`message:${name}:user`);
2674
+ const assistant = MessageId.make(`message:${name}:assistant`);
2675
+ const item = (index: number) => ({
2676
+ id: TurnItemId.make(`item:${name}:${index}`),
2677
+ threadId,
2678
+ runId,
2679
+ nodeId,
2680
+ providerThreadId: null,
2681
+ providerTurnId: null,
2682
+ nativeItemRef: null,
2683
+ parentItemId: null,
2684
+ ordinal: firstOrdinal + index,
2685
+ status: "completed",
2686
+ title: null,
2687
+ startedAt: recordsAt(2),
2688
+ completedAt: recordsAt(2),
2689
+ updatedAt: recordsAt(2),
2690
+ });
2691
+ const message = (id: MessageId, role: "user" | "assistant", second: number) => ({
2692
+ id: EventId.make(`event:${id}`),
2693
+ type: "message.updated",
2694
+ threadId,
2695
+ occurredAt: recordsAt(second),
2696
+ payload: {
2697
+ createdBy: role === "user" ? "user" : "agent",
2698
+ creationSource: role === "user" ? "web" : "provider",
2699
+ id,
2700
+ threadId,
2701
+ runId,
2702
+ nodeId,
2703
+ role,
2704
+ text: `${name} ${role}`,
2705
+ attachments: [],
2706
+ streaming: false,
2707
+ createdAt: recordsAt(second),
2708
+ updatedAt: recordsAt(second),
2709
+ },
2710
+ });
2711
+ const turnItem = (index: number, payload: object) => ({
2712
+ id: EventId.make(`event:item:${name}:${index}`),
2713
+ type: "turn-item.updated",
2714
+ threadId,
2715
+ occurredAt: recordsAt(2),
2716
+ payload: { ...item(index), ...payload },
2717
+ });
2718
+ const events = [
2719
+ message(assistant, "assistant", 1),
2720
+ message(user, "user", 2),
2721
+ turnItem(0, {
2722
+ type: "user_message",
2723
+ createdBy: "user",
2724
+ creationSource: "web",
2725
+ messageId: user,
2726
+ inputIntent: "turn_start",
2727
+ text: `${name} user`,
2728
+ attachments: [],
2729
+ }),
2730
+ // A message streamed over two items keeps its first ordinal.
2731
+ ...[1, 2].map((index) =>
2732
+ turnItem(index, {
2733
+ type: "assistant_message",
2734
+ messageId: assistant,
2735
+ text: `${name} assistant ${index}`,
2736
+ streaming: false,
2737
+ }),
2738
+ ),
2739
+ turnItem(3, {
2740
+ type: "dynamic_tool",
2741
+ toolName: "tool",
2742
+ input: {},
2743
+ output: { messageId: user },
2744
+ }),
2745
+ ];
2746
+ return { events, user, assistant };
2747
+ };
2748
+ const first = conversation("first", 1);
2749
+ const second = conversation("second", 10);
2750
+ for (const event of [...first.events, ...second.events]) yield* store.apply(event as never);
2751
+
2752
+ const { statements, tracer } = traceSqlStatements();
2753
+ const indexed = yield* store
2754
+ .getThreadRecords(threadId, ["messages"])
2755
+ .pipe(Effect.withTracer(tracer));
2756
+ yield* assertReadsThroughMessageOrdinalIndex(
2757
+ statements.find((statement) => statement.includes("MIN(ordinal) AS ordinal")),
2758
+ ["thread_id=?"],
2759
+ );
2760
+ assert.deepEqual(
2761
+ indexed.messages.map((message) => message.id),
2762
+ [first.user, first.assistant, second.user, second.assistant],
2763
+ );
2764
+ // A narrow read (ids, runs or one role) seeks only its own messages in the same index.
2765
+ const narrowReads = [
2766
+ {
2767
+ filter: { messageIds: [second.assistant, first.user] },
2768
+ loaded: [first.user, second.assistant],
2769
+ },
2770
+ { filter: { messageRunIds: [RunId.make("run:first")] }, loaded: [first.user, first.assistant] },
2771
+ { filter: { messageRoles: ["user" as const] }, loaded: [first.user, second.user] },
2772
+ ];
2773
+ for (const { filter, loaded } of narrowReads) {
2774
+ const narrow = traceSqlStatements();
2775
+ const narrowed = yield* store
2776
+ .getThreadRecords(threadId, ["messages"], filter)
2777
+ .pipe(Effect.withTracer(narrow.tracer));
2778
+ assert.deepEqual(
2779
+ narrowed.messages.map((message) => message.id),
2780
+ loaded,
2781
+ );
2782
+ const bounded = narrow.statements.find((statement) =>
2783
+ statement.includes("MIN(ordinal) AS ordinal"),
2784
+ );
2785
+ yield* assertReadsThroughMessageOrdinalIndex(bounded, ["thread_id=?", "<expr>=?"]);
2786
+ }
2787
+});
2788
+
2789
+it.effect("reads message ordinals through their index", () =>
2790
+ messageOrdinalsReadThroughTheirIndex.pipe(Effect.provide(layerTest)),
2791
+);
2792
+
2793
const assertProjectScopedShells = Effect.fn("assertProjectScopedShells")(function* (
2794
suffix: string,
2795
) {
apps/server/src/orchestration-v2/ProjectionStore.ts
+5
-3
@@ -4341,7 +4341,7 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
4341
decodeRows(decodeContextTransferPayload, threadId)(contextTransferRows),
4342
]);
4343
const messageOrdinals = new Map<string, number>();
4344
- // The literal `type = 'user_message'` lets SQLite pick the partial user-message index.
4344
+ // Only user items can name a user message, so a user-only read needs no assistant items.
4345
const userOnly = messages.every((message) => message.role === "user");
4346
// The loaded items already order the messages when they hold every item the lookup reads.
4347
const loadsEveryItemOf = (type: OrchestrationV2TurnItem["type"]) =>
@@ -4367,11 +4367,13 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
4367
(filter.messageRoles.includes("user") && filter.messageRoles.includes("assistant")))
4368
? undefined
4369
: messages.map((message) => message.id);
4370
+ // Migration 94 indexes exactly this expression, type list and json_valid term: changing
4371
+ // any, even the IN order, silently drops the index. ProjectionStore.test.ts asserts the plan.
4372
const rows = yield* sql<{ message_id: string; ordinal: number }>`
4373
SELECT json_extract(payload_json, '$.messageId') AS message_id, MIN(ordinal) AS ordinal
4374
FROM orchestration_v2_projection_turn_items
4373
- WHERE thread_id = ${threadId}
4374
- AND ${userOnly ? sql`type = 'user_message'` : sql`type IN ('user_message', 'assistant_message')`}
4375
+ WHERE thread_id = ${threadId} AND type IN ('user_message', 'assistant_message')
4376
+ AND json_valid(payload_json)
4377
${loadedMessageIds === undefined ? sql`` : sql`AND json_extract(payload_json, '$.messageId') IN (SELECT value FROM json_each(${encodeIdList(loadedMessageIds)}))`}
4378
GROUP BY json_extract(payload_json, '$.messageId')
4379
`;
apps/server/src/persistence/Migrations.ts
+2
@@ -101,6 +101,7 @@ import Migration0090 from "./Migrations/090_AuthConnectDevices.ts";
101
import Migration0091 from "./Migrations/091_AuthConnectDeniedRequests.ts";
102
import Migration0092 from "./Migrations/092_QueuedTurnInputIndexJsonValid.ts";
103
import Migration0093 from "./Migrations/093_ProviderTurnAttemptIndex.ts";
104
+import Migration0094 from "./Migrations/094_TurnItemMessageOrdinalIndex.ts";
105
106
const migrationEntries = [
107
[1, "OrchestrationEvents", Migration0001],
@@ -197,6 +198,7 @@ const migrationEntries = [
198
[91, "AuthConnectDeniedRequests", Migration0091],
199
[92, "QueuedTurnInputIndexJsonValid", Migration0092],
200
[93, "ProviderTurnAttemptIndex", Migration0093],
201
+ [94, "TurnItemMessageOrdinalIndex", Migration0094],
202
] as const;
203
204
export const migrationManifest = migrationEntries.map(([id, name]) => [id, name] as const);
apps/server/src/persistence/Migrations/094_TurnItemMessageOrdinalIndex.test.ts
new
+58
@@ -0,0 +1,58 @@
1
+import { assert, it } from "@effect/vitest";
2
+import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
3
+import * as Effect from "effect/Effect";
4
+import * as SqlClient from "effect/sql/SqlClient";
5
+
6
+import { runMigrations } from "../Migrations.ts";
7
+
8
+const ordinalsOf = (threadId: string) => `
9
+ SELECT json_extract(payload_json, '$.messageId') AS message_id, MIN(ordinal) AS ordinal
10
+ FROM orchestration_v2_projection_turn_items
11
+ WHERE thread_id = '${threadId}' AND type IN ('user_message', 'assistant_message')
12
+ AND json_valid(payload_json)
13
+ GROUP BY json_extract(payload_json, '$.messageId')
14
+ ORDER BY message_id
15
+`;
16
+
17
+const insertTurnItem = (
18
+ id: string,
19
+ threadId: string,
20
+ ordinal: number,
21
+ type: string,
22
+ payloadJson: string,
23
+) =>
24
+ Effect.gen(function* () {
25
+ const sql = yield* SqlClient.SqlClient;
26
+ yield* sql`
27
+ INSERT INTO orchestration_v2_projection_turn_items (
28
+ turn_item_id, thread_id, run_id, ordinal, type, status, updated_at, payload_json
29
+ )
30
+ VALUES (
31
+ ${id}, ${threadId}, NULL, ${ordinal}, ${type}, 'completed',
32
+ '2026-11-01T00:00:00.000Z', ${payloadJson}
33
+ )
34
+ `;
35
+ });
36
+
37
+// Without the index a payload that is not JSON fails no write; with it, it must fail none either.
38
+it.effect("migrates over a message whose payload is not JSON, and takes one after it", () =>
39
+ Effect.gen(function* () {
40
+ const sql = yield* SqlClient.SqlClient;
41
+ yield* runMigrations({ toMigrationInclusive: 93 });
42
+ yield* insertTurnItem("bad-1", "thread-a", 1, "assistant_message", "{not json");
43
+ yield* insertTurnItem("ok-1", "thread-a", 2, "user_message", '{"messageId":"m1"}');
44
+
45
+ assert.deepEqual(
46
+ (yield* runMigrations()).map(([id]) => id),
47
+ [94],
48
+ );
49
+ yield* insertTurnItem("bad-2", "thread-a", 3, "user_message", "{not json");
50
+ yield* insertTurnItem("ok-2", "thread-a", 4, "assistant_message", '{"messageId":"m1"}');
51
+ yield* sql`
52
+ UPDATE orchestration_v2_projection_turn_items SET payload_json = '{still not json'
53
+ WHERE turn_item_id = 'ok-2'
54
+ `;
55
+
56
+ assert.deepEqual(yield* sql.unsafe(ordinalsOf("thread-a")), [{ message_id: "m1", ordinal: 2 }]);
57
+ }).pipe(Effect.provide(NodeSqliteClient.layer({ filename: ":memory:" }))),
58
+);
apps/server/src/persistence/Migrations/094_TurnItemMessageOrdinalIndex.ts
new
+20
@@ -0,0 +1,20 @@
1
+import * as Effect from "effect/Effect";
2
+import * as SqlClient from "effect/sql/SqlClient";
3
+
4
+/**
5
+ * A projection read groups a thread's message items by `$.messageId` for each message's first
6
+ * ordinal; without this index it parses every message item's payload. The expression and the
7
+ * WHERE must stay identical to that query's, or SQLite will not use the index. `json_valid` keeps
8
+ * a payload that is not JSON out of it: json_extract would fail its write.
9
+ */
10
+export default Effect.gen(function* () {
11
+ const sql = yield* SqlClient.SqlClient;
12
+
13
+ yield* sql`
14
+ CREATE INDEX IF NOT EXISTS orchestration_v2_projection_turn_items_message_ordinal_idx
15
+ ON orchestration_v2_projection_turn_items(
16
+ thread_id, json_extract(payload_json, '$.messageId'), ordinal
17
+ )
18
+ WHERE type IN ('user_message', 'assistant_message') AND json_valid(payload_json)
19
+ `;
20
+});
apps/server/src/persistence/reconcileV2PreviewMigration.test.ts
+2
@@ -73,6 +73,7 @@ describe("V2 preview upgrade", () => {
73
[91, "AuthConnectDeniedRequests"],
74
[92, "QueuedTurnInputIndexJsonValid"],
75
[93, "ProviderTurnAttemptIndex"],
76
+ [94, "TurnItemMessageOrdinalIndex"],
77
]);
78
assert.deepStrictEqual(yield* runMigrations(), []);
79
assert.deepStrictEqual(yield* sql`SELECT * FROM orchestration_v2_legacy_imports`, imports);
@@ -189,6 +190,7 @@ describe("V2 preview upgrade", () => {
190
[91, "AuthConnectDeniedRequests"],
191
[92, "QueuedTurnInputIndexJsonValid"],
192
[93, "ProviderTurnAttemptIndex"],
193
+ [94, "TurnItemMessageOrdinalIndex"],
194
]);
195
}).pipe(Effect.provide(NodeSqliteClient.layer({ filename: ":memory:" }))),
196
);
docs/internals/performance-regressions.md
+7
@@ -131,6 +131,13 @@ queries read item counts from a per-thread, per-run table that turn-item trigger
131
use a partial index for nonterminal background items, including idle items. Latest user-message
132
reads use an index ordered by update time.
133
134
+A projection read that orders messages by their first user or assistant turn item groups those
135
+items by `$.messageId` through a partial index on that expression (migration 94), so it does not
136
+parse every message item's payload; the index's expression and `WHERE` must stay identical to the
137
+query's. Migration 94 scans the turn-item table once on first start; a message item whose payload
138
+is not valid JSON is left out of the index. Each message-item write re-parses the old and new
139
+payload for the index, so its cost grows with the payload.
140
+
141
Command palette results keep live VCS and linked pull-request queries leased to the visible
142
viewport, including a small overscan region. Cached badges remain available while leases are
143
released. Local Git status reads skip divergence calculations; callers that need ahead/behind