depa-actor 0.1.2 → 0.2.0

package/dist-cjs/orchestration/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+// depa-actor — Orchestration (Fiber Scheduling)
+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 = void 0;
+var types_js_1 = require("./types.cjs");
+Object.defineProperty(exports, "DEFAULT_ORCHESTRATOR_OPTIONS", { enumerable: true, get: function () { return types_js_1.DEFAULT_ORCHESTRATOR_OPTIONS; } });
+var reducer_js_1 = require("./reducer.cjs");
+Object.defineProperty(exports, "createOrchestratorState", { enumerable: true, get: function () { return reducer_js_1.createOrchestratorState; } });
+Object.defineProperty(exports, "reduceOrchestrator", { enumerable: true, get: function () { return reducer_js_1.reduceOrchestrator; } });
+var recovery_js_1 = require("./recovery.cjs");
+Object.defineProperty(exports, "applyFailure", { enumerable: true, get: function () { return recovery_js_1.applyFailure; } });
+var scheduler_js_1 = require("./scheduler.cjs");
+Object.defineProperty(exports, "computeEffectivePriority", { enumerable: true, get: function () { return scheduler_js_1.computeEffectivePriority; } });
+Object.defineProperty(exports, "selectNextFiberId", { enumerable: true, get: function () { return scheduler_js_1.selectNextFiberId; } });
+Object.defineProperty(exports, "scheduleOne", { enumerable: true, get: function () { return scheduler_js_1.scheduleOne; } });
+var aiAgent_js_1 = require("./presets/aiAgent.cjs");
+Object.defineProperty(exports, "createAiAgentSchedulerHooks", { enumerable: true, get: function () { return aiAgent_js_1.createAiAgentSchedulerHooks; } });
+var runtimeAdapter_js_1 = require("./runtimeAdapter.cjs");
+Object.defineProperty(exports, "dispatchEffects", { enumerable: true, get: function () { return runtimeAdapter_js_1.dispatchEffects; } });

package/dist-cjs/orchestration/presets/aiAgent.cjs

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAiAgentSchedulerHooks = createAiAgentSchedulerHooks;
+function isAiHumanWaitReason(reason) {
+    return reason === 'human_clarification' || reason === 'human_approval' || reason === 'human_answer';
+}
+function getEffectiveSuspendPolicy(fiber) {
+    const raw = fiber?.suspendPolicy;
+    return raw === 'continue_others' || raw === 'pause_all' ? raw : undefined;
+}
+function isBlockingLaneForPauseAll(lane) {
+    // Treat any non-background lane as blocking by default.
+    if (lane === 'background' || lane === 'collective') {
+        return false;
+    }
+    return true;
+}
+function isAllowedLaneDuringPauseAll(lane) {
+    return lane === 'background' || lane === 'collective';
+}
+function hasPauseAllHumanWaitInBlockingLane(state) {
+    return Object.values(state.fibers).some((fiber) => {
+        return (fiber?.status === 'suspended' &&
+            isAiHumanWaitReason(fiber?.waitingReason) &&
+            getEffectiveSuspendPolicy(fiber) === 'pause_all' &&
+            isBlockingLaneForPauseAll(fiber?.lane));
+    });
+}
+// AIAgent-compatible scheduling hooks:
+// - When a pause_all human wait exists in a blocking lane (interactive/member), only allow background/collective lanes.
+function createAiAgentSchedulerHooks() {
+    return {
+        filterCandidate: ({ state, fiber }) => {
+            if (!hasPauseAllHumanWaitInBlockingLane(state)) {
+                return true;
+            }
+            return isAllowedLaneDuringPauseAll(fiber?.lane);
+        },
+    };
+}

package/dist-cjs/orchestration/recovery.cjs

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyFailure = applyFailure;
+function cloneFiberMap(state) {
+    return { ...state.fibers };
+}
+function buildDeadLetterEffects(state, fiber, reason) {
+    const effects = [
+        {
+            kind: 'dead_letter',
+            fiberId: fiber.id,
+            reason,
+        },
+    ];
+    const route = state.options.deadLetterFactory?.(fiber, reason);
+    if (route) {
+        effects.push({
+            kind: 'dead_letter',
+            fiberId: fiber.id,
+            reason,
+            to: route.to,
+            step: route.step,
+        });
+    }
+    return effects;
+}
+function computeRetryDelay(retryDelayMs, retryBackoffMultiplier, attempts) {
+    const base = Math.max(0, retryDelayMs);
+    const multiplier = Math.max(1, retryBackoffMultiplier);
+    return Math.floor(base * Math.pow(multiplier, Math.max(0, attempts - 1)));
+}
+function applyFailure(state, fiberId, now, error) {
+    const fiber = state.fibers[fiberId];
+    if (!fiber) {
+        return { state, effects: [] };
+    }
+    if (fiber.status === 'completed' || fiber.status === 'cancelled' || fiber.status === 'dead_letter') {
+        return { state, effects: [] };
+    }
+    const nextFibers = cloneFiberMap(state);
+    if (state.options.retryEnabled && fiber.attempts < fiber.maxAttempts) {
+        const nextAttempts = fiber.attempts + 1;
+        const delay = computeRetryDelay(state.options.retryDelayMs, state.options.retryBackoffMultiplier, nextAttempts);
+        const updated = {
+            ...fiber,
+            status: 'suspended',
+            waitingReason: 'retry_backoff',
+            suspendPolicy: undefined,
+            retryAt: now + delay,
+            timeoutAt: undefined,
+            attempts: nextAttempts,
+            lastError: error,
+            updatedAt: now,
+        };
+        nextFibers[fiberId] = updated;
+        return {
+            state: {
+                ...state,
+                fibers: nextFibers,
+            },
+            effects: [],
+        };
+    }
+    if (state.options.deadLetterEnabled) {
+        const updated = {
+            ...fiber,
+            status: 'dead_letter',
+            waitingReason: undefined,
+            suspendPolicy: undefined,
+            retryAt: undefined,
+            lastError: error,
+            updatedAt: now,
+        };
+        nextFibers[fiberId] = updated;
+        const deadLetters = [
+            ...state.deadLetters,
+            {
+                fiberId: fiber.id,
+                actorId: fiber.actorId,
+                reason: error,
+                at: now,
+                attempts: fiber.attempts,
+                step: fiber.step,
+            },
+        ];
+        return {
+            state: {
+                ...state,
+                fibers: nextFibers,
+                deadLetters,
+            },
+            effects: buildDeadLetterEffects(state, updated, error),
+        };
+    }
+    const updated = {
+        ...fiber,
+        status: 'failed',
+        waitingReason: undefined,
+        suspendPolicy: undefined,
+        retryAt: undefined,
+        lastError: error,
+        updatedAt: now,
+    };
+    nextFibers[fiberId] = updated;
+    return {
+        state: {
+            ...state,
+            fibers: nextFibers,
+        },
+        effects: [],
+    };
+}

package/dist-cjs/orchestration/reducer.cjs

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOrchestratorState = createOrchestratorState;
+exports.reduceOrchestrator = reduceOrchestrator;
+const recovery_js_1 = require("./recovery.cjs");
+const types_js_1 = require("./types.cjs");
+function isTerminalStatus(status) {
+    return status === 'completed' || status === 'cancelled' || status === 'failed' || status === 'dead_letter';
+}
+function cloneFiberMap(state) {
+    return { ...state.fibers };
+}
+function upsertParentChildRelation(fibers, fiber, now) {
+    if (!fiber.parentId) {
+        return;
+    }
+    const parent = fibers[fiber.parentId];
+    if (!parent) {
+        return;
+    }
+    if (!parent.childIds.includes(fiber.id)) {
+        fibers[fiber.parentId] = {
+            ...parent,
+            childIds: [...parent.childIds, fiber.id],
+            updatedAt: now,
+        };
+    }
+}
+function createFiberRecord(input, now, order, state) {
+    const timeoutMs = input.timeoutMs ?? state.options.defaultTimeoutMs;
+    return {
+        id: input.id,
+        actorId: input.actorId,
+        parentId: input.parentId,
+        childIds: [],
+        lane: input.lane ?? 'default',
+        status: 'ready',
+        basePriority: input.basePriority,
+        age: 0,
+        attempts: 0,
+        maxAttempts: Math.max(0, input.maxAttempts ?? 0),
+        step: input.step,
+        waitingReason: undefined,
+        suspendPolicy: undefined,
+        timeoutMs: timeoutMs > 0 ? timeoutMs : undefined,
+        timeoutAt: undefined,
+        retryAt: undefined,
+        lastError: undefined,
+        order,
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+function createOrchestratorState(options) {
+    const raw = (options ?? {});
+    const effectiveDefault = raw.defaultSuspendPolicy ??
+        types_js_1.DEFAULT_ORCHESTRATOR_OPTIONS.defaultSuspendPolicy;
+    const base = {
+        ...types_js_1.DEFAULT_ORCHESTRATOR_OPTIONS,
+        ...raw,
+    };
+    return {
+        options: {
+            ...base,
+            defaultSuspendPolicy: effectiveDefault,
+        },
+        fibers: {},
+        deadLetters: [],
+        sequence: 0,
+    };
+}
+function applyTick(state, now) {
+    let nextState = state;
+    let aggregatedEffects = [];
+    const ids = Object.keys(state.fibers);
+    for (const id of ids) {
+        const fiber = nextState.fibers[id];
+        if (!fiber) {
+            continue;
+        }
+        if (isTerminalStatus(fiber.status)) {
+            continue;
+        }
+        if (nextState.options.timeoutEnabled &&
+            fiber.timeoutAt !== undefined &&
+            now >= fiber.timeoutAt &&
+            (fiber.status === 'running' || fiber.status === 'ready' || fiber.status === 'suspended')) {
+            const timed = (0, recovery_js_1.applyFailure)(nextState, id, now, 'timeout');
+            nextState = timed.state;
+            aggregatedEffects = [...aggregatedEffects, ...timed.effects];
+            continue;
+        }
+        const iter = nextState.fibers[id];
+        if (iter &&
+            iter.status === 'suspended' &&
+            iter.waitingReason === 'retry_backoff' &&
+            iter.retryAt !== undefined &&
+            now >= iter.retryAt) {
+            nextState = {
+                ...nextState,
+                fibers: {
+                    ...nextState.fibers,
+                    [id]: {
+                        ...iter,
+                        status: 'ready',
+                        waitingReason: undefined,
+                        retryAt: undefined,
+                        timeoutAt: undefined,
+                        updatedAt: now,
+                    },
+                },
+            };
+        }
+    }
+    return {
+        state: nextState,
+        effects: aggregatedEffects,
+    };
+}
+function reduceOrchestrator(state, action) {
+    if (action.type === 'tick') {
+        return applyTick(state, action.now);
+    }
+    if (action.type === 'spawn') {
+        const nextSequence = state.sequence + 1;
+        const nextFibers = cloneFiberMap(state);
+        const record = createFiberRecord(action.fiber, action.now, nextSequence, state);
+        nextFibers[action.fiber.id] = record;
+        upsertParentChildRelation(nextFibers, action.fiber, action.now);
+        return {
+            state: {
+                ...state,
+                sequence: nextSequence,
+                fibers: nextFibers,
+            },
+            effects: [],
+        };
+    }
+    const current = state.fibers[action.fiberId];
+    if (!current) {
+        return { state, effects: [] };
+    }
+    if (action.type === 'yield') {
+        if (isTerminalStatus(current.status)) {
+            return { state, effects: [] };
+        }
+        return {
+            state: {
+                ...state,
+                fibers: {
+                    ...state.fibers,
+                    [action.fiberId]: {
+                        ...current,
+                        status: 'ready',
+                        waitingReason: undefined,
+                        suspendPolicy: undefined,
+                        timeoutAt: undefined,
+                        step: action.nextStep ?? current.step,
+                        updatedAt: action.now,
+                    },
+                },
+            },
+            effects: [],
+        };
+    }
+    if (action.type === 'suspend') {
+        if (isTerminalStatus(current.status)) {
+            return { state, effects: [] };
+        }
+        const effectivePolicy = action.suspendPolicy ??
+            state.options.defaultSuspendPolicy ??
+            'continue_others';
+        return {
+            state: {
+                ...state,
+                fibers: {
+                    ...state.fibers,
+                    [action.fiberId]: {
+                        ...current,
+                        status: 'suspended',
+                        waitingReason: action.reason,
+                        suspendPolicy: effectivePolicy,
+                        timeoutAt: undefined,
+                        updatedAt: action.now,
+                    },
+                },
+            },
+            effects: [],
+        };
+    }
+    if (action.type === 'resume') {
+        if (isTerminalStatus(current.status)) {
+            return { state, effects: [] };
+        }
+        return {
+            state: {
+                ...state,
+                fibers: {
+                    ...state.fibers,
+                    [action.fiberId]: {
+                        ...current,
+                        status: 'ready',
+                        waitingReason: undefined,
+                        suspendPolicy: undefined,
+                        retryAt: undefined,
+                        timeoutAt: undefined,
+                        step: action.nextStep ?? current.step,
+                        updatedAt: action.now,
+                    },
+                },
+            },
+            effects: [],
+        };
+    }
+    if (action.type === 'complete') {
+        return {
+            state: {
+                ...state,
+                fibers: {
+                    ...state.fibers,
+                    [action.fiberId]: {
+                        ...current,
+                        status: 'completed',
+                        waitingReason: undefined,
+                        suspendPolicy: undefined,
+                        timeoutAt: undefined,
+                        updatedAt: action.now,
+                    },
+                },
+            },
+            effects: [],
+        };
+    }
+    if (action.type === 'fail') {
+        return (0, recovery_js_1.applyFailure)(state, action.fiberId, action.now, action.error);
+    }
+    if (action.type === 'cancel') {
+        const nextFibers = cloneFiberMap(state);
+        const queue = [action.fiberId];
+        const seen = new Set();
+        while (queue.length > 0) {
+            const id = queue.shift();
+            if (seen.has(id)) {
+                continue;
+            }
+            seen.add(id);
+            const item = nextFibers[id];
+            if (!item) {
+                continue;
+            }
+            nextFibers[id] = {
+                ...item,
+                status: 'cancelled',
+                waitingReason: undefined,
+                suspendPolicy: undefined,
+                timeoutAt: undefined,
+                retryAt: undefined,
+                lastError: action.reason,
+                updatedAt: action.now,
+            };
+            if (action.propagateToChildren) {
+                for (const childId of item.childIds) {
+                    queue.push(childId);
+                }
+            }
+        }
+        return {
+            state: {
+                ...state,
+                fibers: nextFibers,
+            },
+            effects: [],
+        };
+    }
+    return { state, effects: [] };
+}

package/dist-cjs/orchestration/runtimeAdapter.cjs

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchEffects = dispatchEffects;
+function dispatchEffects(runtime, effects, senderId) {
+    const from = senderId ?? '__fiber_scheduler__';
+    for (const effect of effects) {
+        if (effect.kind === 'send') {
+            runtime.sendFrom(from, effect.to, effect.step.tag, effect.step.payload);
+        }
+        if (effect.kind === 'dead_letter' && effect.to && effect.step) {
+            runtime.sendFrom(from, effect.to, effect.step.tag, effect.step.payload);
+        }
+    }
+}

package/dist-cjs/orchestration/scheduler.cjs

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeEffectivePriority = computeEffectivePriority;
+exports.selectNextFiberId = selectNextFiberId;
+exports.scheduleOne = scheduleOne;
+function isSchedulable(fiber) {
+    return fiber.status === 'ready';
+}
+function computeEffectivePriority(fiber, agingStep) {
+    return fiber.basePriority - fiber.age * Math.max(0, agingStep);
+}
+function selectNextFiberId(state, now) {
+    const hooks = state.options.schedulerHooks;
+    const selectionNow = typeof now === 'number' ? now : Date.now();
+    let candidates = Object.values(state.fibers).filter(isSchedulable);
+    if (hooks?.filterCandidates) {
+        candidates = hooks.filterCandidates({ state, candidates, now: selectionNow });
+    }
+    else if (hooks?.filterCandidate) {
+        const f = hooks.filterCandidate;
+        candidates = candidates.filter(fiber => f({ state, fiber, now: selectionNow }));
+    }
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    const agingStep = state.options.agingStep;
+    candidates.sort((a, b) => {
+        const pa = computeEffectivePriority(a, agingStep);
+        const pb = computeEffectivePriority(b, agingStep);
+        if (pa !== pb) {
+            return pa - pb;
+        }
+        return a.order - b.order;
+    });
+    return candidates[0]?.id;
+}
+function scheduleOne(state, now) {
+    const selectedFiberId = selectNextFiberId(state, now);
+    if (!selectedFiberId) {
+        return { state, effects: [] };
+    }
+    const selected = state.fibers[selectedFiberId];
+    if (!selected) {
+        return { state, effects: [] };
+    }
+    const timeoutMs = selected.timeoutMs ?? state.options.defaultTimeoutMs;
+    const timeoutAt = state.options.timeoutEnabled && timeoutMs > 0 ? now + timeoutMs : undefined;
+    const nextFibers = { ...state.fibers };
+    for (const [id, fiber] of Object.entries(state.fibers)) {
+        if (id === selectedFiberId) {
+            nextFibers[id] = {
+                ...fiber,
+                status: 'running',
+                age: 0,
+                timeoutAt,
+                updatedAt: now,
+            };
+            continue;
+        }
+        if (fiber.status === 'ready') {
+            nextFibers[id] = {
+                ...fiber,
+                age: fiber.age + Math.max(0, state.options.agingStep),
+                updatedAt: now,
+            };
+        }
+    }
+    const effects = [];
+    const withStep = nextFibers[selectedFiberId];
+    if (withStep?.step) {
+        effects.push({
+            kind: 'send',
+            fiberId: selectedFiberId,
+            to: withStep.actorId,
+            step: withStep.step,
+        });
+    }
+    return {
+        state: {
+            ...state,
+            fibers: nextFibers,
+        },
+        effects,
+        selectedFiberId,
+    };
+}

package/dist-cjs/orchestration/types.cjs

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ORCHESTRATOR_OPTIONS = void 0;
+exports.DEFAULT_ORCHESTRATOR_OPTIONS = {
+    senderId: '__fiber_scheduler__',
+    agingStep: 1,
+    defaultSuspendPolicy: 'continue_others',
+    timeoutEnabled: false,
+    defaultTimeoutMs: 0,
+    retryEnabled: false,
+    retryDelayMs: 0,
+    retryBackoffMultiplier: 1,
+    deadLetterEnabled: false,
+};

package/dist-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist-cjs/pipeline/ActorPipeline.cjs

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * depa-actor — ActorPipeline
+ *
+ * Adapts the DOP 6-step pipeline (from depa-processor) to actor context.
+ *
+ * Mapping:
+ *   OuterRuntime = ActorSelf
+ *   OuterInput   = envelope payload
+ *   OuterConfig  = actor state
+ *
+ * createPipelineHandler() wraps a pipeline definition into an ActorHandler.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPipelineHandler = createPipelineHandler;
+// ─── createPipelineHandler ───────────────────────────────────────────
+function createPipelineHandler(pipeline) {
+    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);
+    };
+}

package/dist-cjs/runtime/ActorRuntime.cjs

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * depa-actor — ActorRuntime
+ *
+ * Lifecycle and plugin layer over ActorSystem.
+ * ActorSystem = engine, ActorRuntime = managed environment.
+ *
+ * Future AiAgentVm will hold an ActorRuntime instance.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActorRuntime = void 0;
+const ActorSystem_js_1 = require("../core/ActorSystem.cjs");
+// ─── ActorRuntime ────────────────────────────────────────────────────
+class ActorRuntime {
+    system;
+    plugins = [];
+    facets = new Map();
+    constructor(getRuntime, plugins) {
+        this.plugins = plugins ?? [];
+        this.system = new ActorSystem_js_1.ActorSystem(getRuntime, (entry) => this.handleLog(entry));
+    }
+    // ── Plugin management ──
+    addPlugin(plugin) {
+        this.plugins.push(plugin);
+    }
+    hasFacet(name) {
+        return this.facets.has(name);
+    }
+    getFacet(name) {
+        return this.facets.get(name);
+    }
+    setFacet(name, facet) {
+        this.facets.set(name, facet);
+        return facet;
+    }
+    ensureFacet(name, create) {
+        const existing = this.facets.get(name);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = create();
+        this.facets.set(name, created);
+        return created;
+    }
+    // ── Delegated API (convenience) ──
+    register(id, def) {
+        this.system.register(id, def);
+        for (const p of this.plugins) {
+            p.onRegister?.(id, def);
+        }
+    }
+    unregister(id) {
+        this.system.unregister(id);
+        for (const p of this.plugins) {
+            p.onUnregister?.(id);
+        }
+    }
+    sendFrom(from, to, tag, payload) {
+        this.system.sendFrom(from, to, tag, payload);
+    }
+    refFrom(from, to) {
+        return this.system.refFrom(from, to);
+    }
+    ids() {
+        return this.system.ids();
+    }
+    has(id) {
+        return this.system.has(id);
+    }
+    // ── Internal ──
+    handleLog(entry) {
+        for (const p of this.plugins) {
+            p.onLog?.(entry);
+        }
+    }
+}
+exports.ActorRuntime = ActorRuntime;