Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
es terminology
Julius Marminge7934639aa137
diff --git a/.plans/14-server-authoritative-event-sourcing-cleanup.md b/.plans/14-server-authoritative-event-sourcing-cleanup.mdnew file mode 100644index 000000000..e3a125b81--- /dev/null+++ b/.plans/14-server-authoritative-event-sourcing-cleanup.md@@ -0,0 +1,206 @@+# Server-Authoritative Event-Sourcing Cleanup Plan++Goal:+- Move to a cleaner service architecture with:+ - durable, server-authoritative event sourcing+ - strict command routing/validation+ - pluggable provider adapters+ - explicit separation between transport, domain orchestration, provider runtime, and persistence++## Target Service Graph (ASCII)++```text+ +---------------------------++ | wsServer |+ | transport |+ +---------------------------++ | orchestration.dispatchCommand+ v+ +-------------------------------------------++ | OrchestrationCommandRouter |+ +-------------------------------------------++ |+ v+ +-------------------------------------------++ | OrchestrationCommandHandlers |+ +-------------------------------------------++ |+ v+ +-------------------------------------------++ | OrchestrationEventStore |+ +-------------------------------------------++ |+ v+ +-------------------------------------------++ | OrchestrationProjectionService |+ +-------------------------------------------++ | snapshot/replay+ +---------------------------> wsServer+++wsServer -- providers.* RPC --> +---------------------------++ | ProviderService |+ +---------------------------++ | |+ v v+ +-------------------+ +-------------------------++ | ProviderSession | | ProviderAdapterRegistry |+ | Registry (durable)| +-------------------------++ +-------------------+ |+ ^ v+ | +-------------------------++ | | ProviderAdapter(s) |+ | +-------------------------++ | |+ | runtime events v+ | +---------------------------++ +----------| ProviderRuntimeIngestion |+ +---------------------------++ | | |+ v v v+ Router Session Checkpoint+ Registry Service++ +-------------------------------------------++ | CheckpointService |+ +-------------------------------------------++ | | |+ v v v+ +--------------------+ +-------------+ +-------------------++ | CheckpointCatalog | | Checkpoint | | ProviderAdapter(s)|+ | (durable) | | Store (git) | | (read/rollback) |+ +--------------------+ +-------------+ +-------------------++ |+ v+ +------++ |SQLite|+ +------+++OrchestrationEventStore ------> SQLite+OrchestrationProjectionService -> SQLite+ProviderSessionRegistry ------> SQLite+CheckpointCatalog ------> SQLite+```++## Commit Series++### Commit 1: Split public vs system orchestration command contracts+- Create separate schemas/types:+ - `ClientOrchestrationCommandSchema`+ - `SystemOrchestrationCommandSchema`+ - `OrchestrationCommandSchema = union(client, system)`+- Ensure client transport can only submit client commands.+- Keep system commands for server-internal workflows only.+- Expected files:+ - `packages/contracts/src/orchestration.ts`+ - `apps/server/src/wsServer.ts`+ - orchestration/service tests+- Tests:+ - reject system-only command via WS dispatch path+ - preserve internal dispatch functionality for system commands++### Commit 2: Introduce `OrchestrationCommandRouter` + handler boundary+- Add dedicated router service to validate, authorize, and route commands.+- Move command-to-event mapping out of `orchestration/Layer.ts` into handlers.+- Add aggregate-level invariant checks before append (thread exists, project exists, etc.).+- Expected files:+ - `apps/server/src/orchestration/Services/CommandRouter.ts` (new)+ - `apps/server/src/orchestration/Layers/CommandRouter.ts` (new)+ - `apps/server/src/orchestration/Layer.ts`+ - `apps/server/src/orchestration/reducer.ts` (only if needed for event payload changes)+- Tests:+ - router validation and invariant failures+ - handler happy-path tests per command type++### Commit 3: Harden event store for idempotency + optimistic append metadata+- Add DB-level idempotency guard for `command_id` (`UNIQUE` where non-null).+- Extend append API to support idempotent replays and deterministic return of prior event on duplicate `commandId`.+- Add optional aggregate version metadata for future optimistic concurrency.+- Expected files:+ - `apps/server/src/persistence/Migrations/00x_*.ts` (new migration)+ - `apps/server/src/persistence/Services/OrchestrationEvents.ts`+ - `apps/server/src/persistence/Layers/OrchestrationEvents.ts`+- Tests:+ - duplicate command ID append returns same event/sequence (or explicit idempotent behavior)+ - concurrent append behavior stays ordered and deterministic++### Commit 4: Extract provider-runtime -> orchestration bridge from `wsServer`+- Create `ProviderRuntimeIngestionService` that:+ - subscribes to `ProviderService.streamEvents`+ - translates runtime events into orchestration commands+ - dispatches through router/engine+- Remove provider-to-orchestration state mutation logic from `wsServer`.+- Expected files:+ - `apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts` (new)+ - `apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts` (new)+ - `apps/server/src/wsServer.ts`+- Tests:+ - ingestion service mapping tests (turn started/completed, message delta/completed, runtime error)+ - ws integration confirms same external push behavior++### Commit 5: Make session directory durable (`ProviderSessionRegistry`)+- Replace in-memory-only `ProviderSessionDirectoryLive` with persistence-backed registry.+- Keep in-memory cache optional, but source of truth must be persistent.+- Add startup reconciliation to prune dead sessions / keep known thread mapping.+- Expected files:+ - `apps/server/src/provider/Services/ProviderSessionDirectory.ts` (or new SessionRegistry service)+ - `apps/server/src/provider/Layers/ProviderSessionDirectory.ts`+ - `apps/server/src/persistence/Migrations/00x_*.ts` (new table/indexes)+ - provider persistence tests+- Tests:+ - survives server restart with correct mapping+ - stale session cleanup semantics++### Commit 6: Re-key checkpoint metadata from session to thread identity+- Change checkpoint catalog primary identity from `provider_session_id` to durable `thread_id`.+- Keep `session_id` as nullable metadata only.+- Update checkpoint flows (`initialize`, `capture`, `list`, `diff`, `revert`) to use thread identity.+- Expected files:+ - `apps/server/src/persistence/Migrations/00x_*.ts` (checkpoint schema migration)+ - `apps/server/src/persistence/Services/Checkpoints.ts`+ - `apps/server/src/persistence/Layers/Checkpoints.ts`+ - `apps/server/src/checkpointing/Layers/CheckpointService.ts`+- Tests:+ - resume/new session over same thread sees same checkpoint history+ - revert/diff still work after session churn++### Commit 7: Add durable projection persistence for orchestration read models+- Introduce projection tables/snapshots persisted in DB to avoid full replay dependency.+- Keep event stream as source of truth; projection rebuild stays deterministic.+- `getSnapshot` reads from projection store (memory cache optional).+- Expected files:+ - `apps/server/src/persistence/Migrations/00x_*.ts` (projection tables)+ - `apps/server/src/orchestration/*` projection service/layer+ - `apps/server/src/wsServer.ts` (snapshot/replay path wiring)+- Tests:+ - cold boot snapshot load without replaying full history in process+ - projection rebuild from events yields same result as previous reducer semantics++### Commit 8: Narrow `ProviderService` responsibilities+- Keep `ProviderService` focused on provider RPC/session lifecycle + unified runtime stream.+- Move checkpoint-capture side effects out of provider event worker into dedicated ingestion/checkpoint pipeline service.+- Preserve adapter pluggability and provider-neutral contracts.+- Expected files:+ - `apps/server/src/provider/Layers/ProviderService.ts`+ - new orchestration/checkpoint runtime coordinator service(s)+- Tests:+ - provider service routing stays intact+ - checkpoint capture still triggered by turn completion through new coordinator++### Commit 9: Remove dead legacy path and finalize docs+- Remove unused legacy manager/store path from active architecture:+ - `providerManager.ts`+ - `filesystemCheckpointStore.ts` (if no longer needed by tests/tools)+- Update architecture docs with final service boundaries and boot/runtime graph.+- Expected files:+ - legacy files + references+ - `AGENTS.md`/docs as needed+ - `.plans` docs linkage+- Tests:+ - full server integration suite passes on Effect-only path+ - no regressions in WS protocol behavior++## Risk Controls+- Keep WS method names and payload contracts stable throughout.+- Gate each commit with targeted integration tests before moving forward.+- Avoid broad event-type churn in one step; migrate schemas incrementally with clear compatibility windows.diff --git a/apps/server/src/orchestration/Errors.ts b/apps/server/src/orchestration/Errors.tsindex e7b4d8c0d..35091b3eb 100644--- a/apps/server/src/orchestration/Errors.ts+++ b/apps/server/src/orchestration/Errors.ts@@ -1,6 +1,6 @@import { SchemaIssue, Schema } from "effect";-import type { OrchestrationEventRepositoryError } from "../persistence/Errors.ts";+import type { OrchestrationEventStoreError } from "../persistence/Errors.ts";export class OrchestrationCommandJsonParseError extends Schema.TaggedErrorClass<OrchestrationCommandJsonParseError>()("OrchestrationCommandJsonParseError",@@ -26,8 +26,21 @@ export class OrchestrationCommandDecodeError extends Schema.TaggedErrorClass<Orc}}-export class OrchestrationReducerDecodeError extends Schema.TaggedErrorClass<OrchestrationReducerDecodeError>()(- "OrchestrationReducerDecodeError",+export class OrchestrationCommandInvariantError extends Schema.TaggedErrorClass<OrchestrationCommandInvariantError>()(+ "OrchestrationCommandInvariantError",+ {+ commandType: Schema.String,+ detail: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Orchestration command invariant failed (${this.commandType}): ${this.detail}`;+ }+}++export class OrchestrationProjectorDecodeError extends Schema.TaggedErrorClass<OrchestrationProjectorDecodeError>()(+ "OrchestrationProjectorDecodeError",{eventType: Schema.String,issue: Schema.String,@@ -35,7 +48,7 @@ export class OrchestrationReducerDecodeError extends Schema.TaggedErrorClass<Orc},) {override get message(): string {- return `Reducer decode failed for ${this.eventType}: ${this.issue}`;+ return `Projector decode failed for ${this.eventType}: ${this.issue}`;}}@@ -53,8 +66,9 @@ export class OrchestrationListenerCallbackError extends Schema.TaggedErrorClass<}export type OrchestrationDispatchError =- | OrchestrationEventRepositoryError- | OrchestrationReducerDecodeError+ | OrchestrationEventStoreError+ | OrchestrationCommandInvariantError+ | OrchestrationProjectorDecodeError| OrchestrationListenerCallbackError;export type OrchestrationEngineError =@@ -69,9 +83,9 @@ export function toOrchestrationCommandDecodeError(error: Schema.SchemaError) {});}-export function toReducerDecodeError(eventType: string) {- return (error: Schema.SchemaError): OrchestrationReducerDecodeError =>- new OrchestrationReducerDecodeError({+export function toProjectorDecodeError(eventType: string) {+ return (error: Schema.SchemaError): OrchestrationProjectorDecodeError =>+ new OrchestrationProjectorDecodeError({eventType,issue: SchemaIssue.makeFormatterDefault()(error.issue),cause: error,diff --git a/apps/server/src/orchestration/Layer.test.ts b/apps/server/src/orchestration/Layer.test.tsindex e82811c12..af5da282a 100644--- a/apps/server/src/orchestration/Layer.test.ts+++ b/apps/server/src/orchestration/Layer.test.ts@@ -3,18 +3,18 @@ import { Effect, Layer, ManagedRuntime, Queue, Stream } from "effect";import { describe, expect, it } from "vitest";import {- OrchestrationEventRepository,- type OrchestrationEventRepositoryShape,-} from "../persistence/Services/OrchestrationEvents.ts";+ OrchestrationEventStore,+ type OrchestrationEventStoreShape,+} from "../persistence/Services/OrchestrationEventStore.ts";import { PersistenceSqlError } from "../persistence/Errors.ts";import { SqlitePersistenceMemory } from "../persistence/Layers/Sqlite.ts";-import { OrchestrationEngineLive } from "./Layer.ts";-import { OrchestrationEngineService } from "./Service.ts";-import { OrchestrationEventRepositoryLive } from "../persistence/Layers/OrchestrationEvents.ts";+import { OrchestrationEngineLive } from "./Layers/OrchestrationEngine.ts";+import { OrchestrationEngineService } from "./Services/OrchestrationEngine.ts";+import { OrchestrationEventStoreLive } from "../persistence/Layers/OrchestrationEventStore.ts";export async function createOrchestrationSystem() {const orchestrationLayer = OrchestrationEngineLive.pipe(- Layer.provide(OrchestrationEventRepositoryLive),+ Layer.provide(OrchestrationEventStoreLive),Layer.provide(SqlitePersistenceMemory),);const runtime = ManagedRuntime.make(orchestrationLayer);@@ -27,7 +27,7 @@ export async function createOrchestrationSystem() {}describe("OrchestrationEngine", () => {- it("returns deterministic snapshots for repeated reads", async () => {+ it("returns deterministic read models for repeated reads", async () => {const createdAt = new Date().toISOString();const projectId = "project-1";const threadId = "thread-1";@@ -59,9 +59,9 @@ describe("OrchestrationEngine", () => {createdAt,}),);- const snapshotA = await system.run(engine.getSnapshot());- const snapshotB = await system.run(engine.getSnapshot());- expect(snapshotB).toEqual(snapshotA);+ const readModelA = await system.run(engine.getReadModel());+ const readModelB = await system.run(engine.getReadModel());+ expect(readModelB).toEqual(readModelA);await system.dispose();});@@ -89,7 +89,11 @@ describe("OrchestrationEngine", () => {createdAt: new Date().toISOString(),}),);- const events = await system.run(engine.replayEvents(0));+ const events = await system.run(+ Stream.runCollect(engine.readEvents(0)).pipe(+ Effect.map((chunk): OrchestrationEvent[] => Array.from(chunk)),+ ),+ );expect(events.length).toBe(2);expect(events[0]?.type).toBe("thread.created");expect(events[1]?.type).toBe("thread.deleted");@@ -167,7 +171,7 @@ describe("OrchestrationEngine", () => {}),);- const firstThread = (await system.run(engine.getSnapshot())).threads.find(+ const firstThread = (await system.run(engine.getReadModel())).threads.find((thread) => thread.id === "thread-turn-diff",);expect(firstThread?.turnDiffSummaries).toEqual([@@ -289,7 +293,7 @@ describe("OrchestrationEngine", () => {}),);- const thread = (await system.run(engine.getSnapshot())).threads.find(+ const thread = (await system.run(engine.getReadModel())).threads.find((entry) => entry.id === "thread-revert",);expect(thread?.messages.map((message) => message.id)).toEqual(["user-1", "assistant:turn-1"]);@@ -299,20 +303,20 @@ describe("OrchestrationEngine", () => {});it("allows stop to be called multiple times", async () => {- const inMemoryStore: OrchestrationEventRepositoryShape = {+ const inMemoryStore: OrchestrationEventStoreShape = {append(event) {return Effect.succeed({ ...event, sequence: 1 });},readFromSequence() {- return Effect.succeed([]);+ return Stream.empty;},readAll() {- return Effect.succeed([]);+ return Stream.empty;},};const runtime = ManagedRuntime.make(OrchestrationEngineLive.pipe(- Layer.provide(Layer.succeed(OrchestrationEventRepository, inMemoryStore)),+ Layer.provide(Layer.succeed(OrchestrationEventStore, inMemoryStore)),),);await runtime.runPromise(Effect.service(OrchestrationEngineService));@@ -325,7 +329,7 @@ describe("OrchestrationEngine", () => {let nextSequence = 1;let shouldFailFirstAppend = true;- const flakyStore: OrchestrationEventRepositoryShape = {+ const flakyStore: OrchestrationEventStoreShape = {append(event) {if (shouldFailFirstAppend) {shouldFailFirstAppend = false;@@ -345,16 +349,16 @@ describe("OrchestrationEngine", () => {return Effect.succeed(savedEvent);},readFromSequence(sequenceExclusive) {- return Effect.succeed(events.filter((event) => event.sequence > sequenceExclusive));+ return Stream.fromIterable(events.filter((event) => event.sequence > sequenceExclusive));},readAll() {- return Effect.succeed(events);+ return Stream.fromIterable(events);},};const runtime = ManagedRuntime.make(OrchestrationEngineLive.pipe(- Layer.provide(Layer.succeed(OrchestrationEventRepository, flakyStore)),+ Layer.provide(Layer.succeed(OrchestrationEventStore, flakyStore)),),);const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));@@ -391,8 +395,69 @@ describe("OrchestrationEngine", () => {);expect(result.sequence).toBe(1);- expect((await runtime.runPromise(engine.getSnapshot())).sequence).toBe(1);+ expect((await runtime.runPromise(engine.getReadModel())).sequence).toBe(1);await runtime.dispose();});++ it("fails command dispatch when command invariants are violated", async () => {+ const system = await createOrchestrationSystem();+ const engine = system.engine;+ const createdAt = new Date().toISOString();++ await expect(+ system.run(+ engine.dispatch({+ type: "message.send",+ commandId: "cmd-invariant-missing-thread",+ threadId: "thread-missing",+ messageId: "msg-missing",+ role: "user",+ text: "hello",+ streaming: false,+ createdAt,+ }),+ ),+ ).rejects.toThrow("Thread 'thread-missing' does not exist");++ await system.dispose();+ });++ it("rejects duplicate thread creation", async () => {+ const system = await createOrchestrationSystem();+ const engine = system.engine;+ const createdAt = new Date().toISOString();++ await system.run(+ engine.dispatch({+ type: "thread.create",+ commandId: "cmd-thread-duplicate-1",+ threadId: "thread-duplicate",+ projectId: "project-duplicate",+ title: "duplicate",+ model: "gpt-5-codex",+ branch: null,+ worktreePath: null,+ createdAt,+ }),+ );++ await expect(+ system.run(+ engine.dispatch({+ type: "thread.create",+ commandId: "cmd-thread-duplicate-2",+ threadId: "thread-duplicate",+ projectId: "project-duplicate",+ title: "duplicate",+ model: "gpt-5-codex",+ branch: null,+ worktreePath: null,+ createdAt,+ }),+ ),+ ).rejects.toThrow("already exists");++ await system.dispose();+ });});diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.tsnew file mode 100644index 000000000..8dcc809fe--- /dev/null+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.ts@@ -0,0 +1,110 @@+import type {+ OrchestrationCommand,+ OrchestrationEvent,+ OrchestrationReadModel,+} from "@t3tools/contracts";+import { OrchestrationCommandSchema } from "@t3tools/contracts";+import { Deferred, Effect, Layer, PubSub, Queue, Schema, Stream } from "effect";++import { createLogger } from "../../logger.ts";+import { OrchestrationEventStore } from "../../persistence/Services/OrchestrationEventStore.ts";+import {+ toOrchestrationCommandDecodeError,+ toOrchestrationJsonParseError,+ type OrchestrationDispatchError,+} from "../Errors.ts";+import { decideOrchestrationCommand } from "../decider.ts";+import { createEmptyReadModel, projectEvent } from "../projector.ts";+import {+ OrchestrationEngineService,+ type OrchestrationEngineShape,+} from "../Services/OrchestrationEngine.ts";++interface CommandEnvelope {+ command: OrchestrationCommand;+ result: Deferred.Deferred<{ sequence: number }, OrchestrationDispatchError>;+}++const decodeUnknownCommand = Schema.decodeUnknownEffect(OrchestrationCommandSchema);++const makeOrchestrationEngine = Effect.gen(function* () {+ const logger = createLogger("orchestration");+ const eventStore = yield* OrchestrationEventStore;++ let readModel = createEmptyReadModel(new Date().toISOString());++ const commandQueue = yield* Queue.unbounded<CommandEnvelope>();+ const eventPubSub = yield* PubSub.unbounded<OrchestrationEvent>();++ const processEnvelope = (envelope: CommandEnvelope): Effect.Effect<void> =>+ Effect.gen(function* () {+ const eventBase = yield* decideOrchestrationCommand({+ command: envelope.command,+ readModel,+ });+ const savedEvent = yield* eventStore.append(eventBase);+ readModel = yield* projectEvent(readModel, savedEvent);+ yield* PubSub.publish(eventPubSub, savedEvent);++ yield* Deferred.succeed(envelope.result, { sequence: savedEvent.sequence });+ }).pipe(Effect.catch((error) => Deferred.fail(envelope.result, error).pipe(Effect.asVoid)));++ // bootstrap read model from event store+ yield* Stream.runForEach(eventStore.readAll(), (event) =>+ Effect.gen(function* () {+ readModel = yield* projectEvent(readModel, event);+ }),+ );++ const worker = Effect.forever(Queue.take(commandQueue).pipe(Effect.flatMap(processEnvelope)));+ yield* Effect.forkScoped(worker);+ logger.info("orchestration engine started", {+ sequence: readModel.sequence,+ });++ const getReadModel: OrchestrationEngineShape["getReadModel"] = () =>+ Effect.sync((): OrchestrationReadModel => readModel);++ const readEvents: OrchestrationEngineShape["readEvents"] = (fromSequenceExclusive) =>+ eventStore.readFromSequence(fromSequenceExclusive);++ const dispatch: OrchestrationEngineShape["dispatch"] = (command) =>+ Effect.gen(function* () {+ const result = yield* Deferred.make<{ sequence: number }, OrchestrationDispatchError>();+ yield* Queue.offer(commandQueue, { command, result });+ return yield* Deferred.await(result);+ });++ const dispatchUnknownCommand: OrchestrationEngineShape["dispatchUnknownCommand"] = (command) =>+ Effect.gen(function* () {+ const payload =+ typeof command === "string"+ ? yield* Effect.try({+ try: () => JSON.parse(command) as unknown,+ catch: toOrchestrationJsonParseError,+ })+ : command;++ const decoded = yield* decodeUnknownCommand(payload).pipe(+ Effect.mapError(toOrchestrationCommandDecodeError),+ );++ return yield* dispatch(decoded);+ });++ const streamDomainEvents: OrchestrationEngineShape["streamDomainEvents"] =+ Stream.fromPubSub(eventPubSub);++ return {+ getReadModel,+ readEvents,+ dispatchUnknownCommand,+ dispatch,+ streamDomainEvents,+ } satisfies OrchestrationEngineShape;+});++export const OrchestrationEngineLive = Layer.effect(+ OrchestrationEngineService,+ makeOrchestrationEngine,+);diff --git a/apps/server/src/orchestration/Service.ts b/apps/server/src/orchestration/Services/OrchestrationEngine.tssimilarity index 79%rename from apps/server/src/orchestration/Service.tsrename to apps/server/src/orchestration/Services/OrchestrationEngine.tsindex bffd33e50..2287f2ae7 100644--- a/apps/server/src/orchestration/Service.ts+++ b/apps/server/src/orchestration/Services/OrchestrationEngine.ts@@ -2,7 +2,7 @@* OrchestrationEngineService - Service interface for orchestration command handling.** Owns command validation/dispatch and in-memory read-model updates backed by- * `OrchestrationEventRepository` persistence. It does not own provider process+ * `OrchestrationEventStore` persistence. It does not own provider process* management or transport concerns (e.g. websocket request parsing).** Uses Effect `ServiceMap.Service` for dependency injection. Command dispatch,@@ -18,26 +18,26 @@ import type {import { ServiceMap } from "effect";import type { Effect, Stream } from "effect";-import type { OrchestrationDispatchError, OrchestrationEngineError } from "./Errors.ts";-import type { OrchestrationEventRepositoryError } from "../persistence/Errors.ts";+import type { OrchestrationDispatchError, OrchestrationEngineError } from "../Errors.ts";+import type { OrchestrationEventStoreError } from "../../persistence/Errors.ts";export interface OrchestrationEngineShape {/**- * Read the current in-memory orchestration snapshot.+ * Read the current in-memory orchestration read model.** @returns Effect containing the latest read model.*/- readonly getSnapshot: () => Effect.Effect<OrchestrationReadModel, never, never>;+ readonly getReadModel: () => Effect.Effect<OrchestrationReadModel, never, never>;/*** Replay persisted orchestration events from an exclusive sequence cursor.** @param fromSequenceExclusive - Sequence cursor (exclusive).- * @returns Effect containing ordered events.+ * @returns Stream containing ordered events.*/- readonly replayEvents: (+ readonly readEvents: (fromSequenceExclusive: number,- ) => Effect.Effect<OrchestrationEvent[], OrchestrationEventRepositoryError, never>;+ ) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError, never>;/*** Validate and dispatch an unknown command payload.@@ -47,7 +47,7 @@ export interface OrchestrationEngineShape {* @param command - Unknown command payload.* @returns Effect containing the sequence of the persisted event.*/- readonly dispatchUnknown: (+ readonly dispatchUnknownCommand: (command: unknown,) => Effect.Effect<{ sequence: number }, OrchestrationEngineError, never>;@@ -74,7 +74,7 @@ export interface OrchestrationEngineShape {* ```ts* const program = Effect.gen(function* () {* const engine = yield* OrchestrationEngineService- * return yield* engine.getSnapshot()+ * return yield* engine.getReadModel()* })* ```*/diff --git a/apps/server/src/orchestration/commandInvariants.test.ts b/apps/server/src/orchestration/commandInvariants.test.tsnew file mode 100644index 000000000..7ed1c7f84--- /dev/null+++ b/apps/server/src/orchestration/commandInvariants.test.ts@@ -0,0 +1,161 @@+import { describe, expect, it } from "vitest";+import type { OrchestrationCommand, OrchestrationReadModel } from "@t3tools/contracts";+import { Effect } from "effect";++import {+ findThreadById,+ listThreadsByProjectId,+ requireNonNegativeInteger,+ requireThread,+ requireThreadAbsent,+} from "./commandInvariants.ts";++const now = new Date().toISOString();++const readModel: OrchestrationReadModel = {+ sequence: 2,+ updatedAt: now,+ gitByProjectId: {},+ threads: [+ {+ id: "thread-1",+ projectId: "project-a",+ title: "Thread A",+ model: "gpt-5-codex",+ branch: null,+ worktreePath: null,+ createdAt: now,+ updatedAt: now,+ latestTurnId: null,+ latestTurnStartedAt: null,+ latestTurnCompletedAt: null,+ latestTurnDurationMs: null,+ messages: [],+ session: null,+ turnDiffSummaries: [],+ activities: [],+ error: null,+ },+ {+ id: "thread-2",+ projectId: "project-b",+ title: "Thread B",+ model: "gpt-5-codex",+ branch: null,+ worktreePath: null,+ createdAt: now,+ updatedAt: now,+ latestTurnId: null,+ latestTurnStartedAt: null,+ latestTurnCompletedAt: null,+ latestTurnDurationMs: null,+ messages: [],+ session: null,+ turnDiffSummaries: [],+ activities: [],+ error: null,+ },+ ],+};++const messageSendCommand: OrchestrationCommand = {+ type: "message.send",+ commandId: "cmd-1",+ threadId: "thread-1",+ messageId: "msg-1",+ role: "user",+ text: "hello",+ streaming: false,+ createdAt: now,+};++describe("commandInvariants", () => {+ it("finds threads by id and project", () => {+ expect(findThreadById(readModel, "thread-1")?.projectId).toBe("project-a");+ expect(findThreadById(readModel, "missing")).toBeUndefined();+ expect(listThreadsByProjectId(readModel, "project-b").map((thread) => thread.id)).toEqual([+ "thread-2",+ ]);+ });++ it("requires existing thread", async () => {+ const thread = await Effect.runPromise(+ requireThread({+ readModel,+ command: messageSendCommand,+ threadId: "thread-1",+ }),+ );+ expect(thread.id).toBe("thread-1");++ await expect(+ Effect.runPromise(+ requireThread({+ readModel,+ command: messageSendCommand,+ threadId: "missing",+ }),+ ),+ ).rejects.toThrow("does not exist");+ });++ it("requires missing thread for create flows", async () => {+ await Effect.runPromise(+ requireThreadAbsent({+ readModel,+ command: {+ type: "thread.create",+ commandId: "cmd-2",+ threadId: "thread-3",+ projectId: "project-a",+ title: "new",+ model: "gpt-5-codex",+ branch: null,+ worktreePath: null,+ createdAt: now,+ },+ threadId: "thread-3",+ }),+ );++ await expect(+ Effect.runPromise(+ requireThreadAbsent({+ readModel,+ command: {+ type: "thread.create",+ commandId: "cmd-3",+ threadId: "thread-1",+ projectId: "project-a",+ title: "dup",+ model: "gpt-5-codex",+ branch: null,+ worktreePath: null,+ createdAt: now,+ },+ threadId: "thread-1",+ }),+ ),+ ).rejects.toThrow("already exists");+ });++ it("requires non-negative integers", async () => {+ await Effect.runPromise(+ requireNonNegativeInteger({+ commandType: "thread.revert",+ field: "turnCount",+ value: 0,+ }),+ );++ await expect(+ Effect.runPromise(+ requireNonNegativeInteger({+ commandType: "thread.revert",+ field: "turnCount",+ value: -1,+ }),+ ),+ ).rejects.toThrow("greater than or equal to 0");+ });+});diff --git a/apps/server/src/orchestration/commandInvariants.ts b/apps/server/src/orchestration/commandInvariants.tsnew file mode 100644index 000000000..e5e0f5875--- /dev/null+++ b/apps/server/src/orchestration/commandInvariants.ts@@ -0,0 +1,80 @@+import type { OrchestrationCommand, OrchestrationReadModel, OrchestrationThread } from "@t3tools/contracts";+import { Effect } from "effect";++import { OrchestrationCommandInvariantError } from "./Errors.ts";++function invariantError(commandType: string, detail: string): OrchestrationCommandInvariantError {+ return new OrchestrationCommandInvariantError({+ commandType,+ detail,+ });+}++export function findThreadById(+ readModel: OrchestrationReadModel,+ threadId: string,+): OrchestrationThread | undefined {+ return readModel.threads.find((thread) => thread.id === threadId);+}++export function listThreadsByProjectId(+ readModel: OrchestrationReadModel,+ projectId: string,+): ReadonlyArray<OrchestrationThread> {+ return readModel.threads.filter((thread) => thread.projectId === projectId);+}++export function requireThread(+ input: {+ readonly readModel: OrchestrationReadModel;+ readonly command: OrchestrationCommand;+ readonly threadId: string;+ },+): Effect.Effect<OrchestrationThread, OrchestrationCommandInvariantError> {+ const thread = findThreadById(input.readModel, input.threadId);+ if (thread) {+ return Effect.succeed(thread);+ }+ return Effect.fail(+ invariantError(+ input.command.type,+ `Thread '${input.threadId}' does not exist for command '${input.command.type}'.`,+ ),+ );+}++export function requireThreadAbsent(+ input: {+ readonly readModel: OrchestrationReadModel;+ readonly command: OrchestrationCommand;+ readonly threadId: string;+ },+): Effect.Effect<void, OrchestrationCommandInvariantError> {+ if (!findThreadById(input.readModel, input.threadId)) {+ return Effect.void;+ }+ return Effect.fail(+ invariantError(+ input.command.type,+ `Thread '${input.threadId}' already exists and cannot be created twice.`,+ ),+ );+}++export function requireNonNegativeInteger(+ input: {+ readonly commandType: OrchestrationCommand["type"];+ readonly field: string;+ readonly value: number;+ },+): Effect.Effect<void, OrchestrationCommandInvariantError> {+ if (Number.isInteger(input.value) && input.value >= 0) {+ return Effect.void;+ }+ return Effect.fail(+ invariantError(+ input.commandType,+ `${input.field} must be an integer greater than or equal to 0.`,+ ),+ );+}diff --git a/apps/server/src/orchestration/Layer.ts b/apps/server/src/orchestration/decider.tssimilarity index 55%rename from apps/server/src/orchestration/Layer.tsrename to apps/server/src/orchestration/decider.tsindex c03029b93..b1e4c5d79 100644--- a/apps/server/src/orchestration/Layer.ts+++ b/apps/server/src/orchestration/decider.ts@@ -3,28 +3,31 @@ import type {OrchestrationEvent,OrchestrationReadModel,} from "@t3tools/contracts";-import { OrchestrationCommandSchema } from "@t3tools/contracts";-import { Deferred, Effect, Layer, PubSub, Queue, Schema, Stream } from "effect";+import { Effect } from "effect";-import { createLogger } from "../logger.ts";-import { OrchestrationEventRepository } from "../persistence/Services/OrchestrationEvents.ts";+import { OrchestrationCommandInvariantError } from "./Errors.ts";import {- toOrchestrationCommandDecodeError,- toOrchestrationJsonParseError,- type OrchestrationDispatchError,-} from "./Errors.ts";-import { createEmptyReadModel, reduceEvent } from "./reducer.ts";-import { OrchestrationEngineService, type OrchestrationEngineShape } from "./Service.ts";--interface CommandEnvelope {- command: OrchestrationCommand;- result: Deferred.Deferred<{ sequence: number }, OrchestrationDispatchError>;-}--function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEvent, "sequence"> {+ requireNonNegativeInteger,+ requireThread,+ requireThreadAbsent,+} from "./commandInvariants.ts";++export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand")(function* ({+ command,+ readModel,+}: {+ readonly command: OrchestrationCommand;+ readonly readModel: OrchestrationReadModel;+}): Effect.fn.Return<Omit<OrchestrationEvent, "sequence">, OrchestrationCommandInvariantError> {const eventId = crypto.randomUUID();+switch (command.type) {case "thread.create":+ yield* requireThreadAbsent({+ readModel,+ command,+ threadId: command.threadId,+ });return {eventId,type: "thread.created",@@ -44,6 +47,11 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEve},};case "thread.delete":+ yield* requireThread({+ readModel,+ command,+ threadId: command.threadId,+ });return {eventId,type: "thread.deleted",@@ -57,6 +65,11 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEve},};case "thread.meta.update":+ yield* requireThread({+ readModel,+ command,+ threadId: command.threadId,+ });return {eventId,type: "thread.meta-updated",@@ -74,6 +87,11 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEve},};case "message.send":+ yield* requireThread({+ readModel,+ command,+ threadId: command.threadId,+ });return {eventId,type: "message.sent",@@ -91,6 +109,11 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEve},};case "thread.session":+ yield* requireThread({+ readModel,+ command,+ threadId: command.threadId,+ });return {eventId,type: "thread.session-set",@@ -121,6 +144,11 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEve},};case "thread.turnDiff.complete":+ yield* requireThread({+ readModel,+ command,+ threadId: command.threadId,+ });return {eventId,type: "thread.turn-diff-completed",@@ -143,6 +171,11 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEve},};case "thread.activity.append":+ yield* requireThread({+ readModel,+ command,+ threadId: command.threadId,+ });return {eventId,type: "thread.activity-appended",@@ -156,6 +189,21 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEve},};case "thread.revert":+ yield* requireThread({+ readModel,+ command,+ threadId: command.threadId,+ });+ yield* requireNonNegativeInteger({+ commandType: command.type,+ field: "turnCount",+ value: command.turnCount,+ });+ yield* requireNonNegativeInteger({+ commandType: command.type,+ field: "messageCount",+ value: command.messageCount,+ });return {eventId,type: "thread.reverted",@@ -169,90 +217,13 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEvemessageCount: command.messageCount,},};+ default: {+ command satisfies never;+ const fallback = command as any;+ return yield* new OrchestrationCommandInvariantError({+ commandType: fallback.type,+ detail: `Unknown command type: ${fallback.type}`,+ });+ }}-}--const decodeUnknownCommand = Schema.decodeUnknownEffect(OrchestrationCommandSchema);--const makeOrchestrationEngine = Effect.gen(function* () {- const logger = createLogger("orchestration");- const eventStore = yield* OrchestrationEventRepository;-- let readModel = createEmptyReadModel(new Date().toISOString());-- const commandQueue = yield* Queue.unbounded<CommandEnvelope>();- const eventPubSub = yield* PubSub.unbounded<OrchestrationEvent>();-- const processEnvelope = (envelope: CommandEnvelope): Effect.Effect<void> =>- Effect.gen(function* () {- const eventBase = mapCommandToEvent(envelope.command);- const savedEvent = yield* eventStore.append(eventBase);- readModel = yield* reduceEvent(readModel, savedEvent);- yield* PubSub.publish(eventPubSub, savedEvent);-- yield* Deferred.succeed(envelope.result, { sequence: savedEvent.sequence });- }).pipe(Effect.catch((error) => Deferred.fail(envelope.result, error).pipe(Effect.asVoid)));-- const bootstrapReadModel: Effect.Effect<void, OrchestrationDispatchError> = Effect.gen(- function* () {- const existingEvents = yield* eventStore.readAll();- for (const event of existingEvents) {- readModel = yield* reduceEvent(readModel, event);- }- },- );-- yield* bootstrapReadModel;-- const worker = Effect.forever(Queue.take(commandQueue).pipe(Effect.flatMap(processEnvelope)));- yield* Effect.forkScoped(worker);- logger.info("orchestration engine started", {- sequence: readModel.sequence,- });-- const getSnapshot: OrchestrationEngineShape["getSnapshot"] = () =>- Effect.sync((): OrchestrationReadModel => readModel);-- const replayEvents: OrchestrationEngineShape["replayEvents"] = (fromSequenceExclusive) =>- eventStore.readFromSequence(fromSequenceExclusive);-- const dispatch: OrchestrationEngineShape["dispatch"] = (command) =>- Effect.gen(function* () {- const result = yield* Deferred.make<{ sequence: number }, OrchestrationDispatchError>();- yield* Queue.offer(commandQueue, { command, result });- return yield* Deferred.await(result);- });-- const dispatchUnknown: OrchestrationEngineShape["dispatchUnknown"] = (command) =>- Effect.gen(function* () {- const payload =- typeof command === "string"- ? yield* Effect.try({- try: () => JSON.parse(command) as unknown,- catch: toOrchestrationJsonParseError,- })- : command;-- const decoded = yield* decodeUnknownCommand(payload).pipe(- Effect.mapError(toOrchestrationCommandDecodeError),- );-- return yield* dispatch(decoded);- });-- const streamDomainEvents: OrchestrationEngineShape["streamDomainEvents"] =- Stream.fromPubSub(eventPubSub);-- return {- getSnapshot,- replayEvents,- dispatchUnknown,- dispatch,- streamDomainEvents,- } satisfies OrchestrationEngineShape;});--export const OrchestrationEngineLive = Layer.effect(- OrchestrationEngineService,- makeOrchestrationEngine,-);diff --git a/apps/server/src/orchestration/reducer.test.ts b/apps/server/src/orchestration/projector.test.tssimilarity index 87%rename from apps/server/src/orchestration/reducer.test.tsrename to apps/server/src/orchestration/projector.test.tsindex 97cb5a9d1..4be935ac5 100644--- a/apps/server/src/orchestration/reducer.test.ts+++ b/apps/server/src/orchestration/projector.test.ts@@ -2,9 +2,9 @@ import type { OrchestrationEvent } from "@t3tools/contracts";import { Effect } from "effect";import { describe, expect, it } from "vitest";-import { createEmptyReadModel, reduceEvent } from "./reducer.ts";+import { createEmptyReadModel, projectEvent } from "./projector.ts";-describe("orchestration reducer", () => {+describe("orchestration projector", () => {it("applies thread.created events using runtime schema decoding", async () => {const now = new Date().toISOString();const model = createEmptyReadModel(now);@@ -28,7 +28,7 @@ describe("orchestration reducer", () => {},};- const next = await Effect.runPromise(reduceEvent(model, event));+ const next = await Effect.runPromise(projectEvent(model, event));expect(next.sequence).toBe(1);expect(next.threads).toEqual([{@@ -73,10 +73,10 @@ describe("orchestration reducer", () => {},};- await expect(Effect.runPromise(reduceEvent(model, event))).rejects.toBeDefined();+ await expect(Effect.runPromise(projectEvent(model, event))).rejects.toBeDefined();});- it("keeps reducer forward-compatible for unknown event types", async () => {+ it("keeps projector forward-compatible for unknown event types", async () => {const now = new Date().toISOString();const model = createEmptyReadModel(now);const event: OrchestrationEvent = {@@ -90,7 +90,7 @@ describe("orchestration reducer", () => {payload: { test: true },};- const next = await Effect.runPromise(reduceEvent(model, event));+ const next = await Effect.runPromise(projectEvent(model, event));expect(next.sequence).toBe(7);expect(next.updatedAt).toBe("2026-01-01T00:00:00.000Z");expect(next.threads).toEqual([]);@@ -168,9 +168,9 @@ describe("orchestration reducer", () => {},};- const afterCreate = await Effect.runPromise(reduceEvent(model, createdEvent));- const afterRunning = await Effect.runPromise(reduceEvent(afterCreate, runningSessionEvent));- const afterReady = await Effect.runPromise(reduceEvent(afterRunning, readySessionEvent));+ const afterCreate = await Effect.runPromise(projectEvent(model, createdEvent));+ const afterRunning = await Effect.runPromise(projectEvent(afterCreate, runningSessionEvent));+ const afterReady = await Effect.runPromise(projectEvent(afterRunning, readySessionEvent));const thread = afterReady.threads[0];expect(thread?.latestTurnId).toBe("turn-1");@@ -241,9 +241,9 @@ describe("orchestration reducer", () => {},};- const afterCreate = await Effect.runPromise(reduceEvent(model, createdEvent));- const afterDelta = await Effect.runPromise(reduceEvent(afterCreate, deltaEvent));- const afterComplete = await Effect.runPromise(reduceEvent(afterDelta, completionEvent));+ const afterCreate = await Effect.runPromise(projectEvent(model, createdEvent));+ const afterDelta = await Effect.runPromise(projectEvent(afterCreate, deltaEvent));+ const afterComplete = await Effect.runPromise(projectEvent(afterDelta, completionEvent));const message = afterComplete.threads[0]?.messages[0];expect(message).toEqual({diff --git a/apps/server/src/orchestration/reducer.ts b/apps/server/src/orchestration/projector.tssimilarity index 97%rename from apps/server/src/orchestration/reducer.tsrename to apps/server/src/orchestration/projector.tsindex bf643572e..168e439d3 100644--- a/apps/server/src/orchestration/reducer.ts+++ b/apps/server/src/orchestration/projector.ts@@ -17,7 +17,7 @@ import {} from "@t3tools/contracts";import { Effect, Schema } from "effect";-import { toReducerDecodeError, type OrchestrationReducerDecodeError } from "./Errors.ts";+import { toProjectorDecodeError, type OrchestrationProjectorDecodeError } from "./Errors.ts";type ThreadPatch = Partial<Omit<OrchestrationThread, "id" | "projectId">>;@@ -34,10 +34,10 @@ function decodeForEvent<A>(value: unknown,eventType: string,field: string,-): Effect.Effect<A, OrchestrationReducerDecodeError> {+): Effect.Effect<A, OrchestrationProjectorDecodeError> {return Schema.decodeUnknownEffect(schema)(value).pipe(- Effect.mapError(toReducerDecodeError(`${eventType}:${field}`)),- ) as Effect.Effect<A, OrchestrationReducerDecodeError>;+ Effect.mapError(toProjectorDecodeError(`${eventType}:${field}`)),+ ) as Effect.Effect<A, OrchestrationProjectorDecodeError>;}const ThreadCreatedPayloadSchema = Schema.Struct({@@ -104,10 +104,10 @@ export function createEmptyReadModel(nowIso: string): OrchestrationReadModel {};}-export function reduceEvent(+export function projectEvent(model: OrchestrationReadModel,event: OrchestrationEvent,-): Effect.Effect<OrchestrationReadModel, OrchestrationReducerDecodeError> {+): Effect.Effect<OrchestrationReadModel, OrchestrationProjectorDecodeError> {const nextBase: OrchestrationReadModel = {...model,sequence: event.sequence,diff --git a/apps/server/src/persistence/Errors.ts b/apps/server/src/persistence/Errors.tsindex 75f23a89e..a90739514 100644--- a/apps/server/src/persistence/Errors.ts+++ b/apps/server/src/persistence/Errors.ts@@ -158,7 +158,7 @@ export type ProjectRepositoryError =| ProjectPathMissingError| ProjectNotFoundError;-export type OrchestrationEventRepositoryError =+export type OrchestrationEventStoreError =| PersistenceSqlError| PersistenceDecodeError| PersistenceSerializationError;diff --git a/apps/server/src/persistence/Layers/OrchestrationEvents.test.ts b/apps/server/src/persistence/Layers/OrchestrationEventStore.test.tssimilarity index 56%rename from apps/server/src/persistence/Layers/OrchestrationEvents.test.tsrename to apps/server/src/persistence/Layers/OrchestrationEventStore.test.tsindex dddba6a72..19f72ff4f 100644--- a/apps/server/src/persistence/Layers/OrchestrationEvents.test.ts+++ b/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts@@ -1,25 +1,25 @@-import { Effect, Layer } from "effect";+import { Effect, Layer, Stream } from "effect";import { assert, it } from "@effect/vitest";-import { OrchestrationEventRepository } from "../Services/OrchestrationEvents.ts";+import { OrchestrationEventStore } from "../Services/OrchestrationEventStore.ts";import { SqlitePersistenceMemory } from "./Sqlite.ts";-import { OrchestrationEventRepositoryLive } from "./OrchestrationEvents.ts";+import { OrchestrationEventStoreLive } from "./OrchestrationEventStore.ts";import { NodeServices } from "@effect/platform-node";const layer = it.layer(Layer.mergeAll(- Layer.provide(OrchestrationEventRepositoryLive, SqlitePersistenceMemory),+ Layer.provide(OrchestrationEventStoreLive, SqlitePersistenceMemory),NodeServices.layer,),);-layer("OrchestrationEventRepository", (it) => {+layer("OrchestrationEventStore", (it) => {it.effect("stores and replays events", () =>Effect.gen(function* () {const createdAt = new Date().toISOString();- const repository = yield* OrchestrationEventRepository;- const saved = yield* repository.append({+ const eventStore = yield* OrchestrationEventStore;+ const saved = yield* eventStore.append({eventId: "event-1",type: "thread.created",aggregateType: "thread",@@ -30,7 +30,9 @@ layer("OrchestrationEventRepository", (it) => {});assert.equal(saved.sequence, 1);- const replayed = yield* repository.readFromSequence(0);+ const replayed = yield* Stream.runCollect(eventStore.readFromSequence(0)).pipe(+ Effect.map(Array.from),+ );assert.deepEqual(replayed, [saved]);}),);diff --git a/apps/server/src/persistence/Layers/OrchestrationEvents.ts b/apps/server/src/persistence/Layers/OrchestrationEventStore.tssimilarity index 66%rename from apps/server/src/persistence/Layers/OrchestrationEvents.tsrename to apps/server/src/persistence/Layers/OrchestrationEventStore.tsindex 4da8c8c06..c1a79890c 100644--- a/apps/server/src/persistence/Layers/OrchestrationEvents.ts+++ b/apps/server/src/persistence/Layers/OrchestrationEventStore.ts@@ -2,19 +2,19 @@ import type { OrchestrationEvent } from "@t3tools/contracts";import { OrchestrationEventSchema } from "@t3tools/contracts";import * as SqlClient from "effect/unstable/sql/SqlClient";import * as SqlSchema from "effect/unstable/sql/SqlSchema";-import { Effect, Layer, Schema } from "effect";+import { Effect, Layer, Schema, Stream } from "effect";import {toPersistenceDecodeCauseError,toPersistenceDecodeError,toPersistenceSerializationError,toPersistenceSqlError,- type OrchestrationEventRepositoryError,+ type OrchestrationEventStoreError,} from "../Errors.ts";import {- OrchestrationEventRepository,- type OrchestrationEventRepositoryShape,-} from "../Services/OrchestrationEvents.ts";+ OrchestrationEventStore,+ type OrchestrationEventStoreShape,+} from "../Services/OrchestrationEventStore.ts";const decodeEvent = Schema.decodeUnknownEffect(OrchestrationEventSchema);@@ -43,11 +43,13 @@ const ReadFromSequenceRequestSchema = Schema.Struct({sequenceExclusive: Schema.Number,limit: Schema.Number,});+const DEFAULT_READ_FROM_SEQUENCE_LIMIT = 1_000;+const READ_PAGE_SIZE = 500;function eventRowToOrchestrationEvent(row: Schema.Schema.Type<typeof EventRowSchema>,operation: string,-): Effect.Effect<OrchestrationEvent, OrchestrationEventRepositoryError> {+): Effect.Effect<OrchestrationEvent, OrchestrationEventStoreError> {return Effect.try({try: () => JSON.parse(row.payloadJson) as unknown,catch: toPersistenceDecodeCauseError(`${operation}:parsePayloadJson`),@@ -67,7 +69,7 @@ function eventRowToOrchestrationEvent();}-const makeRepository = Effect.gen(function* () {+const makeEventStore = Effect.gen(function* () {const sql = yield* SqlClient.SqlClient;const appendEventRow = SqlSchema.findOne({@@ -126,10 +128,10 @@ const makeRepository = Effect.gen(function* () {`,});- const append: OrchestrationEventRepositoryShape["append"] = (event) =>+ const append: OrchestrationEventStoreShape["append"] = (event) =>Effect.try({try: () => JSON.stringify(event.payload),- catch: toPersistenceSerializationError("OrchestrationEventRepository.append:encodePayload"),+ catch: toPersistenceSerializationError("OrchestrationEventStore.append:encodePayload"),}).pipe(Effect.flatMap((payloadJson) =>appendEventRow({@@ -141,38 +143,68 @@ const makeRepository = Effect.gen(function* () {commandId: event.commandId,payloadJson,}).pipe(- Effect.mapError(toPersistenceSqlError("OrchestrationEventRepository.append:insert")),+ Effect.mapError(toPersistenceSqlError("OrchestrationEventStore.append:insert")),Effect.flatMap((row) =>- eventRowToOrchestrationEvent(row, "OrchestrationEventRepository.append:rowToEvent"),+ eventRowToOrchestrationEvent(row, "OrchestrationEventStore.append:rowToEvent"),),),),);- const readFromSequence: OrchestrationEventRepositoryShape["readFromSequence"] = (+ const readFromSequence: OrchestrationEventStoreShape["readFromSequence"] = (sequenceExclusive,- limit = 1_000,- ) =>- readEventRowsFromSequence({ sequenceExclusive, limit }).pipe(- Effect.mapError(toPersistenceSqlError("OrchestrationEventRepository.readFromSequence:query")),- Effect.flatMap((rows) =>- Effect.forEach(rows, (row) =>- eventRowToOrchestrationEvent(- row,- "OrchestrationEventRepository.readFromSequence:rowToEvent",+ limit = DEFAULT_READ_FROM_SEQUENCE_LIMIT,+ ) => {+ const normalizedLimit = Math.max(0, Math.floor(limit));+ if (normalizedLimit === 0) {+ return Stream.empty;+ }+ const readPage = (cursor: number, remaining: number): Stream.Stream<+ OrchestrationEvent,+ OrchestrationEventStoreError+ > =>+ Stream.fromEffect(+ readEventRowsFromSequence({+ sequenceExclusive: cursor,+ limit: Math.min(remaining, READ_PAGE_SIZE),+ }).pipe(+ Effect.mapError(toPersistenceSqlError("OrchestrationEventStore.readFromSequence:query")),+ Effect.flatMap((rows) =>+ Effect.forEach(rows, (row) =>+ eventRowToOrchestrationEvent(+ row,+ "OrchestrationEventStore.readFromSequence:rowToEvent",+ ),+ ),),),- ),- );+ ).pipe(+ Stream.flatMap((events) => {+ if (events.length === 0) {+ return Stream.empty;+ }+ const nextRemaining = remaining - events.length;+ if (nextRemaining <= 0) {+ return Stream.fromIterable(events);+ }+ return Stream.concat(+ Stream.fromIterable(events),+ readPage(events[events.length - 1]!.sequence, nextRemaining),+ );+ }),+ );++ return readPage(sequenceExclusive, normalizedLimit);+ };return {append,readFromSequence,readAll: () => readFromSequence(0, Number.MAX_SAFE_INTEGER),- } satisfies OrchestrationEventRepositoryShape;+ } satisfies OrchestrationEventStoreShape;});-export const OrchestrationEventRepositoryLive = Layer.effect(- OrchestrationEventRepository,- makeRepository,+export const OrchestrationEventStoreLive = Layer.effect(+ OrchestrationEventStore,+ makeEventStore,);diff --git a/apps/server/src/persistence/Services/OrchestrationEvents.ts b/apps/server/src/persistence/Services/OrchestrationEventStore.tssimilarity index 50%rename from apps/server/src/persistence/Services/OrchestrationEvents.tsrename to apps/server/src/persistence/Services/OrchestrationEventStore.tsindex 88545f142..568866e55 100644--- a/apps/server/src/persistence/Services/OrchestrationEvents.ts+++ b/apps/server/src/persistence/Services/OrchestrationEventStore.ts@@ -1,5 +1,5 @@/**- * OrchestrationEventRepository - Repository interface for orchestration events.+ * OrchestrationEventStore - Event store interface for orchestration events.** Owns durable append/replay access to the orchestration event stream. It does* not reduce events into read models or apply command validation rules.@@ -7,15 +7,15 @@* Uses Effect `ServiceMap.Service` for dependency injection and exposes typed* persistence/decode errors for event append and replay operations.*- * @module OrchestrationEventRepository+ * @module OrchestrationEventStore*/import type { OrchestrationEvent } from "@t3tools/contracts";import { ServiceMap } from "effect";-import type { Effect } from "effect";+import type { Effect, Stream } from "effect";-import type { OrchestrationEventRepositoryError } from "../Errors.ts";+import type { OrchestrationEventStoreError } from "../Errors.ts";-export interface OrchestrationEventRepositoryShape {+export interface OrchestrationEventStoreShape {/*** Persist a new orchestration event.*@@ -24,40 +24,40 @@ export interface OrchestrationEventRepositoryShape {*/readonly append: (event: Omit<OrchestrationEvent, "sequence">,- ) => Effect.Effect<OrchestrationEvent, OrchestrationEventRepositoryError>;+ ) => Effect.Effect<OrchestrationEvent, OrchestrationEventStoreError>;/*** Replay events after the provided sequence.** @param sequenceExclusive - Sequence cursor (exclusive).- * @param limit - Maximum number of events to return.- * @returns Effect containing ordered events.+ * @param limit - Maximum number of events to emit.+ * @returns Stream containing ordered events.*/readonly readFromSequence: (sequenceExclusive: number,limit?: number,- ) => Effect.Effect<OrchestrationEvent[], OrchestrationEventRepositoryError>;+ ) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError>;/*** Read all events from the beginning of the stream.*- * @returns Effect containing all stored events.+ * @returns Stream containing all stored events.*/- readonly readAll: () => Effect.Effect<OrchestrationEvent[], OrchestrationEventRepositoryError>;+ readonly readAll: () => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError>;}/**- * OrchestrationEventRepository - Service tag for orchestration event persistence.+ * OrchestrationEventStore - Service tag for orchestration event persistence.** @example* ```ts* const program = Effect.gen(function* () {- * const events = yield* OrchestrationEventRepository- * return yield* events.readAll()+ * const events = yield* OrchestrationEventStore+ * return yield* Stream.runCollect(events.readAll())* })* ```*/-export class OrchestrationEventRepository extends ServiceMap.Service<- OrchestrationEventRepository,- OrchestrationEventRepositoryShape->()("orchestration/EventRepository") {}+export class OrchestrationEventStore extends ServiceMap.Service<+ OrchestrationEventStore,+ OrchestrationEventStoreShape+>()("orchestration/EventStore") {}diff --git a/apps/server/src/wsServer.ts b/apps/server/src/wsServer.tsindex b251500a9..7fb9ab4f0 100644--- a/apps/server/src/wsServer.ts+++ b/apps/server/src/wsServer.ts@@ -36,13 +36,16 @@ import {import { TerminalManager } from "./terminalManager";import { loadResolvedKeybindingsConfig, upsertKeybindingRule } from "./keybindings";import { searchWorkspaceEntries } from "./workspaceEntries";-import { OrchestrationEngineLive } from "./orchestration/Layer";-import { OrchestrationEngineService, type OrchestrationEngineShape } from "./orchestration/Service";+import { OrchestrationEngineLive } from "./orchestration/Layers/OrchestrationEngine";+import {+ OrchestrationEngineService,+ type OrchestrationEngineShape,+} from "./orchestration/Services/OrchestrationEngine";import { ProjectRepositoryLive } from "./persistence/Layers/Projects";import { makeSqlitePersistenceLive } from "./persistence/Layers/Sqlite";import { ProjectRepository, type ProjectRepositoryShape } from "./persistence/Services/Projects";import assert from "node:assert";-import { OrchestrationEventRepositoryLive } from "./persistence/Layers/OrchestrationEvents";+import { OrchestrationEventStoreLive } from "./persistence/Layers/OrchestrationEventStore";import { makeCodexAdapterLive } from "./provider/Layers/CodexAdapter";import { ProviderAdapterRegistryLive } from "./provider/Layers/ProviderAdapterRegistry";import { makeProviderServiceLive } from "./provider/Layers/ProviderService";@@ -358,8 +361,8 @@ export function createServer(options: ServerOptions) {const processEvent = (event: ProviderRuntimeEvent) =>Effect.gen(function* () {- const snapshot = yield* orchestrationEngine.getSnapshot();- const thread = snapshot.threads.find(+ const readModel = yield* orchestrationEngine.getReadModel();+ const thread = readModel.threads.find((entry) => entry.session?.sessionId === event.sessionId,);if (!thread) return;@@ -735,8 +738,8 @@ export function createServer(options: ServerOptions) {const params = request.params as { sessionId?: string };const sessionId = params.sessionId;if (typeof sessionId === "string") {- const snapshot = await effectRuntime.runPromise(orchestrationEngine.getSnapshot());- const thread = snapshot.threads.find((entry) => entry.session?.sessionId === sessionId);+ const readModel = await effectRuntime.runPromise(orchestrationEngine.getReadModel());+ const thread = readModel.threads.find((entry) => entry.session?.sessionId === sessionId);if (thread) {const now = new Date().toISOString();await effectRuntime.runPromise(@@ -909,7 +912,7 @@ export function createServer(options: ServerOptions) {};case ORCHESTRATION_WS_METHODS.getSnapshot:- return effectRuntime.runPromise(orchestrationEngine.getSnapshot());+ return effectRuntime.runPromise(orchestrationEngine.getReadModel());case ORCHESTRATION_WS_METHODS.dispatchCommand:orchestrationCommandLogger?.write({@@ -917,21 +920,23 @@ export function createServer(options: ServerOptions) {requestId: request.id,command: request.params,});- return effectRuntime.runPromise(orchestrationEngine.dispatchUnknown(request.params));+ return effectRuntime.runPromise(orchestrationEngine.dispatchUnknownCommand(request.params));case ORCHESTRATION_WS_METHODS.replayEvents:return effectRuntime.runPromise(- orchestrationEngine.replayEvents(- Math.max(- 0,- Math.floor(- Number(- (request.params as { fromSequenceExclusive?: number } | undefined)- ?.fromSequenceExclusive ?? 0,+ Stream.runCollect(+ orchestrationEngine.readEvents(+ Math.max(+ 0,+ Math.floor(+ Number(+ (request.params as { fromSequenceExclusive?: number } | undefined)+ ?.fromSequenceExclusive ?? 0,+ ),),),),- ),+ ).pipe(Effect.map((events) => Array.from(events))),);default:@@ -952,7 +957,7 @@ export function createServer(options: ServerOptions) {const persistenceLayer = customPersistenceLayer ?? makeSqlitePersistenceLive(dbPath);const orchestrationLayer = Layer.provide(OrchestrationEngineLive,- OrchestrationEventRepositoryLive,+ OrchestrationEventStoreLive,);const codexAdapterLayer = makeCodexAdapterLive({nativeEventLogPath: path.join(providerLogsDir, "provider-native.ndjson"),