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.
more effect: error handling
Julius Marmingeb152462b2cd5
diff --git a/apps/server/src/orchestration/Errors.ts b/apps/server/src/orchestration/Errors.tsnew file mode 100644index 000000000..0f199e2ba--- /dev/null+++ b/apps/server/src/orchestration/Errors.ts@@ -0,0 +1,95 @@+import { ParseResult, Schema } from "effect";++import type { OrchestrationEventRepositoryError } from "../persistence/Errors";++export class OrchestrationCommandJsonParseError extends Schema.TaggedError<OrchestrationCommandJsonParseError>()(+ "OrchestrationCommandJsonParseError",+ {+ detail: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Invalid orchestration command JSON: ${this.detail}`;+ }+}++export class OrchestrationCommandDecodeError extends Schema.TaggedError<OrchestrationCommandDecodeError>()(+ "OrchestrationCommandDecodeError",+ {+ issue: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Invalid orchestration command payload: ${this.issue}`;+ }+}++export class OrchestrationReducerDecodeError extends Schema.TaggedError<OrchestrationReducerDecodeError>()(+ "OrchestrationReducerDecodeError",+ {+ eventType: Schema.String,+ issue: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Reducer decode failed for ${this.eventType}: ${this.issue}`;+ }+}++export class OrchestrationListenerCallbackError extends Schema.TaggedError<OrchestrationListenerCallbackError>()(+ "OrchestrationListenerCallbackError",+ {+ listener: Schema.Literal("read-model", "domain-event"),+ detail: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Orchestration ${this.listener} listener failed: ${this.detail}`;+ }+}++export type OrchestrationDispatchError =+ | OrchestrationEventRepositoryError+ | OrchestrationReducerDecodeError+ | OrchestrationListenerCallbackError;++export type OrchestrationEngineError =+ | OrchestrationDispatchError+ | OrchestrationCommandJsonParseError+ | OrchestrationCommandDecodeError;++export function toOrchestrationCommandDecodeError(error: ParseResult.ParseError) {+ return new OrchestrationCommandDecodeError({+ issue: ParseResult.TreeFormatter.formatErrorSync(error),+ cause: error,+ });+}++export function toReducerDecodeError(eventType: string) {+ return (error: ParseResult.ParseError): OrchestrationReducerDecodeError =>+ new OrchestrationReducerDecodeError({+ eventType,+ issue: ParseResult.TreeFormatter.formatErrorSync(error),+ cause: error,+ });+}++export function toOrchestrationJsonParseError(cause: unknown) {+ return new OrchestrationCommandJsonParseError({+ detail: `Failed to parse orchestration command JSON: ${cause}`,+ cause,+ });+}++export function toListenerCallbackError(listener: "read-model" | "domain-event") {+ return (cause: unknown): OrchestrationListenerCallbackError =>+ new OrchestrationListenerCallbackError({+ listener,+ detail: `Failed to invoke orchestration ${listener} listener: ${cause}`,+ cause,+ });+}diff --git a/apps/server/src/orchestration/Layer.test.ts b/apps/server/src/orchestration/Layer.test.tsindex 87afdcea4..76a028567 100644--- a/apps/server/src/orchestration/Layer.test.ts+++ b/apps/server/src/orchestration/Layer.test.ts@@ -10,6 +10,7 @@ import {OrchestrationEventRepository,type OrchestrationEventRepositoryShape,} from "../persistence/Services/OrchestrationEvents";+import { PersistenceSqlError } from "../persistence/Errors";import { Layer, ManagedRuntime } from "effect";@@ -375,7 +376,12 @@ describe("OrchestrationEngine", () => {append(event) {if (shouldFailFirstAppend) {shouldFailFirstAppend = false;- return Effect.die(new Error("append failed"));+ return Effect.fail(+ new PersistenceSqlError({+ operation: "test.append",+ detail: "append failed",+ }),+ );}const savedEvent = {...event,diff --git a/apps/server/src/orchestration/Layer.ts b/apps/server/src/orchestration/Layer.tsindex 9974132fe..3c9590501 100644--- a/apps/server/src/orchestration/Layer.ts+++ b/apps/server/src/orchestration/Layer.ts@@ -4,33 +4,24 @@ import type {OrchestrationReadModel,} from "@t3tools/contracts";import { OrchestrationCommandSchema } from "@t3tools/contracts";-import {- Cause,- Deferred,- Effect,- Either,- Fiber,- Layer,- PubSub,- Queue,- Runtime,- Schema,-} from "effect";+import { Deferred, Effect, Layer, PubSub, Queue, Schema } from "effect";import { createLogger } from "../logger";import { OrchestrationEventRepository } from "../persistence/Services/OrchestrationEvents";+import {+ toListenerCallbackError,+ toOrchestrationCommandDecodeError,+ toOrchestrationJsonParseError,+ type OrchestrationDispatchError,+} from "./Errors";import { createEmptyReadModel, reduceEvent } from "./reducer";import { OrchestrationEngineService, type OrchestrationEngineShape } from "./Service";type CommandEnvelope = {command: OrchestrationCommand;- result: Deferred.Deferred<{ sequence: number }, Error>;+ result: Deferred.Deferred<{ sequence: number }, OrchestrationDispatchError>;};-function asError(error: unknown, fallbackMessage: string): Error {- return error instanceof Error ? error : new Error(fallbackMessage);-}-function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEvent, "sequence"> {const eventId = crypto.randomUUID();switch (command.type) {@@ -169,129 +160,134 @@ function mapCommandToEvent(command: OrchestrationCommand): Omit<OrchestrationEve}}-const decodeUnknownCommand = Schema.decodeUnknownEither(OrchestrationCommandSchema);+const decodeUnknownCommand = Schema.decodeUnknown(OrchestrationCommandSchema);-export const makeOrchestrationEngine = Effect.gen(function* () {- const logger = createLogger("orchestration");- const eventStore = yield* OrchestrationEventRepository;- const runtime = Runtime.defaultRuntime;+const makeOrchestrationEngine = () =>+ Effect.gen(function* () {+ const logger = createLogger("orchestration");+ const eventStore = yield* OrchestrationEventRepository;- let readModel = createEmptyReadModel(new Date().toISOString());+ let readModel = createEmptyReadModel(new Date().toISOString());- const commandQueue = yield* Queue.unbounded<CommandEnvelope>();- const readModelPubSub = yield* PubSub.unbounded<OrchestrationReadModel>();- const eventPubSub = yield* PubSub.unbounded<OrchestrationEvent>();+ const commandQueue = yield* Queue.unbounded<CommandEnvelope>();+ const readModelPubSub = yield* PubSub.unbounded<OrchestrationReadModel>();+ const eventPubSub = yield* PubSub.unbounded<OrchestrationEvent>();- const readModelListeners = new Set<(snapshot: OrchestrationReadModel) => void>();- const domainEventListeners = new Set<(event: OrchestrationEvent) => void>();+ const readModelListeners = new Set<(snapshot: OrchestrationReadModel) => void>();+ const domainEventListeners = new Set<(event: OrchestrationEvent) => void>();- 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);+ const notifyReadModelListeners = (snapshot: OrchestrationReadModel) =>+ Effect.forEach(readModelListeners, (listener) =>+ Effect.try({+ try: () => listener(snapshot),+ catch: toListenerCallbackError("read-model"),+ }),+ ).pipe(Effect.asVoid);- const snapshot = readModel;- yield* Effect.all([- PubSub.publish(eventPubSub, savedEvent),- PubSub.publish(readModelPubSub, snapshot),- ]);+ const notifyDomainEventListeners = (event: OrchestrationEvent) =>+ Effect.forEach(domainEventListeners, (listener) =>+ Effect.try({+ try: () => listener(event),+ catch: toListenerCallbackError("domain-event"),+ }),+ ).pipe(Effect.asVoid);- for (const listener of domainEventListeners) {- listener(savedEvent);- }- for (const listener of readModelListeners) {- listener(snapshot);- }+ 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* Deferred.succeed(envelope.result, { sequence: savedEvent.sequence });- }).pipe(- Effect.catchAllCause((cause) =>- Deferred.fail(- envelope.result,- asError(Cause.squash(cause), "Unknown command processing error"),- ).pipe(Effect.asVoid),- ),- );+ const snapshot = readModel;+ yield* Effect.all([+ PubSub.publish(eventPubSub, savedEvent),+ PubSub.publish(readModelPubSub, snapshot),+ ]);- const bootstrapReadModel: Effect.Effect<void, unknown> = Effect.gen(function* () {- const existingEvents = yield* eventStore.readAll();- for (const event of existingEvents) {- readModel = yield* reduceEvent(readModel, event);- }- });+ yield* notifyDomainEventListeners(savedEvent);+ yield* notifyReadModelListeners(snapshot);- yield* bootstrapReadModel;+ yield* Deferred.succeed(envelope.result, { sequence: savedEvent.sequence });+ }).pipe(+ Effect.catchAll((error) => Deferred.fail(envelope.result, error).pipe(Effect.asVoid)),+ );- const worker = Effect.forever(Queue.take(commandQueue).pipe(Effect.flatMap(processEnvelope)));- const workerFiber: Fiber.RuntimeFiber<void, unknown> = Runtime.runFork(runtime)(worker);- logger.info("orchestration engine started", {- sequence: readModel.sequence,- });+ 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;- yield* Effect.addFinalizer(() => Fiber.interrupt(workerFiber).pipe(Effect.orDie));+ 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 getSnapshot: OrchestrationEngineShape["getSnapshot"] = () =>+ Effect.sync((): OrchestrationReadModel => readModel);- const replayEvents: OrchestrationEngineShape["replayEvents"] = (fromSequenceExclusive) =>- eventStore.readFromSequence(fromSequenceExclusive);+ const replayEvents: OrchestrationEngineShape["replayEvents"] = (fromSequenceExclusive) =>+ eventStore.readFromSequence(fromSequenceExclusive);- const dispatch: OrchestrationEngineShape["dispatch"] = (command) =>- Effect.gen(function* () {- const result = yield* Deferred.make<{ sequence: number }, Error>();- yield* Queue.offer(commandQueue, { command, result });- return yield* Deferred.await(result);- }).pipe(Effect.mapError((error) => asError(error, "Queue offer failed")));+ 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* () {- let payload: unknown = command;- if (typeof command === "string") {- try {- payload = JSON.parse(command) as unknown;- } catch {- return yield* Effect.fail(- new Error("Invalid orchestration command: payload is not valid JSON"),- );- }- }- const decoded = decodeUnknownCommand(payload);- if (Either.isLeft(decoded)) {- return yield* Effect.fail(- new Error(`Invalid orchestration command: ${decoded.left.toString()}`),+ 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.right);- });- const subscribeToReadModel: OrchestrationEngineShape["subscribeToReadModel"] = (callback) =>- Effect.sync(() => {- readModelListeners.add(callback);- return () => {- readModelListeners.delete(callback);- };- });+ return yield* dispatch(decoded);+ });- const subscribeToDomainEvents: OrchestrationEngineShape["subscribeToDomainEvents"] = (callback) =>- Effect.sync(() => {- domainEventListeners.add(callback);- return () => {- domainEventListeners.delete(callback);- };- });+ const subscribeToReadModel: OrchestrationEngineShape["subscribeToReadModel"] = (callback) =>+ Effect.sync(() => {+ readModelListeners.add(callback);+ return () => {+ readModelListeners.delete(callback);+ };+ });- return {- getSnapshot,- replayEvents,- dispatchUnknown,- dispatch,- subscribeToReadModel,- subscribeToDomainEvents,- } satisfies OrchestrationEngineShape;-});+ const subscribeToDomainEvents: OrchestrationEngineShape["subscribeToDomainEvents"] = (+ callback,+ ) =>+ Effect.sync(() => {+ domainEventListeners.add(callback);+ return () => {+ domainEventListeners.delete(callback);+ };+ });++ return {+ getSnapshot,+ replayEvents,+ dispatchUnknown,+ dispatch,+ subscribeToReadModel,+ subscribeToDomainEvents,+ } satisfies OrchestrationEngineShape;+ });export const OrchestrationEngineLive = Layer.scoped(OrchestrationEngineService,- makeOrchestrationEngine,+ makeOrchestrationEngine(),);diff --git a/apps/server/src/orchestration/Service.ts b/apps/server/src/orchestration/Service.tsindex 9959f897a..57eee9dab 100644--- a/apps/server/src/orchestration/Service.ts+++ b/apps/server/src/orchestration/Service.ts@@ -1,3 +1,11 @@+/**+ * OrchestrationEngineService - Service interface for orchestration command handling.+ *+ * Uses Effect `Context.Tag` for dependency injection. Command dispatch,+ * replay, and unknown-input decoding all return typed domain errors.+ *+ * @module OrchestrationEngineService+ */import type {OrchestrationCommand,OrchestrationEvent,@@ -6,19 +14,81 @@ import type {import { Context } from "effect";import type { Effect } from "effect";+import type { OrchestrationDispatchError, OrchestrationEngineError } from "./Errors";+import type { OrchestrationEventRepositoryError } from "../persistence/Errors";+export interface OrchestrationEngineShape {+ /**+ * Read the current in-memory orchestration snapshot.+ *+ * @returns Effect containing the latest read model.+ */readonly getSnapshot: () => Effect.Effect<OrchestrationReadModel>;- readonly replayEvents: (fromSequenceExclusive: number) => Effect.Effect<OrchestrationEvent[]>;- readonly dispatchUnknown: (command: unknown) => Effect.Effect<{ sequence: number }, Error>;- readonly dispatch: (command: OrchestrationCommand) => Effect.Effect<{ sequence: number }, Error>;++ /**+ * Replay persisted orchestration events from an exclusive sequence cursor.+ *+ * @param fromSequenceExclusive - Sequence cursor (exclusive).+ * @returns Effect containing ordered events.+ */+ readonly replayEvents: (+ fromSequenceExclusive: number,+ ) => Effect.Effect<OrchestrationEvent[], OrchestrationEventRepositoryError>;++ /**+ * Validate and dispatch an unknown command payload.+ *+ * Accepts either parsed values or raw JSON strings.+ *+ * @param command - Unknown command payload.+ * @returns Effect containing the sequence of the persisted event.+ */+ readonly dispatchUnknown: (+ command: unknown,+ ) => Effect.Effect<{ sequence: number }, OrchestrationEngineError>;++ /**+ * Dispatch a validated orchestration command.+ *+ * @param command - Valid orchestration command.+ * @returns Effect containing the sequence of the persisted event.+ */+ readonly dispatch: (+ command: OrchestrationCommand,+ ) => Effect.Effect<{ sequence: number }, OrchestrationDispatchError>;++ /**+ * Subscribe to read model updates.+ *+ * @param callback - Handler invoked on every read model update.+ * @returns Effect containing an unsubscribe function.+ */readonly subscribeToReadModel: (callback: (snapshot: OrchestrationReadModel) => void,) => Effect.Effect<() => void>;++ /**+ * Subscribe to domain event fan-out.+ *+ * @param callback - Handler invoked for every persisted domain event.+ * @returns Effect containing an unsubscribe function.+ */readonly subscribeToDomainEvents: (callback: (event: OrchestrationEvent) => void,) => Effect.Effect<() => void>;}+/**+ * OrchestrationEngineService - Context tag for orchestration engine access.+ *+ * @example+ * ```ts+ * const program = Effect.gen(function* () {+ * const engine = yield* OrchestrationEngineService+ * return yield* engine.getSnapshot()+ * })+ * ```+ */export class OrchestrationEngineService extends Context.Tag("orchestration/Engine")<OrchestrationEngineService,OrchestrationEngineShapediff --git a/apps/server/src/orchestration/reducer.ts b/apps/server/src/orchestration/reducer.tsindex 1b05441b1..01f9e8c09 100644--- a/apps/server/src/orchestration/reducer.ts+++ b/apps/server/src/orchestration/reducer.ts@@ -9,7 +9,6 @@ import type {import {OrchestrationGitReadModelSchema,OrchestrationMessageSchema,- OrchestrationReadModelSchema,OrchestrationSessionSchema,OrchestrationThreadSchema,OrchestrationTurnDiffFileSchema,@@ -17,6 +16,8 @@ import {} from "@t3tools/contracts";import { Effect, Schema } from "effect";+import { toReducerDecodeError, type OrchestrationReducerDecodeError } from "./Errors";+type ThreadPatch = Partial<Omit<OrchestrationThread, "id" | "projectId">>;function updateThread(@@ -27,12 +28,16 @@ function updateThread(return threads.map((thread) => (thread.id === threadId ? { ...thread, ...patch } : thread));}-const decodeReadModelSync = Schema.decodeUnknownSync(OrchestrationReadModelSchema);-const decodeMessage = Schema.decodeUnknown(OrchestrationMessageSchema);-const decodeSession = Schema.decodeUnknown(OrchestrationSessionSchema);-const decodeThread = Schema.decodeUnknown(OrchestrationThreadSchema);-const decodeGitReadModel = Schema.decodeUnknown(OrchestrationGitReadModelSchema);-const decodeTurnDiffSummary = Schema.decodeUnknown(OrchestrationTurnDiffSummarySchema);+function decodeForEvent<A>(+ schema: Schema.Schema<A>,+ value: unknown,+ eventType: string,+ field: string,+): Effect.Effect<A, OrchestrationReducerDecodeError> {+ return Schema.decodeUnknown(schema)(value).pipe(+ Effect.mapError(toReducerDecodeError(`${eventType}:${field}`)),+ );+}const ThreadCreatedPayloadSchema = Schema.Struct({id: Schema.String,@@ -44,7 +49,6 @@ const ThreadCreatedPayloadSchema = Schema.Struct({createdAt: Schema.String,updatedAt: Schema.String,});-const decodeThreadCreatedPayload = Schema.decodeUnknown(ThreadCreatedPayloadSchema);const ThreadMetaUpdatedPayloadSchema = Schema.Struct({threadId: Schema.String,@@ -54,7 +58,6 @@ const ThreadMetaUpdatedPayloadSchema = Schema.Struct({worktreePath: Schema.optional(Schema.NullOr(Schema.String)),updatedAt: Schema.String,});-const decodeThreadMetaUpdatedPayload = Schema.decodeUnknown(ThreadMetaUpdatedPayloadSchema);const MessageSentPayloadSchema = Schema.Struct({id: Schema.String,@@ -64,13 +67,11 @@ const MessageSentPayloadSchema = Schema.Struct({createdAt: Schema.String,streaming: Schema.Boolean,});-const decodeMessageSentPayload = Schema.decodeUnknown(MessageSentPayloadSchema);const ThreadSessionSetPayloadSchema = Schema.Struct({threadId: Schema.String,session: OrchestrationSessionSchema,});-const decodeThreadSessionSetPayload = Schema.decodeUnknown(ThreadSessionSetPayloadSchema);const ThreadTurnDiffCompletedPayloadSchema = Schema.Struct({threadId: Schema.String,@@ -81,30 +82,26 @@ const ThreadTurnDiffCompletedPayloadSchema = Schema.Struct({assistantMessageId: Schema.optional(Schema.String),checkpointTurnCount: Schema.optional(Schema.Number),});-const decodeThreadTurnDiffCompletedPayload = Schema.decodeUnknown(- ThreadTurnDiffCompletedPayloadSchema,-);const ThreadRevertedPayloadSchema = Schema.Struct({threadId: Schema.String,turnCount: Schema.Number,messageCount: Schema.Number,});-const decodeThreadRevertedPayload = Schema.decodeUnknown(ThreadRevertedPayloadSchema);export function createEmptyReadModel(nowIso: string): OrchestrationReadModel {- return decodeReadModelSync({+ return {sequence: 0,threads: [],gitByProjectId: {},updatedAt: nowIso,- });+ };}export function reduceEvent(model: OrchestrationReadModel,event: OrchestrationEvent,-): Effect.Effect<OrchestrationReadModel, unknown> {+): Effect.Effect<OrchestrationReadModel, OrchestrationReducerDecodeError> {const nextBase: OrchestrationReadModel = {...model,sequence: event.sequence,@@ -114,25 +111,35 @@ export function reduceEvent(switch (event.type) {case "thread.created":return Effect.gen(function* () {- const payload = yield* decodeThreadCreatedPayload(event.payload);- const thread: OrchestrationThread = yield* decodeThread({- id: payload.id,- projectId: payload.projectId,- title: payload.title,- model: payload.model,- branch: payload.branch,- worktreePath: payload.worktreePath,- createdAt: payload.createdAt,- updatedAt: payload.updatedAt,- latestTurnId: null,- latestTurnStartedAt: null,- latestTurnCompletedAt: null,- latestTurnDurationMs: null,- messages: [],- session: null,- turnDiffSummaries: [],- error: null,- });+ const payload = yield* decodeForEvent(+ ThreadCreatedPayloadSchema,+ event.payload,+ event.type,+ "payload",+ );+ const thread: OrchestrationThread = yield* decodeForEvent(+ OrchestrationThreadSchema,+ {+ id: payload.id,+ projectId: payload.projectId,+ title: payload.title,+ model: payload.model,+ branch: payload.branch,+ worktreePath: payload.worktreePath,+ createdAt: payload.createdAt,+ updatedAt: payload.updatedAt,+ latestTurnId: null,+ latestTurnStartedAt: null,+ latestTurnCompletedAt: null,+ latestTurnDurationMs: null,+ messages: [],+ session: null,+ turnDiffSummaries: [],+ error: null,+ },+ event.type,+ "thread",+ );const existing = nextBase.threads.find((entry) => entry.id === thread.id);return {...nextBase,@@ -147,7 +154,12 @@ export function reduceEvent(threads: nextBase.threads.filter((thread) => thread.id !== event.aggregateId),});case "thread.meta-updated":- return decodeThreadMetaUpdatedPayload(event.payload).pipe(+ return decodeForEvent(+ ThreadMetaUpdatedPayloadSchema,+ event.payload,+ event.type,+ "payload",+ ).pipe(Effect.map((payload) => {const thread = nextBase.threads.find((entry) => entry.id === payload.threadId);if (!thread) {@@ -167,19 +179,29 @@ export function reduceEvent();case "message.sent":return Effect.gen(function* () {- const payload = yield* decodeMessageSentPayload(event.payload);+ const payload = yield* decodeForEvent(+ MessageSentPayloadSchema,+ event.payload,+ event.type,+ "payload",+ );const targetThread = nextBase.threads.find((thread) => thread.id === payload.threadId);if (!targetThread) {return nextBase;}- const message: OrchestrationMessage = yield* decodeMessage({- id: payload.id,- role: payload.role,- text: payload.text,- createdAt: payload.createdAt,- streaming: payload.streaming,- });+ const message: OrchestrationMessage = yield* decodeForEvent(+ OrchestrationMessageSchema,+ {+ id: payload.id,+ role: payload.role,+ text: payload.text,+ createdAt: payload.createdAt,+ streaming: payload.streaming,+ },+ event.type,+ "message",+ );const existingMessage = targetThread.messages.find((entry) => entry.id === message.id);const nextMessages = existingMessage? targetThread.messages.map((entry) =>@@ -208,16 +230,26 @@ export function reduceEvent(});case "thread.session-set":return Effect.gen(function* () {- const payload = yield* decodeThreadSessionSetPayload(event.payload);+ const payload = yield* decodeForEvent(+ ThreadSessionSetPayloadSchema,+ event.payload,+ event.type,+ "payload",+ );const thread = nextBase.threads.find((entry) => entry.id === payload.threadId);if (!thread) {return nextBase;}- const session: OrchestrationSession = yield* decodeSession({- ...payload.session,- threadId: payload.threadId,- });+ const session: OrchestrationSession = yield* decodeForEvent(+ OrchestrationSessionSchema,+ {+ ...payload.session,+ threadId: payload.threadId,+ },+ event.type,+ "session",+ );return {...nextBase,@@ -230,24 +262,34 @@ export function reduceEvent(});case "thread.turn-diff-completed":return Effect.gen(function* () {- const payload = yield* decodeThreadTurnDiffCompletedPayload(event.payload);+ const payload = yield* decodeForEvent(+ ThreadTurnDiffCompletedPayloadSchema,+ event.payload,+ event.type,+ "payload",+ );const thread = nextBase.threads.find((entry) => entry.id === payload.threadId);if (!thread) {return nextBase;}- const nextSummary = yield* decodeTurnDiffSummary({- turnId: payload.turnId,- completedAt: payload.completedAt,- ...(payload.status !== undefined ? { status: payload.status } : {}),- files: payload.files,- ...(payload.assistantMessageId !== undefined- ? { assistantMessageId: payload.assistantMessageId }- : {}),- ...(payload.checkpointTurnCount !== undefined- ? { checkpointTurnCount: payload.checkpointTurnCount }- : {}),- });+ const nextSummary = yield* decodeForEvent(+ OrchestrationTurnDiffSummarySchema,+ {+ turnId: payload.turnId,+ completedAt: payload.completedAt,+ ...(payload.status !== undefined ? { status: payload.status } : {}),+ files: payload.files,+ ...(payload.assistantMessageId !== undefined+ ? { assistantMessageId: payload.assistantMessageId }+ : {}),+ ...(payload.checkpointTurnCount !== undefined+ ? { checkpointTurnCount: payload.checkpointTurnCount }+ : {}),+ },+ event.type,+ "turnDiffSummary",+ );const turnDiffSummaries = [...thread.turnDiffSummaries.filter((summary) => summary.turnId !== payload.turnId),nextSummary,@@ -264,7 +306,7 @@ export function reduceEvent(};});case "thread.reverted":- return decodeThreadRevertedPayload(event.payload).pipe(+ return decodeForEvent(ThreadRevertedPayloadSchema, event.payload, event.type, "payload").pipe(Effect.map((payload) => {const thread = nextBase.threads.find((entry) => entry.id === payload.threadId);if (!thread) {@@ -311,7 +353,12 @@ export function reduceEvent(}),);case "git.read-model-upsert":- return decodeGitReadModel(event.payload).pipe(+ return decodeForEvent(+ OrchestrationGitReadModelSchema,+ event.payload,+ event.type,+ "payload",+ ).pipe(Effect.map((gitReadModel: OrchestrationGitReadModel) => ({...nextBase,gitByProjectId: {diff --git a/apps/server/src/persistence/Errors.ts b/apps/server/src/persistence/Errors.tsnew file mode 100644index 000000000..940357abe--- /dev/null+++ b/apps/server/src/persistence/Errors.ts@@ -0,0 +1,126 @@+import { ParseResult, Schema } from "effect";++export class PersistenceSqlError extends Schema.TaggedError<PersistenceSqlError>()(+ "PersistenceSqlError",+ {+ operation: Schema.String,+ detail: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `SQL error in ${this.operation}: ${this.detail}`;+ }+}++export class PersistenceDecodeError extends Schema.TaggedError<PersistenceDecodeError>()(+ "PersistenceDecodeError",+ {+ operation: Schema.String,+ issue: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Decode error in ${this.operation}: ${this.issue}`;+ }+}++export class PersistenceSerializationError extends Schema.TaggedError<PersistenceSerializationError>()(+ "PersistenceSerializationError",+ {+ operation: Schema.String,+ detail: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Serialization error in ${this.operation}: ${this.detail}`;+ }+}++export class ProjectValidationError extends Schema.TaggedError<ProjectValidationError>()(+ "ProjectValidationError",+ {+ operation: Schema.String,+ issue: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Project validation failed in ${this.operation}: ${this.issue}`;+ }+}++export class ProjectPathMissingError extends Schema.TaggedError<ProjectPathMissingError>()(+ "ProjectPathMissingError",+ {+ cwd: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Project path does not exist: ${this.cwd}`;+ }+}++export class ProjectNotFoundError extends Schema.TaggedError<ProjectNotFoundError>()(+ "ProjectNotFoundError",+ {+ projectId: Schema.String,+ cause: Schema.optional(Schema.Defect),+ },+) {+ override get message(): string {+ return `Project not found: ${this.projectId}`;+ }+}++export type ProjectRepositoryError =+ | PersistenceSqlError+ | PersistenceDecodeError+ | PersistenceSerializationError+ | ProjectValidationError+ | ProjectPathMissingError+ | ProjectNotFoundError;++export type OrchestrationEventRepositoryError =+ | PersistenceSqlError+ | PersistenceDecodeError+ | PersistenceSerializationError;++export function toPersistenceSqlError(operation: string) {+ return (cause: unknown): PersistenceSqlError =>+ new PersistenceSqlError({+ operation,+ detail: `Failed to execute ${operation}`,+ cause,+ });+}++export function toPersistenceDecodeError(operation: string) {+ return (error: ParseResult.ParseError): PersistenceDecodeError =>+ new PersistenceDecodeError({+ operation,+ issue: ParseResult.TreeFormatter.formatErrorSync(error),+ cause: error,+ });+}++export function toPersistenceDecodeCauseError(operation: string) {+ return (cause: unknown): PersistenceDecodeError =>+ new PersistenceDecodeError({+ operation,+ issue: `Failed to execute ${operation}`,+ cause,+ });+}++export function toPersistenceSerializationError(operation: string) {+ return (cause: unknown): PersistenceSerializationError =>+ new PersistenceSerializationError({+ operation,+ detail: `Failed to execute ${operation}`,+ cause,+ });+}diff --git a/apps/server/src/persistence/Layers/OrchestrationEvents.test.ts b/apps/server/src/persistence/Layers/OrchestrationEvents.test.tsindex b9768172b..e9ca28dff 100644--- a/apps/server/src/persistence/Layers/OrchestrationEvents.test.ts+++ b/apps/server/src/persistence/Layers/OrchestrationEvents.test.ts@@ -80,9 +80,8 @@ describe("OrchestrationEventRepository", () => {).get() as { name: string } | undefined;expect(tableRow?.name).toBeDefined();- if (!tableRow) {- throw new Error("Expected migrations table to exist");- }+ expect(tableRow).toBeDefined();+ if (!tableRow) return;const migrationRows = db.prepare(diff --git a/apps/server/src/persistence/Layers/OrchestrationEvents.ts b/apps/server/src/persistence/Layers/OrchestrationEvents.tsindex 29f256582..d3a684110 100644--- a/apps/server/src/persistence/Layers/OrchestrationEvents.ts+++ b/apps/server/src/persistence/Layers/OrchestrationEvents.ts@@ -4,13 +4,20 @@ import * as SqlClient from "@effect/sql/SqlClient";import * as SqlSchema from "@effect/sql/SqlSchema";import { Effect, Layer, Schema } from "effect";+import {+ toPersistenceDecodeCauseError,+ toPersistenceDecodeError,+ toPersistenceSerializationError,+ toPersistenceSqlError,+ type OrchestrationEventRepositoryError,+} from "../Errors";import { makeSqlitePersistenceLive } from "./Sqlite";import {OrchestrationEventRepository,type OrchestrationEventRepositoryShape,} from "../Services/OrchestrationEvents";-const decodeEvent = Schema.decodeUnknownSync(OrchestrationEventSchema);+const decodeEvent = Schema.decodeUnknown(OrchestrationEventSchema);const EventRowSchema = Schema.Struct({sequence: Schema.Number,@@ -40,17 +47,27 @@ const ReadFromSequenceRequestSchema = Schema.Struct({limit: Schema.Number,});-function eventRowToOrchestrationEvent(row: EventRow): OrchestrationEvent {- return decodeEvent({- sequence: row.sequence,- eventId: row.eventId,- type: row.type,- aggregateType: row.aggregateType,- aggregateId: row.aggregateId,- occurredAt: row.occurredAt,- commandId: row.commandId,- payload: JSON.parse(row.payloadJson) as unknown,- });+function eventRowToOrchestrationEvent(+ row: EventRow,+ operation: string,+): Effect.Effect<OrchestrationEvent, OrchestrationEventRepositoryError> {+ return Effect.try({+ try: () => JSON.parse(row.payloadJson) as unknown,+ catch: toPersistenceDecodeCauseError(`${operation}:parsePayloadJson`),+ }).pipe(+ Effect.flatMap((payload) =>+ decodeEvent({+ sequence: row.sequence,+ eventId: row.eventId,+ type: row.type,+ aggregateType: row.aggregateType,+ aggregateId: row.aggregateId,+ occurredAt: row.occurredAt,+ commandId: row.commandId,+ payload,+ }).pipe(Effect.mapError(toPersistenceDecodeError(`${operation}:decodeEvent`))),+ ),+ );}const makeRepository = Effect.gen(function* () {@@ -113,23 +130,42 @@ const makeRepository = Effect.gen(function* () {});const append: OrchestrationEventRepositoryShape["append"] = (event) =>- appendEventRow({- eventId: event.eventId,- type: event.type,- aggregateType: event.aggregateType,- aggregateId: event.aggregateId,- occurredAt: event.occurredAt,- commandId: event.commandId,- payloadJson: JSON.stringify(event.payload),- }).pipe(Effect.map(eventRowToOrchestrationEvent), Effect.orDie);+ Effect.try({+ try: () => JSON.stringify(event.payload),+ catch: toPersistenceSerializationError("OrchestrationEventRepository.append:encodePayload"),+ }).pipe(+ Effect.flatMap((payloadJson) =>+ appendEventRow({+ eventId: event.eventId,+ type: event.type,+ aggregateType: event.aggregateType,+ aggregateId: event.aggregateId,+ occurredAt: event.occurredAt,+ commandId: event.commandId,+ payloadJson,+ }).pipe(+ Effect.mapError(toPersistenceSqlError("OrchestrationEventRepository.append:insert")),+ Effect.flatMap((row) =>+ eventRowToOrchestrationEvent(row, "OrchestrationEventRepository.append:rowToEvent"),+ ),+ ),+ ),+ );const readFromSequence: OrchestrationEventRepositoryShape["readFromSequence"] = (sequenceExclusive,limit = 1_000,) =>readEventRowsFromSequence({ sequenceExclusive, limit }).pipe(- Effect.map((rows) => rows.map(eventRowToOrchestrationEvent)),- Effect.orDie,+ Effect.mapError(toPersistenceSqlError("OrchestrationEventRepository.readFromSequence:query")),+ Effect.flatMap((rows) =>+ Effect.forEach(rows, (row) =>+ eventRowToOrchestrationEvent(+ row,+ "OrchestrationEventRepository.readFromSequence:rowToEvent",+ ),+ ),+ ),);return {diff --git a/apps/server/src/persistence/Layers/Projects.ts b/apps/server/src/persistence/Layers/Projects.tsindex dc50541bc..1504545de 100644--- a/apps/server/src/persistence/Layers/Projects.ts+++ b/apps/server/src/persistence/Layers/Projects.ts@@ -8,6 +8,7 @@ import type {ProjectListResult,ProjectRecord,ProjectScript,+ ProjectUpdateScriptsInput,ProjectUpdateScriptsResult,} from "@t3tools/contracts";import {@@ -22,6 +23,16 @@ import * as SqlClient from "@effect/sql/SqlClient";import * as SqlSchema from "@effect/sql/SqlSchema";import { Effect, Layer, Option, Schema } from "effect";+import {+ PersistenceDecodeError,+ ProjectNotFoundError,+ ProjectPathMissingError,+ ProjectValidationError,+ toPersistenceDecodeCauseError,+ toPersistenceSerializationError,+ toPersistenceSqlError,+ type ProjectRepositoryError,+} from "../Errors";import { ProjectRepository, type ProjectRepositoryShape } from "../Services/Projects";const ProjectRowSchema = Schema.Struct({@@ -98,25 +109,101 @@ function inferProjectName(cwd: string): string {return name.length > 0 ? name : "project";}-function parseScriptsJson(raw: string): ProjectScript[] {- try {- const parsed = JSON.parse(raw) as unknown;- const scripts = projectScriptsSchema.parse(parsed);- return normalizeProjectScripts(scripts);- } catch {- return [];+function parseProjectScripts(+ value: unknown,+ operation: string,+): Effect.Effect<ProjectScript[], PersistenceDecodeError> {+ const parsed = projectScriptsSchema.safeParse(value);+ if (!parsed.success) {+ return Effect.fail(+ new PersistenceDecodeError({+ operation,+ issue: parsed.error.message,+ cause: (parsed.error as { cause?: unknown }).cause,+ }),+ );}+ return Effect.succeed(normalizeProjectScripts(parsed.data));}-function rowToProjectRecord(row: ProjectRow): ProjectRecord {- return projectRecordSchema.parse({- id: row.id,- cwd: row.cwd,- name: row.name,- scripts: parseScriptsJson(row.scriptsJson),- createdAt: row.createdAt,- updatedAt: row.updatedAt,- });+function decodeScriptsJson(+ raw: string,+ operation: string,+): Effect.Effect<ProjectScript[], ProjectRepositoryError> {+ return Effect.try({+ try: () => JSON.parse(raw) as unknown,+ catch: toPersistenceDecodeCauseError(`${operation}:parseScriptsJson`),+ }).pipe(Effect.flatMap((value) => parseProjectScripts(value, `${operation}:decodeScripts`)));+}++function rowToProjectRecord(+ row: ProjectRow,+ operation: string,+): Effect.Effect<ProjectRecord, ProjectRepositoryError> {+ return decodeScriptsJson(row.scriptsJson, `${operation}:scripts`).pipe(+ Effect.flatMap((scripts) => {+ const parsed = projectRecordSchema.safeParse({+ id: row.id,+ cwd: row.cwd,+ name: row.name,+ scripts,+ createdAt: row.createdAt,+ updatedAt: row.updatedAt,+ });+ if (!parsed.success) {+ return Effect.fail(+ new PersistenceDecodeError({+ operation: `${operation}:projectRecord`,+ issue: parsed.error.message,+ cause: (parsed.error as { cause?: unknown }).cause,+ }),+ );+ }+ return Effect.succeed(parsed.data);+ }),+ );+}++function decodeAddInput(rawInput: ProjectAddInput) {+ const parsed = projectAddInputSchema.safeParse(rawInput);+ if (!parsed.success) {+ return Effect.fail(+ new ProjectValidationError({+ operation: "ProjectRepository.add",+ issue: parsed.error.message,+ cause: (parsed.error as { cause?: unknown }).cause,+ }),+ );+ }+ return Effect.succeed(parsed.data);+}++function decodeUpdateScriptsInput(rawInput: ProjectUpdateScriptsInput) {+ const parsed = projectUpdateScriptsInputSchema.safeParse(rawInput);+ if (!parsed.success) {+ return Effect.fail(+ new ProjectValidationError({+ operation: "ProjectRepository.updateScripts",+ issue: parsed.error.message,+ cause: (parsed.error as { cause?: unknown }).cause,+ }),+ );+ }+ return Effect.succeed(parsed.data);+}++function decodeRemoveInput(rawInput: unknown) {+ const parsed = projectRemoveInputSchema.safeParse(rawInput);+ if (!parsed.success) {+ return Effect.fail(+ new ProjectValidationError({+ operation: "ProjectRepository.remove",+ issue: parsed.error.message,+ cause: (parsed.error as { cause?: unknown }).cause,+ }),+ );+ }+ return Effect.succeed(parsed.data);}const makeRepository = Effect.gen(function* () {@@ -231,24 +318,31 @@ const makeRepository = Effect.gen(function* () {const list: ProjectRepositoryShape["list"] = () =>listProjectRows(undefined).pipe(- Effect.map((rows): ProjectListResult => rows.map(rowToProjectRecord)),- Effect.map((projects) =>- projects.map((project) => ({ ...project, scripts: cloneScripts(project.scripts) })),+ Effect.mapError(toPersistenceSqlError("ProjectRepository.list:query")),+ Effect.flatMap((rows) =>+ Effect.forEach(rows, (row) =>+ rowToProjectRecord(row, "ProjectRepository.list:rowToProject"),+ ),+ ),+ Effect.map(+ (projects): ProjectListResult =>+ projects.map((project) => ({ ...project, scripts: cloneScripts(project.scripts) })),),- Effect.orDie,);const add: ProjectRepositoryShape["add"] = (rawInput) =>Effect.gen(function* () {- const input = projectAddInputSchema.parse(rawInput as ProjectAddInput);+ const input = yield* decodeAddInput(rawInput);const normalizedCwd = normalizeCwd(input.cwd);if (!isDirectory(normalizedCwd)) {- return yield* Effect.fail(new Error(`Project path does not exist: ${normalizedCwd}`));+ return yield* Effect.fail(new ProjectPathMissingError({ cwd: normalizedCwd }));}- const existing = yield* findProjectByCwd({ cwd: normalizedCwd }).pipe(Effect.orDie);+ const existing = yield* findProjectByCwd({ cwd: normalizedCwd }).pipe(+ Effect.mapError(toPersistenceSqlError("ProjectRepository.add:findByCwd")),+ );if (Option.isSome(existing)) {- const project = rowToProjectRecord(existing.value);+ const project = yield* rowToProjectRecord(existing.value, "ProjectRepository.add:existing");const result: ProjectAddResult = {project: {...project,@@ -267,9 +361,9 @@ const makeRepository = Effect.gen(function* () {scriptsJson: "[]",createdAt: now,updatedAt: now,- }).pipe(Effect.orDie);+ }).pipe(Effect.mapError(toPersistenceSqlError("ProjectRepository.add:insert")));- const created = rowToProjectRecord(row);+ const created = yield* rowToProjectRecord(row, "ProjectRepository.add:created");const result: ProjectAddResult = {project: {...created,@@ -282,27 +376,48 @@ const makeRepository = Effect.gen(function* () {const remove: ProjectRepositoryShape["remove"] = (rawInput) =>Effect.gen(function* () {- const input = projectRemoveInputSchema.parse(rawInput);- yield* deleteProject({ id: input.id }).pipe(Effect.orDie);+ const input = yield* decodeRemoveInput(rawInput);+ const existing = yield* findProjectById({ id: input.id }).pipe(+ Effect.mapError(toPersistenceSqlError("ProjectRepository.remove:findById")),+ );+ if (Option.isNone(existing)) {+ return yield* Effect.fail(new ProjectNotFoundError({ projectId: input.id }));+ }++ yield* deleteProject({ id: input.id }).pipe(+ Effect.mapError(toPersistenceSqlError("ProjectRepository.remove:delete")),+ );});const updateScripts: ProjectRepositoryShape["updateScripts"] = (rawInput) =>Effect.gen(function* () {- const input = projectUpdateScriptsInputSchema.parse(rawInput);- const existing = yield* findProjectById({ id: input.id }).pipe(Effect.orDie);+ const input = yield* decodeUpdateScriptsInput(rawInput);+ const existing = yield* findProjectById({ id: input.id }).pipe(+ Effect.mapError(toPersistenceSqlError("ProjectRepository.updateScripts:findById")),+ );if (Option.isNone(existing)) {- return yield* Effect.fail(new Error(`Project not found: ${input.id}`));+ return yield* Effect.fail(new ProjectNotFoundError({ projectId: input.id }));}- const nextScripts = normalizeProjectScripts(projectScriptsSchema.parse(input.scripts));+ const nextScripts = yield* parseProjectScripts(+ input.scripts,+ "ProjectRepository.updateScripts:decodeScripts",+ );+ const scriptsJson = yield* Effect.try({+ try: () => JSON.stringify(nextScripts),+ catch: toPersistenceSerializationError("ProjectRepository.updateScripts:encodeScripts"),+ });const nextUpdatedAt = new Date().toISOString();const updatedRow = yield* updateProjectScripts({id: input.id,- scriptsJson: JSON.stringify(nextScripts),+ scriptsJson,updatedAt: nextUpdatedAt,- }).pipe(Effect.orDie);+ }).pipe(Effect.mapError(toPersistenceSqlError("ProjectRepository.updateScripts:update")));- const updated = rowToProjectRecord(updatedRow);+ const updated = yield* rowToProjectRecord(+ updatedRow,+ "ProjectRepository.updateScripts:updated",+ );const result: ProjectUpdateScriptsResult = {project: {...updated,@@ -314,17 +429,19 @@ const makeRepository = Effect.gen(function* () {const pruneMissing: ProjectRepositoryShape["pruneMissing"] = () =>listProjectRows(undefined).pipe(+ Effect.mapError(toPersistenceSqlError("ProjectRepository.pruneMissing:query")),Effect.flatMap((rows) =>Effect.forEach(rows, (row) => {const normalizedCwd = normalizeCwd(row.cwd);if (isDirectory(normalizedCwd)) {return Effect.void;}- return deleteProject({ id: row.id }).pipe(Effect.orDie);+ return deleteProject({ id: row.id }).pipe(+ Effect.mapError(toPersistenceSqlError("ProjectRepository.pruneMissing:delete")),+ );}),),Effect.asVoid,- Effect.orDie,);return {diff --git a/apps/server/src/persistence/Services/OrchestrationEvents.ts b/apps/server/src/persistence/Services/OrchestrationEvents.tsindex d78573335..745b54902 100644--- a/apps/server/src/persistence/Services/OrchestrationEvents.ts+++ b/apps/server/src/persistence/Services/OrchestrationEvents.ts@@ -1,18 +1,59 @@+/**+ * OrchestrationEventRepository - Repository interface for orchestration events.+ *+ * Uses Effect `Context.Tag` for dependency injection and exposes typed+ * persistence/decode errors for event append and replay operations.+ *+ * @module OrchestrationEventRepository+ */import type { OrchestrationEvent } from "@t3tools/contracts";import { Context } from "effect";import type { Effect } from "effect";+import type { OrchestrationEventRepositoryError } from "../Errors";+export interface OrchestrationEventRepositoryShape {+ /**+ * Persist a new orchestration event.+ *+ * @param event - Event payload without sequence (assigned by storage).+ * @returns Effect containing the stored event with assigned sequence.+ */readonly append: (event: Omit<OrchestrationEvent, "sequence">,- ) => Effect.Effect<OrchestrationEvent>;+ ) => Effect.Effect<OrchestrationEvent, OrchestrationEventRepositoryError>;++ /**+ * Replay events after the provided sequence.+ *+ * @param sequenceExclusive - Sequence cursor (exclusive).+ * @param limit - Maximum number of events to return.+ * @returns Effect containing ordered events.+ */readonly readFromSequence: (sequenceExclusive: number,limit?: number,- ) => Effect.Effect<OrchestrationEvent[]>;- readonly readAll: () => Effect.Effect<OrchestrationEvent[]>;+ ) => Effect.Effect<OrchestrationEvent[], OrchestrationEventRepositoryError>;++ /**+ * Read all events from the beginning of the stream.+ *+ * @returns Effect containing all stored events.+ */+ readonly readAll: () => Effect.Effect<OrchestrationEvent[], OrchestrationEventRepositoryError>;}+/**+ * OrchestrationEventRepository - Context tag for orchestration event persistence.+ *+ * @example+ * ```ts+ * const program = Effect.gen(function* () {+ * const events = yield* OrchestrationEventRepository+ * return yield* events.readAll()+ * })+ * ```+ */export class OrchestrationEventRepository extends Context.Tag("orchestration/EventRepository")<OrchestrationEventRepository,OrchestrationEventRepositoryShapediff --git a/apps/server/src/persistence/Services/Projects.ts b/apps/server/src/persistence/Services/Projects.tsindex 24288b3a6..f16e5c49c 100644--- a/apps/server/src/persistence/Services/Projects.ts+++ b/apps/server/src/persistence/Services/Projects.ts@@ -1,3 +1,11 @@+/**+ * ProjectRepository - Repository interface for project persistence.+ *+ * Uses Effect `Context.Tag` for dependency injection and returns typed+ * domain errors for all operations.+ *+ * @module ProjectRepository+ */import type {ProjectAddInput,ProjectAddResult,@@ -9,16 +17,61 @@ import type {import { Context } from "effect";import type { Effect } from "effect";+import type { ProjectRepositoryError } from "../Errors";+export interface ProjectRepositoryShape {- readonly list: () => Effect.Effect<ProjectListResult>;- readonly add: (input: ProjectAddInput) => Effect.Effect<ProjectAddResult, Error>;- readonly remove: (input: ProjectRemoveInput) => Effect.Effect<void, Error>;+ /**+ * List all persisted projects.+ *+ * @returns Effect containing all project records.+ */+ readonly list: () => Effect.Effect<ProjectListResult, ProjectRepositoryError>;++ /**+ * Add a project by cwd, or return the existing project when the cwd already exists.+ *+ * @param input - Project creation payload.+ * @returns Effect containing the project and whether it was newly created.+ */+ readonly add: (input: ProjectAddInput) => Effect.Effect<ProjectAddResult, ProjectRepositoryError>;++ /**+ * Remove a persisted project.+ *+ * @param input - Project removal payload.+ * @returns Effect containing void.+ */+ readonly remove: (input: ProjectRemoveInput) => Effect.Effect<void, ProjectRepositoryError>;++ /**+ * Update the scripts for an existing project.+ *+ * @param input - Script update payload.+ * @returns Effect containing the updated project.+ */readonly updateScripts: (input: ProjectUpdateScriptsInput,- ) => Effect.Effect<ProjectUpdateScriptsResult, Error>;- readonly pruneMissing: () => Effect.Effect<void>;+ ) => Effect.Effect<ProjectUpdateScriptsResult, ProjectRepositoryError>;++ /**+ * Remove projects whose cwd no longer exists on disk.+ *+ * @returns Effect containing void.+ */+ readonly pruneMissing: () => Effect.Effect<void, ProjectRepositoryError>;}+/**+ * ProjectRepository - Context tag for project persistence dependency injection.+ *+ * @example+ * ```ts+ * const program = Effect.gen(function* () {+ * const projects = yield* ProjectRepository+ * return yield* projects.list()+ * })+ * ```+ */export class ProjectRepository extends Context.Tag("persistence/ProjectRepository")<ProjectRepository,ProjectRepositoryShape