depa-actor 0.2.0 → 0.2.1

package/dist-cjs/addressing.cjs

@@ -0,0 +1,424 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActorAddressingError = exports.ACTOR_REGISTRATION_SCHEMA_VERSION = exports.ACTOR_OWNER_SNAPSHOT_SCHEMA_VERSION = exports.ACTOR_ADDRESS_SCHEMA_VERSION = void 0;
+exports.parseActorAddress = parseActorAddress;
+exports.actorAddressKey = actorAddressKey;
+exports.parseActorSelector = parseActorSelector;
+exports.parseActorOwnerSnapshot = parseActorOwnerSnapshot;
+exports.parseActorRegistrationReceipt = parseActorRegistrationReceipt;
+exports.createLocalActorAddressingRuntime = createLocalActorAddressingRuntime;
+exports.registerActor = registerActor;
+exports.resolveActor = resolveActor;
+exports.dispatchActor = dispatchActor;
+exports.unregisterActor = unregisterActor;
+exports.rebuildActorRegistrations = rebuildActorRegistrations;
+exports.createActorRefEndpoint = createActorRefEndpoint;
+exports.ACTOR_ADDRESS_SCHEMA_VERSION = 'depa-actor-address/v1';
+exports.ACTOR_OWNER_SNAPSHOT_SCHEMA_VERSION = 'depa-actor-owner-snapshot/v1';
+exports.ACTOR_REGISTRATION_SCHEMA_VERSION = 'depa-actor-registration/v1';
+class ActorAddressingError extends Error {
+    code;
+    name = 'ActorAddressingError';
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+exports.ActorAddressingError = ActorAddressingError;
+const ADDRESS_KEYS = [
+    'schemaVersion',
+    'namespace',
+    'deploymentId',
+    'actorKind',
+    'logicalKey',
+];
+const OWNER_SNAPSHOT_KEYS = [
+    'schemaVersion',
+    'ownerRevision',
+    'snapshotReceipt',
+    'registrations',
+];
+const OWNER_REGISTRATION_KEYS = ['address', 'handlerIdentity'];
+const REGISTRATION_RECEIPT_KEYS = [
+    'schemaVersion',
+    'address',
+    'ownerRevision',
+    'snapshotReceipt',
+    'handlerIdentity',
+    'registrationId',
+];
+const REGISTER_INPUT_KEYS = ['address', 'ownerSnapshot', 'endpoint'];
+const ENDPOINT_KEYS = ['handlerIdentity', 'dispatch'];
+const ADDRESS_SEGMENT = /^[A-Za-z0-9](?:[A-Za-z0-9._~-]{0,126}[A-Za-z0-9])?$/;
+const OPAQUE_TOKEN = /^[A-Za-z0-9](?:[A-Za-z0-9._~:/-]{0,254}[A-Za-z0-9])?$/;
+const runtimeStates = new WeakMap();
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertExactRecord(value, keys, code, label) {
+    if (!isRecord(value)) {
+        throw new ActorAddressingError(code, `${label} must be an object`);
+    }
+    const actualKeys = Object.keys(value).sort();
+    const expectedKeys = [...keys].sort();
+    if (actualKeys.length !== expectedKeys.length ||
+        actualKeys.some((key, index) => key !== expectedKeys[index])) {
+        throw new ActorAddressingError(code, `${label} must contain only: ${expectedKeys.join(', ')}`);
+    }
+}
+function parseAddressSegment(value, field, code = 'invalid-address') {
+    if (typeof value !== 'string' ||
+        value !== value.normalize('NFC') ||
+        !ADDRESS_SEGMENT.test(value)) {
+        throw new ActorAddressingError(code, `${field} must be a canonical actor-address segment`);
+    }
+    return value;
+}
+function parseOpaqueToken(value, field, code) {
+    if (typeof value !== 'string' ||
+        value !== value.normalize('NFC') ||
+        !OPAQUE_TOKEN.test(value) ||
+        value.includes('..') ||
+        value.includes('//') ||
+        value.includes('%')) {
+        throw new ActorAddressingError(code, `${field} must be a canonical non-empty token`);
+    }
+    return value;
+}
+function parseActorAddress(value) {
+    assertExactRecord(value, ADDRESS_KEYS, 'invalid-address', 'ActorAddress');
+    if (value.schemaVersion !== exports.ACTOR_ADDRESS_SCHEMA_VERSION) {
+        throw new ActorAddressingError('invalid-address', 'Unsupported ActorAddress schemaVersion');
+    }
+    return Object.freeze({
+        schemaVersion: exports.ACTOR_ADDRESS_SCHEMA_VERSION,
+        namespace: parseAddressSegment(value.namespace, 'namespace'),
+        deploymentId: parseAddressSegment(value.deploymentId, 'deploymentId'),
+        actorKind: parseAddressSegment(value.actorKind, 'actorKind'),
+        logicalKey: parseAddressSegment(value.logicalKey, 'logicalKey'),
+    });
+}
+function actorAddressKey(address) {
+    const parsed = parseActorAddress(address);
+    return [
+        parsed.schemaVersion,
+        parsed.namespace,
+        parsed.deploymentId,
+        parsed.actorKind,
+        parsed.logicalKey,
+    ].join(':');
+}
+function parseActorSelector(value) {
+    if (!isRecord(value)) {
+        throw new ActorAddressingError('invalid-selector', 'ActorSelector must be an object');
+    }
+    const keys = Object.keys(value);
+    if (keys.length !== 1 || (keys[0] !== 'byAddress' && keys[0] !== 'byAlias')) {
+        throw new ActorAddressingError('invalid-selector', 'ActorSelector must contain exactly one of byAddress or byAlias');
+    }
+    if (keys[0] === 'byAddress') {
+        try {
+            return Object.freeze({ byAddress: parseActorAddress(value.byAddress) });
+        }
+        catch (error) {
+            if (error instanceof ActorAddressingError) {
+                throw new ActorAddressingError('invalid-selector', `Invalid byAddress: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    return Object.freeze({
+        byAlias: parseOpaqueToken(value.byAlias, 'byAlias', 'invalid-selector'),
+    });
+}
+function parseActorOwnerSnapshot(value) {
+    assertExactRecord(value, OWNER_SNAPSHOT_KEYS, 'invalid-owner-snapshot', 'ActorOwnerSnapshot');
+    if (value.schemaVersion !== exports.ACTOR_OWNER_SNAPSHOT_SCHEMA_VERSION) {
+        throw new ActorAddressingError('invalid-owner-snapshot', 'Unsupported owner snapshot schemaVersion');
+    }
+    if (!Array.isArray(value.registrations)) {
+        throw new ActorAddressingError('invalid-owner-snapshot', 'registrations must be an array');
+    }
+    const registrations = [];
+    const seen = new Set();
+    for (const registration of value.registrations) {
+        assertExactRecord(registration, OWNER_REGISTRATION_KEYS, 'invalid-owner-snapshot', 'owner snapshot registration');
+        let address;
+        try {
+            address = parseActorAddress(registration.address);
+        }
+        catch (error) {
+            if (error instanceof ActorAddressingError) {
+                throw new ActorAddressingError('invalid-owner-snapshot', error.message);
+            }
+            throw error;
+        }
+        const key = actorAddressKey(address);
+        if (seen.has(key)) {
+            throw new ActorAddressingError('duplicate-snapshot-address', `Owner snapshot contains duplicate address: ${key}`);
+        }
+        seen.add(key);
+        registrations.push(Object.freeze({
+            address,
+            handlerIdentity: parseOpaqueToken(registration.handlerIdentity, 'handlerIdentity', 'invalid-owner-snapshot'),
+        }));
+    }
+    return Object.freeze({
+        schemaVersion: exports.ACTOR_OWNER_SNAPSHOT_SCHEMA_VERSION,
+        ownerRevision: parseOpaqueToken(value.ownerRevision, 'ownerRevision', 'invalid-owner-snapshot'),
+        snapshotReceipt: parseOpaqueToken(value.snapshotReceipt, 'snapshotReceipt', 'invalid-owner-snapshot'),
+        registrations: Object.freeze(registrations),
+    });
+}
+function parseActorRegistrationReceipt(value) {
+    assertExactRecord(value, REGISTRATION_RECEIPT_KEYS, 'registration-mismatch', 'ActorRegistrationReceipt');
+    if (value.schemaVersion !== exports.ACTOR_REGISTRATION_SCHEMA_VERSION) {
+        throw new ActorAddressingError('registration-mismatch', 'Unsupported registration schemaVersion');
+    }
+    return Object.freeze({
+        schemaVersion: exports.ACTOR_REGISTRATION_SCHEMA_VERSION,
+        address: parseActorAddress(value.address),
+        ownerRevision: parseOpaqueToken(value.ownerRevision, 'ownerRevision', 'registration-mismatch'),
+        snapshotReceipt: parseOpaqueToken(value.snapshotReceipt, 'snapshotReceipt', 'registration-mismatch'),
+        handlerIdentity: parseOpaqueToken(value.handlerIdentity, 'handlerIdentity', 'registration-mismatch'),
+        registrationId: parseOpaqueToken(value.registrationId, 'registrationId', 'registration-mismatch'),
+    });
+}
+function assertEmptyConfig(config) {
+    if (!isRecord(config) || Object.keys(config).length !== 0) {
+        throw new ActorAddressingError('registration-mismatch', 'Processor config must be an empty object');
+    }
+}
+function runtimeState(runtime) {
+    const state = runtimeStates.get(runtime);
+    if (!state) {
+        throw new ActorAddressingError('registration-mismatch', 'runtime must be created by createLocalActorAddressingRuntime');
+    }
+    return state;
+}
+function createLocalActorAddressingRuntime(config = {}) {
+    if (!isRecord(config)) {
+        throw new ActorAddressingError('registration-mismatch', 'runtime config must be an object');
+    }
+    const allowedKeys = new Set(['runtimeInstanceId', 'resolveAlias', 'registrationIdFactory']);
+    if (Object.keys(config).some((key) => !allowedKeys.has(key))) {
+        throw new ActorAddressingError('registration-mismatch', 'runtime config contains an unsupported field');
+    }
+    if (config.resolveAlias !== undefined && typeof config.resolveAlias !== 'function') {
+        throw new ActorAddressingError('registration-mismatch', 'resolveAlias must be a function');
+    }
+    if (config.registrationIdFactory !== undefined &&
+        typeof config.registrationIdFactory !== 'function') {
+        throw new ActorAddressingError('registration-mismatch', 'registrationIdFactory must be a function');
+    }
+    const randomPart = Math.random().toString(36).slice(2) || '0';
+    const runtimeInstanceId = parseOpaqueToken(config.runtimeInstanceId ?? `local-runtime-${Date.now().toString(36)}-${randomPart}`, 'runtimeInstanceId', 'registration-mismatch');
+    const runtime = Object.freeze({ runtimeInstanceId });
+    runtimeStates.set(runtime, {
+        registrations: new Map(),
+        registrationIds: new Set(),
+        resolveAlias: config.resolveAlias,
+        registrationIdFactory: config.registrationIdFactory ??
+            ((input) => `${input.runtimeInstanceId}:registration-${input.sequence}`),
+        sequence: 0,
+    });
+    return runtime;
+}
+function parseEndpoint(value) {
+    assertExactRecord(value, ENDPOINT_KEYS, 'registration-mismatch', 'LocalActorEndpoint');
+    const handlerIdentity = parseOpaqueToken(value.handlerIdentity, 'handlerIdentity', 'registration-mismatch');
+    if (typeof value.dispatch !== 'function') {
+        throw new ActorAddressingError('registration-mismatch', 'endpoint.dispatch must be a function');
+    }
+    return Object.freeze({
+        handlerIdentity,
+        dispatch: value.dispatch,
+    });
+}
+function parseRegisterInput(input) {
+    assertExactRecord(input, REGISTER_INPUT_KEYS, 'registration-mismatch', 'RegisterActorInput');
+    return {
+        address: parseActorAddress(input.address),
+        ownerSnapshot: parseActorOwnerSnapshot(input.ownerSnapshot),
+        endpoint: parseEndpoint(input.endpoint),
+    };
+}
+function resolveRegistration(runtime, selector) {
+    const state = runtimeState(runtime);
+    const parsedSelector = parseActorSelector(selector);
+    let address;
+    if ('byAddress' in parsedSelector) {
+        address = parsedSelector.byAddress;
+    }
+    else {
+        const resolved = state.resolveAlias?.(parsedSelector.byAlias);
+        if (resolved === undefined) {
+            throw new ActorAddressingError('unresolved-selector', `Actor alias is unresolved: ${parsedSelector.byAlias}`);
+        }
+        try {
+            address = parseActorAddress(resolved);
+        }
+        catch (error) {
+            if (error instanceof ActorAddressingError) {
+                throw new ActorAddressingError('unresolved-selector', `Actor alias resolved to an invalid address: ${parsedSelector.byAlias}`);
+            }
+            throw error;
+        }
+    }
+    const registration = state.registrations.get(actorAddressKey(address));
+    if (!registration) {
+        throw new ActorAddressingError('unresolved-selector', `Actor address is not registered: ${actorAddressKey(address)}`);
+    }
+    return registration;
+}
+function expectedRegistrationId(value, required) {
+    if (!isRecord(value)) {
+        throw new ActorAddressingError('stale-registration', 'invocation must be an object');
+    }
+    const allowedKeys = required ? ['expectedRegistrationId'] : ['expectedRegistrationId'];
+    if (Object.keys(value).some((key) => !allowedKeys.includes(key))) {
+        throw new ActorAddressingError('stale-registration', 'invocation contains an unsupported field');
+    }
+    if (value.expectedRegistrationId === undefined && !required)
+        return undefined;
+    return parseOpaqueToken(value.expectedRegistrationId, 'expectedRegistrationId', 'stale-registration');
+}
+function assertCurrentRegistration(registration, expectedId) {
+    if (expectedId !== undefined && expectedId !== registration.registrationId) {
+        throw new ActorAddressingError('stale-registration', `Expected registration ${expectedId} is not current`);
+    }
+}
+function registerActor(runtime, input, config) {
+    assertEmptyConfig(config);
+    const parsed = parseRegisterInput(input);
+    const state = runtimeState(runtime);
+    const key = actorAddressKey(parsed.address);
+    if (state.registrations.has(key)) {
+        throw new ActorAddressingError('already-registered', `Actor is already registered: ${key}`);
+    }
+    const ownerEntry = parsed.ownerSnapshot.registrations.find((entry) => actorAddressKey(entry.address) === key);
+    if (!ownerEntry || ownerEntry.handlerIdentity !== parsed.endpoint.handlerIdentity) {
+        throw new ActorAddressingError('registration-mismatch', 'Address and handler identity must be authorized by the owner snapshot');
+    }
+    const sequence = state.sequence + 1;
+    const registrationId = parseOpaqueToken(state.registrationIdFactory({
+        runtimeInstanceId: runtime.runtimeInstanceId,
+        sequence,
+        address: parsed.address,
+    }), 'registrationId', 'registration-mismatch');
+    if (state.registrationIds.has(registrationId)) {
+        throw new ActorAddressingError('registration-mismatch', `registrationIdFactory returned a duplicate id: ${registrationId}`);
+    }
+    state.sequence = sequence;
+    const receipt = Object.freeze({
+        schemaVersion: exports.ACTOR_REGISTRATION_SCHEMA_VERSION,
+        address: parsed.address,
+        ownerRevision: parsed.ownerSnapshot.ownerRevision,
+        snapshotReceipt: parsed.ownerSnapshot.snapshotReceipt,
+        handlerIdentity: parsed.endpoint.handlerIdentity,
+        registrationId,
+    });
+    state.registrations.set(key, {
+        address: parsed.address,
+        receipt,
+        endpoint: parsed.endpoint,
+    });
+    state.registrationIds.add(registrationId);
+    return receipt;
+}
+function resolveActor(runtime, selector, invocation, config) {
+    assertEmptyConfig(config);
+    const expectedId = expectedRegistrationId(invocation, false);
+    const registration = resolveRegistration(runtime, selector);
+    assertCurrentRegistration(registration.receipt, expectedId);
+    return Object.freeze({
+        address: registration.address,
+        receipt: registration.receipt,
+    });
+}
+async function dispatchActor(runtime, selector, invocation, config) {
+    assertEmptyConfig(config);
+    if (!isRecord(invocation)) {
+        throw new ActorAddressingError('stale-registration', 'dispatch invocation must be an object');
+    }
+    const keys = Object.keys(invocation);
+    if (!keys.includes('input') || keys.some((key) => key !== 'input' && key !== 'expectedRegistrationId')) {
+        throw new ActorAddressingError('stale-registration', 'dispatch invocation must contain input and optional expectedRegistrationId');
+    }
+    const registration = resolveRegistration(runtime, selector);
+    const expectedId = invocation.expectedRegistrationId === undefined
+        ? undefined
+        : parseOpaqueToken(invocation.expectedRegistrationId, 'expectedRegistrationId', 'stale-registration');
+    assertCurrentRegistration(registration.receipt, expectedId);
+    return await registration.endpoint.dispatch(invocation.input);
+}
+function unregisterActor(runtime, selector, invocation, config) {
+    assertEmptyConfig(config);
+    const expectedId = expectedRegistrationId(invocation, true);
+    const registration = resolveRegistration(runtime, selector);
+    assertCurrentRegistration(registration.receipt, expectedId);
+    runtimeState(runtime).registrations.delete(actorAddressKey(registration.address));
+    runtimeState(runtime).registrationIds.delete(registration.receipt.registrationId);
+    return registration.receipt;
+}
+function rebuildActorRegistrations(runtime, input, config) {
+    const snapshot = parseActorOwnerSnapshot(input);
+    assertExactRecord(config, ['endpointFor'], 'registration-mismatch', 'RebuildActorRegistrationsConfig');
+    if (typeof config.endpointFor !== 'function') {
+        throw new ActorAddressingError('registration-mismatch', 'endpointFor must be a function');
+    }
+    const state = runtimeState(runtime);
+    if (state.registrations.size !== 0) {
+        throw new ActorAddressingError('already-registered', 'Registration recovery requires a fresh empty local runtime');
+    }
+    const endpoints = snapshot.registrations.map((registration) => {
+        const endpoint = parseEndpoint(config.endpointFor(registration));
+        if (endpoint.handlerIdentity !== registration.handlerIdentity) {
+            throw new ActorAddressingError('registration-mismatch', `Recovered endpoint identity does not match snapshot for ${actorAddressKey(registration.address)}`);
+        }
+        return endpoint;
+    });
+    let nextSequence = state.sequence;
+    const plannedIds = new Set();
+    const planned = snapshot.registrations.map((registration, index) => {
+        nextSequence += 1;
+        const registrationId = parseOpaqueToken(state.registrationIdFactory({
+            runtimeInstanceId: runtime.runtimeInstanceId,
+            sequence: nextSequence,
+            address: registration.address,
+        }), 'registrationId', 'registration-mismatch');
+        if (state.registrationIds.has(registrationId) || plannedIds.has(registrationId)) {
+            throw new ActorAddressingError('registration-mismatch', `registrationIdFactory returned a duplicate id: ${registrationId}`);
+        }
+        plannedIds.add(registrationId);
+        const receipt = Object.freeze({
+            schemaVersion: exports.ACTOR_REGISTRATION_SCHEMA_VERSION,
+            address: registration.address,
+            ownerRevision: snapshot.ownerRevision,
+            snapshotReceipt: snapshot.snapshotReceipt,
+            handlerIdentity: registration.handlerIdentity,
+            registrationId,
+        });
+        return {
+            key: actorAddressKey(registration.address),
+            registration: {
+                address: registration.address,
+                receipt,
+                endpoint: endpoints[index],
+            },
+        };
+    });
+    for (const item of planned) {
+        state.registrations.set(item.key, item.registration);
+        state.registrationIds.add(item.registration.receipt.registrationId);
+    }
+    state.sequence = nextSequence;
+    return Object.freeze(planned.map((item) => item.registration.receipt));
+}
+function createActorRefEndpoint(ref, tag, handlerIdentity) {
+    const parsedHandlerIdentity = parseOpaqueToken(handlerIdentity, 'handlerIdentity', 'registration-mismatch');
+    return Object.freeze({
+        handlerIdentity: parsedHandlerIdentity,
+        dispatch: (input) => ref.send(tag, input),
+    });
+}

package/dist-cjs/dispatch/ActorDispatchAdapter.cjs

@@ -2,38 +2,123 @@
 /**
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDispatchHandler = createDispatchHandler;
-// ─── createDispatchHandler ───────────────────────────────────────────
+const depa_processor_1 = require("depa-processor");
+// ─── Internal helpers ────────────────────────────────────────────────
+function isStrategyConfig(routes) {
+    return routes instanceof depa_processor_1.DispatchStrategyConfig;
+}
 /**
- * Creates an ActorHandler that routes envelopes through dispatch routes.
- * Falls back to `defaultHandler` for tags not covered by any route.
+ * 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 createDispatchHandler(routes, defaultHandler) {
-    // Build tag → route index for O(1) lookup
-    const tagIndex = new Map();
-    for (const route of routes) {
-        for (const tag of route.tags) {
-            tagIndex.set(tag, route);
-        }
+function buildKeyBasedConfig(strategy, routes, self, envelope) {
+    const handlerMap = new Map();
+    for (const [key, handler] of Object.entries(routes)) {
+        handlerMap.set(key, () => handler(self, envelope));
+    }
+    switch (strategy) {
+        case depa_processor_1.DispatchStrategyType.ROUTE_KEY:
+            return depa_processor_1.DispatchStrategyConfig.forRouteKeyStrategy({
+                handlerMap: handlerMap,
+            });
+        case depa_processor_1.DispatchStrategyType.ENUM:
+            return depa_processor_1.DispatchStrategyConfig.forEnumStrategy({
+                handlerMap,
+            });
+        case depa_processor_1.DispatchStrategyType.COMMAND_TABLE:
+            return depa_processor_1.DispatchStrategyConfig.forCommandStrategy({
+                commandConverter: (command) => handlerMap.has(command) ? command : null,
+                handlerExtractor: (commandEnum) => 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(strategy, envelope, extractors) {
+    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 depa_processor_1.DispatchStrategyType.CLASS:
+            return (0, depa_processor_1.createClassDispatchRequest)(input);
+        case depa_processor_1.DispatchStrategyType.ROUTE_KEY:
+            return (0, depa_processor_1.createRouteKeyDispatchRequest)(routeKey, input, false);
+        case depa_processor_1.DispatchStrategyType.ENUM:
+            return (0, depa_processor_1.createEnumDispatchRequest)(extractors?.enumOf ? extractors.enumOf(envelope) : envelope.tag, input);
+        case depa_processor_1.DispatchStrategyType.ROUTE_KEY_TO_ENUM:
+            return (0, depa_processor_1.createRouteKeyToEnumDispatchRequest)(routeKey, input);
+        case depa_processor_1.DispatchStrategyType.COMMAND_TABLE:
+            return (0, depa_processor_1.createCommandDispatchRequest)(routeKey, input);
+        case depa_processor_1.DispatchStrategyType.PATH:
+            return (0, depa_processor_1.createPathDispatchRequest)({
+                runtime: undefined,
+                request: input,
+                path,
+            });
+        case depa_processor_1.DispatchStrategyType.ACTION_PATH:
+            return (0, depa_processor_1.createActionPathDispatchRequest)({
+                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 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.
+ */
+function createDispatchHandler(params) {
+    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);
-            }
+        const config = isStrategyConfig(routes)
+            ? routes
+            : buildKeyBasedConfig(strategy, routes, self, envelope);
+        const engine = new depa_processor_1.DispatchEngine();
+        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;
         }
-        else if (defaultHandler) {
+        if (defaultHandler) {
             await defaultHandler(self, envelope);
         }
     };

package/dist-cjs/index.cjs

@@ -1,8 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dispatchEffects = exports.createAiAgentSchedulerHooks = exports.scheduleOne = exports.selectNextFiberId = exports.computeEffectivePriority = exports.applyFailure = exports.reduceOrchestrator = exports.createOrchestratorState = exports.DEFAULT_ORCHESTRATOR_OPTIONS = exports.createDispatchHandler = exports.createPipelineHandler = exports.dispatchInstructions = exports.takeNextCommandFromGroup = exports.pushFrontCommandToGroup = exports.pushFrontCommand = exports.pushBackCommandToGroup = exports.pushBackCommand = exports.popSelectedCommandFromGroup = exports.popNextCommand = exports.popFrontCommand = exports.popBackCommand = exports.drainWhereCommandDequeFromGroup = exports.drainCommandDequeFromGroup = exports.defaultCommandDequeSelector = exports.createCommandDequeGroup = exports.createCommandDeque = exports.createOperandStack = exports.createInstructionStack = exports.createStackMachine = exports.createRuntimeIndexHook = exports.RuntimeIndexHook = exports.createPersistenceEffectPort = exports.createRecoveryHooks = exports.createSnapshotCodec = exports.createCompletionBindingRegistry = exports.createCompletionSignalRegistry = exports.CompletionBindingRegistry = exports.CompletionSignalRegistry = exports.ActorRuntime = exports.ActorSystem = void 0;
+exports.DEFAULT_ORCHESTRATOR_OPTIONS = exports.DispatchStrategyConfig = exports.DispatchStrategyType = exports.createDispatchHandler = exports.createPipelineHandler = exports.dispatchInstructions = exports.takeNextCommandFromGroup = exports.pushFrontCommandToGroup = exports.pushFrontCommand = exports.pushBackCommandToGroup = exports.pushBackCommand = exports.popSelectedCommandFromGroup = exports.popNextCommand = exports.popFrontCommand = exports.popBackCommand = exports.drainWhereCommandDequeFromGroup = exports.drainCommandDequeFromGroup = exports.defaultCommandDequeSelector = exports.createCommandDequeGroup = exports.createCommandDeque = exports.createOperandStack = exports.createInstructionStack = exports.createStackMachine = exports.createRuntimeIndexHook = exports.RuntimeIndexHook = exports.createPersistenceEffectPort = exports.createRecoveryHooks = exports.createSnapshotCodec = exports.createCompletionBindingRegistry = exports.createCompletionSignalRegistry = exports.CompletionBindingRegistry = exports.CompletionSignalRegistry = exports.ActorRuntime = exports.createActorRefEndpoint = exports.rebuildActorRegistrations = exports.unregisterActor = exports.dispatchActor = exports.resolveActor = exports.registerActor = exports.createLocalActorAddressingRuntime = exports.parseActorRegistrationReceipt = exports.parseActorOwnerSnapshot = exports.parseActorSelector = exports.parseActorAddress = exports.actorAddressKey = exports.ActorAddressingError = exports.ACTOR_REGISTRATION_SCHEMA_VERSION = exports.ACTOR_OWNER_SNAPSHOT_SCHEMA_VERSION = exports.ACTOR_ADDRESS_SCHEMA_VERSION = exports.ActorSystem = void 0;
+exports.dispatchEffects = exports.createAiAgentSchedulerHooks = exports.scheduleOne = exports.selectNextFiberId = exports.computeEffectivePriority = exports.applyFailure = exports.reduceOrchestrator = exports.createOrchestratorState = void 0;
 var ActorSystem_js_1 = require("./core/ActorSystem.cjs");
 Object.defineProperty(exports, "ActorSystem", { enumerable: true, get: function () { return ActorSystem_js_1.ActorSystem; } });
+var addressing_js_1 = require("./addressing.cjs");
+Object.defineProperty(exports, "ACTOR_ADDRESS_SCHEMA_VERSION", { enumerable: true, get: function () { return addressing_js_1.ACTOR_ADDRESS_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "ACTOR_OWNER_SNAPSHOT_SCHEMA_VERSION", { enumerable: true, get: function () { return addressing_js_1.ACTOR_OWNER_SNAPSHOT_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "ACTOR_REGISTRATION_SCHEMA_VERSION", { enumerable: true, get: function () { return addressing_js_1.ACTOR_REGISTRATION_SCHEMA_VERSION; } });
+Object.defineProperty(exports, "ActorAddressingError", { enumerable: true, get: function () { return addressing_js_1.ActorAddressingError; } });
+Object.defineProperty(exports, "actorAddressKey", { enumerable: true, get: function () { return addressing_js_1.actorAddressKey; } });
+Object.defineProperty(exports, "parseActorAddress", { enumerable: true, get: function () { return addressing_js_1.parseActorAddress; } });
+Object.defineProperty(exports, "parseActorSelector", { enumerable: true, get: function () { return addressing_js_1.parseActorSelector; } });
+Object.defineProperty(exports, "parseActorOwnerSnapshot", { enumerable: true, get: function () { return addressing_js_1.parseActorOwnerSnapshot; } });
+Object.defineProperty(exports, "parseActorRegistrationReceipt", { enumerable: true, get: function () { return addressing_js_1.parseActorRegistrationReceipt; } });
+Object.defineProperty(exports, "createLocalActorAddressingRuntime", { enumerable: true, get: function () { return addressing_js_1.createLocalActorAddressingRuntime; } });
+Object.defineProperty(exports, "registerActor", { enumerable: true, get: function () { return addressing_js_1.registerActor; } });
+Object.defineProperty(exports, "resolveActor", { enumerable: true, get: function () { return addressing_js_1.resolveActor; } });
+Object.defineProperty(exports, "dispatchActor", { enumerable: true, get: function () { return addressing_js_1.dispatchActor; } });
+Object.defineProperty(exports, "unregisterActor", { enumerable: true, get: function () { return addressing_js_1.unregisterActor; } });
+Object.defineProperty(exports, "rebuildActorRegistrations", { enumerable: true, get: function () { return addressing_js_1.rebuildActorRegistrations; } });
+Object.defineProperty(exports, "createActorRefEndpoint", { enumerable: true, get: function () { return addressing_js_1.createActorRefEndpoint; } });
 var ActorRuntime_js_1 = require("./runtime/ActorRuntime.cjs");
 Object.defineProperty(exports, "ActorRuntime", { enumerable: true, get: function () { return ActorRuntime_js_1.ActorRuntime; } });
 var completion_js_1 = require("./runtime/completion.cjs");
@@ -40,6 +58,13 @@ var ActorPipeline_js_1 = require("./pipeline/ActorPipeline.cjs");
 Object.defineProperty(exports, "createPipelineHandler", { enumerable: true, get: function () { return ActorPipeline_js_1.createPipelineHandler; } });
 var ActorDispatchAdapter_js_1 = require("./dispatch/ActorDispatchAdapter.cjs");
 Object.defineProperty(exports, "createDispatchHandler", { enumerable: true, get: function () { return ActorDispatchAdapter_js_1.createDispatchHandler; } });
+// 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.
+var depa_processor_1 = require("depa-processor");
+Object.defineProperty(exports, "DispatchStrategyType", { enumerable: true, get: function () { return depa_processor_1.DispatchStrategyType; } });
+Object.defineProperty(exports, "DispatchStrategyConfig", { enumerable: true, get: function () { return depa_processor_1.DispatchStrategyConfig; } });
 var index_js_2 = require("./orchestration/index.cjs");
 Object.defineProperty(exports, "DEFAULT_ORCHESTRATOR_OPTIONS", { enumerable: true, get: function () { return index_js_2.DEFAULT_ORCHESTRATOR_OPTIONS; } });
 Object.defineProperty(exports, "createOrchestratorState", { enumerable: true, get: function () { return index_js_2.createOrchestratorState; } });