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.
look over effect services
Julius Marminge9fae3ee0e95b
diff --git a/.plans/16c-pr89-remediation-checklist.md b/.plans/16c-pr89-remediation-checklist.mdindex eded5e722..c7273eb07 100644--- a/.plans/16c-pr89-remediation-checklist.md+++ b/.plans/16c-pr89-remediation-checklist.md@@ -210,8 +210,8 @@ Counts: active `51` (`valid=33`, `partially-valid=18`), closed-invalid `6`- Threads: PRRT_kwDORLtfbc5wiLhQ- Audit note: Snapshot sequence can under-report due to extra projectors, but replay impact is lower now.-- [ ] `C033` Three error classes defined but never instantiated anywhere- - Status: `TODO`+- [x] `C033` Three error classes defined but never instantiated anywhere+ - Status: `DONE`- Verdict: `partially-valid`- Severity: `Low`- Area: `Checkpointing correctness`@@ -219,8 +219,8 @@ Counts: active `51` (`valid=33`, `partially-valid=18`), closed-invalid `6`- Threads: PRRT_kwDORLtfbc5wlYgo- Audit note: Original claim overstated; some errors used, others appear unused.-- [ ] `C034` Redundant `CheckpointInvariantError` in `CheckpointServiceError` union type- - Status: `TODO`+- [x] `C034` Redundant `CheckpointInvariantError` in `CheckpointServiceError` union type+ - Status: `DONE`- Verdict: `valid`- Severity: `Low`- Area: `Checkpointing correctness`@@ -228,8 +228,8 @@ Counts: active `51` (`valid=33`, `partially-valid=18`), closed-invalid `6`- Threads: PRRT_kwDORLtfbc5wj5fn- Audit note: CheckpointInvariantError remains redundantly included in service union.-- [ ] `C035` Redundant error type in CheckpointServiceError union definition- - Status: `TODO`+- [x] `C035` Redundant error type in CheckpointServiceError union definition+ - Status: `DONE`- Verdict: `valid`- Severity: `Low`- Area: `Checkpointing correctness`diff --git a/apps/server/src/checkpointing/Errors.ts b/apps/server/src/checkpointing/Errors.tsindex 0e0ecf1d0..782d0918e 100644--- a/apps/server/src/checkpointing/Errors.ts+++ b/apps/server/src/checkpointing/Errors.ts@@ -19,37 +19,6 @@ export class CheckpointUnavailableError extends Schema.TaggedErrorClass<Checkpoi}}-/**- * CheckpointRepositoryError - Checkpointing unavailable for cwd/repository.- */-export class CheckpointRepositoryError extends Schema.TaggedErrorClass<CheckpointRepositoryError>()(- "CheckpointRepositoryError",- {- cwd: Schema.String,- detail: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Checkpoint repository error for ${this.cwd}: ${this.detail}`;- }-}--/**- * CheckpointSessionNotFoundError - Session is missing in checkpoint workflow.- */-export class CheckpointSessionNotFoundError extends Schema.TaggedErrorClass<CheckpointSessionNotFoundError>()(- "CheckpointSessionNotFoundError",- {- sessionId: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Checkpoint session not found: ${this.sessionId}`;- }-}-/*** CheckpointInvariantError - Inconsistent provider/filesystem/catalog state.*/@@ -69,11 +38,6 @@ export class CheckpointInvariantError extends Schema.TaggedErrorClass<Checkpointexport type CheckpointStoreError =| GitCommandError| CheckpointInvariantError- | CheckpointUnavailableError- | CheckpointRepositoryError;+ | CheckpointUnavailableError;-export type CheckpointServiceError =- | CheckpointStoreError- | ProjectionRepositoryError- | CheckpointSessionNotFoundError- | CheckpointInvariantError;+export type CheckpointServiceError = CheckpointStoreError | ProjectionRepositoryError;diff --git a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.tsindex 7e504f370..5cf26c86d 100644--- a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts+++ b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts@@ -1,6 +1,5 @@import {OrchestrationGetTurnDiffResult,- type ProjectId,type OrchestrationGetFullThreadDiffInput,type OrchestrationGetFullThreadDiffResult,type OrchestrationGetTurnDiffResult as OrchestrationGetTurnDiffResultType,diff --git a/apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts b/apps/server/src/checkpointing/Services/CheckpointDiffQuery.tsindex ea6ef17c0..dfa40cd75 100644--- a/apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts+++ b/apps/server/src/checkpointing/Services/CheckpointDiffQuery.ts@@ -1,3 +1,11 @@+/**+ * CheckpointDiffQuery - Query interface for computed checkpoint diffs.+ *+ * Provides read-only diff operations across checkpoint snapshots used by+ * orchestration APIs.+ *+ * @module CheckpointDiffQuery+ */import type {OrchestrationGetFullThreadDiffInput,OrchestrationGetFullThreadDiffResult,@@ -9,15 +17,32 @@ import type { Effect } from "effect";import type { CheckpointServiceError } from "../Errors.ts";+/**+ * CheckpointDiffQueryShape - Service API for checkpoint diff queries.+ */export interface CheckpointDiffQueryShape {+ /**+ * Read the patch diff for a single turn checkpoint transition.+ *+ * Verifies checkpoint availability in both projection state and filesystem.+ */readonly getTurnDiff: (input: OrchestrationGetTurnDiffInput,) => Effect.Effect<OrchestrationGetTurnDiffResult, CheckpointServiceError>;++ /**+ * Read the full patch diff across a thread range of checkpoints.+ *+ * Delegates to turn diff with `fromTurnCount = 0`.+ */readonly getFullThreadDiff: (input: OrchestrationGetFullThreadDiffInput,) => Effect.Effect<OrchestrationGetFullThreadDiffResult, CheckpointServiceError>;}+/**+ * CheckpointDiffQuery - Service tag for checkpoint diff queries.+ */export class CheckpointDiffQuery extends ServiceMap.Service<CheckpointDiffQuery,CheckpointDiffQueryShapediff --git a/apps/server/src/checkpointing/Services/CheckpointStore.ts b/apps/server/src/checkpointing/Services/CheckpointStore.tsindex c6f7c7c6c..b004c87fd 100644--- a/apps/server/src/checkpointing/Services/CheckpointStore.ts+++ b/apps/server/src/checkpointing/Services/CheckpointStore.ts@@ -39,6 +39,9 @@ export interface DeleteCheckpointRefsInput {readonly checkpointRefs: ReadonlyArray<CheckpointRef>;}+/**+ * CheckpointStoreShape - Service API for checkpoint capture/restore and diff access.+ */export interface CheckpointStoreShape {/*** Check whether cwd is inside a Git worktree.@@ -47,6 +50,8 @@ export interface CheckpointStoreShape {/*** Capture a checkpoint commit and store it at the provided checkpoint ref.+ *+ * Uses an isolated temporary Git index and writes a hidden ref.*/readonly captureCheckpoint: (input: CaptureCheckpointInput,@@ -61,6 +66,8 @@ export interface CheckpointStoreShape {/*** Restore workspace/staging state to a checkpoint.+ *+ * Optionally falls back to current `HEAD` when the checkpoint ref is missing.*/readonly restoreCheckpoint: (input: RestoreCheckpointInput,@@ -68,6 +75,8 @@ export interface CheckpointStoreShape {/*** Compute patch diff between two checkpoint refs.+ *+ * Can optionally treat missing "from" ref as `HEAD`.*/readonly diffCheckpoints: (input: DiffCheckpointsInput,@@ -75,6 +84,8 @@ export interface CheckpointStoreShape {/*** Delete the provided checkpoint refs.+ *+ * Best-effort delete: missing refs are tolerated.*/readonly deleteCheckpointRefs: (input: DeleteCheckpointRefsInput,diff --git a/apps/server/src/config.ts b/apps/server/src/config.tsindex ba523e3b5..1dc0573a6 100644--- a/apps/server/src/config.ts+++ b/apps/server/src/config.ts@@ -1,3 +1,11 @@+/**+ * ServerConfig and NetService - Runtime configuration services.+ *+ * Defines process-level server configuration and networking helpers used by+ * startup and runtime layers.+ *+ * @module ServerConfig+ */import * as Net from "node:net";import { Data, Effect, FileSystem, Layer, Path, ServiceMap } from "effect";@@ -5,6 +13,9 @@ export const DEFAULT_PORT = 3773;export type RuntimeMode = "web" | "desktop";+/**+ * ServerConfigShape - Process/runtime configuration required by the server.+ */export interface ServerConfigShape {readonly mode: RuntimeMode;readonly port: number;@@ -20,6 +31,9 @@ export interface ServerConfigShape {readonly logWebSocketEvents: boolean;}+/**+ * ServerConfig - Service tag for server runtime configuration.+ */export class ServerConfig extends ServiceMap.Service<ServerConfig, ServerConfigShape>()("server/ServerConfig",) {}@@ -31,10 +45,21 @@ export class NetError extends Data.TaggedError("NetError")<{readonly cause?: unknown;}> {}+/**+ * NetServiceShape - Networking helper operations used during startup.+ */export interface NetServiceShape {+ /**+ * Resolve an available listening port, preferring the provided port first.+ *+ * Falls back to an ephemeral OS-assigned port when the preferred port is in use.+ */readonly findAvailablePort: (preferred: number) => Effect.Effect<number, NetError>;}+/**+ * NetService - Service tag for startup networking helpers.+ */export class NetService extends ServiceMap.Service<NetService, NetServiceShape>()("server/NetService",) {diff --git a/apps/server/src/git/Errors.ts b/apps/server/src/git/Errors.tsindex 106c0ab45..15bf482f7 100644--- a/apps/server/src/git/Errors.ts+++ b/apps/server/src/git/Errors.ts@@ -57,26 +57,11 @@ export class GitManagerError extends Schema.TaggedErrorClass<GitManagerError>()(}}-/**- * GitCoreError - Errors emitted by low-level Git repository operations.- */-export type GitCoreError = GitCommandError;--/**- * GitHubCliServiceError - Errors emitted by GitHub CLI service helpers.- */-export type GitHubCliServiceError = GitHubCliError;--/**- * TextGenerationServiceError - Errors emitted by commit/PR text generation.- */-export type TextGenerationServiceError = TextGenerationError;-/*** GitManagerServiceError - Errors emitted by stacked Git workflow orchestration.*/export type GitManagerServiceError =| GitManagerError- | GitCoreError- | GitHubCliServiceError- | TextGenerationServiceError;+ | GitCommandError+ | GitHubCliError+ | TextGenerationError;diff --git a/apps/server/src/git/Services/GitService.ts b/apps/server/src/git/Services/GitService.tsindex 185ec1d14..9bd43f3cc 100644--- a/apps/server/src/git/Services/GitService.ts+++ b/apps/server/src/git/Services/GitService.ts@@ -27,6 +27,9 @@ export interface ExecuteGitResult {readonly stderr: string;}+/**+ * GitServiceShape - Service API for Git command execution.+ */export interface GitServiceShape {/*** Execute a Git command.diff --git a/apps/server/src/keybindings.ts b/apps/server/src/keybindings.tsindex b727017f1..b433b05fd 100644--- a/apps/server/src/keybindings.ts+++ b/apps/server/src/keybindings.ts@@ -1,3 +1,11 @@+/**+ * Keybindings - Keybinding configuration service definitions.+ *+ * Owns parsing, validation, merge, and persistence of user keybinding+ * configuration consumed by the server runtime.+ *+ * @module Keybindings+ */import {KeybindingRule,KeybindingsConfig,@@ -388,16 +396,34 @@ function mergeWithDefaultKeybindings(custom: ResolvedKeybindingsConfig): Resolvereturn merged.slice(-MAX_KEYBINDINGS_COUNT);}+/**+ * KeybindingsShape - Service API for keybinding configuration operations.+ */export interface KeybindingsShape {+ /**+ * Load and resolve keybindings from disk merged with defaults.+ *+ * Returns an in-memory cached result after the first successful load.+ */readonly loadResolvedKeybindingsConfig: Effect.Effect<readonly ResolvedKeybindingRule[],KeybindingsConfigError>;++ /**+ * Upsert a keybinding rule and persist the resulting configuration.+ *+ * Writes config atomically and enforces the max rule count by truncating+ * oldest entries when needed.+ */readonly upsertKeybindingRule: (rule: KeybindingRule,) => Effect.Effect<ResolvedKeybindingsConfig, KeybindingsConfigError>;}+/**+ * Keybindings - Service tag for keybinding configuration operations.+ */export class Keybindings extends ServiceMap.Service<Keybindings, KeybindingsShape>()("server/Keybindings",) {}diff --git a/apps/server/src/main.ts b/apps/server/src/main.tsindex 035895935..97d237d51 100644--- a/apps/server/src/main.ts+++ b/apps/server/src/main.ts@@ -1,3 +1,11 @@+/**+ * CliConfig - CLI/runtime bootstrap service definitions.+ *+ * Defines startup-only service contracts used while resolving process config+ * and constructing server runtime layers.+ *+ * @module CliConfig+ */import { Config, Data, Effect, FileSystem, Layer, Option, Path, Schema, ServiceMap } from "effect";import { Command, Flag } from "effect/unstable/cli";@@ -32,12 +40,29 @@ interface CliInput {readonly logWebSocketEvents: Option.Option<boolean>;}+/**+ * CliConfigShape - Startup helpers required while building server layers.+ */export interface CliConfigShape {+ /**+ * Current process working directory.+ */readonly cwd: string;++ /**+ * Apply OS-specific PATH normalization.+ */readonly fixPath: Effect.Effect<void>;++ /**+ * Resolve static web asset directory for server mode.+ */readonly resolveStaticDir: Effect.Effect<string | undefined>;}+/**+ * CliConfig - Service tag for startup CLI/runtime helpers.+ */export class CliConfig extends ServiceMap.Service<CliConfig, CliConfigShape>()("server/CliConfig") {static readonly layer = Layer.effect(CliConfig,diff --git a/apps/server/src/open.ts b/apps/server/src/open.tsindex d88f519f8..dbfadbfce 100644--- a/apps/server/src/open.ts+++ b/apps/server/src/open.ts@@ -1,3 +1,11 @@+/**+ * Open - Browser/editor launch service interface.+ *+ * Owns process launch helpers for opening URLs in a browser and workspace+ * paths in a configured editor.+ *+ * @module Open+ */import { spawn } from "node:child_process";import { EDITORS, type EditorId } from "@t3tools/contracts";@@ -22,11 +30,26 @@ interface EditorLaunch {readonly args: ReadonlyArray<string>;}+/**+ * OpenShape - Service API for browser and editor launch actions.+ */export interface OpenShape {+ /**+ * Open a URL target in the default browser.+ */readonly openBrowser: (target: string) => Effect.Effect<void, OpenError>;++ /**+ * Open a workspace path in a selected editor integration.+ *+ * Launches the editor as a detached process so server startup is not blocked.+ */readonly openInEditor: (input: OpenInEditorInput) => Effect.Effect<void, OpenError>;}+/**+ * Open - Service tag for browser/editor launch operations.+ */export class Open extends ServiceMap.Service<Open, OpenShape>()("server/Open") {}// ==============================diff --git a/apps/server/src/orchestration/Errors.ts b/apps/server/src/orchestration/Errors.tsindex 81e83751b..5882ead3e 100644--- a/apps/server/src/orchestration/Errors.ts+++ b/apps/server/src/orchestration/Errors.ts@@ -1,8 +1,6 @@import { SchemaIssue, Schema } from "effect";import type {- OrchestrationCommandReceiptRepositoryError,- OrchestrationEventStoreError,ProjectionRepositoryError,} from "../persistence/Errors.ts";@@ -83,8 +81,6 @@ export class OrchestrationListenerCallbackError extends Schema.TaggedErrorClass<}export type OrchestrationDispatchError =- | OrchestrationEventStoreError- | OrchestrationCommandReceiptRepositoryError| ProjectionRepositoryError| OrchestrationCommandInvariantError| OrchestrationCommandPreviouslyRejectedErrordiff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.tsindex dfaa8c008..2c2b77001 100644--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts@@ -14,9 +14,7 @@ import * as SqlClient from "effect/unstable/sql/SqlClient";import * as SqlSchema from "effect/unstable/sql/SqlSchema";import {- PersistenceDecodeError,- PersistenceSerializationError,- PersistenceSqlError,+ isPersistenceError,toPersistenceDecodeError,toPersistenceSqlError,type ProjectionRepositoryError,@@ -106,19 +104,6 @@ function toPersistenceSqlOrDecodeError(sqlOperation: string, decodeOperation: st: toPersistenceSqlError(sqlOperation)(cause);}-function toProjectionRepositoryError(operation: string) {- return (cause: unknown): ProjectionRepositoryError => {- if (- cause instanceof PersistenceSqlError ||- cause instanceof PersistenceDecodeError ||- cause instanceof PersistenceSerializationError- ) {- return cause;- }- return toPersistenceSqlError(operation)(cause);- };-}-const makeProjectionSnapshotQuery = Effect.gen(function* () {const sql = yield* SqlClient.SqlClient;@@ -441,7 +426,12 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {}),).pipe(- Effect.mapError(toProjectionRepositoryError("ProjectionSnapshotQuery.getSnapshot:query")),+ Effect.mapError((error) => {+ if (isPersistenceError(error)) {+ return error;+ }+ return toPersistenceSqlError("ProjectionSnapshotQuery.getSnapshot:query")(error);+ }),);return {diff --git a/apps/server/src/orchestration/Services/CheckpointReactor.ts b/apps/server/src/orchestration/Services/CheckpointReactor.tsindex 330b800b1..3e4688b89 100644--- a/apps/server/src/orchestration/Services/CheckpointReactor.ts+++ b/apps/server/src/orchestration/Services/CheckpointReactor.ts@@ -1,16 +1,33 @@+/**+ * CheckpointReactor - Checkpoint reaction service interface.+ *+ * Owns background workers that react to orchestration checkpoint lifecycle+ * events and apply checkpoint side effects.+ *+ * @module CheckpointReactor+ */import { ServiceMap } from "effect";import type { Effect, Scope } from "effect";+/**+ * CheckpointReactorShape - Service API for checkpoint reactor lifecycle.+ */export interface CheckpointReactorShape {/*** Start the checkpoint reactor.** The returned effect must be run in a scope so all worker fibers can be* finalized on shutdown.+ *+ * Consumes both orchestration-domain and provider-runtime events via an+ * internal queue.*/readonly start: Effect.Effect<void, never, Scope.Scope>;}+/**+ * CheckpointReactor - Service tag for checkpoint reactor workers.+ */export class CheckpointReactor extends ServiceMap.Service<CheckpointReactor,CheckpointReactorShapediff --git a/apps/server/src/orchestration/Services/OrchestrationEngine.ts b/apps/server/src/orchestration/Services/OrchestrationEngine.tsindex ed2bf6a35..4907860cb 100644--- a/apps/server/src/orchestration/Services/OrchestrationEngine.ts+++ b/apps/server/src/orchestration/Services/OrchestrationEngine.ts@@ -21,6 +21,9 @@ import type { Effect, Stream } from "effect";import type { OrchestrationDispatchError } from "../Errors.ts";import type { OrchestrationEventStoreError } from "../../persistence/Errors.ts";+/**+ * OrchestrationEngineShape - Service API for orchestration command and event flow.+ */export interface OrchestrationEngineShape {/*** Read the current in-memory orchestration read model.@@ -44,6 +47,9 @@ export interface OrchestrationEngineShape {** @param command - Valid orchestration command.* @returns Effect containing the sequence of the persisted event.+ *+ * Dispatch is serialized through an internal queue and deduplicated via+ * command receipts.*/readonly dispatch: (command: OrchestrationCommand,@@ -51,6 +57,8 @@ export interface OrchestrationEngineShape {/*** Stream persisted domain events in dispatch order.+ *+ * This is a hot runtime stream (new events only), not a historical replay.*/readonly streamDomainEvents: Stream.Stream<OrchestrationEvent>;}diff --git a/apps/server/src/orchestration/Services/OrchestrationReactor.ts b/apps/server/src/orchestration/Services/OrchestrationReactor.tsindex 185750fb2..384da07b2 100644--- a/apps/server/src/orchestration/Services/OrchestrationReactor.ts+++ b/apps/server/src/orchestration/Services/OrchestrationReactor.ts@@ -1,6 +1,17 @@+/**+ * OrchestrationReactor - Composite orchestration reactor service interface.+ *+ * Coordinates startup of orchestration runtime reactors that translate domain+ * events into downstream side effects.+ *+ * @module OrchestrationReactor+ */import { ServiceMap } from "effect";import type { Effect, Scope } from "effect";+/**+ * OrchestrationReactorShape - Service API for orchestration reactor lifecycle.+ */export interface OrchestrationReactorShape {/*** Start orchestration-side reactors for provider/runtime/checkpoint flows.@@ -11,6 +22,9 @@ export interface OrchestrationReactorShape {readonly start: Effect.Effect<void, never, Scope.Scope>;}+/**+ * OrchestrationReactor - Service tag for orchestration reactor coordination.+ */export class OrchestrationReactor extends ServiceMap.Service<OrchestrationReactor,OrchestrationReactorShapediff --git a/apps/server/src/orchestration/Services/ProjectionPipeline.ts b/apps/server/src/orchestration/Services/ProjectionPipeline.tsindex 9457aaf8d..370409a9d 100644--- a/apps/server/src/orchestration/Services/ProjectionPipeline.ts+++ b/apps/server/src/orchestration/Services/ProjectionPipeline.ts@@ -1,24 +1,41 @@+/**+ * OrchestrationProjectionPipeline - Event projection pipeline service interface.+ *+ * Coordinates projection bootstrap/replay and per-event projection updates for+ * orchestration read models.+ *+ * @module OrchestrationProjectionPipeline+ */import type { OrchestrationEvent } from "@t3tools/contracts";import { ServiceMap } from "effect";import type { Effect } from "effect";-import type {- OrchestrationEventStoreError,- ProjectionRepositoryError,-} from "../../persistence/Errors.ts";--export type OrchestrationProjectionPipelineError =- | OrchestrationEventStoreError- | ProjectionRepositoryError;+import type { ProjectionRepositoryError } from "../../persistence/Errors.ts";+/**+ * OrchestrationProjectionPipelineShape - Service API for projection execution.+ */export interface OrchestrationProjectionPipelineShape {- readonly bootstrap: Effect.Effect<void, OrchestrationProjectionPipelineError>;+ /**+ * Bootstrap projections by replaying persisted events.+ *+ * Resumes each projector from its stored projection-state cursor.+ */+ readonly bootstrap: Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * Project a single orchestration event into projection repositories.+ *+ * Projectors are executed sequentially to preserve deterministic ordering.+ */readonly projectEvent: (event: OrchestrationEvent,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * OrchestrationProjectionPipeline - Service tag for orchestration projections.+ */export class OrchestrationProjectionPipeline extends ServiceMap.Service<OrchestrationProjectionPipeline,OrchestrationProjectionPipelineShapediff --git a/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.tsindex 66e27a3fe..bd8d57cf5 100644--- a/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts+++ b/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts@@ -1,13 +1,33 @@+/**+ * ProjectionSnapshotQuery - Read-model snapshot query service interface.+ *+ * Exposes the current orchestration projection snapshot for read-only API+ * access.+ *+ * @module ProjectionSnapshotQuery+ */import type { OrchestrationReadModel } from "@t3tools/contracts";import { ServiceMap } from "effect";import type { Effect } from "effect";import type { ProjectionRepositoryError } from "../../persistence/Errors.ts";+/**+ * ProjectionSnapshotQueryShape - Service API for read-model snapshots.+ */export interface ProjectionSnapshotQueryShape {+ /**+ * Read the latest orchestration projection snapshot.+ *+ * Rehydrates from projection tables and derives snapshot sequence from+ * projector cursor state.+ */readonly getSnapshot: () => Effect.Effect<OrchestrationReadModel, ProjectionRepositoryError>;}+/**+ * ProjectionSnapshotQuery - Service tag for projection snapshot queries.+ */export class ProjectionSnapshotQuery extends ServiceMap.Service<ProjectionSnapshotQuery,ProjectionSnapshotQueryShapediff --git a/apps/server/src/orchestration/Services/ProviderCommandReactor.ts b/apps/server/src/orchestration/Services/ProviderCommandReactor.tsindex 1069137ab..7007e8e0f 100644--- a/apps/server/src/orchestration/Services/ProviderCommandReactor.ts+++ b/apps/server/src/orchestration/Services/ProviderCommandReactor.ts@@ -1,16 +1,33 @@+/**+ * ProviderCommandReactor - Provider command reaction service interface.+ *+ * Owns background workers that react to orchestration intent events and+ * dispatch provider-side command execution.+ *+ * @module ProviderCommandReactor+ */import { ServiceMap } from "effect";import type { Effect, Scope } from "effect";+/**+ * ProviderCommandReactorShape - Service API for provider command reactors.+ */export interface ProviderCommandReactorShape {/*** Start reacting to provider-intent orchestration domain events.** The returned effect must be run in a scope so all worker fibers can be* finalized on shutdown.+ *+ * Filters orchestration domain events to provider-intent types before+ * processing.*/readonly start: Effect.Effect<void, never, Scope.Scope>;}+/**+ * ProviderCommandReactor - Service tag for provider command reaction workers.+ */export class ProviderCommandReactor extends ServiceMap.Service<ProviderCommandReactor,ProviderCommandReactorShapediff --git a/apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts b/apps/server/src/orchestration/Services/ProviderRuntimeIngestion.tsindex ba45bac85..13574acf9 100644--- a/apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts+++ b/apps/server/src/orchestration/Services/ProviderRuntimeIngestion.ts@@ -1,16 +1,33 @@+/**+ * ProviderRuntimeIngestionService - Provider runtime ingestion service interface.+ *+ * Owns background workers that consume provider runtime streams and emit+ * orchestration commands/events.+ *+ * @module ProviderRuntimeIngestionService+ */import { ServiceMap } from "effect";import type { Effect, Scope } from "effect";+/**+ * ProviderRuntimeIngestionShape - Service API for runtime ingestion lifecycle.+ */export interface ProviderRuntimeIngestionShape {/*** Start ingesting provider runtime events into orchestration commands.** The returned effect must be run in a scope so all worker fibers can be* finalized on shutdown.+ *+ * Uses an internal queue and continues after non-interrupt failures by+ * logging warnings.*/readonly start: Effect.Effect<void, never, Scope.Scope>;}+/**+ * ProviderRuntimeIngestionService - Service tag for runtime ingestion workers.+ */export class ProviderRuntimeIngestionService extends ServiceMap.Service<ProviderRuntimeIngestionService,ProviderRuntimeIngestionShapediff --git a/apps/server/src/persistence/Errors.ts b/apps/server/src/persistence/Errors.tsindex a2b3b57c2..cb1cb2f3f 100644--- a/apps/server/src/persistence/Errors.ts+++ b/apps/server/src/persistence/Errors.ts@@ -30,19 +30,6 @@ export class PersistenceDecodeError extends Schema.TaggedErrorClass<PersistenceD}}-export class PersistenceSerializationError extends Schema.TaggedErrorClass<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 function toPersistenceSqlError(operation: string) {return (cause: unknown): PersistenceSqlError =>new PersistenceSqlError({@@ -70,85 +57,8 @@ export function toPersistenceDecodeCauseError(operation: string) {});}-export function toPersistenceSerializationError(operation: string) {- return (cause: unknown): PersistenceSerializationError =>- new PersistenceSerializationError({- operation,- detail: `Failed to execute ${operation}`,- cause,- });-}--// ===============================-// Project Repository Errors-// ===============================--export class ProjectValidationError extends Schema.TaggedErrorClass<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.TaggedErrorClass<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.TaggedErrorClass<ProjectNotFoundError>()(- "ProjectNotFoundError",- {- projectId: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Project not found: ${this.projectId}`;- }-}--// ===============================-// Checkpoint Repository Errors-// ===============================--export class CheckpointRepositoryValidationError extends Schema.TaggedErrorClass<CheckpointRepositoryValidationError>()(- "CheckpointRepositoryValidationError",- {- operation: Schema.String,- issue: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Checkpoint repository validation failed in ${this.operation}: ${this.issue}`;- }-}--export class CheckpointRepositoryPersistenceError extends Schema.TaggedErrorClass<CheckpointRepositoryPersistenceError>()(- "CheckpointRepositoryPersistenceError",- {- operation: Schema.String,- detail: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Checkpoint repository persistence error in ${this.operation}: ${this.detail}`;- }-}+export const isPersistenceError = (u: unknown) =>+ Schema.is(PersistenceSqlError)(u) || Schema.is(PersistenceDecodeError)(u);// ===============================// Provider Session Repository Errors@@ -180,22 +90,7 @@ export class ProviderSessionRepositoryPersistenceError extends Schema.TaggedErro}}-export type ProjectRepositoryError =- | PersistenceSqlError- | PersistenceDecodeError- | PersistenceSerializationError- | ProjectValidationError- | ProjectPathMissingError- | ProjectNotFoundError;--export type OrchestrationEventStoreError =- | PersistenceSqlError- | PersistenceDecodeError- | PersistenceSerializationError;--export type CheckpointRepositoryError =- | CheckpointRepositoryValidationError- | CheckpointRepositoryPersistenceError;+export type OrchestrationEventStoreError = PersistenceSqlError | PersistenceDecodeError;export type ProviderSessionRepositoryError =| ProviderSessionRepositoryValidationError@@ -205,12 +100,6 @@ export type OrchestrationCommandReceiptRepositoryError =| PersistenceSqlError| PersistenceDecodeError;-export type ProviderSessionRuntimeRepositoryError =- | PersistenceSqlError- | PersistenceDecodeError- | PersistenceSerializationError;+export type ProviderSessionRuntimeRepositoryError = PersistenceSqlError | PersistenceDecodeError;-export type ProjectionRepositoryError =- | PersistenceSqlError- | PersistenceDecodeError- | PersistenceSerializationError;+export type ProjectionRepositoryError = PersistenceSqlError | PersistenceDecodeError;diff --git a/apps/server/src/persistence/NodeSqliteClient.ts b/apps/server/src/persistence/NodeSqliteClient.tsindex cdfcee4e9..cfbcb8b9c 100644--- a/apps/server/src/persistence/NodeSqliteClient.ts+++ b/apps/server/src/persistence/NodeSqliteClient.ts@@ -1,6 +1,8 @@/*** Port of `@effect/sql-sqlite-node` that uses the native `node:sqlite`* bindings instead of `better-sqlite3`.+ *+ * @module SqliteClient*/import { DatabaseSync, type StatementSync } from "node:sqlite";@@ -27,6 +29,9 @@ export const TypeId: TypeId = "~local/sqlite-node/SqliteClient";export type TypeId = "~local/sqlite-node/SqliteClient";+/**+ * SqliteClient - Effect service tag for the sqlite SQL client.+ */export const SqliteClient = ServiceMap.Service<Client.SqlClient>("@local/sqlite-node/SqliteClient");export interface SqliteClientConfig {diff --git a/apps/server/src/persistence/Services/OrchestrationCommandReceipts.ts b/apps/server/src/persistence/Services/OrchestrationCommandReceipts.tsindex 95fbbf493..c1ec79c9f 100644--- a/apps/server/src/persistence/Services/OrchestrationCommandReceipts.ts+++ b/apps/server/src/persistence/Services/OrchestrationCommandReceipts.ts@@ -1,3 +1,11 @@+/**+ * OrchestrationCommandReceiptRepository - Repository interface for command receipts.+ *+ * Owns persistence operations for deduplication and status tracking of+ * orchestration command handling.+ *+ * @module OrchestrationCommandReceiptRepository+ */import {CommandId,IsoDateTime,@@ -28,11 +36,22 @@ export const GetByCommandIdInput = Schema.Struct({});export type GetByCommandIdInput = typeof GetByCommandIdInput.Type;+/**+ * OrchestrationCommandReceiptRepositoryShape - Service API for command receipts.+ */export interface OrchestrationCommandReceiptRepositoryShape {+ /**+ * Insert or replace a command receipt row.+ *+ * Upserts by `commandId` for idempotent command-result tracking.+ */readonly upsert: (receipt: OrchestrationCommandReceipt,) => Effect.Effect<void, OrchestrationCommandReceiptRepositoryError>;+ /**+ * Read a command receipt by command id.+ */readonly getByCommandId: (input: GetByCommandIdInput,) => Effect.Effect<@@ -41,6 +60,9 @@ export interface OrchestrationCommandReceiptRepositoryShape {>;}+/**+ * OrchestrationCommandReceiptRepository - Service tag for command receipt persistence.+ */export class OrchestrationCommandReceiptRepository extends ServiceMap.Service<OrchestrationCommandReceiptRepository,OrchestrationCommandReceiptRepositoryShapediff --git a/apps/server/src/persistence/Services/OrchestrationEventStore.ts b/apps/server/src/persistence/Services/OrchestrationEventStore.tsindex 2ee8e8486..6a557c037 100644--- a/apps/server/src/persistence/Services/OrchestrationEventStore.ts+++ b/apps/server/src/persistence/Services/OrchestrationEventStore.ts@@ -15,12 +15,17 @@ import type { Effect, Stream } from "effect";import type { OrchestrationEventStoreError } from "../Errors.ts";+/**+ * OrchestrationEventStoreShape - Service API for orchestration event persistence.+ */export interface OrchestrationEventStoreShape {/*** Persist a new orchestration event.** @param event - Event payload without sequence (assigned by storage).* @returns Effect containing the stored event with assigned sequence.+ *+ * Actor kind is inferred from command/metadata before persistence.*/readonly append: (event: Omit<OrchestrationEvent, "sequence">,@@ -32,6 +37,8 @@ export interface OrchestrationEventStoreShape {* @param sequenceExclusive - Sequence cursor (exclusive).* @param limit - Maximum number of events to emit.* @returns Stream containing ordered events.+ *+ * Reads in fixed-size pages and normalizes non-integer/negative limits.*/readonly readFromSequence: (sequenceExclusive: number,diff --git a/apps/server/src/persistence/Services/ProjectionCheckpoints.ts b/apps/server/src/persistence/Services/ProjectionCheckpoints.tsindex cc5a93eb8..d10c86d81 100644--- a/apps/server/src/persistence/Services/ProjectionCheckpoints.ts+++ b/apps/server/src/persistence/Services/ProjectionCheckpoints.ts@@ -1,3 +1,11 @@+/**+ * ProjectionCheckpointRepository - Projection repository interface for checkpoints.+ *+ * Owns persistence operations for projected checkpoint summaries in thread+ * timelines.+ *+ * @module ProjectionCheckpointRepository+ */import {CheckpointRef,IsoDateTime,@@ -41,22 +49,44 @@ export const DeleteByThreadIdInput = Schema.Struct({});export type DeleteByThreadIdInput = typeof DeleteByThreadIdInput.Type;+/**+ * ProjectionCheckpointRepositoryShape - Service API for projected checkpoints.+ */export interface ProjectionCheckpointRepositoryShape {+ /**+ * Insert or replace a projected checkpoint row.+ *+ * Upserts by composite key `(threadId, checkpointTurnCount)`.+ */readonly upsert: (row: ProjectionCheckpoint) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * List projected checkpoints for a thread.+ *+ * Returned in ascending checkpoint turn-count order.+ */readonly listByThreadId: (input: ListByThreadIdInput,) => Effect.Effect<ReadonlyArray<ProjectionCheckpoint>, ProjectionRepositoryError>;+ /**+ * Read a projected checkpoint by thread and turn-count key.+ */readonly getByThreadAndTurnCount: (input: GetByThreadAndTurnCountInput,) => Effect.Effect<Option.Option<ProjectionCheckpoint>, ProjectionRepositoryError>;+ /**+ * Delete projected checkpoint rows by thread.+ */readonly deleteByThreadId: (input: DeleteByThreadIdInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionCheckpointRepository - Service tag for checkpoint projection persistence.+ */export class ProjectionCheckpointRepository extends ServiceMap.Service<ProjectionCheckpointRepository,ProjectionCheckpointRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts b/apps/server/src/persistence/Services/ProjectionPendingApprovals.tsindex 1d4083625..8e0d3736b 100644--- a/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts+++ b/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts@@ -1,3 +1,11 @@+/**+ * ProjectionPendingApprovalRepository - Repository interface for pending approvals.+ *+ * Owns persistence operations for projected approval requests awaiting user+ * decisions.+ *+ * @module ProjectionPendingApprovalRepository+ */import {ApprovalRequestId,IsoDateTime,@@ -37,24 +45,46 @@ export const DeleteProjectionPendingApprovalInput = Schema.Struct({});export type DeleteProjectionPendingApprovalInput = typeof DeleteProjectionPendingApprovalInput.Type;+/**+ * ProjectionPendingApprovalRepositoryShape - Service API for pending approvals.+ */export interface ProjectionPendingApprovalRepositoryShape {+ /**+ * Insert or replace a projected pending approval row.+ *+ * Upserts by `requestId`.+ */readonly upsert: (row: ProjectionPendingApproval,) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * List pending approvals for a thread.+ *+ * Returned in ascending creation order.+ */readonly listByThreadId: (input: ListProjectionPendingApprovalsInput,) => Effect.Effect<ReadonlyArray<ProjectionPendingApproval>, ProjectionRepositoryError>;+ /**+ * Read a pending approval row by request id.+ */readonly getByRequestId: (input: GetProjectionPendingApprovalInput,) => Effect.Effect<Option.Option<ProjectionPendingApproval>, ProjectionRepositoryError>;+ /**+ * Delete a pending approval row by request id.+ */readonly deleteByRequestId: (input: DeleteProjectionPendingApprovalInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionPendingApprovalRepository - Service tag for pending approval persistence.+ */export class ProjectionPendingApprovalRepository extends ServiceMap.Service<ProjectionPendingApprovalRepository,ProjectionPendingApprovalRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionPendingTurnStarts.ts b/apps/server/src/persistence/Services/ProjectionPendingTurnStarts.tsindex 58c2572fe..6b6f9a065 100644--- a/apps/server/src/persistence/Services/ProjectionPendingTurnStarts.ts+++ b/apps/server/src/persistence/Services/ProjectionPendingTurnStarts.ts@@ -1,3 +1,11 @@+/**+ * ProjectionPendingTurnStartRepository - Repository interface for pending turn starts.+ *+ * Owns persistence operations for projected "pending turn start" markers used+ * while creating new turns from queued messages.+ *+ * @module ProjectionPendingTurnStartRepository+ */import { IsoDateTime, MessageId, ThreadId } from "@t3tools/contracts";import { Option, Schema, ServiceMap } from "effect";import type { Effect } from "effect";@@ -21,20 +29,37 @@ export const DeleteProjectionPendingTurnStartInput = Schema.Struct({});export type DeleteProjectionPendingTurnStartInput = typeof DeleteProjectionPendingTurnStartInput.Type;+/**+ * ProjectionPendingTurnStartRepositoryShape - Service API for pending turn-start markers.+ */export interface ProjectionPendingTurnStartRepositoryShape {+ /**+ * Insert or replace a pending turn-start row.+ *+ * Maintains at most one pending marker per thread.+ */readonly upsert: (row: ProjectionPendingTurnStart,) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * Read a pending turn-start marker by thread id.+ */readonly getByThreadId: (input: GetProjectionPendingTurnStartInput,) => Effect.Effect<Option.Option<ProjectionPendingTurnStart>, ProjectionRepositoryError>;+ /**+ * Delete a pending turn-start marker by thread id.+ */readonly deleteByThreadId: (input: DeleteProjectionPendingTurnStartInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionPendingTurnStartRepository - Service tag for pending turn-start persistence.+ */export class ProjectionPendingTurnStartRepository extends ServiceMap.Service<ProjectionPendingTurnStartRepository,ProjectionPendingTurnStartRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionProjects.ts b/apps/server/src/persistence/Services/ProjectionProjects.tsindex bb51dc1c0..c3fcea002 100644--- a/apps/server/src/persistence/Services/ProjectionProjects.ts+++ b/apps/server/src/persistence/Services/ProjectionProjects.ts@@ -1,3 +1,11 @@+/**+ * ProjectionProjectRepository - Projection repository interface for projects.+ *+ * Owns persistence operations for project rows in the orchestration projection+ * read model.+ *+ * @module ProjectionProjectRepository+ */import { IsoDateTime, ProjectId, ProjectScript } from "@t3tools/contracts";import { Option, Schema, ServiceMap } from "effect";import type { Effect } from "effect";@@ -26,23 +34,45 @@ export const DeleteProjectionProjectInput = Schema.Struct({});export type DeleteProjectionProjectInput = typeof DeleteProjectionProjectInput.Type;+/**+ * ProjectionProjectRepositoryShape - Service API for projected project records.+ */export interface ProjectionProjectRepositoryShape {+ /**+ * Insert or replace a projected project row.+ *+ * Upserts by `projectId` and persists scripts through JSON encoding.+ */readonly upsert: (row: ProjectionProject) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * Read a projected project row by id.+ */readonly getById: (input: GetProjectionProjectInput,) => Effect.Effect<Option.Option<ProjectionProject>, ProjectionRepositoryError>;+ /**+ * List all projected project rows.+ *+ * Returned in deterministic creation order.+ */readonly listAll: () => Effect.Effect<ReadonlyArray<ProjectionProject>,ProjectionRepositoryError>;+ /**+ * Soft-delete a projected project row by id.+ */readonly deleteById: (input: DeleteProjectionProjectInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionProjectRepository - Service tag for project projection persistence.+ */export class ProjectionProjectRepository extends ServiceMap.Service<ProjectionProjectRepository,ProjectionProjectRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionState.ts b/apps/server/src/persistence/Services/ProjectionState.tsindex c079f941b..7e3a2f6b9 100644--- a/apps/server/src/persistence/Services/ProjectionState.ts+++ b/apps/server/src/persistence/Services/ProjectionState.ts@@ -1,3 +1,11 @@+/**+ * ProjectionStateRepository - Projection repository interface for projector cursors.+ *+ * Owns persistence operations for projection cursor state used to resume+ * incremental event projection.+ *+ * @module ProjectionStateRepository+ */import { IsoDateTime, NonNegativeInt } from "@t3tools/contracts";import { Option, Schema, ServiceMap } from "effect";import type { Effect } from "effect";@@ -16,18 +24,40 @@ export const GetProjectionStateInput = Schema.Struct({});export type GetProjectionStateInput = typeof GetProjectionStateInput.Type;+/**+ * ProjectionStateRepositoryShape - Service API for projector state records.+ */export interface ProjectionStateRepositoryShape {+ /**+ * Insert or replace a projection cursor row.+ *+ * Upserts by projector name.+ */readonly upsert: (row: ProjectionState) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * Read projection cursor state for a projector key.+ */readonly getByProjector: (input: GetProjectionStateInput,) => Effect.Effect<Option.Option<ProjectionState>, ProjectionRepositoryError>;+ /**+ * List all projector cursor rows.+ */readonly listAll: () => Effect.Effect<ReadonlyArray<ProjectionState>, ProjectionRepositoryError>;+ /**+ * Read the minimum applied sequence across all projectors.+ *+ * Returns `null` when no projector state rows exist.+ */readonly minLastAppliedSequence: () => Effect.Effect<number | null, ProjectionRepositoryError>;}+/**+ * ProjectionStateRepository - Service tag for projection cursor persistence.+ */export class ProjectionStateRepository extends ServiceMap.Service<ProjectionStateRepository,ProjectionStateRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionThreadActivities.ts b/apps/server/src/persistence/Services/ProjectionThreadActivities.tsindex 3284805c9..2e5d67909 100644--- a/apps/server/src/persistence/Services/ProjectionThreadActivities.ts+++ b/apps/server/src/persistence/Services/ProjectionThreadActivities.ts@@ -1,3 +1,11 @@+/**+ * ProjectionThreadActivityRepository - Projection repository interface for thread activity.+ *+ * Owns persistence operations for activity timeline entries projected from+ * orchestration events.+ *+ * @module ProjectionThreadActivityRepository+ */import {EventId,IsoDateTime,@@ -33,20 +41,39 @@ export const DeleteProjectionThreadActivitiesInput = Schema.Struct({export type DeleteProjectionThreadActivitiesInput =typeof DeleteProjectionThreadActivitiesInput.Type;+/**+ * ProjectionThreadActivityRepositoryShape - Service API for projected thread activity.+ */export interface ProjectionThreadActivityRepositoryShape {+ /**+ * Insert or replace a projected thread activity row.+ *+ * Upserts by `activityId` and JSON-encodes payload.+ */readonly upsert: (row: ProjectionThreadActivity,) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * List projected thread activity rows for a thread.+ *+ * Returned in ascending creation order.+ */readonly listByThreadId: (input: ListProjectionThreadActivitiesInput,) => Effect.Effect<ReadonlyArray<ProjectionThreadActivity>, ProjectionRepositoryError>;+ /**+ * Delete projected thread activity rows by thread.+ */readonly deleteByThreadId: (input: DeleteProjectionThreadActivitiesInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionThreadActivityRepository - Service tag for thread activity persistence.+ */export class ProjectionThreadActivityRepository extends ServiceMap.Service<ProjectionThreadActivityRepository,ProjectionThreadActivityRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionThreadMessages.ts b/apps/server/src/persistence/Services/ProjectionThreadMessages.tsindex 79bdb6237..6f59b6a8e 100644--- a/apps/server/src/persistence/Services/ProjectionThreadMessages.ts+++ b/apps/server/src/persistence/Services/ProjectionThreadMessages.ts@@ -1,3 +1,11 @@+/**+ * ProjectionThreadMessageRepository - Projection repository interface for messages.+ *+ * Owns persistence operations for projected thread messages rendered in the+ * orchestration read model.+ *+ * @module ProjectionThreadMessageRepository+ */import {OrchestrationMessageRole,MessageId,@@ -32,20 +40,39 @@ export const DeleteProjectionThreadMessagesInput = Schema.Struct({});export type DeleteProjectionThreadMessagesInput = typeof DeleteProjectionThreadMessagesInput.Type;+/**+ * ProjectionThreadMessageRepositoryShape - Service API for projected thread messages.+ */export interface ProjectionThreadMessageRepositoryShape {+ /**+ * Insert or replace a projected thread message row.+ *+ * Upserts by `messageId`.+ */readonly upsert: (message: ProjectionThreadMessage,) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * List projected thread messages for a thread.+ *+ * Returned in ascending creation order.+ */readonly listByThreadId: (input: ListProjectionThreadMessagesInput,) => Effect.Effect<ReadonlyArray<ProjectionThreadMessage>, ProjectionRepositoryError>;+ /**+ * Delete projected thread messages by thread.+ */readonly deleteByThreadId: (input: DeleteProjectionThreadMessagesInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionThreadMessageRepository - Service tag for message projection persistence.+ */export class ProjectionThreadMessageRepository extends ServiceMap.Service<ProjectionThreadMessageRepository,ProjectionThreadMessageRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionThreadSessions.ts b/apps/server/src/persistence/Services/ProjectionThreadSessions.tsindex a6b20a777..57f460b76 100644--- a/apps/server/src/persistence/Services/ProjectionThreadSessions.ts+++ b/apps/server/src/persistence/Services/ProjectionThreadSessions.ts@@ -1,3 +1,11 @@+/**+ * ProjectionThreadSessionRepository - Repository interface for thread sessions.+ *+ * Owns persistence operations for projected provider-session linkage and+ * runtime status for each thread.+ *+ * @module ProjectionThreadSessionRepository+ */import {IsoDateTime,OrchestrationSessionStatus,@@ -33,18 +41,35 @@ export const DeleteProjectionThreadSessionInput = Schema.Struct({});export type DeleteProjectionThreadSessionInput = typeof DeleteProjectionThreadSessionInput.Type;+/**+ * ProjectionThreadSessionRepositoryShape - Service API for projected thread sessions.+ */export interface ProjectionThreadSessionRepositoryShape {+ /**+ * Insert or replace a projected thread-session row.+ *+ * Upserts by `threadId`.+ */readonly upsert: (row: ProjectionThreadSession) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * Read projected thread-session state by thread id.+ */readonly getByThreadId: (input: GetProjectionThreadSessionInput,) => Effect.Effect<Option.Option<ProjectionThreadSession>, ProjectionRepositoryError>;+ /**+ * Delete projected thread-session state by thread id.+ */readonly deleteByThreadId: (input: DeleteProjectionThreadSessionInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionThreadSessionRepository - Service tag for thread-session persistence.+ */export class ProjectionThreadSessionRepository extends ServiceMap.Service<ProjectionThreadSessionRepository,ProjectionThreadSessionRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionThreadTurns.ts b/apps/server/src/persistence/Services/ProjectionThreadTurns.tsindex 7aad85ddf..d33271793 100644--- a/apps/server/src/persistence/Services/ProjectionThreadTurns.ts+++ b/apps/server/src/persistence/Services/ProjectionThreadTurns.ts@@ -1,3 +1,10 @@+/**+ * ProjectionThreadTurnRepository - Projection repository interface for turns.+ *+ * Owns persistence operations for projected turn records in thread timelines.+ *+ * @module ProjectionThreadTurnRepository+ */import {IsoDateTime,MessageId,@@ -38,22 +45,44 @@ export const DeleteProjectionThreadTurnsInput = Schema.Struct({});export type DeleteProjectionThreadTurnsInput = typeof DeleteProjectionThreadTurnsInput.Type;+/**+ * ProjectionThreadTurnRepositoryShape - Service API for projected thread turns.+ */export interface ProjectionThreadTurnRepositoryShape {+ /**+ * Insert or replace a projected turn row.+ *+ * Upserts by `turnId`.+ */readonly upsert: (turn: ProjectionThreadTurn) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * List projected turns for a thread.+ *+ * Returned in ascending `turnCount` order.+ */readonly listByThreadId: (input: ListProjectionThreadTurnsInput,) => Effect.Effect<ReadonlyArray<ProjectionThreadTurn>, ProjectionRepositoryError>;+ /**+ * Read a projected turn row by turn id.+ */readonly getByTurnId: (input: GetProjectionThreadTurnInput,) => Effect.Effect<Option.Option<ProjectionThreadTurn>, ProjectionRepositoryError>;+ /**+ * Delete projected turn rows by thread.+ */readonly deleteByThreadId: (input: DeleteProjectionThreadTurnsInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionThreadTurnRepository - Service tag for turn projection persistence.+ */export class ProjectionThreadTurnRepository extends ServiceMap.Service<ProjectionThreadTurnRepository,ProjectionThreadTurnRepositoryShapediff --git a/apps/server/src/persistence/Services/ProjectionThreads.ts b/apps/server/src/persistence/Services/ProjectionThreads.tsindex 88f91bf74..940991285 100644--- a/apps/server/src/persistence/Services/ProjectionThreads.ts+++ b/apps/server/src/persistence/Services/ProjectionThreads.ts@@ -1,3 +1,11 @@+/**+ * ProjectionThreadRepository - Projection repository interface for threads.+ *+ * Owns persistence operations for projected thread records in the+ * orchestration read model.+ *+ * @module ProjectionThreadRepository+ */import { IsoDateTime, ProjectId, ThreadId, TurnId } from "@t3tools/contracts";import { Option, Schema, ServiceMap } from "effect";import type { Effect } from "effect";@@ -33,22 +41,44 @@ export const ListProjectionThreadsByProjectInput = Schema.Struct({});export type ListProjectionThreadsByProjectInput = typeof ListProjectionThreadsByProjectInput.Type;+/**+ * ProjectionThreadRepositoryShape - Service API for projected thread records.+ */export interface ProjectionThreadRepositoryShape {+ /**+ * Insert or replace a projected thread row.+ *+ * Upserts by `threadId`.+ */readonly upsert: (thread: ProjectionThread) => Effect.Effect<void, ProjectionRepositoryError>;+ /**+ * Read a projected thread row by id.+ */readonly getById: (input: GetProjectionThreadInput,) => Effect.Effect<Option.Option<ProjectionThread>, ProjectionRepositoryError>;+ /**+ * List projected threads for a project.+ *+ * Returned in deterministic creation order.+ */readonly listByProjectId: (input: ListProjectionThreadsByProjectInput,) => Effect.Effect<ReadonlyArray<ProjectionThread>, ProjectionRepositoryError>;+ /**+ * Soft-delete a projected thread row by id.+ */readonly deleteById: (input: DeleteProjectionThreadInput,) => Effect.Effect<void, ProjectionRepositoryError>;}+/**+ * ProjectionThreadRepository - Service tag for thread projection persistence.+ */export class ProjectionThreadRepository extends ServiceMap.Service<ProjectionThreadRepository,ProjectionThreadRepositoryShapediff --git a/apps/server/src/persistence/Services/ProviderSessionRuntime.ts b/apps/server/src/persistence/Services/ProviderSessionRuntime.tsindex 8cf2bc465..77ad0ff69 100644--- a/apps/server/src/persistence/Services/ProviderSessionRuntime.ts+++ b/apps/server/src/persistence/Services/ProviderSessionRuntime.ts@@ -1,3 +1,10 @@+/**+ * ProviderSessionRuntimeRepository - Repository interface for provider runtime sessions.+ *+ * Owns persistence operations for provider runtime metadata and resume cursors.+ *+ * @module ProviderSessionRuntimeRepository+ */import {IsoDateTime,ProviderSessionId,@@ -33,25 +40,47 @@ export const DeleteProviderSessionRuntimeInput = Schema.Struct({});export type DeleteProviderSessionRuntimeInput = typeof DeleteProviderSessionRuntimeInput.Type;+/**+ * ProviderSessionRuntimeRepositoryShape - Service API for provider runtime records.+ */export interface ProviderSessionRuntimeRepositoryShape {+ /**+ * Insert or replace a provider runtime row.+ *+ * Upserts by `providerSessionId`, including JSON payload/cursor fields.+ */readonly upsert: (runtime: ProviderSessionRuntime,) => Effect.Effect<void, ProviderSessionRuntimeRepositoryError>;+ /**+ * Read provider runtime state by provider session id.+ */readonly getBySessionId: (input: GetProviderSessionRuntimeInput,) => Effect.Effect<Option.Option<ProviderSessionRuntime>, ProviderSessionRuntimeRepositoryError>;+ /**+ * List all provider runtime rows.+ *+ * Returned in ascending last-seen order.+ */readonly list: () => Effect.Effect<ReadonlyArray<ProviderSessionRuntime>,ProviderSessionRuntimeRepositoryError>;+ /**+ * Delete provider runtime state by provider session id.+ */readonly deleteBySessionId: (input: DeleteProviderSessionRuntimeInput,) => Effect.Effect<void, ProviderSessionRuntimeRepositoryError>;}+/**+ * ProviderSessionRuntimeRepository - Service tag for provider runtime persistence.+ */export class ProviderSessionRuntimeRepository extends ServiceMap.Service<ProviderSessionRuntimeRepository,ProviderSessionRuntimeRepositoryShapediff --git a/apps/server/src/persistence/Services/ProviderSessions.ts b/apps/server/src/persistence/Services/ProviderSessions.tsindex 445c63bc0..54c34e434 100644--- a/apps/server/src/persistence/Services/ProviderSessions.ts+++ b/apps/server/src/persistence/Services/ProviderSessions.ts@@ -1,3 +1,11 @@+/**+ * ProviderSessionRepository - Repository interface for provider session lookup.+ *+ * Owns persistence operations that map internal sessions to provider kinds and+ * optional thread ownership.+ *+ * @module ProviderSessionRepository+ */import type { ProviderKind, ProviderSessionId, ThreadId } from "@t3tools/contracts";import { Option, ServiceMap } from "effect";import type { Effect } from "effect";@@ -26,25 +34,47 @@ export interface GetProviderSessionInput {readonly sessionId: ProviderSessionId;}+/**+ * ProviderSessionRepositoryShape - Service API for provider-session records.+ */export interface ProviderSessionRepositoryShape {+ /**+ * Insert or replace a provider-session row.+ *+ * Upserts by `sessionId`.+ */readonly upsertSession: (input: UpsertProviderSessionInput,) => Effect.Effect<void, ProviderSessionRepositoryError>;+ /**+ * Read a provider-session row by session id.+ */readonly getSession: (input: GetProviderSessionInput,) => Effect.Effect<Option.Option<ProviderSessionEntry>, ProviderSessionRepositoryError>;+ /**+ * List all provider-session rows.+ *+ * Returned in deterministic creation order.+ */readonly listSessions: () => Effect.Effect<ReadonlyArray<ProviderSessionEntry>,ProviderSessionRepositoryError>;+ /**+ * Delete a provider-session row by session id.+ */readonly deleteSession: (input: DeleteProviderSessionInput,) => Effect.Effect<void, ProviderSessionRepositoryError>;}+/**+ * ProviderSessionRepository - Service tag for provider-session persistence.+ */export class ProviderSessionRepository extends ServiceMap.Service<ProviderSessionRepository,ProviderSessionRepositoryShapediff --git a/apps/server/src/provider/Errors.ts b/apps/server/src/provider/Errors.tsindex 3ba38d995..a3d29f77c 100644--- a/apps/server/src/provider/Errors.ts+++ b/apps/server/src/provider/Errors.ts@@ -51,23 +51,6 @@ export class ProviderAdapterSessionClosedError extends Schema.TaggedErrorClass<P}}-/**- * ProviderAdapterProtocolError - Invalid/unexpected provider protocol payload.- */-export class ProviderAdapterProtocolError extends Schema.TaggedErrorClass<ProviderAdapterProtocolError>()(- "ProviderAdapterProtocolError",- {- provider: Schema.String,- operation: Schema.String,- detail: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Provider adapter protocol error (${this.provider}) in ${this.operation}: ${this.detail}`;- }-}-/*** ProviderAdapterRequestError - Provider protocol request failed or timed out.*/@@ -164,61 +147,10 @@ export class ProviderSessionDirectoryPersistenceError extends Schema.TaggedError}}-/**- * ProviderCheckpointUnavailableError - Checkpointing unavailable for this session.- */-export class ProviderCheckpointUnavailableError extends Schema.TaggedErrorClass<ProviderCheckpointUnavailableError>()(- "ProviderCheckpointUnavailableError",- {- sessionId: Schema.String,- detail: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Provider checkpoint unavailable for session ${this.sessionId}: ${this.detail}`;- }-}--/**- * ProviderCheckpointRangeError - Requested checkpoint range is invalid.- */-export class ProviderCheckpointRangeError extends Schema.TaggedErrorClass<ProviderCheckpointRangeError>()(- "ProviderCheckpointRangeError",- {- sessionId: Schema.String,- fromTurnCount: Schema.Number,- toTurnCount: Schema.Number,- detail: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Provider checkpoint range error for session ${this.sessionId}: ${this.fromTurnCount}..${this.toTurnCount} (${this.detail})`;- }-}--/**- * ProviderFilesystemError - Filesystem checkpoint capture/restore failure.- */-export class ProviderFilesystemError extends Schema.TaggedErrorClass<ProviderFilesystemError>()(- "ProviderFilesystemError",- {- sessionId: Schema.String,- detail: Schema.String,- cause: Schema.optional(Schema.Defect),- },-) {- override get message(): string {- return `Provider filesystem checkpoint error for session ${this.sessionId}: ${this.detail}`;- }-}-export type ProviderAdapterError =| ProviderAdapterValidationError| ProviderAdapterSessionNotFoundError| ProviderAdapterSessionClosedError- | ProviderAdapterProtocolError| ProviderAdapterRequestError| ProviderAdapterProcessError;@@ -227,8 +159,5 @@ export type ProviderServiceError =| ProviderUnsupportedError| ProviderSessionNotFoundError| ProviderSessionDirectoryPersistenceError- | ProviderCheckpointUnavailableError- | ProviderCheckpointRangeError- | ProviderFilesystemError| ProviderAdapterError| CheckpointServiceError;diff --git a/apps/server/src/provider/Services/CodexAdapter.ts b/apps/server/src/provider/Services/CodexAdapter.tsindex 2c33eabb7..9eac2c994 100644--- a/apps/server/src/provider/Services/CodexAdapter.ts+++ b/apps/server/src/provider/Services/CodexAdapter.ts@@ -15,6 +15,9 @@ import { ServiceMap } from "effect";import type { ProviderAdapterError } from "../Errors.ts";import type { ProviderAdapterShape } from "./ProviderAdapter.ts";+/**+ * CodexAdapterShape - Service API for the Codex provider adapter.+ */export interface CodexAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {readonly provider: "codex";}diff --git a/apps/server/src/provider/Services/ProviderAdapterRegistry.ts b/apps/server/src/provider/Services/ProviderAdapterRegistry.tsindex 420086a7c..5591742ae 100644--- a/apps/server/src/provider/Services/ProviderAdapterRegistry.ts+++ b/apps/server/src/provider/Services/ProviderAdapterRegistry.ts@@ -14,6 +14,9 @@ import type { Effect } from "effect";import type { ProviderAdapterError, ProviderUnsupportedError } from "../Errors.ts";import type { ProviderAdapterShape } from "./ProviderAdapter.ts";+/**+ * ProviderAdapterRegistryShape - Service API for adapter lookup by provider kind.+ */export interface ProviderAdapterRegistryShape {/*** Resolve the adapter for a provider kind.diff --git a/apps/server/src/provider/Services/ProviderService.ts b/apps/server/src/provider/Services/ProviderService.tsindex d704b7be1..cbe45fe6a 100644--- a/apps/server/src/provider/Services/ProviderService.ts+++ b/apps/server/src/provider/Services/ProviderService.ts@@ -28,6 +28,9 @@ import type { Effect, Stream } from "effect";import type { ProviderServiceError } from "../Errors.ts";+/**+ * ProviderServiceShape - Service API for provider session and turn orchestration.+ */export interface ProviderServiceShape {/*** Start a provider session.@@ -67,6 +70,8 @@ export interface ProviderServiceShape {/*** List active provider sessions.+ *+ * Aggregates runtime session lists from all registered adapters.*/readonly listSessions: () => Effect.Effect<ReadonlyArray<ProviderSession>>;@@ -83,6 +88,8 @@ export interface ProviderServiceShape {** Persisted session bindings remain so stale sessions can be resumed after* process restart.+ *+ * Runtime alias mappings are cleared as part of shutdown.*/readonly stopAll: () => Effect.Effect<void, ProviderServiceError>;diff --git a/apps/server/src/provider/Services/ProviderSessionDirectory.ts b/apps/server/src/provider/Services/ProviderSessionDirectory.tsindex af04a38aa..2d3c23976 100644--- a/apps/server/src/provider/Services/ProviderSessionDirectory.ts+++ b/apps/server/src/provider/Services/ProviderSessionDirectory.ts@@ -42,9 +42,15 @@ export type ProviderSessionDirectoryWriteError =| ProviderValidationError| ProviderSessionDirectoryPersistenceError;+/**+ * ProviderSessionDirectoryShape - Service API for provider session ownership metadata.+ */export interface ProviderSessionDirectoryShape {/*** Record or update ownership for one provider session.+ *+ * Preserves existing persisted fields when omitted and shallow-merges+ * runtime payload objects.*/readonly upsert: (binding: ProviderSessionBinding,diff --git a/apps/server/src/terminal/Services/Manager.ts b/apps/server/src/terminal/Services/Manager.tsindex 94c757d5a..22cbd4ecc 100644--- a/apps/server/src/terminal/Services/Manager.ts+++ b/apps/server/src/terminal/Services/Manager.ts@@ -1,3 +1,11 @@+/**+ * TerminalManager - Terminal session orchestration service interface.+ *+ * Owns terminal lifecycle operations, output fanout, and session state+ * transitions for thread-scoped terminals.+ *+ * @module TerminalManager+ */import {TerminalClearInput,TerminalCloseInput,@@ -40,17 +48,61 @@ export interface TerminalStartInput extends TerminalOpenInput {rows: number;}+/**+ * TerminalManagerShape - Service API for terminal session lifecycle operations.+ */export interface TerminalManagerShape {+ /**+ * Open or attach to a terminal session.+ *+ * Reuses an existing session for the same thread/terminal id and restores+ * persisted history on first open.+ */readonly open: (input: TerminalOpenInput) => Effect.Effect<TerminalSessionSnapshot, unknown>;++ /**+ * Write input bytes to a terminal session.+ */readonly write: (input: TerminalWriteInput) => Effect.Effect<void, unknown>;++ /**+ * Resize the PTY backing a terminal session.+ */readonly resize: (input: TerminalResizeInput) => Effect.Effect<void, unknown>;++ /**+ * Clear terminal output history.+ */readonly clear: (input: TerminalClearInput) => Effect.Effect<void, unknown>;++ /**+ * Restart a terminal session in place.+ *+ * Always resets history before spawning the new process.+ */readonly restart: (input: TerminalOpenInput) => Effect.Effect<TerminalSessionSnapshot, unknown>;++ /**+ * Close an active terminal session.+ *+ * When `terminalId` is omitted, closes all sessions for the thread.+ */readonly close: (input: TerminalCloseInput) => Effect.Effect<void, unknown>;++ /**+ * Subscribe to terminal runtime events.+ */readonly subscribe: (listener: (event: TerminalEvent) => void) => Effect.Effect<() => void>;++ /**+ * Dispose all managed terminal resources.+ */readonly dispose: () => Effect.Effect<void>;}+/**+ * TerminalManager - Service tag for terminal session orchestration.+ */export class TerminalManager extends ServiceMap.Service<TerminalManager, TerminalManagerShape>()("terminal/TerminalManager",) {}diff --git a/apps/server/src/terminal/Services/PTY.ts b/apps/server/src/terminal/Services/PTY.tsindex 1ab7fc55c..ca9e51ea0 100644--- a/apps/server/src/terminal/Services/PTY.ts+++ b/apps/server/src/terminal/Services/PTY.ts@@ -1,3 +1,11 @@+/**+ * PtyAdapter - Terminal PTY adapter service contract.+ *+ * Defines the process primitives required by terminal session management+ * without binding to a specific PTY implementation.+ *+ * @module PtyAdapter+ */import { ServiceMap } from "effect";export interface PtyExitEvent {@@ -23,10 +31,19 @@ export interface PtySpawnInput {env: NodeJS.ProcessEnv;}+/**+ * PtyAdapterShape - Service API for spawning and controlling PTY processes.+ */export interface PtyAdapterShape {+ /**+ * Spawn a PTY process for a terminal session.+ */spawn(input: PtySpawnInput): PtyProcess;}+/**+ * PtyAdapter - Service tag for PTY process integration.+ */export class PtyAdapter extends ServiceMap.Service<PtyAdapter, PtyAdapterShape>()("terminal/PtyAdapter",) {}diff --git a/apps/server/src/wsServer.ts b/apps/server/src/wsServer.tsindex ed61fe39e..eb825f020 100644--- a/apps/server/src/wsServer.ts+++ b/apps/server/src/wsServer.ts@@ -1,3 +1,11 @@+/**+ * Server - HTTP/WebSocket server service interface.+ *+ * Owns startup and shutdown lifecycle of the HTTP server, static asset serving,+ * and WebSocket request routing.+ *+ * @module Server+ */import fs from "node:fs";import http from "node:http";import path from "node:path";@@ -49,15 +57,28 @@ const MIME_TYPES: Record<string, string> = {".map": "application/json",};+/**+ * ServerShape - Service API for server lifecycle control.+ */export interface ServerShape {+ /**+ * Start HTTP and WebSocket listeners.+ */readonly start: Effect.Effect<http.Server,unknown,Scope.Scope | ServerRuntimeServices | ServerConfig>;++ /**+ * Wait for process shutdown signals.+ */readonly stopSignal: Effect.Effect<unknown, never>;}+/**+ * Server - Service tag for HTTP/WebSocket lifecycle management.+ */export class Server extends ServiceMap.Service<Server, ServerShape>()("server/Server") {}const isServerNotRunningError = (error: unknown): boolean => {