🤖 feat: Effect + oRPC integration spike (oRPC 1.14, effect v4-rc, handlerGen bridge)

[ThomasK33]

Summary

Spike evaluating progressive Effect adoption anchored on the oRPC layer, plus the dependency upgrades it forces. The Effect ↔ oRPC bridge (@orpc/experimental-effect) is wired into ORPCContext, one real leaf service (MemoryMetaService) and one real procedure chain (memory.setPinned) are converted to Effect.gen, and a validation namespace (effectSpike.*) proves typed error propagation, Effect Schema inputs, and abort-driven cancellation with exactly-once scope finalizers. Full findings + phased adoption plan: rfc/20260831_effect-orpc-spike.md.

Warning

Spike caveat, per the RFC's own recommendation: this PR adds effect@4.0.0-rc.112 (a pre-stable RC) as a production dependency and carries a local trpc-cli compatibility patch (no released trpc-cli supports oRPC 1.14). Merging adopts those risks on main; the conservative alternative is to land the oRPC 1.14 migration alone and hold the Effect bridge until v4 stabilizes. Merge-on-green was explicitly requested by @ThomasK33.

Background

We want typed error channels, structured concurrency (cancellation + resource scoping), and dependency-injected services for backend code. oRPC ships an official-but-experimental Effect integration; this spike answers whether it fits xum's existing router/context architecture and what incremental adoption would look like. Findings validated by tests in src/node/orpc/effectSpike.test.ts.

Dependency upgrades

Change	Why
@orpc/{client,server,openapi,zod} ^1.11/^1.12 → 1.14.11	@orpc/experimental-effect exact-pins its oRPC deps at 1.14.11; mixed versions ship duplicate classes and break instanceof ORPCError
@orpc/experimental-effect@1.14.11 (new)	The Effect bridge under evaluation (~40-line runtime; handlerGen, WithEffectContext, toStandardSchema)
effect@4.0.0-rc.112 (new)	Peer requirement of the bridge (>=4.0.0-beta.90); v3 stable is not supported
patches/trpc-cli@0.12.1.patch (new)	oRPC 1.14 removed isProcedure/traverseContractProcedures, which every released trpc-cli uses — xum api would crash at startup. Patch adds a local router walk, duck-typed procedure detection, and 1.14 def-shape shims (inputSchemas[])

oRPC 1.12→1.14 app migration included: @orpc/server/ws→/websocket, @orpc/zod/zod4→@orpc/zod, client fetch links split url into origin + path-only url, websocket links take connect: () => ws, OpenAPIGenerator converters/base options, ValidationError.invalidData, removed ORPCError.status (now derived from COMMON_ERROR_STATUS_MAP), instanceof Procedure, and createAuthMiddleware collapsed to a single typed middleware (1.14 .use() rejects unions of differently-typed middlewares).

Implementation

• Bridge wiring: ORPCContext extends WithEffectContext<OrpcEffectServices>; ServiceContainer.toORPCContext() pre-builds the Effect service Context under "effect/context" (src/node/orpc/effectContext.ts). Handlers opt in per-procedure via handlerGen (no global Builder.prototype patching); async handlers coexist untouched.
• Leaf-service conversion pattern: MemoryMetaService internals are Effect.gen with an Effect Semaphore write lock (interruption-safe) and a Schema.TaggedError (MemoryMetaWriteError) failure channel — behind an unchanged Promise facade, so all pre-existing callers and tests work unmodified.
• Real procedure conversion: memory.setPinned → setMemoryPinnedEffect (Effect.gen; Effect.result/Effect.try replace try/catch; typed write failures map into the existing ResultSchema string error). Wire contract unchanged.
• Validation namespace effectSpike.*: service injection via Effect context, Effect Schema input (toStandardSchema) coexisting with Zod outputs, Schema.TaggedError → defined oRPC error (.errors() map + catchTag, no untyped catch), scoped hold with acquire/release probe, and an async-vs-effect echo pair for overhead measurement (~3.4µs/call Effect overhead).

Validation

• 7 new spike tests prove the headline claims: typed error round-trip with defined: true + schema-validated data; client abort interrupts the handler fiber promptly with the release finalizer running exactly once; Effect Schema inputs reject bad payloads as BAD_REQUEST.
• Existing suites green after both the 1.14 migration and the Effect conversion: src/node/orpc/* (62), memoryMeta/memoryOperations, cli.test.ts/server.test.ts (31, exercising the patched trpc-cli end-to-end) — 125 pass / 3 skip / 0 fail.
• make typecheck green on both tsconfigs; ESLint + prettier clean on touched files.
• tests/ipc/streaming/queuedMessages.test.ts determinism fix (CI Test / Integration): oRPC 1.14's in-process iterator delivers queued-message-changed before the sendMessage promise resolves, so the suite's count-snapshot helper (wait for the next NEW event) already contained the queued event and observed the later drain [] instead — failing all 8 tests deterministically on this branch (confirmed via event-history dump: [[], ["Say 'SECOND'..."], []]). Replaced count-snapshot waits with predicate-based history scans (queued assertions) and latest-state convergence (drain waits). 2× 8/8 green locally against the live API. Supersedes the 🤖 tests: queuedMessages integration suite fails on unmodified main (queued-message-changed never observed) #4023 triage — that issue's "fails on unmodified main" local repro was contaminated by a provider-auth env issue.

Risks

• Effect v4 RC churn (medium): APIs may shift before v4 stable; confined to MemoryMetaService, memory.setPinned, and the spike namespace — all revertible without wire-contract changes.
• oRPC 1.14 behavioral surface (medium): the upgrade touches every RPC link (HTTP/WS, browser/CLI/ACP) and the OpenAPI generator. Covered by existing server/CLI/analytics tests, but transport edge cases (proxy prefixes, WS reconnects) get their real soak only in use.
• trpc-cli patch (low): local patch must be maintained until upstream supports oRPC 1.14; cli.test.ts covers the patched paths.
• memory.setPinned failure mode change (low, intentional): sidecar write failures now return {success:false, error} instead of an untyped INTERNAL_SERVER_ERROR rejection.

---

📋 Spike findings RFC (rfc/20260831_effect-orpc-spike.md)

---

author: @mux
date: 2026-08-31

---

Spike Findings: Progressive Effect Migration via oRPC Integration

Status: Spike report (branch effect-orpc-spike, not intended to merge as-is)

Objective

Evaluate a progressive migration of xum's backend to Effect,
anchored on the existing oRPC layer:

1. Wire @orpc/experimental-effect into the oRPC context/router.
2. Convert a representative leaf, I/O-heavy service and its procedures to Effect.gen.
3. Validate Schema.TaggedError → typed oRPC error propagation without untyped catch blocks.
4. Evaluate resource scoping (Scope/finalizers) and cancellation for long-lived operations.
5. Recommend an incremental adoption architecture.

Everything below was validated by code in this branch (src/node/orpc/effectSpike.ts,
src/node/orpc/effectSpike.test.ts, converted MemoryMetaService/setMemoryPinned),
with all affected suites green: 128 tests across oRPC/memory/CLI files plus 7 new spike tests.

TL;DR

• The integration works and is remarkably small. @orpc/experimental-effect is a
  ~40-line runtime bridge: handlers become generators that yield* Effects, services are
  injected via a pre-built Context on the oRPC context, AbortSignal maps to fiber
  interruption, and ORPCError instances in the failure channel become typed, defined
  oRPC errors. Typed error propagation, scoped finalizers under client aborts, and Effect
  Schema inputs all behave exactly as advertised.
• The version prerequisites are the real cost. The official package requires
  Effect v4 (currently RC) and pins oRPC 1.14.x exactly. Migrating xum from oRPC
  1.12→1.14 was bounded (~12 files, this branch did it) but breaks trpc-cli's oRPC
  support (fixed here with a bun patch). Effect v4 RC is pre-stable.
• Overhead is negligible for xum's workloads: ~3–4µs per call added by the Effect
  runtime on a no-op procedure (in-process router client, Bun; 8.8µs/call async vs
  12.2µs/call Effect). Any real I/O dwarfs this.
• Recommendation: adopt in narrow slices, gated on Effect v4 stable. The
  service-internal conversion pattern (Effect core + thin Promise facade) is immediately
  usable and low-risk; the oRPC bridge layer is a one-file change once versions align. If
  we want to start before v4 stabilizes, a hand-rolled handlerGen (the bridge is ~40
  lines, MIT) against stable Effect 3.x is a viable interim path.

What was built

1. Bridge wiring (objective 1)

• ORPCContext now extends WithEffectContext<OrpcEffectServices>: one well-known key,
  "effect/context", carrying a pre-built Context.Context of Effect services
  (src/node/orpc/effectContext.ts, built in ServiceContainer.toORPCContext()).
• Handlers use handlerGen directly (.handler(handlerGen(function* ({ context, errors, signal }, input) { ... }))).
  The .effect() builder sugar exists but requires a side-effect import that patches
  Builder.prototype globally; handlerGen has zero global footprint and was preferred.
• The optional "effect/wrap" hook wraps every Effect handler per request with
  { path, procedure, signal } — the natural future seam for tracing/metrics
  (@effect/opentelemetry) without touching individual handlers.

2. Leaf service conversion (objective 2)

MemoryMetaService (host-local JSON sidecar; pure disk I/O, one write lock) was converted:

• Internals are Effect.gen; the promise MutexMap became an Effect Semaphore, so lock
  acquisition participates in interruption (a fiber cancelled while waiting never runs its
  critical section — a real correctness upgrade over the promise mutex).
• The public API is preserved by a thin Promise facade (Effect.runPromise per method)
  plus a new Effect-native effects surface for migrated callers. All 12 pre-existing
  service tests pass unchanged — the facade pattern demonstrably de-risks conversion.
• One real procedure chain was converted end-to-end: memory.setPinned →
  setMemoryPinnedEffect (Effect.gen with Effect.result/Effect.try replacing try/catch)
  → handlerGen in the router. The zod wire contract is untouched.

3. Typed errors (objective 3)

MemoryMetaWriteError is a Schema.TaggedError — simultaneously an Error subclass, a
schema, a tagged-union member, and yieldable. The spike procedure declares
.errors({ MEMORY_META_WRITE_FAILED: { data: z.object({ metaPath, reason }) } }) and maps:

yield *
  memoryMeta.effects
    .setPinned(key, pinned)
    .pipe(
      Effect.catchTag("MemoryMetaWriteError", (e) =>
        Effect.fail(
          errors.MEMORY_META_WRITE_FAILED({
            data: { metaPath: e.metaPath, reason: e.reason },
          }),
        ),
      ),
    );

Validated: the client receives ORPCError with code: "MEMORY_META_WRITE_FAILED",
defined: true, and schema-validated data. No untyped catch anywhere on the path — the
failure is typed from writeFileAtomic all the way to the wire.

Caveat found: the bridge's types do not force exhaustive error handling. Yielded
effects may carry any E; only ORPCError members become typed returns, and everything
else silently remains a runtime throw (squashed cause), exactly like today's untyped
rejections. Exhaustiveness is opt-in: teams must adopt a convention (or a lint) that
handler-yielded effects satisfy E extends AnyORPCError | never. Worth building a tiny
yieldStrict helper or ESLint rule during real adoption.

4. Scoping + cancellation (objective 4)

effectSpike.scopedHold acquires a resource with Effect.acquireRelease inside
Effect.scoped and sleeps. Validated by test:

• Client AbortController.abort() interrupts the fiber promptly (60s hold aborted in
  <5s wall including test overhead; actual interruption is immediate).
• The release finalizer runs exactly once, both on abort and on normal completion.
• The bridge maps interruption back to the abort reason (options.signal.reason), so oRPC
  reports the abort exactly like an async handler would.

This is the headline win for xum: today's long-lived operations thread AbortSignal
manually through every layer (e.g. cloneWithProgress(input, signal)) and clean up in
ad-hoc try/finally. Structured concurrency makes "cancellation propagates + resources
release" the default instead of a per-call discipline. Prime future candidates:
routerSubscriptions.ts teardown, process spawns, MCP server lifecycles, stream managers.

5. Performance & ergonomics (objective 5)

• Micro-benchmark (in-process router client, 2k sequential calls each, warmed):
  no-op async handler ≈ 8.8µs/call; identical handlerGen handler ≈ 12.2µs/call;
  Effect runtime overhead ≈ 3.4µs/call. Noise-level for anything touching disk,
  network, or an LLM.
• Ergonomics that worked well: yield* reads like await; service tags double as
  Effects (const svc = yield* MemoryMeta); catchTag gives compiler-checked error
  narrowing; existing zod schemas coexist with Effect Schema inputs per-procedure
  (toStandardSchema), so there is no forced schema migration.
• Frictions: this is not available inside Effect.gen generators (self-alias needed,
  plus an eslint-disable for no-this-alias); sync throws inside generators become
  defects rather than typed failures (fine for ORPCError gates like
  assertMemoryEnabled, but a subtle trap); require-yield lint fires on yield-free
  generator handlers; Effect v4 renames significant v3 API (Effect.catch,
  Context.Service, Semaphore.make*, Effect.result/Result), so most public
  Effect v3 documentation and LLM training data does not directly apply.

Version compatibility findings (the hard constraints)

Constraint	Detail
@orpc/experimental-effect peer	effect >= 4.0.0-beta.90 — Effect v4 only (v4 is at RC today; v3 stable is not supported)
@orpc/experimental-effect deps	Exact-pinned @orpc/{server,shared,contract,json-schema}@1.14.11 — repo must move to oRPC 1.14 in lockstep or ship duplicate oRPC copies (breaks instanceof ORPCError and prototype patches; bun kept stale nested copies until a forced reinstall)
oRPC 1.12→1.14 breaks	@orpc/server/ws→/websocket; @orpc/zod/zod4→@orpc/zod; client links split url into origin + path-only url; websocket links take connect: () => ws; OpenAPIGenerator options (converters, base); ValidationError.data→invalidData; ORPCError.status removed; isProcedure/traverseContractProcedures removed (use instanceof Procedure); procedure defs store inputSchemas[] + orderedMiddlewares; .use() no longer accepts unions of differently-typed middlewares
Ecosystem fallout	No released trpc-cli (≤0.16.0) supports oRPC 1.14 — xum api would crash at startup. This branch carries a bun patch (patches/trpc-cli@0.12.1.patch: local router traversal + duck-typed isProcedure + def-shape shims). Upstreaming or replacing trpc-cli is a prerequisite for a real upgrade.
Package maturity	The experimental- prefix is explicit; v1 line exists (1.14.11) plus 2.0.0 betas tracking oRPC v2. API surface is tiny, so forking/vendoring is a realistic escape hatch.

Recommended incremental adoption architecture

Phased, each phase independently shippable and reversible:

Phase 0 — prerequisites (before any Effect code ships):
oRPC 1.14 upgrade as its own PR (this branch's first commit is that migration, validated);
resolve trpc-cli (upstream a 1.14-compat PR, keep the bun patch, or replace with a thin
custom CLI walker — we already own proxifyOrpc). Hold production Effect adoption until
Effect v4 stable unless we vendor a v3-compatible handlerGen (~40 lines).

Phase 1 — services adopt Effect internally (no oRPC coupling, can start anytime):
convert leaf, I/O-heavy services with the pattern proven here — Effect-native effects
surface + Promise facade, existing tests untouched. Best next candidates:
HistoryService (locks + atomic writes + self-healing reads), config stores,
workspaceFileLocks users. Each conversion upgrades error typing and interruption safety
without any caller changes.

Phase 2 — bridge layer on (one-file switch):
ORPCContext extends WithEffectContext<...> + ServiceContainer builds the service
Context (done in this branch). New/converted procedures use handlerGen; the rest stay
async. Both styles coexist indefinitely — this is the core progressive-migration property.

Phase 3 — typed errors at the wire:
migrate high-value procedures from ResultSchema({success:false,error:string}) toward
.errors() maps fed by Schema.TaggedError (isDefinedError gives clients typed
narrowing). Do this per-procedure; frontend consumes error.defined/error.data.
Adopt an exhaustiveness convention/lint for handler E channels (see caveat above).

Phase 4 — structured concurrency for long-lived ops:
move subscriptions (routerSubscriptions.ts), process spawns, and stream lifecycles onto
Scope/acquireRelease, replacing manual AbortSignal threading. Add an
"effect/wrap" hook for tracing/metrics across all Effect handlers.

Non-goals for now: full Layer-based dependency graph (ServiceContainer already does
this job; revisit only if service construction becomes Effect-native), Effect on the
renderer/browser side, and Effect Schema replacing zod wholesale (coexistence works).

Key risks

1. Effect v4 RC churn — APIs may still shift before stable; don't merge v4 to main yet.
2. Two mental models during migration — mitigated by the facade pattern (callers never
   see Effect until their own conversion) and by keeping handlerGen opt-in per procedure.
3. Untyped-failure escape hatch — the bridge tolerates non-ORPCError failures silently
   (runtime throw); needs a lint/convention to realize the "no untyped errors" promise.
4. Ecosystem lag on oRPC 1.14 (trpc-cli today; audit other oRPC-adjacent deps before
   upgrading main).

Validation record

• make typecheck green (both tsconfigs).
• bun test src/node/orpc/ src/node/services/memoryMeta.test.ts src/node/services/memoryOperations.test.ts src/cli/cli.test.ts src/cli/server.test.ts → 125 pass / 3 skip / 0 fail.
• bun test src/node/orpc/effectSpike.test.ts → 7/7: service injection, Effect Schema
  validation, typed error round-trip (success + failure with defined:true + data),
  abort-interruption with exactly-once finalizers, normal-completion finalizers, benchmark.
• ESLint clean on all touched files.

---

Generated with xum • Model: anthropic:claude-fable-5 • Thinking: xhigh • Cost: $35.81

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7fecd704ea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: a4c9d15356

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 48fca8634f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 65a2cd3d9a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 887674fa32

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 57f03bba0d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".