depa-actor 0.2.0 → 0.2.2

package/src/dispatch/ActorDispatchAdapter.ts

@@ -1,11 +1,32 @@
 /**
  * depa-actor — Dispatch Bridge
  *
- * Optional bridge to depa-processor DispatchEngine.
- * Only this file imports from depa-processor concepts.
- * No hard dependency — uses structural typing.
+ * Drives the depa-processor `DispatchEngine` (all 7 strategies) from the actor
+ * side. The envelope → DispatchRequest adaptation and the actor `tag` overlay
+ * live HERE, in depa-actor — the generic `DispatchEngine` / `DispatchStrategyConfig`
+ * stay free of any actor (`envelope` / `tag` / `ActorSelf`) knowledge.
+ *
+ * Two orthogonal axes:
+ *   1. `tag` — actor's first-level route (which mailbox). Selecting a handler by
+ *      tag is the actor system's job (`ActorDef.handlers[tag]`); a dispatch handler
+ *      built here is slotted UNDER a tag, so tag selection happens upstream.
+ *      `tag` is NOT a DispatchStrategyType — it is an orthogonal overlay dimension.
+ *   2. `strategy` — one of the 7 `DispatchStrategyType` values, used as the
+ *      second-level resolution within the selected tag.
  */
 
+import {
+  DispatchEngine,
+  DispatchStrategyConfig,
+  DispatchStrategyType,
+  createClassDispatchRequest,
+  createRouteKeyDispatchRequest,
+  createEnumDispatchRequest,
+  createRouteKeyToEnumDispatchRequest,
+  createCommandDispatchRequest,
+  createPathDispatchRequest,
+  createActionPathDispatchRequest,
+} from 'depa-processor';
 import type {
   MailboxSchema,
   ActorSelf,
@@ -13,71 +34,221 @@ import type {
   ActorHandler,
 } from '../core/types.js';
 
-// ─── DispatchRoute (structural, no import) ───────────────────────────
+// ─── Actor sub-handler ───────────────────────────────────────────────
 
 /**
- * A dispatch route maps a tag to a dispatch key and handler.
- * This is a structural interface — no dependency on depa-processor.
+ * A resolved actor sub-handler: receives `(self, envelope)` and performs side
+ * effects (write state / send messages). This is the `TResult = void | Promise<void>`
+ * shape the underlying DispatchEngine resolves to.
  */
-export interface DispatchRoute<
+export type ActorRouteHandler<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  envelope: ActorEnvelope<TSchema>,
+) => void | Promise<void>;
+
+// ─── Key extraction (envelope → dispatch coordinate) ─────────────────
+
+/**
+ * Maps an envelope to the dispatch coordinate consumed by the selected strategy.
+ * Defaults are provided per strategy; override to route by payload fields, etc.
+ */
+export interface DispatchKeyExtractors<TSchema extends MailboxSchema> {
+  /** ROUTE_KEY / ROUTE_KEY_TO_ENUM / COMMAND_TABLE — defaults to `envelope.tag`. */
+  routeKeyOf?: (envelope: ActorEnvelope<TSchema>) => string;
+  /** ENUM — defaults to `envelope.tag`. */
+  enumOf?: (envelope: ActorEnvelope<TSchema>) => string | number;
+  /** CLASS / key-based strategies' input — defaults to `envelope.payload`. */
+  inputOf?: (envelope: ActorEnvelope<TSchema>) => unknown;
+  /** PATH / ACTION_PATH — defaults to `envelope.tag`. */
+  pathOf?: (envelope: ActorEnvelope<TSchema>) => string;
+  /** ACTION_PATH action — defaults to `undefined`. */
+  actionOf?: (envelope: ActorEnvelope<TSchema>) => unknown;
+}
+
+// ─── createDispatchHandler params (object-param, B2 composable) ───────
+
+/**
+ * Parameters for {@link createDispatchHandler}.
+ *
+ * `routes` is either:
+ *  - a plain key → actor-sub-handler map (for the common key-based strategies
+ *    CLASS-by-key is not applicable; use ROUTE_KEY / ENUM / COMMAND_TABLE), or
+ *  - a fully-built `DispatchStrategyConfig<void | Promise<void>>` for advanced
+ *    strategies (PATH / ACTION_PATH / CLASS / ROUTE_KEY_TO_ENUM) where the
+ *    handler wiring is expressed in depa-processor terms.
+ *
+ * When a `DispatchStrategyConfig` is supplied, its handlers receive the raw
+ * dispatch `input` / `context` (already adapted from the envelope) and may
+ * close over `self` via the surrounding scope.
+ */
+export interface CreateDispatchHandlerParams<
   TRuntime,
   TSchema extends MailboxSchema,
   TState,
 > {
-  /** Which tags this route handles */
-  tags: (keyof TSchema & string)[];
-
-  /** Resolve dispatch key from envelope */
-  resolveKey: (envelope: ActorEnvelope<TSchema>) => string;
-
-  /** Route table: dispatch key → handler */
-  routes: Record<string, (
-    self: ActorSelf<TRuntime, TSchema, TState>,
-    envelope: ActorEnvelope<TSchema>,
-  ) => void | Promise<void>>;
-
-  /** Fallback if no route matches */
-  fallback?: (
-    self: ActorSelf<TRuntime, TSchema, TState>,
-    envelope: ActorEnvelope<TSchema>,
-    key: string,
-  ) => void | Promise<void>;
+  /** Which of the 7 strategies to use for second-level resolution. */
+  strategy: DispatchStrategyType;
+
+  /**
+   * Route table. For key-based strategies (ROUTE_KEY / ENUM / COMMAND_TABLE)
+   * pass a `Record<key, ActorRouteHandler>`. For advanced strategies, pass a
+   * prebuilt `DispatchStrategyConfig` whose `TResult = void | Promise<void>`.
+   */
+  routes:
+    | Record<string, ActorRouteHandler<TRuntime, TSchema, TState>>
+    | DispatchStrategyConfig<void | Promise<void>>;
+
+  /** Optional fallback when the strategy does not resolve a handler. */
+  defaultHandler?: ActorHandler<TRuntime, TSchema, TState>;
+
+  /** Optional envelope → dispatch-coordinate extractors. */
+  extractors?: DispatchKeyExtractors<TSchema>;
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────
+
+function isStrategyConfig(
+  routes: unknown,
+): routes is DispatchStrategyConfig<void | Promise<void>> {
+  return routes instanceof DispatchStrategyConfig;
+}
+
+/**
+ * Build a `DispatchStrategyConfig<void>` from a plain key → handler map for the
+ * supported key-based strategies. The map values are pre-bound to `(self, envelope)`
+ * by capturing the current dispatch's `self` / `envelope` via a thunk.
+ */
+function buildKeyBasedConfig<TRuntime, TSchema extends MailboxSchema, TState>(
+  strategy: DispatchStrategyType,
+  routes: Record<string, ActorRouteHandler<TRuntime, TSchema, TState>>,
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  envelope: ActorEnvelope<TSchema>,
+): DispatchStrategyConfig<void | Promise<void>> {
+  const handlerMap = new Map<
+    string | number,
+    (input: unknown) => void | Promise<void>
+  >();
+  for (const [key, handler] of Object.entries(routes)) {
+    handlerMap.set(key, () => handler(self, envelope));
+  }
+
+  switch (strategy) {
+    case DispatchStrategyType.ROUTE_KEY:
+      return DispatchStrategyConfig.forRouteKeyStrategy<void | Promise<void>>({
+        handlerMap: handlerMap as Map<string, (input: unknown) => void | Promise<void>>,
+      });
+    case DispatchStrategyType.ENUM:
+      return DispatchStrategyConfig.forEnumStrategy<void | Promise<void>>({
+        handlerMap,
+      });
+    case DispatchStrategyType.COMMAND_TABLE:
+      return DispatchStrategyConfig.forCommandStrategy<void | Promise<void>>({
+        commandConverter: (command: string) =>
+          handlerMap.has(command) ? command : null,
+        handlerExtractor: (commandEnum: string | number) =>
+          handlerMap.get(commandEnum) ?? null,
+      });
+    default:
+      throw new Error(
+        `createDispatchHandler: strategy ${strategy} requires a prebuilt ` +
+          `DispatchStrategyConfig in 'routes' (plain key→handler maps support ` +
+          `ROUTE_KEY / ENUM / COMMAND_TABLE only).`,
+      );
+  }
+}
+
+/** Build the strategy-appropriate DispatchRequest from the envelope. */
+function buildRequest<TSchema extends MailboxSchema>(
+  strategy: DispatchStrategyType,
+  envelope: ActorEnvelope<TSchema>,
+  extractors: DispatchKeyExtractors<TSchema> | undefined,
+) {
+  const input = extractors?.inputOf ? extractors.inputOf(envelope) : envelope.payload;
+  const routeKey = extractors?.routeKeyOf
+    ? extractors.routeKeyOf(envelope)
+    : envelope.tag;
+  const path = extractors?.pathOf ? extractors.pathOf(envelope) : envelope.tag;
+
+  switch (strategy) {
+    case DispatchStrategyType.CLASS:
+      return createClassDispatchRequest<void | Promise<void>>(input);
+    case DispatchStrategyType.ROUTE_KEY:
+      return createRouteKeyDispatchRequest<void | Promise<void>>(routeKey, input, false);
+    case DispatchStrategyType.ENUM:
+      return createEnumDispatchRequest<void | Promise<void>>(
+        extractors?.enumOf ? extractors.enumOf(envelope) : envelope.tag,
+        input,
+      );
+    case DispatchStrategyType.ROUTE_KEY_TO_ENUM:
+      return createRouteKeyToEnumDispatchRequest<void | Promise<void>>(routeKey, input);
+    case DispatchStrategyType.COMMAND_TABLE:
+      return createCommandDispatchRequest<void | Promise<void>>(routeKey, input);
+    case DispatchStrategyType.PATH:
+      return createPathDispatchRequest<void | Promise<void>, unknown, unknown>({
+        runtime: undefined,
+        request: input,
+        path,
+      });
+    case DispatchStrategyType.ACTION_PATH:
+      return createActionPathDispatchRequest<void | Promise<void>, unknown, unknown, unknown>({
+        runtime: undefined,
+        request: input,
+        action: extractors?.actionOf ? extractors.actionOf(envelope) : undefined,
+        path,
+      });
+    default:
+      throw new Error(`createDispatchHandler: unknown strategy ${String(strategy)}`);
+  }
 }
 
 // ─── createDispatchHandler ───────────────────────────────────────────
 
 /**
- * Creates an ActorHandler that routes envelopes through dispatch routes.
- * Falls back to `defaultHandler` for tags not covered by any route.
+ * Creates an ActorHandler that resolves an envelope to a sub-handler via one of
+ * the 7 depa-processor dispatch strategies (opt-in, per-handler — DX form C / B2).
+ *
+ * Object-param signature: `{ strategy, routes, defaultHandler?, extractors? }`.
+ *
+ * Composability:
+ *  - slot the returned handler under a `tag` in `ActorDef.handlers` → `tag` overlay
+ *    (first-level) + `strategy` (second-level), the two axes are orthogonal.
+ *  - the resolved sub-handler may itself be a `createPipelineHandler(...)` result,
+ *    so dispatch and pipeline nest freely.
+ *
+ * No declarative `ActorDef.dispatch` field and no global feature flag / enableXxx
+ * API exist — enabling rich dispatch is expressed purely by import + composition.
  */
 export function createDispatchHandler<
   TRuntime,
   TSchema extends MailboxSchema,
   TState,
 >(
-  routes: DispatchRoute<TRuntime, TSchema, TState>[],
-  defaultHandler?: ActorHandler<TRuntime, TSchema, TState>,
+  params: CreateDispatchHandlerParams<TRuntime, TSchema, TState>,
 ): ActorHandler<TRuntime, TSchema, TState> {
-  // Build tag → route index for O(1) lookup
-  const tagIndex = new Map<string, DispatchRoute<TRuntime, TSchema, TState>>();
-  for (const route of routes) {
-    for (const tag of route.tags) {
-      tagIndex.set(tag, route);
-    }
-  }
+  const { strategy, routes, defaultHandler, extractors } = params;
 
   return async (self, envelope) => {
-    const route = tagIndex.get(envelope.tag);
-
-    if (route) {
-      const key = route.resolveKey(envelope);
-      const handler = route.routes[key];
-      if (handler) {
-        await handler(self, envelope);
-      } else if (route.fallback) {
-        await route.fallback(self, envelope, key);
-      }
-    } else if (defaultHandler) {
+    const config = isStrategyConfig(routes)
+      ? routes
+      : buildKeyBasedConfig(strategy, routes, self, envelope);
+
+    const engine = new DispatchEngine<void | Promise<void>>();
+    engine.registerStrategy(config);
+
+    const request = buildRequest(strategy, envelope, extractors);
+    const result = await engine.dispatch(request);
+
+    if (result.isHandled()) {
+      // Await the sub-handler's (possibly async) side effect.
+      await result.getResult();
+      return;
+    }
+
+    if (defaultHandler) {
       await defaultHandler(self, envelope);
     }
   };

package/src/index.ts

@@ -15,6 +15,46 @@ export type {
 
 export { ActorSystem } from './core/ActorSystem.js';
 
+// depa-actor — Stable local logical addressing
+export type {
+  ActorAddress,
+  ActorSelector,
+  ActorOwnerSnapshotRegistration,
+  ActorOwnerSnapshot,
+  ActorRegistrationReceipt,
+  ActorAddressingErrorCode,
+  LocalActorEndpoint,
+  LocalActorAddressingRuntime,
+  LocalActorAddressingRuntimeConfig,
+  RegisterActorInput,
+  ActorProcessorConfig,
+  ResolveActorInvocation,
+  DispatchActorInvocation,
+  UnregisterActorInvocation,
+  ResolvedActor,
+  RebuildActorRegistrationsConfig,
+  DirectActorProcessor,
+  TargetedActorProcessor,
+} from './addressing.js';
+export {
+  ACTOR_ADDRESS_SCHEMA_VERSION,
+  ACTOR_OWNER_SNAPSHOT_SCHEMA_VERSION,
+  ACTOR_REGISTRATION_SCHEMA_VERSION,
+  ActorAddressingError,
+  actorAddressKey,
+  parseActorAddress,
+  parseActorSelector,
+  parseActorOwnerSnapshot,
+  parseActorRegistrationReceipt,
+  createLocalActorAddressingRuntime,
+  registerActor,
+  resolveActor,
+  dispatchActor,
+  unregisterActor,
+  rebuildActorRegistrations,
+  createActorRefEndpoint,
+} from './addressing.js';
+
 // depa-actor — Runtime
 export type { ActorPlugin } from './runtime/ActorRuntime.js';
 export { ActorRuntime } from './runtime/ActorRuntime.js';
@@ -108,10 +148,23 @@ export type {
 } from './pipeline/ActorPipeline.js';
 export { createPipelineHandler } from './pipeline/ActorPipeline.js';
 
-// depa-actor — Dispatch bridge
-export type { DispatchRoute } from './dispatch/ActorDispatchAdapter.js';
+// depa-actor — Dispatch bridge (drives depa-processor DispatchEngine, 7 strategies)
+export type {
+  ActorRouteHandler,
+  DispatchKeyExtractors,
+  CreateDispatchHandlerParams,
+} from './dispatch/ActorDispatchAdapter.js';
 export { createDispatchHandler } from './dispatch/ActorDispatchAdapter.js';
 
+// depa-actor — C3 re-export of the common depa-processor subset (single DX entry).
+// Component core-logic seam:
+export type { StdInnerLogic } from 'depa-processor';
+// Dispatch strategy enum + the common-tier strategy config factories
+// (ROUTE_KEY / ENUM / COMMAND_TABLE). Advanced strategies (PATH / ACTION_PATH +
+// AntPathMatcher / PathActionMatchRule), manifest-* and router/ stay in
+// depa-processor and are imported directly by users who need them.
+export { DispatchStrategyType, DispatchStrategyConfig } from 'depa-processor';
+
 // depa-actor — Orchestration (Fiber Scheduling)
 export type {
   FiberId,

package/src/pipeline/ActorPipeline.ts

@@ -1,16 +1,34 @@
 /**
  * depa-actor — ActorPipeline
  *
- * Adapts the DOP 6-step pipeline (from depa-processor) to actor context.
+ * Adapts the DOP 6-step pipeline to actor context by REUSING the depa-processor
+ * `component` primitives (DEPA dimension chain Processor → Actor): the 6-step
+ * orchestration is delegated to `runByFuncStyleAdapter`, identity/null seams come
+ * from `stdMake*`, and the core-logic seam is `StdInnerLogic` verbatim — this module
+ * no longer re-implements a parallel copy of `component/types.ts`.
  *
- * Mapping:
+ * Mapping (outer dimension):
  *   OuterRuntime = ActorSelf
  *   OuterInput   = envelope payload
  *   OuterConfig  = actor state
  *
+ * Step 6 (output) is adapted with `TOuterOutput = void`: actor output is a side
+ * effect (write `self.state` / `self.send`), not a returned value. This thinly
+ * adapts depa-processor's pure-function `StdOuterOutputAdapter` without leaking
+ * actor semantics back into the generic primitive.
+ *
  * createPipelineHandler() wraps a pipeline definition into an ActorHandler.
  */
 
+import { runByFuncStyleAdapter } from 'depa-processor';
+import type {
+  StdOuterComputedAdapter,
+  StdInnerRuntimeAdapter,
+  StdInnerInputAdapter,
+  StdInnerConfigAdapter,
+  StdInnerLogic,
+  StdOuterOutputAdapter,
+} from 'depa-processor';
 import type {
   MailboxSchema,
   ActorSelf,
@@ -18,57 +36,71 @@ import type {
 } from '../core/types.js';
 
 // ─── Pipeline Adapter Types ──────────────────────────────────────────
+// Thin actor-flavoured aliases over the depa-processor component adapters.
+// Outer dimension = (ActorSelf, payload, state); the seam contracts are reused
+// 1:1 from `depa-processor` rather than re-declared.
 
 export type PipelineDerivedAdapter<
   TRuntime, TSchema extends MailboxSchema, TState, TDerived,
-> = (
-  self: ActorSelf<TRuntime, TSchema, TState>,
-  payload: TSchema[keyof TSchema & string],
-  state: TState,
-) => TDerived;
+> = StdOuterComputedAdapter<
+  ActorSelf<TRuntime, TSchema, TState>,
+  TSchema[keyof TSchema & string],
+  TState,
+  TDerived
+>;
 
 export type PipelineInnerRuntimeAdapter<
   TRuntime, TSchema extends MailboxSchema, TState, TDerived, TInnerRuntime,
-> = (
-  self: ActorSelf<TRuntime, TSchema, TState>,
-  payload: TSchema[keyof TSchema & string],
-  state: TState,
-  derived: TDerived,
-) => TInnerRuntime;
+> = StdInnerRuntimeAdapter<
+  ActorSelf<TRuntime, TSchema, TState>,
+  TSchema[keyof TSchema & string],
+  TState,
+  TDerived,
+  TInnerRuntime
+>;
 
 export type PipelineInnerInputAdapter<
   TRuntime, TSchema extends MailboxSchema, TState, TDerived, TInnerInput,
-> = (
-  self: ActorSelf<TRuntime, TSchema, TState>,
-  payload: TSchema[keyof TSchema & string],
-  state: TState,
-  derived: TDerived,
-) => TInnerInput;
+> = StdInnerInputAdapter<
+  ActorSelf<TRuntime, TSchema, TState>,
+  TSchema[keyof TSchema & string],
+  TState,
+  TDerived,
+  TInnerInput
+>;
 
 export type PipelineInnerConfigAdapter<
   TRuntime, TSchema extends MailboxSchema, TState, TDerived, TInnerConfig,
-> = (
-  self: ActorSelf<TRuntime, TSchema, TState>,
-  payload: TSchema[keyof TSchema & string],
-  state: TState,
-  derived: TDerived,
-) => TInnerConfig;
+> = StdInnerConfigAdapter<
+  ActorSelf<TRuntime, TSchema, TState>,
+  TSchema[keyof TSchema & string],
+  TState,
+  TDerived,
+  TInnerConfig
+>;
 
-export type PipelineCoreLogic<TInnerRuntime, TInnerInput, TInnerConfig, TInnerOutput> = (
-  runtime: TInnerRuntime,
-  input: TInnerInput,
-  config: TInnerConfig,
-) => TInnerOutput | Promise<TInnerOutput>;
+/**
+ * Core business logic seam — reuses depa-processor `StdInnerLogic` verbatim:
+ * (runtime, input, config) => output | Promise<output>.
+ */
+export type PipelineCoreLogic<TInnerRuntime, TInnerInput, TInnerConfig, TInnerOutput> =
+  StdInnerLogic<TInnerRuntime, TInnerInput, TInnerConfig, TInnerOutput>;
 
+/**
+ * Step 6 output adapter — actor variant with `TOuterOutput = void`.
+ * The adapter performs side effects (write state / send messages) and returns
+ * nothing. This is the depa-processor `StdOuterOutputAdapter` specialised to void.
+ */
 export type PipelineOutputAdapter<
   TRuntime, TSchema extends MailboxSchema, TState, TDerived, TInnerOutput,
-> = (
-  self: ActorSelf<TRuntime, TSchema, TState>,
-  payload: TSchema[keyof TSchema & string],
-  state: TState,
-  derived: TDerived,
-  innerOutput: TInnerOutput,
-) => void | Promise<void>;
+> = StdOuterOutputAdapter<
+  ActorSelf<TRuntime, TSchema, TState>,
+  TSchema[keyof TSchema & string],
+  TState,
+  TDerived,
+  TInnerOutput,
+  void | Promise<void>
+>;
 
 // ─── Pipeline Definition ─────────────────────────────────────────────
 
@@ -92,6 +124,14 @@ export interface ActorPipelineDef<
 
 // ─── createPipelineHandler ───────────────────────────────────────────
 
+/**
+ * Wrap a pipeline definition into an ActorHandler by delegating the 6-step
+ * orchestration to depa-processor `runByFuncStyleAdapter`.
+ *
+ * Outer dimension: runtime = self, input = payload, config = state.
+ * Step 6 produces `void` — `runByFuncStyleAdapter` runs the output adapter for its
+ * side effects and the (void) return value is discarded.
+ */
 export function createPipelineHandler<
   TRuntime,
   TSchema extends MailboxSchema,
@@ -108,25 +148,31 @@ export function createPipelineHandler<
   >,
 ): ActorHandler<TRuntime, TSchema, TState> {
   return async (self, envelope) => {
-    const payload = envelope.payload;
-    const state = self.state;
-
-    // Step 1: Compute derived
-    const derived = pipeline.computeDerived(self, payload, state);
-
-    // Step 2: Transform runtime
-    const innerRuntime = pipeline.innerRuntime(self, payload, state, derived);
-
-    // Step 3: Transform input
-    const innerInput = pipeline.innerInput(self, payload, state, derived);
-
-    // Step 4: Transform config
-    const innerConfig = pipeline.innerConfig(self, payload, state, derived);
-
-    // Step 5: Core logic
-    const innerOutput = await pipeline.coreLogic(innerRuntime, innerInput, innerConfig);
-
-    // Step 6: Output (side effects on actor state / send messages)
-    await pipeline.output(self, payload, state, derived, innerOutput);
+    // `runByFuncStyleAdapter` returns the output adapter's value verbatim (without
+    // awaiting it). Capture it and await so an async step-6 side effect (write
+    // state / send messages) is fully settled before the handler resolves —
+    // preserving the original `await pipeline.output(...)` semantics.
+    const outputResult = await runByFuncStyleAdapter<
+      ActorSelf<TRuntime, TSchema, TState>,
+      TSchema[keyof TSchema & string],
+      TState,
+      TDerived,
+      void | Promise<void>,
+      TInnerRuntime,
+      TInnerInput,
+      TInnerConfig,
+      TInnerOutput
+    >(
+      self,
+      envelope.payload,
+      self.state,
+      pipeline.computeDerived,
+      pipeline.innerRuntime,
+      pipeline.innerInput,
+      pipeline.innerConfig,
+      pipeline.coreLogic,
+      pipeline.output,
+    );
+    await outputResult;
   };
 }