export interface ExecutionOptions {
    /** Strip internal proxy wrappers and return clean plain JavaScript objects (default: true). Output path always normalizes via toPOJO. */
    pojo?: boolean;

    /** Compatibility option for return format: 'pojo' (default) or 'wrapped'. */
    mode?: 'pojo' | 'wrapped';

    /** Cooperative cancellation signal aborting in-flight async steps and retry delays. */
    signal?: AbortSignal;

    /** Overall workflow SLA deadline in milliseconds. */
    timeout?: number;
    timeoutMs?: number;

    /** Dependency injection container accessible inside steps via param.$services. */
    services?: Record<string, any>;
    dependencies?: Record<string, any>;

    /** Enables durable checkpoint persistence upon wait/suspend. */
    durable?: boolean;

    /** Explicit checkpoint capture flag. */
    checkpoint?: boolean;

    /** Workflow schema version for migration verification upon resumption. */
    workflowVersion?: string | number;

    /** State migration map (e.g. { 'v1->v2': (from, to, state) => newState }) or single migration function. */
    migrations?:
        | Record<string, (fromVersion: any, toVersion: any, state: any) => any>
        | ((fromVersion: any, toVersion: any, state: any) => any);

    /** Multi-tenant partition namespace scoping checkpoints, caches, and idempotency keys. */
    namespace?: string;

    /** Workflow-level idempotency deduplication key or generator function. */
    idempotencyKey?: string | ((ctx: any) => string);

    /** Custom idempotency store adapter. */
    idempotencyStore?: IdempotencyStore;

    /** Retention TTL for idempotency records in milliseconds (Postgres/Redis default: 24h; InMemory: no expiry unless set). */
    idempotencyTtlMs?: number;

    /** Settle polling timeout and interval for concurrent in-progress idempotency claims. */
    settleTimeoutMs?: number;
    pollIntervalMs?: number;

    /** Custom predicate for classifying permanent non-retryable business errors. */
    isPermanentError?: (err: any) => boolean;

    /** Execution hook intercepting step starts and completions within AsyncLocalStorage context. */
    stepExecutionHook?: StepExecutionHook;

    /** Dynamic network egress policy config for this run. */
    networkPolicy?: NetworkPolicyConfig;

    /** Live monitoring event emitter or callback. */
    monitor?: WorkflowEventEmitter | ((event: WorkflowExecutionEvent) => void);

    /** Custom workflow identifier attached to telemetry, logs, and checkpoints. */
    workflowId?: string;

    /** Explicit caller-supplied execution stack ID. */
    stackId?: string;

    /** Internal flag indicating resumption execution. */
    isResume?: boolean;

    /** Optional pre-compiled workflow AST. */
    ast?: WorkflowNode;
}

const result = await myFlow.run(input, { pojo: true });
console.log(result); // Clean plain object

const controller = new AbortController();

setTimeout(() => {
    controller.abort(new Error('User cancelled the operation'));
}, 5000);

try {
    await myFlow.run(input, { signal: controller.signal });
} catch (err) {
    if (err instanceof CancellationException) {
        console.log('Workflow successfully aborted:', err.message);
    }
}

await myFlow.run(input, { timeout: 10000 }); // 10-second deadline

const myFlow = flow(
    Step.create('charge', async (param: any) => {
        const paymentGateway = param.$services.paymentGateway;
        return await paymentGateway.charge(param.amount);
    }),
);

await myFlow.run(
    { amount: 50 },
    {
        services: {
            paymentGateway: new StripePaymentGateway(apiKey),
        },
    },
);

const result = await myFlow.run({ orderId: 'ord_123' }, { durable: true });
if (result.status === 'waiting') {
    console.log(`Workflow suspended with stackId: ${result.stackId}`);
}

const migrations = {
    // Migrates checkpoint created under v1 to v2 schema
    'v1->v2': (fromVersion: string, toVersion: string, oldState: any) => ({
        ...oldState,
        customerFullName: `${oldState.firstName} ${oldState.lastName}`,
    }),
};

await resumeWorkflow(orderWorkflowV2, correlationKey, eventPayload, {
    targetVersion: 'v2',
    migrations,
});

await tenantFlow.run(tenantPayload, {
    namespace: 'org_enterprise_tenant_99',
});

await orderFlow.run(payload, {
    idempotencyKey: ctx => `checkout:${ctx.orderId}`,
});

await myFlow.run(payload, {
    stepExecutionHook: {
        onStepStart: context => console.log(`Starting step ${context.stepName}`),
        onStepEnd: (context, result) => console.log(`Finished step ${context.stepName}`),
    },
});

await myFlow.run(payload, {
    networkPolicy: {
        allowedHosts: ['api.stripe.com'],
        defaultPolicy: 'deny',
        allowLocalhost: true,
    },
});

import { Step, flow } from '@siglo/core';
import { RedisStorageAdapter } from '@siglo/redis';
import { PostgresIdempotencyStore } from '@siglo/postgres';

const checkoutFlow = flow(
    Step.create('reserveInventory', async (ctx: { sku: string; qty: number }) => {
        return { reserved: true };
    }),
    Step.create('processPayment', async (ctx: { amount: number }) => {
        return { paymentId: 'pay_999' };
    }),
);

async function handleOrderWebhook(request: any) {
    const abortController = new AbortController();

    const options = {
        pojo: true,
        signal: abortController.signal,
        timeout: 15000, // 15s SLA
        namespace: request.tenantId,
        workflowId: 'order-checkout',
        workflowVersion: 'v2.0',
        durable: true,
        idempotencyKey: `order:${request.body.orderId}`,
        idempotencyTtlMs: 24 * 60 * 60 * 1000,
        services: {
            db: request.dbClient,
            metrics: request.metricsReporter,
        },
    };

    return await checkoutFlow.run(request.body, options);
}