ceos/opencode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(core): deterministic session log replay with synced watermark (#35040)

Browse source
This commit is contained in:
Kit Langton 2026-07-02 21:38:20 -04:00 • committed by GitHub
commit 57e9e9771d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 205 additions and 87 deletions
Download patch file Download diff file Expand all files Collapse all files

87
packages/core/src/event.ts
View file

@ -4,7 +4,7 @@ import { Cause, Context, Effect, Layer, Option, PubSub, Queue, Schema, Stream }
import { Event } from "@opencode-ai/schema/event"
import type { Data, Definition, Payload } from "@opencode-ai/schema/event"
import type { EventLog } from "@opencode-ai/schema/event-log"
import { and, asc, eq, gt, inArray, sql } from "drizzle-orm"
import { and, asc, eq, gt, inArray, lte, sql } from "drizzle-orm"
import { Database } from "./database/database"
import { EventSequenceTable, EventTable } from "./event/sql"
import { Location } from "./location"
@ -103,10 +103,10 @@ export interface PublishOptions {
readonly commit?: (seq: number) => Effect.Effect<void>
}
/** Marker/event union emitted by `log`. Markers carry no event `id`. */
export type LogItem = Payload | EventLog.CaughtUp
/** Marker/event union emitted by `log`. */
export type LogItem = Payload | EventLog.Synced
export const isCaughtUp = (item: LogItem): item is EventLog.CaughtUp => !("id" in item)
export const isSynced = (item: LogItem): item is EventLog.Synced => item.type === "log.synced"
export interface Interface {
readonly publish: <D extends Definition>(
@ -124,8 +124,8 @@ export interface Interface {
/**
* Durable, ordered, gap-free per-aggregate log read. `follow: false`
* completes at the end of the log; `follow: true` replays then transitions
* to live. Both modes emit a `CaughtUp` marker at the replay boundary; the
* marker may be re-emitted after internal re-attaches.
* to live. Both modes emit one `Synced` marker at the captured replay
* watermark.
*/
readonly log: (input: {
readonly aggregateID: string
@ -178,6 +178,8 @@ export interface LayerOptions {
* buffer is abandoned and the subscriber is told to sweep.
*/
readonly changesKeyCapacity?: number
/** Maximum durable rows read per page while replaying or tailing an aggregate log. */
readonly logReadPageSize?: number
}
export const layerWith = (options?: LayerOptions) =>
@ -199,6 +201,7 @@ export const layerWith = (options?: LayerOptions) =>
readonly wake: PubSub.PubSub<void>
}>()
const { db } = yield* Database.Service
const logReadPageSize = options?.logReadPageSize ?? 512
const getOrCreate = (definition: Definition) =>
Effect.gen(function* () {
@ -573,15 +576,27 @@ export const layerWith = (options?: LayerOptions) =>
const streamLive = (): Stream.Stream<Payload> => Stream.fromPubSub(pubsub.live)
const readAfter = (aggregateID: string, after: number) =>
const readAfter = (
aggregateID: string,
after: number,
input: { readonly through: number; readonly limit: number },
) =>
(options?.beforeAggregateRead?.(aggregateID) ?? Effect.void).pipe(
Effect.andThen(
db
.select()
.from(EventTable)
.where(and(eq(EventTable.aggregate_id, aggregateID), gt(EventTable.seq, after)))
.orderBy(asc(EventTable.seq))
.all(),
Effect.suspend(() => {
const query = db
.select()
.from(EventTable)
.where(
and(
eq(EventTable.aggregate_id, aggregateID),
gt(EventTable.seq, after),
lte(EventTable.seq, input.through),
),
)
.orderBy(asc(EventTable.seq))
return query.limit(input.limit).all()
}),
),
Effect.orDie,
// Skip types missing from the durable manifest instead of failing the
@ -632,28 +647,42 @@ export const layerWith = (options?: LayerOptions) =>
Stream.unwrap(
Effect.gen(function* () {
let sequence = input.after ?? -1
const read = Effect.suspend(() => readAfter(input.aggregateID, sequence)).pipe(
Effect.tap((page) =>
Effect.sync(() => {
sequence = page.seq ?? sequence
}),
),
Effect.map((page) => page.events),
)
const readThrough = (through: number): Stream.Stream<Payload> =>
Stream.paginate(sequence, (cursor) =>
readAfter(input.aggregateID, cursor, { through, limit: logReadPageSize }).pipe(
Effect.tap((page) =>
Effect.sync(() => {
sequence = page.seq ?? sequence
}),
),
Effect.map(
(page) =>
[
page.events,
page.seq !== undefined && page.seq < through ? Option.some(page.seq) : Option.none<number>(),
] as const,
),
),
)
// Subscribing before the historical read means events committed during
// replay either appear in the read or arrive through a post-marker wake.
const wakes = input.follow ? yield* subscribeDurable(input.aggregateID) : undefined
const historical = yield* read
const marker: EventLog.CaughtUp = {
type: "log.caught_up",
const target = yield* latestSequence(db, input.aggregateID)
const marker: EventLog.Synced = {
type: "log.synced",
aggregateID: input.aggregateID,
...(sequence >= 0 ? { seq: Seq.make(sequence) } : {}),
...(target >= 0 ? { seq: Seq.make(target) } : {}),
}
const replay = Stream.fromIterable<LogItem>(historical).pipe(Stream.concat(Stream.make(marker)))
const replay: Stream.Stream<LogItem> = readThrough(target).pipe(
Stream.map((event): LogItem => event),
Stream.concat(Stream.make(marker)),
)
if (!wakes) return replay
const live = Stream.fromSubscription(wakes).pipe(
Stream.mapEffect(() => read),
Stream.flattenIterable,
const live: Stream.Stream<LogItem> = Stream.fromSubscription(wakes).pipe(
Stream.mapEffect(() => latestSequence(db, input.aggregateID)),
Stream.filter((target) => target > sequence),
Stream.flatMap((target) => readThrough(target)),
Stream.map((event): LogItem => event),
)
return Stream.concat(replay, live)
}),

11
packages/core/src/session.ts
View file

@ -163,8 +163,9 @@ export interface Interface {
) => Effect.Effect<SessionMessage.Message[], NotFoundError | MessageDecodeError>
/**
* Durable, ordered, gap-free session log read. Replays public durable
* session events after the exclusive `after` cursor, emits a `CaughtUp`
* marker at the replay boundary, then continues live when `follow` is set.
* session events after the exclusive `after` cursor, emits a `Synced`
* marker at the captured replay watermark, then continues live when `follow`
* is set.
* The marker's seq may exceed the last emitted event because non-public
* durable events share the aggregate's sequence space.
*/
@ -172,7 +173,7 @@ export interface Interface {
sessionID: SessionSchema.ID
after?: number
follow?: boolean
}) => Stream.Stream<SessionEvent.DurableEvent | EventLog.CaughtUp, NotFoundError>
}) => Stream.Stream<SessionEvent.DurableEvent | EventLog.Synced, NotFoundError>
/** Latest durable log seq per session. Sessions without events are absent. */
readonly watermarks: (sessionIDs: ReadonlyArray<SessionSchema.ID>) => Effect.Effect<ReadonlyMap<string, EventV2.Seq>>
readonly switchAgent: (input: { sessionID: SessionSchema.ID; agent: string }) => Effect.Effect<void, NotFoundError>
@ -455,8 +456,8 @@ const layer = Layer.effect(
.pipe(Effect.as(events.log({ aggregateID: input.sessionID, after: input.after, follow: input.follow }))),
).pipe(
Stream.filter(
(item): item is SessionEvent.DurableEvent | EventLog.CaughtUp =>
EventV2.isCaughtUp(item) || isDurableSessionEvent(item),
(item): item is SessionEvent.DurableEvent | EventLog.Synced =>
EventV2.isSynced(item) || isDurableSessionEvent(item),
),
),
watermarks: Effect.fn("V2Session.watermarks")(function* (sessionIDs) {

91
packages/core/test/event.test.ts
View file

@ -1,5 +1,5 @@
import { describe, expect } from "bun:test"
import { Cause, DateTime, Deferred, Effect, Exit, Fiber, Layer, Option, Schema, Stream } from "effect"
import { Cause, DateTime, Deferred, Effect, Exit, Fiber, Layer, Option, Ref, Schema, Stream } from "effect"
import { EventV2 } from "@opencode-ai/core/event"
import { Event } from "@opencode-ai/schema/event"
import { Session } from "@opencode-ai/schema/session"
@ -80,9 +80,7 @@ const durableData = (sessionID: Session.ID, text: string) => ({
/** Followed log read without markers: the old `durable` stream shape. */
const tail = (events: EventV2.Interface, input: { aggregateID: string; after?: number }) =>
events
.log({ ...input, follow: true })
.pipe(Stream.filter((item): item is EventV2.Payload => !EventV2.isCaughtUp(item)))
events.log({ ...input, follow: true }).pipe(Stream.filter((item): item is EventV2.Payload => !EventV2.isSynced(item)))
const it = testEffect(
AppNodeBuilder.build(LayerNode.group([Database.node, EventV2.node, Location.node]), [[Location.node, locationLayer]]),
@ -1128,7 +1126,7 @@ describe("EventV2", () => {
}),
)
it.effect("log without follow replays events and completes with a caught-up marker", () =>
it.effect("log without follow replays events and completes with a synced marker", () =>
Effect.gen(function* () {
const events = yield* EventV2.Service
const aggregateID = Session.ID.create()
@ -1137,16 +1135,16 @@ describe("EventV2", () => {
const items = Array.from(yield* Stream.runCollect(events.log({ aggregateID })))
expect(items.map((item) => (EventV2.isCaughtUp(item) ? item.type : item.durable?.seq))).toEqual([
expect(items.map((item) => (EventV2.isSynced(item) ? item.type : item.durable?.seq))).toEqual([
EventV2.Seq.make(0),
EventV2.Seq.make(1),
"log.caught_up",
"log.synced",
])
expect(items.at(-1)).toEqual({ type: "log.caught_up", aggregateID, seq: EventV2.Seq.make(1) })
expect(items.at(-1)).toEqual({ type: "log.synced", aggregateID, seq: EventV2.Seq.make(1) })
}),
)
it.effect("log caught-up marker omits seq for an empty log and keeps the cursor otherwise", () =>
it.effect("log synced marker omits seq for an empty log and keeps the cursor otherwise", () =>
Effect.gen(function* () {
const events = yield* EventV2.Service
const aggregateID = Session.ID.create()
@ -1155,13 +1153,13 @@ describe("EventV2", () => {
yield* events.publish(DurableMessage, durableData(aggregateID, "zero"))
const drained = Array.from(yield* Stream.runCollect(events.log({ aggregateID, after: 0 })))
expect(empty).toEqual([{ type: "log.caught_up", aggregateID }])
expect(empty).toEqual([{ type: "log.synced", aggregateID }])
expect(empty[0]).not.toHaveProperty("seq")
expect(drained).toEqual([{ type: "log.caught_up", aggregateID, seq: EventV2.Seq.make(0) }])
expect(drained).toEqual([{ type: "log.synced", aggregateID, seq: EventV2.Seq.make(0) }])
}),
)
it.effect("log with follow emits the caught-up marker at the replay-to-live boundary", () =>
it.effect("log with follow emits the synced marker at the replay-to-live boundary", () =>
Effect.gen(function* () {
const events = yield* EventV2.Service
const aggregateID = Session.ID.create()
@ -1174,14 +1172,79 @@ describe("EventV2", () => {
yield* events.publish(DurableMessage, durableData(aggregateID, "one"))
const items = Array.from(yield* Fiber.join(fiber))
expect(items.map((item) => (EventV2.isCaughtUp(item) ? item : item.durable?.seq))).toEqual([
expect(items.map((item) => (EventV2.isSynced(item) ? item : item.durable?.seq))).toEqual([
EventV2.Seq.make(0),
{ type: "log.caught_up", aggregateID, seq: EventV2.Seq.make(0) },
{ type: "log.synced", aggregateID, seq: EventV2.Seq.make(0) },
EventV2.Seq.make(1),
])
}),
)
it.effect("log replays across configured read pages", () =>
Effect.gen(function* () {
const eventLayer = EventV2.layerWith({ logReadPageSize: 2 }).pipe(Layer.provide(LayerNode.compile(Database.node)))
yield* Effect.gen(function* () {
const events = yield* EventV2.Service
const aggregateID = Session.ID.create()
yield* events.publish(DurableMessage, durableData(aggregateID, "zero"))
yield* events.publish(DurableMessage, durableData(aggregateID, "one"))
yield* events.publish(DurableMessage, durableData(aggregateID, "two"))
yield* events.publish(DurableMessage, durableData(aggregateID, "three"))
yield* events.publish(DurableMessage, durableData(aggregateID, "four"))
const items = Array.from(yield* Stream.runCollect(events.log({ aggregateID })))
expect(items.map((item) => (EventV2.isSynced(item) ? item.type : item.durable?.seq))).toEqual([
EventV2.Seq.make(0),
EventV2.Seq.make(1),
EventV2.Seq.make(2),
EventV2.Seq.make(3),
EventV2.Seq.make(4),
"log.synced",
])
expect(items.at(-1)).toEqual({ type: "log.synced", aggregateID, seq: EventV2.Seq.make(4) })
}).pipe(Effect.provide(Layer.merge(LayerNode.compile(Database.node), eventLayer)))
}),
)
it.effect("log with follow emits events committed during replay after the synced marker", () =>
Effect.gen(function* () {
const readStarted = yield* Deferred.make<void>()
const releaseRead = yield* Deferred.make<void>()
const firstRead = yield* Ref.make(true)
const eventLayer = EventV2.layerWith({
beforeAggregateRead: () =>
Ref.getAndSet(firstRead, false).pipe(
Effect.flatMap((shouldBlock) => {
if (!shouldBlock) return Effect.void
return Deferred.succeed(readStarted, undefined).pipe(Effect.andThen(Deferred.await(releaseRead)))
}),
),
}).pipe(Layer.provide(LayerNode.compile(Database.node)))
yield* Effect.gen(function* () {
const events = yield* EventV2.Service
const aggregateID = Session.ID.create()
yield* events.publish(DurableMessage, durableData(aggregateID, "zero"))
const fiber = yield* events
.log({ aggregateID, follow: true })
.pipe(Stream.take(3), Stream.runCollect, Effect.forkScoped)
yield* Deferred.await(readStarted)
yield* events.publish(DurableMessage, durableData(aggregateID, "one"))
yield* Deferred.succeed(releaseRead, undefined)
const items = Array.from(yield* Fiber.join(fiber))
expect(items.map((item) => (EventV2.isSynced(item) ? item : item.durable?.seq))).toEqual([
EventV2.Seq.make(0),
{ type: "log.synced", aggregateID, seq: EventV2.Seq.make(0) },
EventV2.Seq.make(1),
])
}).pipe(Effect.provide(Layer.merge(LayerNode.compile(Database.node), eventLayer)))
}),
)
it.effect("changes emits sweep-required on subscribe then coalesced hints per aggregate", () =>
Effect.gen(function* () {
const events = yield* EventV2.Service

7
packages/core/test/session-create.test.ts
View file

@ -8,7 +8,6 @@ import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
import { LayerNode } from "@opencode-ai/core/effect/layer-node"
import { EventV2 } from "@opencode-ai/core/event"
import { EventTable } from "@opencode-ai/core/event/sql"
import { Job } from "@opencode-ai/core/job"
import { Location } from "@opencode-ai/core/location"
import { ModelV2 } from "@opencode-ai/core/model"
import { ProjectV2 } from "@opencode-ai/core/project"
@ -49,11 +48,11 @@ const it = testEffect(
const location = Location.Ref.make({ directory: AbsolutePath.make("/project") })
const id = SessionV2.ID.create()
/** Public session events from a `log` read, without caught-up markers. */
/** Public session events from a `log` read, without synced markers. */
const logEvents = (session: SessionV2.Interface, sessionID: SessionV2.ID, follow?: boolean) =>
session
.log({ sessionID, follow })
.pipe(Stream.filter((item): item is SessionEvent.DurableEvent => !EventV2.isCaughtUp(item)))
.pipe(Stream.filter((item): item is SessionEvent.DurableEvent => !EventV2.isSynced(item)))
const assertCreateInputTypes = (session: SessionV2.Interface) => {
// @ts-expect-error location or parentID is required.
@ -213,7 +212,7 @@ describe("SessionV2.create", () => {
durable: { seq: 0 },
data: { sessionID: forked.id, parentID: parent.id },
})
expect(yield* SessionInput.find(db, forkContext[0]!.id)).toMatchObject({
expect(yield* SessionInput.find(db, forkContext[0].id)).toMatchObject({
sessionID: forked.id,
prompt: { text: "First" },
promotedSeq: 2,

18
packages/core/test/session-log.test.ts
View file

@ -35,7 +35,7 @@ const it = testEffect(
const location = Location.Ref.make({ directory: AbsolutePath.make("/project") })
describe("SessionV2.log", () => {
it.effect("replays public session events and marks caught-up at the aggregate watermark", () =>
it.effect("replays public session events and marks synced at the aggregate watermark", () =>
Effect.gen(function* () {
const session = yield* SessionV2.Service
const events = yield* EventV2.Service
@ -47,8 +47,8 @@ describe("SessionV2.log", () => {
// Session creation commits a non-public durable event, so the marker's
// seq covers more of the aggregate than the public events emitted.
expect(items.map((item) => item.type)).toEqual(["session.next.renamed", "log.caught_up"])
expect(items.at(-1)).toEqual({ type: "log.caught_up", aggregateID: created.id, seq: watermark })
expect(items.map((item) => item.type)).toEqual(["session.next.renamed", "log.synced"])
expect(items.at(-1)).toEqual({ type: "log.synced", aggregateID: created.id, seq: watermark })
}),
)
@ -64,7 +64,7 @@ describe("SessionV2.log", () => {
yield* session.rename({ sessionID: created.id, title: "renamed live" })
const items = Array.from(yield* Fiber.join(fiber))
expect(items.map((item) => item.type)).toEqual(["log.caught_up", "session.next.renamed"])
expect(items.map((item) => item.type)).toEqual(["log.synced", "session.next.renamed"])
}),
)
@ -95,13 +95,13 @@ describe("SessionV2.log", () => {
const items = Array.from(yield* Stream.runCollect(session.log({ sessionID: created.id, after: 1 })))
expect(
items.map((item): number | string | undefined => (EventV2.isCaughtUp(item) ? item.type : item.durable?.seq)),
).toEqual([3, 4, "log.caught_up"])
expect(items.at(-1)).toEqual({ type: "log.caught_up", aggregateID: created.id, seq: EventV2.Seq.make(4) })
items.map((item): number | string | undefined => (EventV2.isSynced(item) ? item.type : item.durable?.seq)),
).toEqual([3, 4, "log.synced"])
expect(items.at(-1)).toEqual({ type: "log.synced", aggregateID: created.id, seq: EventV2.Seq.make(4) })
}),
)
it.effect("completes with a bare caught-up marker for a migrated Session with no event sequence", () =>
it.effect("completes with a bare synced marker for a migrated Session with no event sequence", () =>
Effect.gen(function* () {
const db = (yield* Database.Service).db
const session = yield* SessionV2.Service
@ -125,7 +125,7 @@ describe("SessionV2.log", () => {
const items = Array.from(yield* Stream.runCollect(session.log({ sessionID })))
expect(items).toEqual([{ type: "log.caught_up", aggregateID: sessionID }])
expect(items).toEqual([{ type: "log.synced", aggregateID: sessionID }])
}),
)
})

5
packages/core/test/session-prompt.test.ts
View file

@ -6,7 +6,6 @@ import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
import { LayerNode } from "@opencode-ai/core/effect/layer-node"
import { EventV2 } from "@opencode-ai/core/event"
import { EventTable } from "@opencode-ai/core/event/sql"
import { Job } from "@opencode-ai/core/job"
import { SessionEvent } from "@opencode-ai/core/session/event"
import { ModelV2 } from "@opencode-ai/core/model"
import { ProviderV2 } from "@opencode-ai/core/provider"
@ -248,7 +247,7 @@ describe("SessionV2.prompt", () => {
const publicEvents = (input: { sessionID: SessionV2.ID; after?: number }) =>
session
.log({ ...input, follow: true })
.pipe(Stream.filter((item): item is SessionEvent.DurableEvent => !EventV2.isCaughtUp(item)))
.pipe(Stream.filter((item): item is SessionEvent.DurableEvent => !EventV2.isSynced(item)))
const fiber = yield* publicEvents({ sessionID }).pipe(Stream.take(4), Stream.runCollect, Effect.forkScoped)
yield* Effect.yieldNow
@ -265,7 +264,7 @@ describe("SessionV2.prompt", () => {
])
expect(
Array.from(
yield* publicEvents({ sessionID, after: streamed[0]!.durable?.seq }).pipe(Stream.take(1), Stream.runCollect),
yield* publicEvents({ sessionID, after: streamed[0].durable?.seq }).pipe(Stream.take(1), Stream.runCollect),
).map((event): [number | undefined, string] => [event.durable?.seq, event.type]),
).toEqual([[1, "session.next.prompt.admitted"]])
}),