✨ Route reduction through api.Reducer middleware and export internals

Add api.Reducer as a middleware interception point for effect reduction,
enabling external packages (e.g., @effectionx/durably) to intercept
instruction processing without forking Effection.

Changes:
- lib/api.ts: Define ReducerApi interface and api.Reducer with createApi
- lib/coroutine.ts: Route reduce calls through reducerApi.invoke() instead
  of directly calling ReducerContext, using routine.scope for correct
  middleware chain resolution
- lib/scope-internal.ts: Install stock Reducer as base-layer api.Reducer
  middleware on the global scope
- experimental.ts: Export InstructionQueue, Instruction type, and
  DelimiterContext for custom reducer implementations
- lib/callcc.ts, lib/delimiter.ts, lib/each.ts, lib/future.ts,
  lib/scope-internal.ts: Add description labels to withResolvers() calls
  so custom reducers can distinguish infrastructure effects from
  user-facing effects

Author: Taras Mankovski

experimental.ts

@@ -1 +1,6 @@
 export * from "./lib/api.ts";
+export {
+  InstructionQueue,
+  type Instruction,
+} from "./lib/reducer.ts";
+export { DelimiterContext } from "./lib/delimiter.ts";

lib/api.ts

@@ -2,6 +2,7 @@
 import type { Api, Context, Operation, Scope } from "./types.ts";
 import { createApiInternal } from "./api-internal.ts";
 import type { ScopeInternal } from "./scope-internal.ts";
+import type { Instruction } from "./reducer.ts";
 
 export function createApi<A extends {}>(name: string, core: A): Api<A> {
   return createApiInternal(name, core);
@@ -18,9 +19,14 @@ interface MainApi {
   main(body: (args: string[]) => Operation<void>): Promise<void>;
 }
 
+interface ReducerApi {
+  reduce(instruction: Instruction): void;
+}
+
 interface Apis {
   Scope: Api<ScopeApi>;
   Main: Api<MainApi>;
+  Reducer: Api<ReducerApi>;
 }
 
 export const api: Apis = {
@@ -41,4 +47,9 @@ export const api: Apis = {
       throw new TypeError(`missing handler for "main()"`);
     },
   }),
+  Reducer: createApi<ReducerApi>("Reducer", {
+    reduce() {
+      throw new TypeError(`no handler for Reducer.reduce()`);
+    },
+  }),
 };

lib/callcc.ts

@@ -11,7 +11,7 @@ export function* callcc<T>(
     reject: (error: Error) => Operation<void>,
   ) => Operation<void>,
 ): Operation<T> {
-  let result = withResolvers<Result<T>>();
+  let result = withResolvers<Result<T>>("await callcc");
 
   let resolve = lift((value: T) => result.resolve(Ok(value)));
 

lib/coroutine.ts

@@ -1,9 +1,11 @@
+import { api as effection } from "./api.ts";
 import { Priority } from "./contexts.ts";
 import { DelimiterContext } from "./delimiter.ts";
-import { ReducerContext } from "./reducer.ts";
 import { Ok } from "./result.ts";
 import type { Coroutine, Operation, Scope } from "./types.ts";
 
+const reducerApi = effection.Reducer;
+
 export interface CoroutineOptions<T> {
   scope: Scope;
   operation(): Operation<T>;
@@ -12,8 +14,6 @@ export interface CoroutineOptions<T> {
 export function createCoroutine<T>(
   { operation, scope }: CoroutineOptions<T>,
 ): Coroutine<T> {
-  let reducer = scope.expect(ReducerContext);
-
   let iterator: Coroutine<T>["data"]["iterator"] | undefined = undefined;
 
   let routine = {
@@ -31,25 +31,25 @@ export function createCoroutine<T>(
     next(result) {
       routine.data.exit((exitResult) => {
         routine.data.exit = (didExit) => didExit(Ok());
-        reducer.reduce([
-          scope.expect(Priority),
+        reducerApi.invoke(routine.scope, "reduce", [[
+          routine.scope.expect(Priority),
           routine,
           exitResult.ok ? result : exitResult,
-          scope.expect(DelimiterContext).validator,
+          routine.scope.expect(DelimiterContext).validator,
           "next",
-        ]);
+        ]]);
       });
     },
     return(result) {
       routine.data.exit((exitResult) => {
         routine.data.exit = (didExit) => didExit(Ok());
-        reducer.reduce([
-          scope.expect(Priority),
+        reducerApi.invoke(routine.scope, "reduce", [[
+          routine.scope.expect(Priority),
           routine,
           exitResult.ok ? result : exitResult,
-          scope.expect(DelimiterContext).validator,
+          routine.scope.expect(DelimiterContext).validator,
           "return",
-        ]);
+        ]]);
       });
     },
   } as Coroutine<T>;

lib/delimiter.ts

@@ -10,7 +10,7 @@ export class Delimiter<T>
   implements Operation<Maybe<Result<T>>>, ErrorBoundary {
   level = 0;
   finalized = false;
-  future = withResolvers<Maybe<Result<T>>>();
+  future = withResolvers<Maybe<Result<T>>>("await delimiter");
   computed = false;
   routine?: Coroutine;
   outcome?: Maybe<Result<T>>;

lib/each.ts

@@ -37,8 +37,8 @@ export function each<T>(stream: Stream<T, unknown>): Operation<Iterable<T>> {
         scope.set(EachStack, []);
       }
 
-      let done = withResolvers<void>();
-      let cxt = withResolvers<EachLoop<T>>();
+      let done = withResolvers<void>("await each done");
+      let cxt = withResolvers<EachLoop<T>>("await each context");
 
       yield* spawn(function* () {
         let subscription = yield* stream;

lib/future.ts

@@ -9,7 +9,7 @@ export interface FutureWithResolvers<T> {
 }
 export function createFuture<T>(): FutureWithResolvers<T> {
   let promise = lazyPromiseWithResolvers<T>();
-  let operation = withResolvers<T>();
+  let operation = withResolvers<T>("await future");
 
   let resolve = (value: T) => {
     promise.resolve(value);

lib/reducer.ts

@@ -58,15 +58,15 @@ export class Reducer {
   };
 }
 
-type Instruction = [
+export type Instruction = [
   number,
   Coroutine<unknown>,
   Result<unknown>,
   () => boolean,
   "return" | "next",
 ];
 
-class InstructionQueue extends PriorityQueue<Instruction> {
+export class InstructionQueue extends PriorityQueue<Instruction> {
   enqueue(instruction: Instruction): void {
     let [priority] = instruction;
     this.push(priority, instruction);

lib/scope-internal.ts

@@ -1,12 +1,14 @@
 import type { ApiInternal } from "./api-internal.ts";
 import { api as effection } from "./api.ts";
 import { Children, Priority } from "./contexts.ts";
+import { Reducer } from "./reducer.ts";
 import { Err, Ok, unbox } from "./result.ts";
 import { createTask } from "./task.ts";
 import type { Context, Operation, Scope, Task } from "./types.ts";
 import { type WithResolvers, withResolvers } from "./with-resolvers.ts";
 
 const api = effection.Scope;
+const reducerApi = effection.Reducer;
 
 export function createScopeInternal(
   parent?: Scope,
@@ -18,6 +20,12 @@ export function createScopeInternal(
         return buildScopeInternal(parent);
       },
     }, { at: "min" });
+    let defaultReducer = new Reducer();
+    global.around(reducerApi, {
+      reduce([instruction]) {
+        defaultReducer.reduce(instruction);
+      },
+    }, { at: "min" });
     return [global, destroy] as const;
   } else {
     return api.invoke(parent, "create", [parent]) as [
@@ -133,7 +141,7 @@ export function buildScopeInternal(
       if (destruction) {
         return yield* destruction.operation;
       }
-      destruction = withResolvers<void>();
+      destruction = withResolvers<void>("await destruction");
       parent?.expect(Children).delete(scope);
       unbind();
       let outcome = Ok();