adispatchd 0.0.0-stage → 0.1.0

package/dist/core/types.js

@@ -0,0 +1,172 @@
+// ---------------------------------------------------------------------------
+// Run status model (Spec §8.1)
+// ---------------------------------------------------------------------------
+/** All technical run states, including the technical extension `recovery_pending`. */
+export const TECHNICAL_STATUSES = [
+    'reserved',
+    'starting',
+    'running',
+    'cancelling',
+    'finalizing',
+    'completed',
+    'crashed',
+    'start_error',
+    'timed_out',
+    'cancelled',
+    'recovery_pending',
+];
+/** Final technical states; a run in one of these never changes state again. */
+export const TERMINAL_STATUSES = ['completed', 'crashed', 'start_error', 'timed_out', 'cancelled'];
+/**
+ * Non-terminal states. A run in one of these holds its lock and counts
+ * towards concurrency. `recovery_pending` keeps the lock to prevent double starts (Spec §14).
+ */
+export const ACTIVE_STATUSES = ['reserved', 'starting', 'running', 'cancelling', 'finalizing', 'recovery_pending'];
+/**
+ * Terminal states that count as technical failures for retry blocks
+ * (Spec §8.1, §11). `cancelled` and business `failure` do not count.
+ */
+export const TECHNICAL_FAILURE_STATUSES = ['crashed', 'start_error', 'timed_out'];
+/** True if `status` is terminal. */
+export function isTerminalStatus(status) {
+    return TERMINAL_STATUSES.includes(status);
+}
+/** True if `status` counts as a technical failure (Spec §11). */
+export function isTechnicalFailure(status) {
+    return TECHNICAL_FAILURE_STATUSES.includes(status);
+}
+/**
+ * Reference state machine for run transitions. Persistence (WI-03) enforces
+ * it; any transition not listed is invalid.
+ *
+ * **Every terminal status is reached only via `finalizing` — no exceptions.**
+ *
+ * Normal path: `reserved → starting → running → finalizing → <terminal>`.
+ *
+ * Finalization protocol (WI-03/WI-08):
+ * 1. `X → finalizing` persists the {@link FinalizationTarget} (columns
+ *    `runs.final_status`, `runs.business_result`, `runs.final_reason`) and, for
+ *    technical failures that reach the limit, the retry block — all in ONE
+ *    transaction (Spec §11 "important order").
+ * 2. The completion hook ({@link hookForOutcome}) runs while `finalizing`.
+ *    After a controller crash, recovery resumes the hook chain of runs still
+ *    in `finalizing` from the persisted target.
+ * 3. `finalizing → target.status` (must equal the persisted target, see
+ *    {@link canTransition}); the lock is released in the same transaction.
+ *
+ * Special cases (also via `finalizing`):
+ * - Cancel before the worker started (`reserved`/`starting` → `cancelling`
+ *   or directly → `finalizing` with target `cancelled`): a uniform path keeps
+ *   the journal and recovery logic simple; WI-08 decides whether `on_cancel`
+ *   runs when `on_start` never ran.
+ * - `on_start` chain failed: `starting → finalizing` with target `start_error`.
+ * - Recovery: `recovery_pending → finalizing` with target `crashed` (or
+ *   `cancelled`) once the process is confirmed gone.
+ *
+ * `cancelling` is entered on a cancel request; `recovery_pending` marks runs
+ * whose process could not be identified or stopped during recovery (keeps the lock).
+ */
+export const RUN_STATUS_TRANSITIONS = {
+    reserved: ['starting', 'cancelling', 'finalizing', 'recovery_pending'],
+    starting: ['running', 'cancelling', 'finalizing', 'recovery_pending'],
+    running: ['cancelling', 'finalizing', 'recovery_pending'],
+    cancelling: ['finalizing', 'recovery_pending'],
+    finalizing: ['completed', 'crashed', 'start_error', 'timed_out', 'cancelled'],
+    recovery_pending: ['finalizing'],
+    completed: [],
+    crashed: [],
+    start_error: [],
+    timed_out: [],
+    cancelled: [],
+};
+/**
+ * True if the reference state machine allows `from → to`. For
+ * `finalizing → <terminal>`, pass the persisted `target`; the transition is
+ * then only valid if `to === target.status`.
+ */
+export function canTransition(from, to, target) {
+    if (!RUN_STATUS_TRANSITIONS[from].includes(to))
+        return false;
+    if (from === 'finalizing' && target !== undefined)
+        return to === target.status;
+    return true;
+}
+/** Lifecycle hooks in declaration order (Spec §10). */
+export const HOOK_NAMES = [
+    'on_start',
+    'on_success',
+    'on_failure',
+    'on_crash',
+    'on_start_error',
+    'on_cancel',
+    'on_timeout',
+];
+/**
+ * The completion hook to run for a final outcome (Spec §8.2 rule 7):
+ * `completed`+`success` → `on_success`, `completed`+`failure` → `on_failure`,
+ * `crashed` → `on_crash`, `start_error` → `on_start_error`,
+ * `timed_out` → `on_timeout`, `cancelled` → `on_cancel`.
+ */
+export function hookForOutcome(status, businessResult) {
+    switch (status) {
+        case 'completed':
+            return businessResult === 'failure' ? 'on_failure' : 'on_success';
+        case 'crashed':
+            return 'on_crash';
+        case 'start_error':
+            return 'on_start_error';
+        case 'timed_out':
+            return 'on_timeout';
+        case 'cancelled':
+            return 'on_cancel';
+    }
+}
+/** Lifecycle action types available in V1 (Spec §10). */
+export const ACTION_TYPES = ['source.update', 'source.comment', 'shell'];
+/** Orchestrator events that can trigger central notifications (Spec §18). */
+export const NOTIFICATION_EVENT_TYPES = ['retry_block_created', 'lifecycle_action_failed', 'recovery_failed'];
+/** Declarative filter operators (Spec §6). */
+export const FILTER_OPERATORS = ['equals', 'not_equals', 'contains', 'in', 'greater_than', 'less_than'];
+/** Type guard for {@link FilterAll}. */
+export function isFilterAll(node) {
+    return 'all' in node;
+}
+/** Type guard for {@link FilterAny}. */
+export function isFilterAny(node) {
+    return 'any' in node;
+}
+/** Type guard for {@link FilterNot}. */
+export function isFilterNot(node) {
+    return 'not' in node;
+}
+/** Type guard for {@link FilterPredicate}. */
+export function isFilterPredicate(node) {
+    return 'field' in node && 'operator' in node;
+}
+/**
+ * Operators that are meaningful per field type; config validation accepts
+ * exactly these. (`equals` on lists is not expressible: list values are only
+ * allowed for `in`.)
+ */
+export const OPERATORS_BY_TYPE = {
+    string: ['equals', 'not_equals', 'contains', 'in'],
+    number: ['equals', 'not_equals', 'in', 'greater_than', 'less_than'],
+    boolean: ['equals', 'not_equals'],
+    date: ['equals', 'not_equals', 'greater_than', 'less_than'],
+    'string[]': ['contains', 'in'],
+};
+/**
+ * Internal run fields available to views (per global item key, latest run by
+ * creation). Not available in workflow filters.
+ */
+export const VIEW_RUN_FIELDS = Object.freeze([
+    { name: 'run.last_id', type: 'string', description: 'ID of the latest run', operators: OPERATORS_BY_TYPE.string },
+    { name: 'run.last_workflow', type: 'string', description: 'Workflow of the latest run', operators: OPERATORS_BY_TYPE.string },
+    { name: 'run.last_status', type: 'string', description: 'Technical status of the latest run', operators: OPERATORS_BY_TYPE.string },
+    { name: 'run.last_result', type: 'string', description: 'Business result (success/failure) of the latest run', operators: OPERATORS_BY_TYPE.string },
+    { name: 'run.last_result.message', type: 'string', description: 'Result message of the latest run', operators: OPERATORS_BY_TYPE.string },
+    { name: 'run.last_status_message', type: 'string', description: 'Last worker status message', operators: OPERATORS_BY_TYPE.string },
+    { name: 'run.last_started_at', type: 'date', description: 'Start of the latest run', operators: OPERATORS_BY_TYPE.date },
+    { name: 'run.last_finished_at', type: 'date', description: 'End of the latest run', operators: OPERATORS_BY_TYPE.date },
+]);
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/worker-protocol.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Worker protocol contract (Spec §9): environment variable names, context
+ * file, result file schema and event line format. Shared by the executor
+ * (writes context, parses result/events), lifecycle (shell actions), API and UI.
+ */
+import { z } from 'zod';
+import type { TriggerType } from './types.js';
+/** Current `schema_version` of context and result files. */
+export declare const WORKER_PROTOCOL_VERSION = 1;
+/** Environment variables provided to every worker (Spec §9.1). */
+export declare const ADISPATCH_ENV: {
+    readonly RUN_ID: 'ADISPATCH_RUN_ID';
+    readonly WORKFLOW_ID: 'ADISPATCH_WORKFLOW_ID';
+    /** Only for source-bound runs. */
+    readonly SOURCE_TYPE: 'ADISPATCH_SOURCE_TYPE';
+    /** Only for source-bound runs. */
+    readonly SOURCE_ID: 'ADISPATCH_SOURCE_ID';
+    /** Only for source-bound runs. */
+    readonly SOURCE_ITEM_ID: 'ADISPATCH_SOURCE_ITEM_ID';
+    /** Only for source-bound runs. */
+    readonly SOURCE_URL: 'ADISPATCH_SOURCE_URL';
+    readonly CONTEXT_FILE: 'ADISPATCH_CONTEXT_FILE';
+    readonly RESULT_FILE: 'ADISPATCH_RESULT_FILE';
+    readonly WORKSPACE: 'ADISPATCH_WORKSPACE';
+};
+/** Content of `context.json` (Spec §9.1). Never contains secrets. */
+export interface WorkerContext {
+    schema_version: typeof WORKER_PROTOCOL_VERSION;
+    run: {
+        id: string;
+        trigger: TriggerType;
+        /** ISO-8601 */
+        started_at: string;
+        /** Cron slot (ISO-8601) for schedule-triggered runs. */
+        scheduled_for?: string;
+    };
+    workflow: {
+        id: string;
+        name?: string;
+    };
+    /** Absent for schedule/manual workflows without an item. */
+    source?: {
+        id: string;
+        type: string;
+        item_id: string;
+        item_key: string;
+        url: string;
+        /** Cheap item fields at start time (e.g. title, labels). */
+        attributes: Record<string, unknown>;
+    };
+    /** Validated manual-start parameters. */
+    parameters: Record<string, string | number | boolean>;
+    workspace: {
+        path: string;
+    };
+}
+/** Maximum accepted size of a result file in bytes. */
+export declare const MAX_RESULT_FILE_BYTES: number;
+/** Artifact reference in a worker result. */
+export declare const workerArtifactSchema: z.ZodObject<{
+    type: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** Schema of the result file `ADISPATCH_RESULT_FILE` (Spec §9.2). */
+export declare const workerResultSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    result: z.ZodEnum<{
+        failure: "failure";
+        success: "success";
+    }>;
+    message: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;
+/** Validated worker result. */
+export type WorkerResult = z.infer<typeof workerResultSchema>;
+/** Artifact entry of a {@link WorkerResult}. */
+export type WorkerArtifact = z.infer<typeof workerArtifactSchema>;
+/**
+ * Parse and validate result-file content. Returns a discriminated result
+ * instead of throwing; any problem means a technical protocol error (Spec §8.2 rule 4).
+ */
+export declare function parseWorkerResult(content: string): {
+    ok: true;
+    result: WorkerResult;
+} | {
+    ok: false;
+    error: string;
+};
+/** Reserved line prefix for structured worker events (Spec §9.3). */
+export declare const ADISPATCH_EVENT_PREFIX = "@@ADISPATCH_EVENT ";
+/** Maximum accepted length of one event line's JSON payload. */
+export declare const MAX_EVENT_LINE_BYTES: number;
+/** Minimal schema of an event payload: an object with a string `type`. */
+export declare const workerEventPayloadSchema: z.ZodObject<{
+    type: z.ZodString;
+}, z.core.$loose>;

package/dist/core/worker-protocol.js

@@ -0,0 +1,75 @@
+/**
+ * Worker protocol contract (Spec §9): environment variable names, context
+ * file, result file schema and event line format. Shared by the executor
+ * (writes context, parses result/events), lifecycle (shell actions), API and UI.
+ */
+import { z } from 'zod';
+/** Current `schema_version` of context and result files. */
+export const WORKER_PROTOCOL_VERSION = 1;
+/** Environment variables provided to every worker (Spec §9.1). */
+export const ADISPATCH_ENV = {
+    RUN_ID: 'ADISPATCH_RUN_ID',
+    WORKFLOW_ID: 'ADISPATCH_WORKFLOW_ID',
+    /** Only for source-bound runs. */
+    SOURCE_TYPE: 'ADISPATCH_SOURCE_TYPE',
+    /** Only for source-bound runs. */
+    SOURCE_ID: 'ADISPATCH_SOURCE_ID',
+    /** Only for source-bound runs. */
+    SOURCE_ITEM_ID: 'ADISPATCH_SOURCE_ITEM_ID',
+    /** Only for source-bound runs. */
+    SOURCE_URL: 'ADISPATCH_SOURCE_URL',
+    CONTEXT_FILE: 'ADISPATCH_CONTEXT_FILE',
+    RESULT_FILE: 'ADISPATCH_RESULT_FILE',
+    WORKSPACE: 'ADISPATCH_WORKSPACE',
+};
+/** Maximum accepted size of a result file in bytes. */
+export const MAX_RESULT_FILE_BYTES = 1024 * 1024;
+/** Artifact reference in a worker result. */
+export const workerArtifactSchema = z
+    .object({
+    type: z.string().min(1).max(64),
+    name: z.string().max(500).optional(),
+    url: z.string().max(4096).optional(),
+})
+    .loose();
+/** Schema of the result file `ADISPATCH_RESULT_FILE` (Spec §9.2). */
+export const workerResultSchema = z.object({
+    schema_version: z.literal(WORKER_PROTOCOL_VERSION),
+    result: z.enum(['success', 'failure']),
+    message: z.string().max(10_000).optional(),
+    details: z.record(z.string(), z.unknown()).optional(),
+    artifacts: z.array(workerArtifactSchema).max(100).optional(),
+});
+/**
+ * Parse and validate result-file content. Returns a discriminated result
+ * instead of throwing; any problem means a technical protocol error (Spec §8.2 rule 4).
+ */
+export function parseWorkerResult(content) {
+    if (Buffer.byteLength(content, 'utf8') > MAX_RESULT_FILE_BYTES) {
+        return { ok: false, error: `result file exceeds ${MAX_RESULT_FILE_BYTES} bytes` };
+    }
+    let json;
+    try {
+        json = JSON.parse(content);
+    }
+    catch (err) {
+        return { ok: false, error: `result file is not valid JSON: ${err.message}` };
+    }
+    const parsed = workerResultSchema.safeParse(json);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+        return { ok: false, error: `result file does not match schema: ${issues}` };
+    }
+    return { ok: true, result: parsed.data };
+}
+/** Reserved line prefix for structured worker events (Spec §9.3). */
+export const ADISPATCH_EVENT_PREFIX = '@@ADISPATCH_EVENT ';
+/** Maximum accepted length of one event line's JSON payload. */
+export const MAX_EVENT_LINE_BYTES = 64 * 1024;
+/** Minimal schema of an event payload: an object with a string `type`. */
+export const workerEventPayloadSchema = z
+    .object({
+    type: z.string().min(1).max(64),
+})
+    .loose();
+//# sourceMappingURL=worker-protocol.js.map

package/dist/core/worker-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-protocol.js","sourceRoot":"","sources":["../../src/core/worker-protocol.ts"],"names":[],"mappings":"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"}

package/dist/executors/classify.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Result classification of a main worker execution (Spec §8.2).
+ *
+ * Binding rules (docs/conventions.md: §8.2 wins over §24.2):
+ * - A non-zero exit code is ALWAYS a technical failure (`crashed`), whatever
+ *   the result file says.
+ * - A business `failure` is only ever derived from a valid result file with
+ *   `result: "failure"` after exit code 0.
+ */
+import type { ExecutionOutcome, OutcomeClassification } from '../core/index.js';
+/**
+ * Classify the raw facts of an execution into the final run outcome,
+ * exactly following the table in Spec §8.2. Pure function.
+ *
+ * Precedence (first match wins):
+ * 1. spawn error → `start_error`
+ * 2. controlled cancel → `cancelled`
+ * 3. timeout → `timed_out`
+ * 4. terminated by a signal → `crashed`
+ * 5. exit code ≠ 0 → `crashed` (result file ignored)
+ * 6. exit code 0 + valid result file → `completed` with its `success`/`failure`
+ * 7. exit code 0 + no result file → `completed` / implicit `success`
+ * 8. exit code 0 + invalid/unreadable result file → `crashed` (protocol error)
+ */
+export declare function classifyOutcome(outcome: ExecutionOutcome): OutcomeClassification;

package/dist/executors/classify.js

@@ -0,0 +1,54 @@
+/**
+ * Classify the raw facts of an execution into the final run outcome,
+ * exactly following the table in Spec §8.2. Pure function.
+ *
+ * Precedence (first match wins):
+ * 1. spawn error → `start_error`
+ * 2. controlled cancel → `cancelled`
+ * 3. timeout → `timed_out`
+ * 4. terminated by a signal → `crashed`
+ * 5. exit code ≠ 0 → `crashed` (result file ignored)
+ * 6. exit code 0 + valid result file → `completed` with its `success`/`failure`
+ * 7. exit code 0 + no result file → `completed` / implicit `success`
+ * 8. exit code 0 + invalid/unreadable result file → `crashed` (protocol error)
+ */
+export function classifyOutcome(outcome) {
+    if (outcome.spawnError) {
+        const code = outcome.spawnError.code ? ` (${outcome.spawnError.code})` : '';
+        return technical('start_error', `worker could not be started${code}: ${outcome.spawnError.message}`);
+    }
+    if (outcome.cancelled) {
+        return technical('cancelled', 'cancelled');
+    }
+    if (outcome.timedOut !== false) {
+        return technical('timed_out', outcome.timedOut === 'idle' ? 'idle timeout exceeded' : 'max duration exceeded');
+    }
+    if (outcome.signal !== null) {
+        return technical('crashed', `terminated by signal ${outcome.signal}`);
+    }
+    if (outcome.exitCode === null) {
+        return technical('crashed', 'process ended without exit code');
+    }
+    if (outcome.exitCode !== 0) {
+        return technical('crashed', `exit code ${outcome.exitCode}`);
+    }
+    switch (outcome.resultFile.state) {
+        case 'valid': {
+            const result = outcome.resultFile.result;
+            return {
+                status: 'completed',
+                businessResult: result.result,
+                reason: result.result === 'success' ? 'exit code 0, result success' : 'exit code 0, result failure',
+                result,
+            };
+        }
+        case 'missing':
+            return { status: 'completed', businessResult: 'success', reason: 'exit code 0, no result file', result: null };
+        case 'invalid':
+            return technical('crashed', `protocol error: ${outcome.resultFile.error}`);
+    }
+}
+function technical(status, reason) {
+    return { status, businessResult: null, reason, result: null };
+}
+//# sourceMappingURL=classify.js.map

package/dist/executors/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/executors/classify.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,SAAS,CAAC,aAAa,EAAE,8BAA8B,IAAI,KAAK,OAAO,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;IACvG,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC;IACjH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC,SAAS,EAAE,wBAAwB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC,SAAS,EAAE,iCAAiC,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC,SAAS,EAAE,aAAa,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,QAAQ,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACjC,KAAK,OAAO,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;YACzC,OAAO;gBACL,MAAM,EAAE,WAAW;gBACnB,cAAc,EAAE,MAAM,CAAC,MAAM;gBAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,6BAA6B;gBACnG,MAAM;aACP,CAAC;QACJ,CAAC;QACD,KAAK,SAAS;YACZ,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,6BAA6B,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QACjH,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC,SAAS,EAAE,mBAAmB,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,MAA6D,EAAE,MAAc;IAC9F,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAChE,CAAC"}

package/dist/executors/dispatcher.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Decoupled, ordered delivery of executor notifications to listeners.
+ *
+ * Emitting never calls listeners synchronously: items are queued and
+ * delivered on a later event-loop turn (`setImmediate`), so slow or throwing
+ * consumers (e.g. SSE) cannot block or break log capture. Delivery order
+ * equals emit order across all channels. Until {@link open} is called, items
+ * are only queued — this lets the caller of `Executor.start()` subscribe
+ * before any early output is delivered.
+ */
+import type { Logger, Unsubscribe } from '../core/index.js';
+type Task = () => void;
+export declare class Dispatcher {
+    private readonly logger?;
+    private readonly queue;
+    private scheduled;
+    private opened;
+    constructor(logger?: Logger | undefined);
+    /** Start delivering (on the next turn) everything queued so far and all later items. */
+    open(): void;
+    /** Queue a task (listener fan-out or completion callback). */
+    enqueue(task: Task): void;
+    private schedule;
+    private drain;
+}
+/** A listener set whose fan-out goes through a {@link Dispatcher}. */
+export declare class Channel<T> {
+    private readonly dispatcher;
+    private readonly logger?;
+    private readonly listeners;
+    constructor(dispatcher: Dispatcher, logger?: Logger | undefined);
+    subscribe(listener: (value: T) => void): Unsubscribe;
+    emit(value: T): void;
+}
+export {};

package/dist/executors/dispatcher.js

@@ -0,0 +1,68 @@
+export class Dispatcher {
+    logger;
+    queue = [];
+    scheduled = false;
+    opened = false;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /** Start delivering (on the next turn) everything queued so far and all later items. */
+    open() {
+        this.opened = true;
+        this.schedule();
+    }
+    /** Queue a task (listener fan-out or completion callback). */
+    enqueue(task) {
+        this.queue.push(task);
+        this.schedule();
+    }
+    schedule() {
+        if (!this.opened || this.scheduled || this.queue.length === 0)
+            return;
+        this.scheduled = true;
+        setImmediate(() => this.drain());
+    }
+    drain() {
+        this.scheduled = false;
+        // Deliver what is queued now; items queued by listeners go to the next turn.
+        const batch = this.queue.splice(0, this.queue.length);
+        for (const task of batch) {
+            try {
+                task();
+            }
+            catch (err) {
+                this.logger?.warn('executor listener threw', { error: err });
+            }
+        }
+        this.schedule();
+    }
+}
+/** A listener set whose fan-out goes through a {@link Dispatcher}. */
+export class Channel {
+    dispatcher;
+    logger;
+    listeners = new Set();
+    constructor(dispatcher, logger) {
+        this.dispatcher = dispatcher;
+        this.logger = logger;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    emit(value) {
+        this.dispatcher.enqueue(() => {
+            for (const listener of [...this.listeners]) {
+                try {
+                    listener(value);
+                }
+                catch (err) {
+                    this.logger?.warn('executor listener threw', { error: err });
+                }
+            }
+        });
+    }
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/executors/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/executors/dispatcher.ts"],"names":[],"mappings":"AAcA,MAAM,OAAO,UAAU;IAKQ,MAAM;IAJlB,KAAK,GAAW,EAAE,CAAC;IAC5B,SAAS,GAAG,KAAK,CAAC;IAClB,MAAM,GAAG,KAAK,CAAC;IAEvB,YAA6B,MAAe;sBAAf,MAAM;IAAY,CAAC;IAEhD,wFAAwF;IACxF,IAAI;QACF,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAED,8DAA8D;IAC9D,OAAO,CAAC,IAAU;QAChB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;IAEO,QAAQ;QACd,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACtE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,YAAY,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;IACnC,CAAC;IAEO,KAAK;QACX,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,6EAA6E;QAC7E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACtD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,IAAI,EAAE,CAAC;YACT,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,yBAAyB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;IAClB,CAAC;CACF;AAED,sEAAsE;AACtE,MAAM,OAAO,OAAO;IAIC,UAAU;IACV,MAAM;IAJR,SAAS,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE3D,YACmB,UAAsB,EACtB,MAAe;0BADf,UAAU;sBACV,MAAM;IACtB,CAAC;IAEJ,SAAS,CAAC,QAA4B;QACpC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAQ;QACX,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE;YAC3B,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3C,IAAI,CAAC;oBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAClB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,yBAAyB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC/D,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/executors/env.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Worker environment (Spec §9.1, §20.3): workers never inherit the controller
+ * environment. They get a minimal set of standard variables, the explicitly
+ * declared `env`, resolved secrets and the `ADISPATCH_*` protocol variables.
+ */
+import { type WorkerContext } from '../core/index.js';
+/** Variables copied from the controller environment (if set). */
+export declare const MINIMAL_ENV_KEYS: readonly ['PATH', 'HOME', 'LANG', 'TZ', 'USER', 'LOGNAME', 'TMPDIR'];
+/** PATH used when the controller has none. */
+export declare const FALLBACK_PATH = "/usr/local/bin:/usr/bin:/bin";
+/** Pick the minimal standard variables from `base` (default `process.env`). */
+export declare function buildMinimalEnv(base?: NodeJS.ProcessEnv): Record<string, string>;
+/** Source block of a context as used for `ADISPATCH_SOURCE_*` (shape of `WorkerContext.source`). */
+export interface OrchSourceInfo {
+    id: string;
+    type: string;
+    item_id: string;
+    url: string;
+}
+/**
+ * Extract a `source` block from any context object (main-worker context or a
+ * custom shell-action context). Returns `undefined` unless all fields are strings.
+ */
+export declare function contextSource(context: WorkerContext | Readonly<Record<string, unknown>>): OrchSourceInfo | undefined;
+/** `ADISPATCH_*` variables for a worker (Spec §9.1). */
+export declare function buildOrchEnv(input: {
+    runId: string;
+    workflowId: string;
+    context: WorkerContext | Readonly<Record<string, unknown>>;
+    contextFile: string;
+    resultFile: string;
+    workspace: string;
+}): Record<string, string>;
+/**
+ * Compose the full worker environment. Precedence (later wins): minimal env
+ * < declared `env` < `secrets` < `ADISPATCH_*` (protocol variables cannot be overridden).
+ */
+export declare function buildWorkerEnv(parts: {
+    base?: NodeJS.ProcessEnv;
+    env?: Readonly<Record<string, string>>;
+    secrets?: Readonly<Record<string, string>>;
+    orch: Readonly<Record<string, string>>;
+}): Record<string, string>;