docs(effect): fix Effect v4 samples and add runtime notes

[dinwwwh]

Fixes the Effect integration docs and the JSDoc in packages/effect/src/context.ts before @orpc/experimental-effect goes stable.

Changes

• OpenTelemetry: the sample imported Tracer from @effect/opentelemetry, which doesn't exist in 4.x. It now uses OtelTracer.layerGlobal, which needs no Resource layer. The tracer goes into the layer behind effect/context instead of Effect.provide(Layer) in effect/wrap. The old way rebuilt the layer for every middlewareGen and handlerGen (measured: 6 builds for 2 requests with 2 middlewares and a handler, against 1 build with a ManagedRuntime).
• Warning against providing layers in effect/wrap, for the same reason.
• Style, following Effect's guide: return yield* Effect.fail(...), and Clock.currentTimeMillis instead of Date.now() in Effect.sync.
• Short notes on:
  • .effect on implement(contract);
  • interruption: aborted requests run finalizers, and handlers need Effect.scoped for acquireRelease;
  • Cloudflare Workers: MixedScheduler('sync'), runtime created at module scope;
  • Next.js: unstable_rethrow inside catchCause.
• JSDoc: the effect/context and effect/wrap examples now type-check.

Not changed

• The Error Handling effect/wrap example still has an empty catchCause body. The effect/wrap rework on claude/festive-ride-65hat8 fixes it. That branch also rewrites the OpenTelemetry section and the effect/wrap JSDoc, so expect a conflict there.
• The Effect Schema section is unchanged.

Verification

• Every changed sample type-checks against effect 4.0.5, @effect/opentelemetry 4.0.5 and next 16.4.2, using temporary *.test-d.ts files that I deleted afterwards.
• I checked the runtime behavior the notes describe in throwaway tests: layer build counts, finalizers running on abort, the scheduler arriving through effect/context, Effect spans nesting under oRPC's spans, and unstable_rethrow letting redirect() through.
• pnpm docs:validate, pnpm vitest run packages/effect and tsc pass.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	orpc	57b95b2	Commit Preview URL Branch Preview URL	Oct 17 2026, 02:33 AM

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/@orpc/ai-sdk@2260

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@2260

@orpc/bun

npm i https://pkg.pr.new/@orpc/bun@2260

@orpc/client

npm i https://pkg.pr.new/@orpc/client@2260

@orpc/cloudflare

npm i https://pkg.pr.new/@orpc/cloudflare@2260

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@2260

@orpc/experimental-effect

npm i https://pkg.pr.new/@orpc/experimental-effect@2260

@orpc/evlog

npm i https://pkg.pr.new/@orpc/evlog@2260

@orpc/hibernation

npm i https://pkg.pr.new/@orpc/hibernation@2260

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@2260

@orpc/experimental-lock

npm i https://pkg.pr.new/@orpc/experimental-lock@2260

@orpc/experimental-msw

npm i https://pkg.pr.new/@orpc/experimental-msw@2260

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@2260

@orpc/next

npm i https://pkg.pr.new/@orpc/next@2260

@orpc/node

npm i https://pkg.pr.new/@orpc/node@2260

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@2260

@orpc/opentelemetry

npm i https://pkg.pr.new/@orpc/opentelemetry@2260

@orpc/pinia-colada

npm i https://pkg.pr.new/@orpc/pinia-colada@2260

@orpc/pino

npm i https://pkg.pr.new/@orpc/pino@2260

@orpc/publisher

npm i https://pkg.pr.new/@orpc/publisher@2260

@orpc/ratelimit

npm i https://pkg.pr.new/@orpc/ratelimit@2260

@orpc/server

npm i https://pkg.pr.new/@orpc/server@2260

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@2260

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@2260

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@2260

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@2260

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@2260

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@2260

commit: 57b95b2

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pullfrog]

✅ No new issues found.

Reviewed changes — full diff (5 commits), docs-only: the Effect integration guide and the WithEffectContext JSDoc.

• OpenTelemetry sample (v4 fix): replaced the non-existent Tracer import with OtelTracer.layerGlobal on the runtime layer, passed as effect/context. Verified against @effect/opentelemetry@4.0.2 — OtelTracer.layerGlobal installs the Effect Tracer.Tracer via layerGlobalTracer and needs no Resource layer; the package root exports no Tracer namespace.
• effect/wrap guidance: new warning plus JSDoc note that the hook runs per middlewareGen/handlerGen (confirmed at packages/effect/src/handler.ts:48 and packages/effect/src/middleware.ts:73), so layers should be provided via effect/context.
• New notes: .effect on implement(contract) (backed by ProcedureImplementer.prototype.effect), Interruption (Effect.scoped for acquireRelease), Cloudflare Workers (Scheduler.MixedScheduler('sync') + module-scope runtime), Next.js (unstable_rethrow inside catchCause).
• Style: return yield* Effect.fail(...), Clock.currentTimeMillis in middlewareGen, Effect.sync(() => Math.random()).
• JSDoc: effect/context and effect/wrap examples now type-check; @see backlink titles match the checker's expected format and the #error-handling anchor resolves.

Every changed API usage was validated against the installed effect@4.0.2 and the published @effect/opentelemetry@4.0.2 source (Context.Service class form, Context.empty()/Context.add currying, Effect.withSpan data-last, Clock.currentTimeMillis, Scheduler.MixedScheduler('sync'), ManagedRuntime.context() returning a Promise). No stale references to the removed Tracer import remain.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[codspeed]

Merging this PR will not alter performance

⚠️ 5 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• not modified (304)
• serve file
• range request
• serve deeply nested encoded path
• not found fall through

✅ 28 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/hopeful-fermat-j5se25 (57b95b2) with main (0358bf8)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩