Skip to content

Commit 57e9e97

Browse files
authored
feat(core): deterministic session log replay with synced watermark (#35040)
1 parent 1aae92c commit 57e9e97

16 files changed

Lines changed: 205 additions & 87 deletions

File tree

‎packages/client/src/generated/types.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1575,7 +1575,7 @@ export type SessionLogOutput =
15751575
readonly data: { readonly timestamp: number; readonly sessionID: string; readonly messageID: string }
15761576
}
15771577
)
1578-
| { readonly type: "log.caught_up"; readonly aggregateID: string; readonly seq?: number }
1578+
| { readonly type: "log.synced"; readonly aggregateID: string; readonly seq?: number }
15791579

15801580
export type SessionInterruptInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
15811581

‎packages/client/test/effect.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import { DateTime, Effect, Stream } from "effect"
33
import { HttpClient, HttpClientResponse } from "effect/unstable/http"
44
import { AbsolutePath, Agent, Event, Location, Model, OpenCode, Prompt, Session, SessionMessage } from "../src/effect"
55

6-
const caughtUp = { type: "log.caught_up" as const, aggregateID: "ses_test", seq: Event.Seq.make(1) }
6+
const synced = { type: "log.synced" as const, aggregateID: "ses_test", seq: Event.Seq.make(1) }
77

88
test("session.get returns the decoded Effect projection", async () => {
99
const httpClient = HttpClient.make((request) =>
@@ -70,7 +70,7 @@ test("session methods retain decoded Effect inputs and outputs", async () => {
7070
return Effect.succeed(
7171
HttpClientResponse.fromWeb(
7272
request,
73-
new Response(`data: ${JSON.stringify(modelSwitchedEvent)}\n\ndata: ${JSON.stringify(caughtUp)}\n\n`, {
73+
new Response(`data: ${JSON.stringify(modelSwitchedEvent)}\n\ndata: ${JSON.stringify(synced)}\n\n`, {
7474
headers: { "content-type": "text/event-stream" },
7575
}),
7676
),
@@ -149,11 +149,11 @@ test("session methods retain decoded Effect inputs and outputs", async () => {
149149
expect(result.context).toEqual([])
150150
expect(logQueries[0]).toEqual({ after: "0" })
151151
const logged = Array.from(result.log)
152-
expect(logged.map((item) => item.type)).toEqual(["session.next.model.switched", "log.caught_up"])
152+
expect(logged.map((item) => item.type)).toEqual(["session.next.model.switched", "log.synced"])
153153
expect(logged[0]?.type === "session.next.model.switched" && DateTime.toEpochMillis(logged[0].data.timestamp)).toBe(
154154
1_717_171_717_000,
155155
)
156-
expect(logged.at(-1)).toEqual(caughtUp)
156+
expect(logged.at(-1)).toEqual(synced)
157157
expect(result.message).toEqual(expect.objectContaining({ id: "msg_model", type: "model-switched" }))
158158
})
159159

‎packages/client/test/promise.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,7 @@ test("session methods use the public HTTP contract", async () => {
232232
})
233233
}
234234
if (url.includes("/log")) {
235-
return new Response(`data: ${JSON.stringify(modelSwitchedEvent)}\n\ndata: ${JSON.stringify(caughtUp)}\n\n`, {
235+
return new Response(`data: ${JSON.stringify(modelSwitchedEvent)}\n\ndata: ${JSON.stringify(synced)}\n\n`, {
236236
headers: { "content-type": "text/event-stream" },
237237
})
238238
}
@@ -273,7 +273,7 @@ test("session methods use the public HTTP contract", async () => {
273273
expect(created.id).toBe("ses_test")
274274
expect(admitted.id).toBe("msg_test")
275275
expect(context).toEqual([])
276-
expect(log).toEqual([modelSwitchedEvent, caughtUp])
276+
expect(log).toEqual([modelSwitchedEvent, synced])
277277
expect(message).toEqual(modelSwitchedMessage)
278278
expect(requests.map((request) => [request.init?.method, request.url])).toEqual([
279279
["GET", "http://localhost:3000/api/session?limit=10&order=desc&parentID=null"],
@@ -368,7 +368,7 @@ const modelSwitchedMessage = {
368368
model: { id: "claude", providerID: "anthropic" },
369369
}
370370

371-
const caughtUp = { type: "log.caught_up", aggregateID: "ses_test", seq: 1 }
371+
const synced = { type: "log.synced", aggregateID: "ses_test", seq: 1 }
372372

373373
const modelSwitchedEvent = {
374374
id: "evt_model",

‎packages/core/src/event.ts‎

Lines changed: 58 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { Cause, Context, Effect, Layer, Option, PubSub, Queue, Schema, Stream }
44
import { Event } from "@opencode-ai/schema/event"
55
import type { Data, Definition, Payload } from "@opencode-ai/schema/event"
66
import type { EventLog } from "@opencode-ai/schema/event-log"
7-
import { and, asc, eq, gt, inArray, sql } from "drizzle-orm"
7+
import { and, asc, eq, gt, inArray, lte, sql } from "drizzle-orm"
88
import { Database } from "./database/database"
99
import { EventSequenceTable, EventTable } from "./event/sql"
1010
import { Location } from "./location"
@@ -103,10 +103,10 @@ export interface PublishOptions {
103103
readonly commit?: (seq: number) => Effect.Effect<void>
104104
}
105105

106-
/** Marker/event union emitted by `log`. Markers carry no event `id`. */
107-
export type LogItem = Payload | EventLog.CaughtUp
106+
/** Marker/event union emitted by `log`. */
107+
export type LogItem = Payload | EventLog.Synced
108108

109-
export const isCaughtUp = (item: LogItem): item is EventLog.CaughtUp => !("id" in item)
109+
export const isSynced = (item: LogItem): item is EventLog.Synced => item.type === "log.synced"
110110

111111
export interface Interface {
112112
readonly publish: <D extends Definition>(
@@ -124,8 +124,8 @@ export interface Interface {
124124
/**
125125
* Durable, ordered, gap-free per-aggregate log read. `follow: false`
126126
* completes at the end of the log; `follow: true` replays then transitions
127-
* to live. Both modes emit a `CaughtUp` marker at the replay boundary; the
128-
* marker may be re-emitted after internal re-attaches.
127+
* to live. Both modes emit one `Synced` marker at the captured replay
128+
* watermark.
129129
*/
130130
readonly log: (input: {
131131
readonly aggregateID: string
@@ -178,6 +178,8 @@ export interface LayerOptions {
178178
* buffer is abandoned and the subscriber is told to sweep.
179179
*/
180180
readonly changesKeyCapacity?: number
181+
/** Maximum durable rows read per page while replaying or tailing an aggregate log. */
182+
readonly logReadPageSize?: number
181183
}
182184

183185
export const layerWith = (options?: LayerOptions) =>
@@ -199,6 +201,7 @@ export const layerWith = (options?: LayerOptions) =>
199201
readonly wake: PubSub.PubSub<void>
200202
}>()
201203
const { db } = yield* Database.Service
204+
const logReadPageSize = options?.logReadPageSize ?? 512
202205

203206
const getOrCreate = (definition: Definition) =>
204207
Effect.gen(function* () {
@@ -573,15 +576,27 @@ export const layerWith = (options?: LayerOptions) =>
573576

574577
const streamLive = (): Stream.Stream<Payload> => Stream.fromPubSub(pubsub.live)
575578

576-
const readAfter = (aggregateID: string, after: number) =>
579+
const readAfter = (
580+
aggregateID: string,
581+
after: number,
582+
input: { readonly through: number; readonly limit: number },
583+
) =>
577584
(options?.beforeAggregateRead?.(aggregateID) ?? Effect.void).pipe(
578585
Effect.andThen(
579-
db
580-
.select()
581-
.from(EventTable)
582-
.where(and(eq(EventTable.aggregate_id, aggregateID), gt(EventTable.seq, after)))
583-
.orderBy(asc(EventTable.seq))
584-
.all(),
586+
Effect.suspend(() => {
587+
const query = db
588+
.select()
589+
.from(EventTable)
590+
.where(
591+
and(
592+
eq(EventTable.aggregate_id, aggregateID),
593+
gt(EventTable.seq, after),
594+
lte(EventTable.seq, input.through),
595+
),
596+
)
597+
.orderBy(asc(EventTable.seq))
598+
return query.limit(input.limit).all()
599+
}),
585600
),
586601
Effect.orDie,
587602
// Skip types missing from the durable manifest instead of failing the
@@ -632,28 +647,42 @@ export const layerWith = (options?: LayerOptions) =>
632647
Stream.unwrap(
633648
Effect.gen(function* () {
634649
let sequence = input.after ?? -1
635-
const read = Effect.suspend(() => readAfter(input.aggregateID, sequence)).pipe(
636-
Effect.tap((page) =>
637-
Effect.sync(() => {
638-
sequence = page.seq ?? sequence
639-
}),
640-
),
641-
Effect.map((page) => page.events),
642-
)
650+
const readThrough = (through: number): Stream.Stream<Payload> =>
651+
Stream.paginate(sequence, (cursor) =>
652+
readAfter(input.aggregateID, cursor, { through, limit: logReadPageSize }).pipe(
653+
Effect.tap((page) =>
654+
Effect.sync(() => {
655+
sequence = page.seq ?? sequence
656+
}),
657+
),
658+
Effect.map(
659+
(page) =>
660+
[
661+
page.events,
662+
page.seq !== undefined && page.seq < through ? Option.some(page.seq) : Option.none<number>(),
663+
] as const,
664+
),
665+
),
666+
)
643667
// Subscribing before the historical read means events committed during
644668
// replay either appear in the read or arrive through a post-marker wake.
645669
const wakes = input.follow ? yield* subscribeDurable(input.aggregateID) : undefined
646-
const historical = yield* read
647-
const marker: EventLog.CaughtUp = {
648-
type: "log.caught_up",
670+
const target = yield* latestSequence(db, input.aggregateID)
671+
const marker: EventLog.Synced = {
672+
type: "log.synced",
649673
aggregateID: input.aggregateID,
650-
...(sequence >= 0 ? { seq: Seq.make(sequence) } : {}),
674+
...(target >= 0 ? { seq: Seq.make(target) } : {}),
651675
}
652-
const replay = Stream.fromIterable<LogItem>(historical).pipe(Stream.concat(Stream.make(marker)))
676+
const replay: Stream.Stream<LogItem> = readThrough(target).pipe(
677+
Stream.map((event): LogItem => event),
678+
Stream.concat(Stream.make(marker)),
679+
)
653680
if (!wakes) return replay
654-
const live = Stream.fromSubscription(wakes).pipe(
655-
Stream.mapEffect(() => read),
656-
Stream.flattenIterable,
681+
const live: Stream.Stream<LogItem> = Stream.fromSubscription(wakes).pipe(
682+
Stream.mapEffect(() => latestSequence(db, input.aggregateID)),
683+
Stream.filter((target) => target > sequence),
684+
Stream.flatMap((target) => readThrough(target)),
685+
Stream.map((event): LogItem => event),
657686
)
658687
return Stream.concat(replay, live)
659688
}),

‎packages/core/src/session.ts‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -163,16 +163,17 @@ export interface Interface {
163163
) => Effect.Effect<SessionMessage.Message[], NotFoundError | MessageDecodeError>
164164
/**
165165
* Durable, ordered, gap-free session log read. Replays public durable
166-
* session events after the exclusive `after` cursor, emits a `CaughtUp`
167-
* marker at the replay boundary, then continues live when `follow` is set.
166+
* session events after the exclusive `after` cursor, emits a `Synced`
167+
* marker at the captured replay watermark, then continues live when `follow`
168+
* is set.
168169
* The marker's seq may exceed the last emitted event because non-public
169170
* durable events share the aggregate's sequence space.
170171
*/
171172
readonly log: (input: {
172173
sessionID: SessionSchema.ID
173174
after?: number
174175
follow?: boolean
175-
}) => Stream.Stream<SessionEvent.DurableEvent | EventLog.CaughtUp, NotFoundError>
176+
}) => Stream.Stream<SessionEvent.DurableEvent | EventLog.Synced, NotFoundError>
176177
/** Latest durable log seq per session. Sessions without events are absent. */
177178
readonly watermarks: (sessionIDs: ReadonlyArray<SessionSchema.ID>) => Effect.Effect<ReadonlyMap<string, EventV2.Seq>>
178179
readonly switchAgent: (input: { sessionID: SessionSchema.ID; agent: string }) => Effect.Effect<void, NotFoundError>
@@ -455,8 +456,8 @@ const layer = Layer.effect(
455456
.pipe(Effect.as(events.log({ aggregateID: input.sessionID, after: input.after, follow: input.follow }))),
456457
).pipe(
457458
Stream.filter(
458-
(item): item is SessionEvent.DurableEvent | EventLog.CaughtUp =>
459-
EventV2.isCaughtUp(item) || isDurableSessionEvent(item),
459+
(item): item is SessionEvent.DurableEvent | EventLog.Synced =>
460+
EventV2.isSynced(item) || isDurableSessionEvent(item),
460461
),
461462
),
462463
watermarks: Effect.fn("V2Session.watermarks")(function* (sessionIDs) {

‎packages/core/test/event.test.ts‎

Lines changed: 77 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { describe, expect } from "bun:test"
2-
import { Cause, DateTime, Deferred, Effect, Exit, Fiber, Layer, Option, Schema, Stream } from "effect"
2+
import { Cause, DateTime, Deferred, Effect, Exit, Fiber, Layer, Option, Ref, Schema, Stream } from "effect"
33
import { EventV2 } from "@opencode-ai/core/event"
44
import { Event } from "@opencode-ai/schema/event"
55
import { Session } from "@opencode-ai/schema/session"
@@ -80,9 +80,7 @@ const durableData = (sessionID: Session.ID, text: string) => ({
8080

8181
/** Followed log read without markers: the old `durable` stream shape. */
8282
const tail = (events: EventV2.Interface, input: { aggregateID: string; after?: number }) =>
83-
events
84-
.log({ ...input, follow: true })
85-
.pipe(Stream.filter((item): item is EventV2.Payload => !EventV2.isCaughtUp(item)))
83+
events.log({ ...input, follow: true }).pipe(Stream.filter((item): item is EventV2.Payload => !EventV2.isSynced(item)))
8684

8785
const it = testEffect(
8886
AppNodeBuilder.build(LayerNode.group([Database.node, EventV2.node, Location.node]), [[Location.node, locationLayer]]),
@@ -1128,7 +1126,7 @@ describe("EventV2", () => {
11281126
}),
11291127
)
11301128

1131-
it.effect("log without follow replays events and completes with a caught-up marker", () =>
1129+
it.effect("log without follow replays events and completes with a synced marker", () =>
11321130
Effect.gen(function* () {
11331131
const events = yield* EventV2.Service
11341132
const aggregateID = Session.ID.create()
@@ -1137,16 +1135,16 @@ describe("EventV2", () => {
11371135

11381136
const items = Array.from(yield* Stream.runCollect(events.log({ aggregateID })))
11391137

1140-
expect(items.map((item) => (EventV2.isCaughtUp(item) ? item.type : item.durable?.seq))).toEqual([
1138+
expect(items.map((item) => (EventV2.isSynced(item) ? item.type : item.durable?.seq))).toEqual([
11411139
EventV2.Seq.make(0),
11421140
EventV2.Seq.make(1),
1143-
"log.caught_up",
1141+
"log.synced",
11441142
])
1145-
expect(items.at(-1)).toEqual({ type: "log.caught_up", aggregateID, seq: EventV2.Seq.make(1) })
1143+
expect(items.at(-1)).toEqual({ type: "log.synced", aggregateID, seq: EventV2.Seq.make(1) })
11461144
}),
11471145
)
11481146

1149-
it.effect("log caught-up marker omits seq for an empty log and keeps the cursor otherwise", () =>
1147+
it.effect("log synced marker omits seq for an empty log and keeps the cursor otherwise", () =>
11501148
Effect.gen(function* () {
11511149
const events = yield* EventV2.Service
11521150
const aggregateID = Session.ID.create()
@@ -1155,13 +1153,13 @@ describe("EventV2", () => {
11551153
yield* events.publish(DurableMessage, durableData(aggregateID, "zero"))
11561154
const drained = Array.from(yield* Stream.runCollect(events.log({ aggregateID, after: 0 })))
11571155

1158-
expect(empty).toEqual([{ type: "log.caught_up", aggregateID }])
1156+
expect(empty).toEqual([{ type: "log.synced", aggregateID }])
11591157
expect(empty[0]).not.toHaveProperty("seq")
1160-
expect(drained).toEqual([{ type: "log.caught_up", aggregateID, seq: EventV2.Seq.make(0) }])
1158+
expect(drained).toEqual([{ type: "log.synced", aggregateID, seq: EventV2.Seq.make(0) }])
11611159
}),
11621160
)
11631161

1164-
it.effect("log with follow emits the caught-up marker at the replay-to-live boundary", () =>
1162+
it.effect("log with follow emits the synced marker at the replay-to-live boundary", () =>
11651163
Effect.gen(function* () {
11661164
const events = yield* EventV2.Service
11671165
const aggregateID = Session.ID.create()
@@ -1174,14 +1172,79 @@ describe("EventV2", () => {
11741172
yield* events.publish(DurableMessage, durableData(aggregateID, "one"))
11751173

11761174
const items = Array.from(yield* Fiber.join(fiber))
1177-
expect(items.map((item) => (EventV2.isCaughtUp(item) ? item : item.durable?.seq))).toEqual([
1175+
expect(items.map((item) => (EventV2.isSynced(item) ? item : item.durable?.seq))).toEqual([
11781176
EventV2.Seq.make(0),
1179-
{ type: "log.caught_up", aggregateID, seq: EventV2.Seq.make(0) },
1177+
{ type: "log.synced", aggregateID, seq: EventV2.Seq.make(0) },
11801178
EventV2.Seq.make(1),
11811179
])
11821180
}),
11831181
)
11841182

1183+
it.effect("log replays across configured read pages", () =>
1184+
Effect.gen(function* () {
1185+
const eventLayer = EventV2.layerWith({ logReadPageSize: 2 }).pipe(Layer.provide(LayerNode.compile(Database.node)))
1186+
1187+
yield* Effect.gen(function* () {
1188+
const events = yield* EventV2.Service
1189+
const aggregateID = Session.ID.create()
1190+
yield* events.publish(DurableMessage, durableData(aggregateID, "zero"))
1191+
yield* events.publish(DurableMessage, durableData(aggregateID, "one"))
1192+
yield* events.publish(DurableMessage, durableData(aggregateID, "two"))
1193+
yield* events.publish(DurableMessage, durableData(aggregateID, "three"))
1194+
yield* events.publish(DurableMessage, durableData(aggregateID, "four"))
1195+
1196+
const items = Array.from(yield* Stream.runCollect(events.log({ aggregateID })))
1197+
1198+
expect(items.map((item) => (EventV2.isSynced(item) ? item.type : item.durable?.seq))).toEqual([
1199+
EventV2.Seq.make(0),
1200+
EventV2.Seq.make(1),
1201+
EventV2.Seq.make(2),
1202+
EventV2.Seq.make(3),
1203+
EventV2.Seq.make(4),
1204+
"log.synced",
1205+
])
1206+
expect(items.at(-1)).toEqual({ type: "log.synced", aggregateID, seq: EventV2.Seq.make(4) })
1207+
}).pipe(Effect.provide(Layer.merge(LayerNode.compile(Database.node), eventLayer)))
1208+
}),
1209+
)
1210+
1211+
it.effect("log with follow emits events committed during replay after the synced marker", () =>
1212+
Effect.gen(function* () {
1213+
const readStarted = yield* Deferred.make<void>()
1214+
const releaseRead = yield* Deferred.make<void>()
1215+
const firstRead = yield* Ref.make(true)
1216+
const eventLayer = EventV2.layerWith({
1217+
beforeAggregateRead: () =>
1218+
Ref.getAndSet(firstRead, false).pipe(
1219+
Effect.flatMap((shouldBlock) => {
1220+
if (!shouldBlock) return Effect.void
1221+
return Deferred.succeed(readStarted, undefined).pipe(Effect.andThen(Deferred.await(releaseRead)))
1222+
}),
1223+
),
1224+
}).pipe(Layer.provide(LayerNode.compile(Database.node)))
1225+
1226+
yield* Effect.gen(function* () {
1227+
const events = yield* EventV2.Service
1228+
const aggregateID = Session.ID.create()
1229+
yield* events.publish(DurableMessage, durableData(aggregateID, "zero"))
1230+
const fiber = yield* events
1231+
.log({ aggregateID, follow: true })
1232+
.pipe(Stream.take(3), Stream.runCollect, Effect.forkScoped)
1233+
1234+
yield* Deferred.await(readStarted)
1235+
yield* events.publish(DurableMessage, durableData(aggregateID, "one"))
1236+
yield* Deferred.succeed(releaseRead, undefined)
1237+
1238+
const items = Array.from(yield* Fiber.join(fiber))
1239+
expect(items.map((item) => (EventV2.isSynced(item) ? item : item.durable?.seq))).toEqual([
1240+
EventV2.Seq.make(0),
1241+
{ type: "log.synced", aggregateID, seq: EventV2.Seq.make(0) },
1242+
EventV2.Seq.make(1),
1243+
])
1244+
}).pipe(Effect.provide(Layer.merge(LayerNode.compile(Database.node), eventLayer)))
1245+
}),
1246+
)
1247+
11851248
it.effect("changes emits sweep-required on subscribe then coalesced hints per aggregate", () =>
11861249
Effect.gen(function* () {
11871250
const events = yield* EventV2.Service

0 commit comments

Comments
 (0)