@drej/core 0.2.0

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+/** Base class for all drej workflow runtime errors. */
+export declare class WorkflowError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a sandbox fails to create, boot, or reach `Running` state. */
+export declare class SandboxError extends WorkflowError {
+    /** The sandbox ID, if one was assigned before the failure. */
+    readonly sandboxId?: string | undefined;
+    constructor(message: string, 
+    /** The sandbox ID, if one was assigned before the failure. */
+    sandboxId?: string | undefined);
+}
+/**
+ * Thrown when execd inside a sandbox never becomes ready within the retry window.
+ * The sandbox is `Running` from the control plane's perspective, but the exec
+ * daemon is not accepting connections.
+ */
+export declare class ExecConnectionError extends WorkflowError {
+    readonly sandboxId: string;
+    constructor(sandboxId: string);
+}
+/**
+ * Thrown when an `exec()` step exits with a non-zero exit code and the
+ * `strict` option is enabled. Carries the exit code and original command.
+ */
+export declare class CommandError extends WorkflowError {
+    readonly exitCode: number;
+    readonly command: string;
+    readonly sandboxId: string;
+    constructor(exitCode: number, command: string, sandboxId: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { LedgerEvent } from "./ledger";
+export type { LedgerEntry, IStorageAdapter } from "./ledger";
+export { LogLevel, ConsoleLogger, noopLogger } from "./logger";
+export type { ILogger } from "./logger";
+export { Workflow, WorkflowStatus } from "./workflow";
+export type { WorkflowRunContext, WorkflowStep, WorkflowCheckpoint, WorkflowDeps, WorkflowHooks, } from "./workflow";
+export { buildStep, resolveExecClient, shouldSnapshot, waitForSnapshot } from "./steps";
+export type { StepDef, Predicate, WorkflowState, SnapshotConfig } from "./steps";
+export { validateWorkflow } from "./validate";
+export { WorkflowError, SandboxError, ExecConnectionError, CommandError } from "./errors";

package/dist/ledger.d.ts

@@ -0,0 +1,67 @@
+/** Events emitted during workflow execution and stored in the ledger. */
+export declare enum LedgerEvent {
+    /** Emitted once when a workflow run starts, before any steps execute. */
+    RunStarted = "run_started",
+    /** Emitted at the beginning of each step. */
+    StepStart = "step_start",
+    /** Emitted when a step finishes successfully. */
+    StepComplete = "step_complete",
+    /** Emitted when a step throws an unrecoverable error. */
+    StepFailed = "step_failed",
+    /** Emitted when a step's rollback handler completes during saga compensation. */
+    StepRolledBack = "step_rolled_back",
+    /** Emitted after all steps finish without error. */
+    WorkflowComplete = "workflow_complete",
+    /** Emitted after rollback completes following a step failure. */
+    WorkflowFailed = "workflow_failed",
+    /** Durable resumption point written after each successful step. */
+    Checkpoint = "checkpoint",
+    /** Streaming output chunk from `exec()` or `execCode()`. */
+    ExecEvent = "exec_event",
+    /** Emitted when a sandbox snapshot is captured mid-run. */
+    Snapshot = "snapshot"
+}
+/** A single event record written to the storage adapter during a workflow run. */
+export interface LedgerEntry {
+    /** Unix timestamp in milliseconds. */
+    ts: number;
+    workflowName: string;
+    runId: string;
+    /** Zero-based index of the step that produced this event. `-1` for run-level events. */
+    stepIndex: number;
+    /** Parallel branch index, when this step is inside a `parallel()` block. */
+    branch?: number;
+    event: LedgerEvent;
+    /** Event-specific data (step output, snapshot ID, exec text, etc.). */
+    payload?: unknown;
+    /** Error message when `event` is `StepFailed` or `WorkflowFailed`. */
+    error?: string;
+}
+/**
+ * Persistence interface for workflow event storage.
+ *
+ * Implement this interface to plug in any storage backend. drej ships two
+ * official implementations: `@drej/sqlite` (local dev, zero infra) and
+ * `@drej/postgres` (production).
+ *
+ * @example
+ * ```ts
+ * import { SQLiteAdapter } from "@drej/sqlite";
+ * const client = new DrejClient({ baseUrl, adapter: new SQLiteAdapter("./drej.db") });
+ * await client.connect();
+ * ```
+ */
+export interface IStorageAdapter {
+    /** Run migrations / open connections. Must be called before first use. */
+    connect?(): Promise<void>;
+    /** Release connections and resources. Call on graceful shutdown. */
+    close?(): Promise<void>;
+    /** Persist a single ledger event. Called automatically during workflow execution. */
+    append(entry: LedgerEntry): Promise<void>;
+    /** Return all events for a specific run, in ascending timestamp order. */
+    readAll(workflowName: string, runId: string): Promise<LedgerEntry[]>;
+    /** Return the most recent checkpoint entry for a run, or `null` if none exists. */
+    lastCheckpoint(workflowName: string, runId: string): Promise<LedgerEntry | null>;
+    /** Return all run IDs recorded under a workflow name. */
+    listRuns(workflowName: string): Promise<string[]>;
+}

package/dist/logger.d.ts

@@ -0,0 +1,23 @@
+export declare enum LogLevel {
+    Debug = 0,
+    Info = 1,
+    Warn = 2,
+    Error = 3,
+    Silent = 4
+}
+export interface ILogger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+export declare class ConsoleLogger implements ILogger {
+    private readonly minLevel;
+    constructor(minLevel?: LogLevel);
+    private log;
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+export declare const noopLogger: ILogger;

package/dist/steps.d.ts

@@ -0,0 +1,100 @@
+import { ControlClient, ExecClient } from "@drej/opensandbox";
+import type { WorkflowStep } from "./workflow";
+export type Predicate = {
+    op: "eq" | "neq";
+    field: string;
+    value: unknown;
+} | {
+    op: "gt" | "lt" | "gte" | "lte";
+    field: string;
+    value: number;
+} | {
+    op: "exists" | "not_exists";
+    field: string;
+} | {
+    op: "and" | "or";
+    predicates: Predicate[];
+};
+export type StepDef = {
+    type: "create_sandbox";
+    image?: {
+        uri: string;
+        auth?: {
+            username: string;
+            password: string;
+        };
+    };
+    snapshotId?: string;
+    timeout?: number;
+    entrypoint?: string[];
+    env?: Record<string, string>;
+    metadata?: Record<string, string>;
+    resourceLimits?: {
+        cpu?: string;
+        memory?: string;
+        gpu?: string;
+    };
+} | {
+    type: "exec_code";
+    code: string;
+    context?: {
+        id: string;
+        language: string;
+    };
+} | {
+    type: "exec_command";
+    command: string;
+    cwd?: string;
+    envs?: Record<string, string>;
+    capture?: string;
+    strict?: boolean;
+} | {
+    type: "delete_sandbox";
+} | {
+    type: "write_file";
+    path: string;
+    content: string;
+    encoding?: "utf8" | "base64";
+} | {
+    type: "read_file";
+    path: string;
+    as: string;
+    encoding?: "utf8" | "base64";
+} | {
+    type: "snapshot";
+} | {
+    type: "retry";
+    step: StepDef;
+    maxAttempts: number;
+    delayMs?: number;
+    backoff?: "fixed" | "exponential";
+} | {
+    type: "conditional";
+    condition: Predicate;
+    then: StepDef[];
+    else?: StepDef[];
+} | {
+    type: "loop";
+    over?: string;
+    items?: unknown[];
+    as: string;
+    steps: StepDef[];
+    concurrently?: boolean;
+} | {
+    type: "parallel";
+    steps: StepDef[];
+} | {
+    type: "sequence";
+    steps: StepDef[];
+};
+export type WorkflowState = Record<string, unknown> & {
+    sandboxId?: string;
+};
+export interface SnapshotConfig {
+    afterSteps?: number[];
+    everyNSteps?: number;
+}
+export declare function resolveExecClient(control: ControlClient, sandboxId: string, retries?: number, delayMs?: number): Promise<ExecClient>;
+export declare function shouldSnapshot(config: SnapshotConfig, stepIndex: number): boolean;
+export declare function waitForSnapshot(control: ControlClient, snapshotId: string, timeoutMs?: number): Promise<void>;
+export declare function buildStep(def: StepDef): WorkflowStep;

package/dist/validate.d.ts

@@ -0,0 +1,2 @@
+import type { StepDef } from "./steps";
+export declare function validateWorkflow(name: string, steps: StepDef[]): void;

package/dist/workflow.d.ts

@@ -0,0 +1,99 @@
+import type { IStorageAdapter, LedgerEntry } from "./ledger";
+import type { ControlClient, ExecClient } from "@drej/opensandbox";
+import type { ILogger } from "./logger";
+export interface WorkflowRunContext {
+    readonly workflowName: string;
+    readonly runId: string;
+    readonly stepIndex: number;
+    readonly control: ControlClient;
+    readonly resolveExec: (sandboxId: string) => Promise<ExecClient>;
+    emit(entry: LedgerEntry): Promise<void>;
+}
+export interface WorkflowStep {
+    readonly id: string;
+    run(input: unknown, ctx: WorkflowRunContext): Promise<unknown>;
+    rollback?(output: unknown, ctx: WorkflowRunContext): Promise<void>;
+}
+export interface WorkflowCheckpoint {
+    workflowName: string;
+    runId: string;
+    stepIndex: number;
+    completedSteps: Record<number, {
+        output: unknown;
+        completedAt: number;
+    }>;
+    timestamp: number;
+}
+export declare enum WorkflowStatus {
+    Idle = "idle",
+    Running = "running",
+    Completed = "completed",
+    Failed = "failed",
+    RolledBack = "rolled_back"
+}
+export interface WorkflowHooks {
+    onStepStart?(info: {
+        workflowName: string;
+        runId: string;
+        stepIndex: number;
+        stepId: string;
+    }): void | Promise<void>;
+    onStepComplete?(info: {
+        workflowName: string;
+        runId: string;
+        stepIndex: number;
+        stepId: string;
+        output: unknown;
+    }): void | Promise<void>;
+    onStepFailed?(info: {
+        workflowName: string;
+        runId: string;
+        stepIndex: number;
+        stepId: string;
+        error: Error;
+    }): void | Promise<void>;
+    onStepRolledBack?(info: {
+        workflowName: string;
+        runId: string;
+        stepIndex: number;
+        stepId: string;
+    }): void | Promise<void>;
+    onWorkflowComplete?(info: {
+        workflowName: string;
+        runId: string;
+        output: unknown;
+    }): void | Promise<void>;
+    onWorkflowFailed?(info: {
+        workflowName: string;
+        runId: string;
+        error: Error;
+    }): void | Promise<void>;
+}
+export interface WorkflowDeps {
+    control: ControlClient;
+    resolveExec: (sandboxId: string) => Promise<ExecClient>;
+    adapter: IStorageAdapter;
+    logger?: ILogger;
+    hooks?: WorkflowHooks;
+}
+export declare class Workflow {
+    private readonly steps;
+    private readonly deps;
+    readonly name: string;
+    readonly runId: string;
+    private _status;
+    private readonly completedSteps;
+    private readonly log;
+    get status(): WorkflowStatus;
+    constructor(name: string, runId: string, steps: WorkflowStep[], deps: WorkflowDeps);
+    private callHook;
+    run(input: unknown, startFromStep?: number): Promise<unknown>;
+    rollback(toStep?: number): Promise<void>;
+    snapshot(): WorkflowCheckpoint;
+    static resumeFromLedger(workflowName: string, runId: string, steps: WorkflowStep[], deps: WorkflowDeps): Promise<{
+        workflow: Workflow;
+        nextStep: number;
+        lastOutput: unknown;
+    }>;
+    private makeContext;
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@drej/core",
+  "version": "0.2.0",
+  "main": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build:types": "tsc --project tsconfig.build.json"
+  },
+  "dependencies": {
+    "@drej/opensandbox": "workspace:*"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "latest"
+  }
+}