The best way to control Claude Code, Codex and more from any computer or phone
perf(server): read pull request metadata from a lightweight snapshot
PR discovery used the full shell snapshot, which derived activity and counted historical items across active threads. Read only PR metadata and its event sequence in one transaction, then decode after releasing the reader. Preserve settled backfill, targeted refreshes, legacy PR normalization, and guarded updates. Validation: check:changed passed with 80 tests after merging main; CI passed on 988187f. Native Electron measurements and a concurrent-write control confirmed metadata parity and coherent sequences. Synthetic measurements cover PR reads and service initialization, not full desktop startup. Model: GPT 6.1 Sol. Harness: Codex in T3 Code.
Yash Singh committed
Nov 3, 2026 at 14:41 UTC
0b5600b1c3df49f705ba245df5aa50c59dc91490
6 files changed
+231
-40
apps/server/src/orchestration-v2/Orchestrator.ts
+11
@@ -438,6 +438,12 @@ export interface OrchestratorV2Shape {
438
},
439
OrchestratorV2Error
440
>;
441
+ readonly getPullRequestSnapshot: (
442
+ options: Parameters<ProjectionStoreV2["Service"]["getPullRequestSnapshot"]>[0],
443
+ ) => Effect.Effect<
444
+ Effect.Success<ReturnType<ProjectionStoreV2["Service"]["getPullRequestSnapshot"]>>,
445
+ OrchestratorV2Error
446
+ >;
447
readonly getShellSnapshot: (
448
options?: ShellSnapshotOptions,
449
) => Effect.Effect<OrchestrationV2ThreadShellSnapshot, OrchestratorV2Error>;
@@ -14143,6 +14149,11 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
14149
.pipe(Effect.mapError((cause) => new OrchestratorProjectionError({ threadId, cause })));
14150
},
14151
),
14152
+ getPullRequestSnapshot: Effect.fn("OrchestratorV2.getPullRequestSnapshot")(function (options) {
14153
+ return projectionStore
14154
+ .getPullRequestSnapshot(options)
14155
+ .pipe(Effect.mapError(shellProjectionError));
14156
+ }),
14157
getShellSnapshot: Effect.fn("OrchestratorV2.getShellSnapshot")(function (options) {
14158
return projectionStore.getShellSnapshot(options).pipe(Effect.mapError(shellProjectionError));
14159
}),
apps/server/src/orchestration-v2/ProjectionStore.test.ts
+81
-2
@@ -32,6 +32,7 @@ import {
32
import * as DateTime from "effect/DateTime";
33
import * as Effect from "effect/Effect";
34
import * as Layer from "effect/Layer";
35
+import * as Option from "effect/Option";
36
import * as Schema from "effect/Schema";
37
import * as Tracer from "effect/Tracer";
38
import * as SqlClient from "effect/sql/SqlClient";
@@ -64,6 +65,7 @@ const encodeUnknownJsonString = Schema.encodeSync(Schema.fromJsonString(Schema.U
65
66
const traceSqlStatements = () => {
67
const statements: Array<string> = [];
68
+ const queryTransactions: Array<string | null> = [];
69
const tracer = Tracer.make({
70
span(options) {
71
const span = new Tracer.NativeSpan(options);
@@ -71,12 +73,19 @@ const traceSqlStatements = () => {
73
span.end = (endTime, exit) => {
74
end(endTime, exit);
75
const query = span.attributes.get("db.query.text");
74
- if (typeof query === "string") statements.push(query);
76
+ if (typeof query === "string") {
77
+ statements.push(query);
78
+ let parent = Option.getOrUndefined(span.parent);
79
+ while (parent?._tag === "Span" && parent.name !== "sql.transaction") {
80
+ parent = Option.getOrUndefined(parent.parent);
81
+ }
82
+ queryTransactions.push(parent?._tag === "Span" ? parent.spanId : null);
83
+ }
84
};
85
return span;
86
},
87
});
79
- return { statements, tracer };
88
+ return { statements, tracer, queryTransactions };
89
};
90
91
/** The shell index flags every live shell and matches its shells on the fields subscriber trims read. */
@@ -3793,6 +3802,76 @@ it.layer(layerTest)("ProjectionStoreV2", (it) => {
3802
.filter((id) => id === readThreadId || id === laterThreadId);
3803
3804
yield* createThread(readThreadId);
3805
+ yield* sql`UPDATE orchestration_v2_projection_threads
3806
+ SET payload_json = json_set(payload_json, '$.linkedPullRequest', json(${JSON.stringify({
3807
+ projectId: "project:shell-read",
3808
+ repository: "acme/project",
3809
+ number: 42,
3810
+ url: "https://github.com/acme/project/pull/42",
3811
+ })})) WHERE thread_id = ${readThreadId}`;
3812
+ const trace = traceSqlStatements();
3813
+ const discovery = yield* projectionStore
3814
+ .getPullRequestSnapshot({})
3815
+ .pipe(Effect.withTracer(trace.tracer));
3816
+ assert.deepEqual(
3817
+ discovery.threads
3818
+ .map((thread) => thread.id)
3819
+ .filter((id) => id === readThreadId || id === laterThreadId),
3820
+ [readThreadId],
3821
+ );
3822
+ assert.strictEqual(discovery.snapshotSequence, 0);
3823
+ assert.strictEqual(trace.queryTransactions.length, 2);
3824
+ assert.isNotNull(trace.queryTransactions[0]);
3825
+ assert.strictEqual(new Set(trace.queryTransactions).size, 1);
3826
+ assert.isFalse(
3827
+ trace.statements.some((query) =>
3828
+ /orchestration_v2_projection_(runs|messages|turn_items|provider_threads)/.test(query),
3829
+ ),
3830
+ );
3831
+ const fullShell = (yield* projectionStore.getShellSnapshot()).threads.find(
3832
+ (thread) => thread.id === readThreadId,
3833
+ )!;
3834
+ const metadata = discovery.threads.find((thread) => thread.id === readThreadId)!;
3835
+ for (const key of Object.keys(metadata) as Array<keyof typeof metadata>) {
3836
+ assert.deepEqual(metadata[key], fullShell[key]);
3837
+ }
3838
+ const narrow = yield* projectionStore.getPullRequestSnapshot({ threadId: readThreadId });
3839
+ assert.deepEqual(
3840
+ narrow.threads,
3841
+ discovery.threads.filter((thread) => thread.id === readThreadId),
3842
+ );
3843
+ const settledPayload = (settledAt: string | null, archivedAt: string | null) => sql`
3844
+ UPDATE orchestration_v2_projection_threads
3845
+ SET payload_json = json_set(payload_json, '$.settledAt', ${settledAt}, '$.archivedAt', ${archivedAt})
3846
+ WHERE thread_id = ${readThreadId}
3847
+ `;
3848
+ yield* settledPayload(DateTime.formatIso(now), null);
3849
+ assert.isFalse(
3850
+ (yield* projectionStore.getPullRequestSnapshot({ unsettledOnly: true })).threads.some(
3851
+ (thread) => thread.id === readThreadId,
3852
+ ),
3853
+ );
3854
+ assert.strictEqual(
3855
+ (yield* projectionStore.getPullRequestSnapshot({ threadId: readThreadId })).threads.length,
3856
+ 1,
3857
+ );
3858
+ yield* settledPayload(null, DateTime.formatIso(now));
3859
+ assert.isFalse(
3860
+ (yield* projectionStore.getPullRequestSnapshot({})).threads.some(
3861
+ (thread) => thread.id === readThreadId,
3862
+ ),
3863
+ );
3864
+ assert.strictEqual(
3865
+ (yield* projectionStore.getPullRequestSnapshot({ threadId: readThreadId })).threads.length,
3866
+ 1,
3867
+ );
3868
+ yield* sql`UPDATE orchestration_v2_projection_threads SET deleted_at = '2026-11-03T00:00:00.000Z' WHERE thread_id = ${readThreadId}`;
3869
+ assert.deepEqual(
3870
+ (yield* projectionStore.getPullRequestSnapshot({ threadId: readThreadId })).threads,
3871
+ [],
3872
+ );
3873
+ yield* sql`UPDATE orchestration_v2_projection_threads SET deleted_at = NULL WHERE thread_id = ${readThreadId}`;
3874
+ yield* settledPayload(null, null);
3875
const decode = yield* sql.withTransaction(projectionStore.readShellSnapshot());
3876
yield* createThread(laterThreadId);
3877
apps/server/src/orchestration-v2/ProjectionStore.ts
+77
@@ -481,6 +481,16 @@ export interface ProjectionStoreV2Shape {
481
readonly apply: (
482
event: OrchestrationV2DomainEvent,
483
) => Effect.Effect<void, ProjectionStoreV2Error>;
484
+ readonly getPullRequestSnapshot: (options: {
485
+ readonly threadId?: ThreadId;
486
+ readonly unsettledOnly?: boolean;
487
+ }) => Effect.Effect<
488
+ {
489
+ readonly snapshotSequence: number;
490
+ readonly threads: ReadonlyArray<typeof PullRequestThread.Type>;
491
+ },
492
+ ProjectionStoreV2Error
493
+ >;
494
readonly getShellSnapshot: (
495
options?: ShellSnapshotOptions,
496
) => Effect.Effect<OrchestrationV2ThreadShellSnapshot, ProjectionStoreV2Error>;
@@ -1097,6 +1107,37 @@ const encodeContextTransferPayload = Schema.encodeEffect(
1107
Schema.fromJsonString(OrchestrationV2ContextTransferJsonSchema),
1108
);
1109
1110
+const PullRequestThread = OrchestrationV2AppThreadJsonSchema.mapFields(
1111
+ ({
1112
+ id,
1113
+ projectId,
1114
+ lineage,
1115
+ branch,
1116
+ worktreePath,
1117
+ archivedAt,
1118
+ settledOverride,
1119
+ settledAt,
1120
+ linkedPullRequest,
1121
+ branchPullRequest,
1122
+ pullRequests,
1123
+ }) => ({
1124
+ id,
1125
+ projectId,
1126
+ lineage,
1127
+ branch,
1128
+ worktreePath,
1129
+ archivedAt,
1130
+ settledOverride,
1131
+ settledAt,
1132
+ linkedPullRequest,
1133
+ branchPullRequest,
1134
+ pullRequests,
1135
+ }),
1136
+);
1137
+const decodePullRequestThread = Schema.decodeUnknownEffect(
1138
+ Schema.fromJsonString(PullRequestThread),
1139
+);
1140
+
1141
const decodeThreadPayload = Schema.decodeUnknownEffect(
1142
Schema.fromJsonString(OrchestrationV2AppThreadJsonSchema),
1143
);
@@ -6895,6 +6936,41 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
6936
Effect.map(decodeShellSnapshot),
6937
);
6938
6939
+ const getPullRequestSnapshot: ProjectionStoreV2Shape["getPullRequestSnapshot"] = Effect.fn(
6940
+ "ProjectionStore.getPullRequestSnapshot",
6941
+ )(function* ({ threadId, unsettledOnly = false }) {
6942
+ const { rows, sequenceRows } = yield* sql.withTransaction(
6943
+ Effect.gen(function* () {
6944
+ const rows = yield* sql<PayloadRow>`
6945
+ SELECT t.payload_json FROM orchestration_v2_projection_threads t
6946
+ WHERE t.deleted_at IS NULL${
6947
+ threadId === undefined
6948
+ ? sql` AND json_extract(t.payload_json, '$.archivedAt') IS NULL`
6949
+ : sql` AND t.thread_id = ${threadId}`
6950
+ }${
6951
+ unsettledOnly
6952
+ ? sql` AND json_extract(t.payload_json, '$.settledAt') IS NULL
6953
+ AND json_extract(t.payload_json, '$.settledOverride') IS NOT 'settled'`
6954
+ : sql``
6955
+ }
6956
+ ORDER BY t.updated_at ASC, t.thread_id ASC
6957
+ `;
6958
+ const sequenceRows = yield* sql<{ readonly snapshot_sequence: number | null }>`
6959
+ SELECT MAX(sequence) AS snapshot_sequence FROM orchestration_events
6960
+ WHERE application_event_version = 2 AND aggregate_kind = 'thread'
6961
+ `;
6962
+ return { rows, sequenceRows };
6963
+ }),
6964
+ );
6965
+ // Decode after releasing the reader, keeping rows and sequence from the same transaction.
6966
+ const threads = yield* Effect.forEach(rows, (row) =>
6967
+ decodePullRequestThread(row.payload_json).pipe(
6968
+ Effect.map((thread) => ({ ...thread, pullRequests: threadPullRequestsOf(thread) })),
6969
+ ),
6970
+ );
6971
+ return { snapshotSequence: sequenceRows[0]?.snapshot_sequence ?? 0, threads };
6972
+ }, Effect.mapError(shellSnapshotReadError));
6973
+
6974
const getShellSnapshot: ProjectionStoreV2Shape["getShellSnapshot"] = (options) =>
6975
sql
6976
.withTransaction(readShellSnapshotRows(options))
@@ -7163,6 +7239,7 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
7239
return {
7240
apply,
7241
getShellSnapshot: readOnReader(getShellSnapshot),
7242
+ getPullRequestSnapshot: readOnReader(getPullRequestSnapshot),
7243
listActiveSubagentThreadIds: readOnReader(listActiveSubagentThreadIds),
7244
countThreads: readOnReader(countThreads),
7245
listActiveShellIndex: readOnReader(listActiveShellIndex),
apps/server/src/orchestration-v2/ProviderTurnControlService.test.ts
+1
@@ -271,6 +271,7 @@ it.effect(
271
getUnreadableThreadIds: () => Effect.die("unused getUnreadableThreadIds"),
272
getThreadSnapshot: () => Effect.die("unused getThreadSnapshot"),
273
getThreadSnapshotWindow: () => Effect.die("unused getThreadSnapshotWindow"),
274
+ getPullRequestSnapshot: () => Effect.die("unused getPullRequestSnapshot"),
275
}),
276
);
277
const layerSessionManager = Layer.succeed(
apps/server/src/orchestration-v2/ThreadPullRequestService.test.ts
+58
-24
@@ -28,6 +28,10 @@ import * as ProjectStore from "./ProjectStore.ts";
28
import * as RepositoryIdentityResolver from "../project/RepositoryIdentityResolver.ts";
29
import * as PullRequestService from "../pullRequest/PullRequestService.ts";
30
import * as ServerActivation from "../serverActivation.ts";
31
+import * as ProjectionStore from "./ProjectionStore.ts";
32
+import * as SqlClient from "effect/sql/SqlClient";
33
+import * as SqlitePersistence from "../persistence/Sqlite.ts";
34
+import { EventId } from "@t3tools/contracts";
35
import * as Orchestrator from "./Orchestrator.ts";
36
import * as ThreadPullRequestService from "./ThreadPullRequestService.ts";
37
@@ -105,15 +109,13 @@ describe("ThreadPullRequestServiceV2 reads", () => {
109
const dependencies = Layer.mergeAll(
110
Layer.mock(Orchestrator.OrchestratorV2)({
111
streamDomainEvents: Stream.fromQueue(domainEvents),
108
- getShellSnapshot: () =>
112
+ getPullRequestSnapshot: () =>
113
Effect.succeed({
114
schemaVersion: 2,
115
snapshotSequence: 1,
116
threads: [thread],
117
archivedThreads: [],
118
}),
115
- getThreadEventSequence: () => Effect.succeed(1),
116
- getThreadShell: () => Effect.succeed(thread),
119
}),
120
Layer.mock(ProjectStore.ProjectStoreV2)({
121
listShells: () => Effect.succeed([project]),
@@ -212,6 +214,8 @@ describe("ThreadPullRequestServiceV2 reads", () => {
214
Effect.gen(function* () {
215
const thread = {
216
...threadShell("worktree-thread"),
217
+ settledOverride: "settled" as const,
218
+ settledAt: NOW,
219
branch: "feature/worktree",
220
worktreePath: "/workspace/worktree",
221
};
@@ -230,7 +234,7 @@ describe("ThreadPullRequestServiceV2 reads", () => {
234
const dependencies = Layer.mergeAll(
235
Layer.mock(Orchestrator.OrchestratorV2)({
236
streamDomainEvents: Stream.never,
233
- getShellSnapshot: () =>
237
+ getPullRequestSnapshot: () =>
238
Deferred.succeed(sweepStarted, undefined).pipe(
239
Effect.as({
240
schemaVersion: 2,
@@ -335,18 +339,17 @@ describe("ThreadPullRequestServiceV2 reads", () => {
339
const dependencies = Layer.mergeAll(
340
Layer.mock(Orchestrator.OrchestratorV2)({
341
streamDomainEvents: Stream.fromQueue(domainEvents),
338
- getShellSnapshot: () =>
339
- Queue.offer(sweeps, undefined).pipe(
340
- Effect.as({
341
- schemaVersion: 2,
342
- snapshotSequence: 1,
343
- threads: [parent, child],
344
- archivedThreads: [],
345
- }),
346
- ),
347
- getThreadEventSequence: () => Effect.succeed(1),
348
- getThreadShell: (threadId) =>
349
- Effect.succeed([parent, child].find((thread) => thread.id === threadId) ?? null),
342
+ getPullRequestSnapshot: ({ threadId }) =>
343
+ threadId !== undefined
344
+ ? Effect.succeed({ snapshotSequence: 1, threads: [child] })
345
+ : Queue.offer(sweeps, undefined).pipe(
346
+ Effect.as({
347
+ schemaVersion: 2,
348
+ snapshotSequence: 1,
349
+ threads: [parent, child],
350
+ archivedThreads: [],
351
+ }),
352
+ ),
353
}),
354
Layer.mock(ProjectStore.ProjectStoreV2)({
355
listShells: () => Effect.succeed([project]),
@@ -457,14 +460,37 @@ describe("ThreadPullRequestServiceV2 reads", () => {
460
const dependencies = Layer.mergeAll(
461
Layer.mock(Orchestrator.OrchestratorV2)({
462
streamDomainEvents: Stream.never,
460
- getShellSnapshot: () =>
461
- Deferred.succeed(sweepStarted, undefined).pipe(
462
- Effect.as({
463
- schemaVersion: 2,
464
- snapshotSequence: 1,
465
- threads: [thread],
466
- archivedThreads: [],
467
- }),
463
+ getPullRequestSnapshot: (options) =>
464
+ Effect.gen(function* () {
465
+ const store = yield* ProjectionStore.ProjectionStoreV2;
466
+ yield* store.apply({
467
+ id: EventId.make(`event:${thread.id}:created`),
468
+ type: "thread.created",
469
+ threadId: thread.id,
470
+ occurredAt: NOW,
471
+ payload: { ...thread, lastVisitedAt: thread.lastVisitedAt ?? null },
472
+ });
473
+ const sql = yield* SqlClient.SqlClient;
474
+ yield* sql`INSERT INTO orchestration_events (
475
+ sequence, event_id, aggregate_kind, stream_id, stream_version, event_type,
476
+ occurred_at, actor_kind, payload_json, metadata_json, application_event_version
477
+ ) VALUES (7, 'pr-discovery', 'thread', ${thread.id}, 1, 'thread.created',
478
+ '2026-09-20T00:00:00.000Z', 'system', '{}', '{}', 2)`;
479
+ for (const table of [
480
+ "orchestration_v2_projection_turn_items",
481
+ "orchestration_v2_projection_messages",
482
+ "orchestration_v2_projection_provider_threads",
483
+ "orchestration_v2_projection_runs",
484
+ ])
485
+ yield* sql.unsafe(`DROP TABLE ${table}`);
486
+ const snapshot = yield* store.getPullRequestSnapshot(options);
487
+ yield* Deferred.succeed(sweepStarted, undefined);
488
+ return snapshot;
489
+ }).pipe(
490
+ Effect.provide(
491
+ ProjectionStore.layer.pipe(Layer.provideMerge(SqlitePersistence.layerMemory)),
492
+ ),
493
+ Effect.orDie,
494
),
495
dispatch: (command) =>
496
Effect.sync(() => {
@@ -529,6 +555,14 @@ describe("ThreadPullRequestServiceV2 reads", () => {
555
expect(commands[0]).toMatchObject({
556
type: "thread.pull-request.sync",
557
threadId: thread.id,
558
+ snapshotSequence: 7,
559
+ expected: {
560
+ workspaceRoot: project.workspaceRoot,
561
+ branch: thread.branch,
562
+ worktreePath: thread.worktreePath,
563
+ linkedPullRequest: savedReference,
564
+ branchPullRequest: savedReference,
565
+ },
566
branchPullRequest: null,
567
});
568
expect(commands[0]).not.toHaveProperty("linkedPullRequest");
apps/server/src/orchestration-v2/ThreadPullRequestService.ts
+3
-14
@@ -7,7 +7,6 @@ import {
7
type ThreadLinkedPullRequest,
8
} from "@t3tools/contracts";
9
import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
10
-import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
10
import * as Cause from "effect/Cause";
11
import * as Context from "effect/Context";
12
import * as SecureRandom from "effect/crypto/SecureRandom";
@@ -120,19 +119,9 @@ export const make = Effect.gen(function* () {
119
};
120
121
const readThreadSnapshot = ({ threadId, backfill }: RefreshRequest) =>
123
- threadId === null
124
- ? orchestrator
125
- .getShellSnapshot({
126
- location: "active",
127
- unsettledOnly: !(backfill || pendingBackfill.size > 0),
128
- })
129
- .pipe(NodeSqliteClient.readOnly)
130
- : Effect.gen(function* () {
131
- // Read sequence first so guarded sync rejects intervening changes.
132
- const snapshotSequence = yield* orchestrator.getThreadEventSequence(threadId);
133
- const thread = yield* orchestrator.getThreadShell(threadId);
134
- return { snapshotSequence, threads: thread === null ? [] : [thread] };
135
- });
122
+ orchestrator.getPullRequestSnapshot(
123
+ threadId === null ? { unsettledOnly: !(backfill || pendingBackfill.size > 0) } : { threadId },
124
+ );
125
126
const synchronize = Effect.fn("ThreadPullRequestServiceV2.synchronize")(function* (
127
request: RefreshRequest,