@devries-cameron20 / t3code Mirror · read-only / commits / a62bc8156d
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 12:15 UTC

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