@devries-cameron20 / t3code-1 / commits / 0b5600b1c3
Fork 0

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,