Skip to content

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
similarity index 79%
rename from apps/server/src/orchestration/Service.ts
rename to apps/server/src/orchestration/Services/OrchestrationEngine.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
similarity index 55%
rename from apps/server/src/orchestration/Layer.ts
rename to apps/server/src/orchestration/decider.ts
index 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<OrchestrationEve
messageCount: 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.ts
similarity index 87%
rename from apps/server/src/orchestration/reducer.test.ts
rename to apps/server/src/orchestration/projector.test.ts
index 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.ts
similarity index 97%
rename from apps/server/src/orchestration/reducer.ts
rename to apps/server/src/orchestration/projector.ts
index 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.ts
index 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.ts
similarity index 56%
rename from apps/server/src/persistence/Layers/OrchestrationEvents.test.ts
rename to apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
index 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.ts
similarity index 66%
rename from apps/server/src/persistence/Layers/OrchestrationEvents.ts
rename to apps/server/src/persistence/Layers/OrchestrationEventStore.ts
index 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.ts
similarity index 50%
rename from apps/server/src/persistence/Services/OrchestrationEvents.ts
rename to apps/server/src/persistence/Services/OrchestrationEventStore.ts
index 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.ts
index 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"),