reqon-dsl 0.2.0 → 0.4.0

package/dist/execution-log/events.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Execution event log — the durable, append-only record of a mission run.
+ *
+ * Every step's start, completion, and side effect is appended as it happens.
+ * Resume becomes "replay the log and fold to last state" (see {@link ./fold}),
+ * and trace/time-travel, audit, and idempotent resume all derive from this one
+ * structure. Recorded values (timestamps, effect ids, outputs) are read back on
+ * replay rather than re-derived, so replay is deterministic.
+ */
+export type ExecutionEventType = 'mission.started' | 'step.started' | 'step.completed' | 'effect.applied' | 'page.completed' | 'checkpoint.advanced' | 'pause.created' | 'pause.resumed' | 'mission.completed' | 'mission.failed';
+interface BaseEvent {
+    /** The run this event belongs to. */
+    executionId: string;
+    /** Event kind (discriminant). */
+    type: ExecutionEventType;
+}
+export interface MissionStartedEvent extends BaseEvent {
+    type: 'mission.started';
+    mission: string;
+}
+export interface StepStartedEvent extends BaseEvent {
+    type: 'step.started';
+    stepId: string;
+    action: string;
+    stepType: string;
+    attempt: number;
+}
+export interface StepCompletedEvent extends BaseEvent {
+    type: 'step.completed';
+    stepId: string;
+    attempt: number;
+}
+/**
+ * A side effect (a fetch or a store write) was applied. The {@link effectId}
+ * is the stable identity used to skip already-applied effects on replay.
+ */
+export interface EffectAppliedEvent extends BaseEvent {
+    type: 'effect.applied';
+    stepId: string;
+    attempt: number;
+    effectType: 'fetch' | 'store';
+    effectId: string;
+}
+/**
+ * A page of a resumable (backfill) paginated fetch finished — its data is
+ * fetched and persisted. Carries the position to resume from: the next page
+ * index and/or cursor. `done` marks the natural end of pagination (the API had
+ * no more), distinct from stopping early on a per-run item cap, so a resume
+ * knows whether to continue or skip.
+ */
+export interface PageCompletedEvent extends BaseEvent {
+    type: 'page.completed';
+    stepId: string;
+    /** Zero-based index of the next page to fetch on resume. */
+    page: number;
+    /** Cursor to resume from (cursor-based pagination). */
+    cursor?: string;
+    /**
+     * Records *fetched* on this page. NOTE: this is the fetched count, not the
+     * persisted count — the page's data is still only in memory when this event is
+     * recorded; the downstream store step persists it afterwards. A crash between
+     * this event and the store's `effect.applied` advances the resume cursor past a
+     * page whose data was never stored. See the known crash-window note in
+     * CODE_REVIEW.md (C2); a full fix defers this advance until after persistence.
+     */
+    recordCount?: number;
+    /** True once pagination has reached its natural end. */
+    done: boolean;
+}
+export interface CheckpointAdvancedEvent extends BaseEvent {
+    type: 'checkpoint.advanced';
+    key: string;
+    syncedAt: string;
+    /** Records fetched in the sync that advanced this checkpoint. */
+    recordCount?: number;
+    /** Opaque pagination cursor to resume from (cursor-based incremental sync). */
+    cursor?: string;
+    /** Mission that advanced the checkpoint (lets a shared log filter by mission). */
+    mission?: string;
+}
+export interface PauseCreatedEvent extends BaseEvent {
+    type: 'pause.created';
+    pauseId: string;
+    /**
+     * The full durable pause state (expiry, resume triggers, captured checkpoint).
+     * Carried in the log so a paused run — and the timer/webhook it waits on — can
+     * be reconstructed from the log alone, no separate pause file. Opaque to the
+     * log layer (typed `unknown` to avoid coupling it to the pause domain).
+     */
+    pause?: unknown;
+}
+export interface PauseResumedEvent extends BaseEvent {
+    type: 'pause.resumed';
+    pauseId: string;
+    resumedBy: string;
+    /** Terminal status of the pause: resumed (default), cancelled, or expired. */
+    status?: 'resumed' | 'cancelled' | 'expired';
+    /** Recorded resume time (ISO 8601). */
+    resumedAt?: string;
+    /** Payload delivered by a webhook resume. */
+    webhookPayload?: unknown;
+}
+export interface MissionCompletedEvent extends BaseEvent {
+    type: 'mission.completed';
+}
+export interface MissionFailedEvent extends BaseEvent {
+    type: 'mission.failed';
+    error: string;
+}
+/** An event as appended by a caller (the log assigns seq + timestamp). */
+export type ExecutionEvent = MissionStartedEvent | StepStartedEvent | StepCompletedEvent | EffectAppliedEvent | PageCompletedEvent | CheckpointAdvancedEvent | PauseCreatedEvent | PauseResumedEvent | MissionCompletedEvent | MissionFailedEvent;
+/** A persisted event: the appended event plus the log's assigned metadata. */
+export type StoredEvent = ExecutionEvent & {
+    /** Monotonic sequence within the execution, starting at 0. */
+    seq: number;
+    /** Recorded wall-clock time (ISO 8601); read back on replay, never re-derived. */
+    at: string;
+};
+/**
+ * Stable identity for a side effect: `(executionId, stepId, attempt, effectType)`
+ * plus a caller-supplied discriminator (e.g. the request signature or record
+ * key). Replay uses this to skip effects already recorded as applied.
+ */
+export declare function effectId(executionId: string, stepId: string, attempt: number, effectType: 'fetch' | 'store', discriminator: string): string;
+export {};

package/dist/execution-log/events.js

@@ -0,0 +1,17 @@
+/**
+ * Execution event log — the durable, append-only record of a mission run.
+ *
+ * Every step's start, completion, and side effect is appended as it happens.
+ * Resume becomes "replay the log and fold to last state" (see {@link ./fold}),
+ * and trace/time-travel, audit, and idempotent resume all derive from this one
+ * structure. Recorded values (timestamps, effect ids, outputs) are read back on
+ * replay rather than re-derived, so replay is deterministic.
+ */
+/**
+ * Stable identity for a side effect: `(executionId, stepId, attempt, effectType)`
+ * plus a caller-supplied discriminator (e.g. the request signature or record
+ * key). Replay uses this to skip effects already recorded as applied.
+ */
+export function effectId(executionId, stepId, attempt, effectType, discriminator) {
+    return `${executionId}::${stepId}::${attempt}::${effectType}::${discriminator}`;
+}

package/dist/execution-log/fold.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fold an execution event log down to current state.
+ *
+ * This is the heart of replay-based resume: replaying the log and folding it
+ * yields the exact state the run was in, including which effects already
+ * applied (so replay skips them) and which pause it is waiting on.
+ */
+import type { StoredEvent } from './events.js';
+export type FoldedStatus = 'pending' | 'running' | 'paused' | 'completed' | 'failed';
+export interface FoldedState {
+    status: FoldedStatus;
+    /** Sequence of the last event folded (-1 for an empty log). */
+    lastSeq: number;
+    /** Step ids that have completed (replay skips re-running them). */
+    completedSteps: Set<string>;
+    /** Effect ids already applied (replay skips re-applying them). */
+    appliedEffects: Set<string>;
+    /** Latest synced-at per checkpoint key. */
+    checkpoints: Map<string, string>;
+    /** Resume position per backfill step id (last persisted page + cursor). */
+    pageProgress: Map<string, {
+        page: number;
+        cursor?: string;
+        done: boolean;
+    }>;
+    /** The pause this run is currently waiting on, if any. */
+    pendingPauseId?: string;
+    /**
+     * The last pause marked resumed in the log. A resume trigger (webhook/timeout)
+     * can record `pause.resumed` before the executor re-runs, so this lets the
+     * executor recognise it must continue past that pause rather than create a new
+     * one. Cleared once the run completes or fails.
+     */
+    resumedPauseId?: string;
+    /** Error message if the run failed. */
+    error?: string;
+}
+export declare function foldLog(events: StoredEvent[]): FoldedState;

package/dist/execution-log/fold.js

@@ -0,0 +1,54 @@
+export function foldLog(events) {
+    const state = {
+        status: 'pending',
+        lastSeq: -1,
+        completedSteps: new Set(),
+        appliedEffects: new Set(),
+        checkpoints: new Map(),
+        pageProgress: new Map(),
+    };
+    for (const event of events) {
+        state.lastSeq = event.seq;
+        switch (event.type) {
+            case 'mission.started':
+                state.status = 'running';
+                break;
+            case 'step.completed':
+                state.completedSteps.add(event.stepId);
+                break;
+            case 'effect.applied':
+                state.appliedEffects.add(event.effectId);
+                break;
+            case 'page.completed':
+                state.pageProgress.set(event.stepId, {
+                    page: event.page,
+                    cursor: event.cursor,
+                    done: event.done,
+                });
+                break;
+            case 'checkpoint.advanced':
+                state.checkpoints.set(event.key, event.syncedAt);
+                break;
+            case 'pause.created':
+                state.status = 'paused';
+                state.pendingPauseId = event.pauseId;
+                break;
+            case 'pause.resumed':
+                state.status = 'running';
+                state.pendingPauseId = undefined;
+                state.resumedPauseId = event.pauseId;
+                break;
+            case 'mission.completed':
+                state.status = 'completed';
+                state.resumedPauseId = undefined;
+                break;
+            case 'mission.failed':
+                state.status = 'failed';
+                state.error = event.error;
+                state.resumedPauseId = undefined;
+                break;
+            // step.started carries no folded state on its own.
+        }
+    }
+    return state;
+}

package/dist/execution-log/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Execution event log — the append-only foundation for durable execution.
+ *
+ * A running mission is modelled as an ordered log of events; resume is replay +
+ * fold (see {@link foldLog}), and idempotent effects fall out of recording an
+ * `effect.applied` event per side effect. This module is the seam the rest of
+ * the durable-execution work (transactional backend, exactly-once effects,
+ * trace/sync/pause as log views) builds on.
+ */
+export type { ExecutionEvent, StoredEvent, ExecutionEventType, MissionStartedEvent, StepStartedEvent, StepCompletedEvent, EffectAppliedEvent, CheckpointAdvancedEvent, PauseCreatedEvent, PauseResumedEvent, MissionCompletedEvent, MissionFailedEvent, } from './events.js';
+export { effectId } from './events.js';
+export type { ExecutionLogStore, CheckpointRecord } from './store.js';
+export { MemoryExecutionLog, FileExecutionLog, reduceCheckpoints } from './store.js';
+export { SqliteExecutionLog } from './sqlite-store.js';
+export { PostgresExecutionLog, type PostgresExecutionLogOptions } from './postgres-store.js';
+export type { FoldedState, FoldedStatus } from './fold.js';
+export { foldLog } from './fold.js';
+export { loadState } from './resume.js';

package/dist/execution-log/index.js

@@ -0,0 +1,6 @@
+export { effectId } from './events.js';
+export { MemoryExecutionLog, FileExecutionLog, reduceCheckpoints } from './store.js';
+export { SqliteExecutionLog } from './sqlite-store.js';
+export { PostgresExecutionLog } from './postgres-store.js';
+export { foldLog } from './fold.js';
+export { loadState } from './resume.js';

package/dist/execution-log/postgres-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Postgres-backed execution log — a transactional, multi-node durable backend.
+ *
+ * Like the SQLite backend, `pg` is an *optional* peer dependency imported lazily
+ * via a non-literal specifier, so the core package carries no database driver
+ * and a missing one yields a clear, actionable error.
+ *
+ * Multi-writer safety: `seq` is assigned inside the INSERT under a
+ * `(execution_id, seq)` primary key. If two appenders race and compute the same
+ * next seq, one wins and the other gets a unique-violation (SQLSTATE 23505) and
+ * retries against the now-higher max — so concurrent appenders always land on
+ * distinct, contiguous sequence numbers.
+ */
+import type { ExecutionEvent, StoredEvent } from './events.js';
+import type { CheckpointRecord, ExecutionLogStore } from './store.js';
+export interface PostgresExecutionLogOptions {
+    /** Table to store events in. Default `reqon_execution_events`. */
+    table?: string;
+}
+export declare class PostgresExecutionLog implements ExecutionLogStore {
+    private connectionString;
+    private pool?;
+    private ready?;
+    private readonly table;
+    constructor(connectionString: string, options?: PostgresExecutionLogOptions);
+    private ensure;
+    private init;
+    append(event: ExecutionEvent): Promise<StoredEvent>;
+    read(executionId: string): Promise<StoredEvent[]>;
+    listCheckpoints(mission?: string): Promise<CheckpointRecord[]>;
+    listPauses(): Promise<StoredEvent[]>;
+    /** Drop all rows. Intended for test setup, not production use. */
+    reset(): Promise<void>;
+    /** Release the connection pool. */
+    close(): Promise<void>;
+}

package/dist/execution-log/postgres-store.js

@@ -0,0 +1,108 @@
+import { reduceCheckpoints } from './store.js';
+const UNIQUE_VIOLATION = '23505';
+const MAX_APPEND_ATTEMPTS = 8;
+export class PostgresExecutionLog {
+    connectionString;
+    pool;
+    ready;
+    table;
+    constructor(connectionString, options = {}) {
+        this.connectionString = connectionString;
+        this.table = options.table ?? 'reqon_execution_events';
+        // The table name is interpolated into SQL (identifiers can't be bound), so
+        // constrain it to a safe identifier to keep that interpolation injection-free.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(this.table)) {
+            throw new Error(`Invalid table name: ${this.table}`);
+        }
+    }
+    async ensure() {
+        if (this.pool)
+            return this.pool;
+        if (!this.ready)
+            this.ready = this.init();
+        return this.ready;
+    }
+    async init() {
+        let Pool;
+        try {
+            // Non-literal specifier: keeps the driver an optional dependency with no
+            // compile-time type coupling (no @types/pg required).
+            const specifier = 'pg';
+            const mod = (await import(specifier));
+            const ctor = mod.Pool ?? mod.default?.Pool;
+            if (!ctor)
+                throw new Error('pg.Pool not found');
+            Pool = ctor;
+        }
+        catch {
+            throw new Error("PostgresExecutionLog requires the optional peer dependency 'pg'. " +
+                'Install it with: npm install pg');
+        }
+        const pool = new Pool({ connectionString: this.connectionString });
+        await pool.query(`CREATE TABLE IF NOT EXISTS ${this.table} (
+        execution_id text NOT NULL,
+        seq integer NOT NULL,
+        at text NOT NULL,
+        data jsonb NOT NULL,
+        PRIMARY KEY (execution_id, seq)
+      )`);
+        this.pool = pool;
+        return pool;
+    }
+    async append(event) {
+        const pool = await this.ensure();
+        const at = new Date().toISOString();
+        const data = JSON.stringify(event);
+        for (let attempt = 0; attempt < MAX_APPEND_ATTEMPTS; attempt++) {
+            try {
+                const res = await pool.query(`INSERT INTO ${this.table} (execution_id, seq, at, data)
+           VALUES (
+             $1,
+             (SELECT COALESCE(MAX(seq) + 1, 0) FROM ${this.table} WHERE execution_id = $1),
+             $2,
+             $3::jsonb
+           )
+           RETURNING seq`, [event.executionId, at, data]);
+                return { ...event, seq: res.rows[0].seq, at };
+            }
+            catch (err) {
+                // A concurrent appender claimed this seq first; retry against the new max.
+                if (err.code === UNIQUE_VIOLATION)
+                    continue;
+                throw err;
+            }
+        }
+        throw new Error(`append failed after ${MAX_APPEND_ATTEMPTS} attempts for execution ${event.executionId}`);
+    }
+    async read(executionId) {
+        const pool = await this.ensure();
+        const res = await pool.query(`SELECT seq, at, data FROM ${this.table} WHERE execution_id = $1 ORDER BY seq ASC`, [executionId]);
+        // jsonb comes back already parsed; overlay the assigned seq + recorded time.
+        return res.rows.map((r) => ({ ...r.data, seq: r.seq, at: r.at }));
+    }
+    async listCheckpoints(mission) {
+        const pool = await this.ensure();
+        const res = await pool.query(`SELECT seq, at, data FROM ${this.table} WHERE data->>'type' = 'checkpoint.advanced'`);
+        const events = res.rows.map((r) => ({ ...r.data, seq: r.seq, at: r.at }));
+        return reduceCheckpoints(events, mission);
+    }
+    async listPauses() {
+        const pool = await this.ensure();
+        const res = await pool.query(`SELECT seq, at, data FROM ${this.table}
+       WHERE data->>'type' IN ('pause.created', 'pause.resumed')`);
+        return res.rows.map((r) => ({ ...r.data, seq: r.seq, at: r.at }));
+    }
+    /** Drop all rows. Intended for test setup, not production use. */
+    async reset() {
+        const pool = await this.ensure();
+        await pool.query(`TRUNCATE ${this.table}`);
+    }
+    /** Release the connection pool. */
+    async close() {
+        if (this.pool) {
+            await this.pool.end();
+            this.pool = undefined;
+            this.ready = undefined;
+        }
+    }
+}

package/dist/execution-log/resume.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resume helpers: load the current folded state of a run from its log.
+ *
+ * Resume is "read the log, fold it, continue" — never a second execution. A
+ * replaying caller checks {@link FoldedState.appliedEffects} before re-running
+ * a side effect, so an effect recorded before a crash is skipped on resume.
+ */
+import type { ExecutionLogStore } from './store.js';
+import { type FoldedState } from './fold.js';
+/** Read and fold an execution's log into its current state. */
+export declare function loadState(store: ExecutionLogStore, executionId: string): Promise<FoldedState>;

package/dist/execution-log/resume.js

@@ -0,0 +1,5 @@
+import { foldLog } from './fold.js';
+/** Read and fold an execution's log into its current state. */
+export async function loadState(store, executionId) {
+    return foldLog(await store.read(executionId));
+}

package/dist/execution-log/sqlite-store.d.ts

@@ -0,0 +1,16 @@
+import type { ExecutionEvent, StoredEvent } from './events.js';
+import type { CheckpointRecord, ExecutionLogStore } from './store.js';
+export declare class SqliteExecutionLog implements ExecutionLogStore {
+    private path;
+    private db?;
+    private insertStmt?;
+    private readStmt?;
+    private checkpointStmt?;
+    private pauseStmt?;
+    constructor(path?: string);
+    private ensureDb;
+    append(event: ExecutionEvent): Promise<StoredEvent>;
+    read(executionId: string): Promise<StoredEvent[]>;
+    listCheckpoints(mission?: string): Promise<CheckpointRecord[]>;
+    listPauses(): Promise<StoredEvent[]>;
+}

package/dist/execution-log/sqlite-store.js

@@ -0,0 +1,101 @@
+/**
+ * SQLite-backed execution log — durable, transactional state for single-process
+ * self-hosting (the "SQLite-of-durable-execution" lane).
+ *
+ * The `better-sqlite3` driver is an *optional* peer dependency: only installed
+ * by users who opt into the SQLite backend. It is imported lazily so the core
+ * package carries no native dependency, and a missing driver yields a clear,
+ * actionable error rather than an opaque module-resolution failure.
+ *
+ * Durability: WAL mode + `synchronous = NORMAL` gives fsync-backed commits that
+ * survive a process crash, and `seq` is assigned atomically inside the INSERT
+ * (guarded by a `(execution_id, seq)` primary key) so concurrent appenders
+ * cannot collide on a sequence number.
+ */
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { reduceCheckpoints } from './store.js';
+export class SqliteExecutionLog {
+    path;
+    db;
+    insertStmt;
+    readStmt;
+    checkpointStmt;
+    pauseStmt;
+    constructor(path = '.reqon-data/execution-log.sqlite') {
+        this.path = path;
+    }
+    async ensureDb() {
+        if (this.db)
+            return this.db;
+        if (this.path !== ':memory:') {
+            await mkdir(dirname(this.path), { recursive: true });
+        }
+        let Database;
+        try {
+            // Non-literal specifier: keeps the driver an optional dependency with no
+            // compile-time type coupling (no @types/better-sqlite3 required).
+            const specifier = 'better-sqlite3';
+            const mod = (await import(specifier));
+            Database = mod.default;
+        }
+        catch {
+            throw new Error("SqliteExecutionLog requires the optional peer dependency 'better-sqlite3'. " +
+                'Install it with: npm install better-sqlite3');
+        }
+        const db = new Database(this.path);
+        db.pragma('journal_mode = WAL');
+        db.pragma('synchronous = NORMAL');
+        db.exec(`CREATE TABLE IF NOT EXISTS events (
+        execution_id TEXT NOT NULL,
+        seq INTEGER NOT NULL,
+        at TEXT NOT NULL,
+        data TEXT NOT NULL,
+        PRIMARY KEY (execution_id, seq)
+      )`);
+        // seq is computed inside the INSERT so it is assigned atomically, and
+        // RETURNING hands it back without a second round-trip.
+        this.insertStmt = db.prepare(`INSERT INTO events (execution_id, seq, at, data)
+       VALUES (
+         @id,
+         (SELECT COALESCE(MAX(seq) + 1, 0) FROM events WHERE execution_id = @id),
+         @at,
+         @data
+       )
+       RETURNING seq`);
+        this.readStmt = db.prepare(`SELECT seq, at, data FROM events WHERE execution_id = @id ORDER BY seq ASC`);
+        this.checkpointStmt = db.prepare(`SELECT execution_id, seq, at, data FROM events
+       WHERE json_extract(data, '$.type') = 'checkpoint.advanced'`);
+        this.pauseStmt = db.prepare(`SELECT execution_id, seq, at, data FROM events
+       WHERE json_extract(data, '$.type') IN ('pause.created', 'pause.resumed')`);
+        this.db = db;
+        return db;
+    }
+    async append(event) {
+        await this.ensureDb();
+        const at = new Date().toISOString();
+        const { executionId } = event;
+        const row = this.insertStmt.get({
+            id: executionId,
+            at,
+            data: JSON.stringify(event),
+        });
+        return { ...event, seq: row.seq, at };
+    }
+    async read(executionId) {
+        await this.ensureDb();
+        const rows = this.readStmt.all({ id: executionId });
+        return rows.map((r) => ({ ...JSON.parse(r.data), seq: r.seq, at: r.at }));
+    }
+    async listCheckpoints(mission) {
+        await this.ensureDb();
+        const rows = this.checkpointStmt.all({});
+        const events = rows.map((r) => ({ ...JSON.parse(r.data), seq: r.seq, at: r.at }));
+        return reduceCheckpoints(events, mission);
+    }
+    async listPauses() {
+        await this.ensureDb();
+        const rows = this.pauseStmt.all({});
+        return rows.map((r) => ({ ...JSON.parse(r.data), seq: r.seq, at: r.at }));
+    }
+}

package/dist/execution-log/store.d.ts

@@ -0,0 +1,72 @@
+import type { ExecutionEvent, StoredEvent } from './events.js';
+/**
+ * The latest sync checkpoint for a key, materialised across executions — the
+ * read model behind log-backed incremental sync. Derived from the most recent
+ * `checkpoint.advanced` event for each key.
+ */
+export interface CheckpointRecord {
+    key: string;
+    syncedAt: string;
+    recordCount?: number;
+    cursor?: string;
+    mission?: string;
+    /** The execution that advanced this checkpoint. */
+    executionId: string;
+}
+export interface ExecutionLogStore {
+    /** Append one event; returns it with its assigned seq and recorded timestamp. */
+    append(event: ExecutionEvent): Promise<StoredEvent>;
+    /** Read all events for an execution, in append order. */
+    read(executionId: string): Promise<StoredEvent[]>;
+    /**
+     * Latest checkpoint per key across all executions in this store (optionally
+     * filtered by mission). The read model for log-backed incremental sync.
+     */
+    listCheckpoints(mission?: string): Promise<CheckpointRecord[]>;
+    /**
+     * All pause lifecycle events (pause.created / pause.resumed) across every
+     * execution in this store, in no guaranteed order. The raw input the
+     * log-backed pause store folds into pause state.
+     */
+    listPauses(): Promise<StoredEvent[]>;
+}
+/**
+ * Fold `checkpoint.advanced` events into the latest checkpoint per key. "Latest"
+ * is the furthest-advanced sync: ordered by `syncedAt` (so a checkpoint never
+ * moves backwards across runs — incremental sync stays monotonic), ties broken
+ * by the recording time `at` then `seq`. Shared by every store backend so the
+ * read-model semantics stay identical across them.
+ */
+export declare function reduceCheckpoints(events: StoredEvent[], mission?: string): CheckpointRecord[];
+/** In-memory execution log — for tests and ephemeral runs. */
+export declare class MemoryExecutionLog implements ExecutionLogStore {
+    private events;
+    append(event: ExecutionEvent): Promise<StoredEvent>;
+    read(executionId: string): Promise<StoredEvent[]>;
+    listCheckpoints(mission?: string): Promise<CheckpointRecord[]>;
+    listPauses(): Promise<StoredEvent[]>;
+}
+/**
+ * Durable execution log: one append-only JSON-lines file per execution.
+ *
+ * Appends are O_APPEND single-line writes, so a crash mid-write can at worst
+ * leave a torn final line, which {@link read} skips. The log therefore survives
+ * a process restart — a resumed run reads its prior events back. Dev-grade: no
+ * atomic seq assignment or locking. For a transactional single-process backend
+ * use {@link SqliteExecutionLog}; Postgres (multi-node) is still to come.
+ */
+export declare class FileExecutionLog implements ExecutionLogStore {
+    private dir;
+    /** Cached next-seq per execution, lazily initialised from disk. */
+    private counts;
+    constructor(dir?: string);
+    private pathFor;
+    append(event: ExecutionEvent): Promise<StoredEvent>;
+    read(executionId: string): Promise<StoredEvent[]>;
+    listCheckpoints(mission?: string): Promise<CheckpointRecord[]>;
+    listPauses(): Promise<StoredEvent[]>;
+    /** Read and parse every execution's events in this directory. */
+    private readAll;
+    private readRaw;
+    private parse;
+}