adispatchd 0.0.0-stage → 0.1.0

package/dist/persistence/database.js

@@ -0,0 +1,124 @@
+/**
+ * Opening the orchestrator database and applying versioned migrations with a
+ * pre-migration backup (Spec §4, §12, §21).
+ */
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { dataPaths, formatCompactTimestamp, noopLogger, systemClock } from '../core/index.js';
+import { MigrationError } from './errors.js';
+import { MIGRATIONS } from './schema.js';
+import { all, get, run, transaction } from './sqlite.js';
+/** Default SQLite busy timeout (ms). */
+export const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+/**
+ * Open (creating if needed) `<dataDir>/adispatchd.sqlite`, configure it
+ * (foreign keys, WAL, busy timeout) and apply pending migrations. If the
+ * database already existed and migrations are pending, it is first backed up
+ * to `<dataDir>/backups/adispatchd-<version>-<ts>.sqlite`.
+ *
+ * The caller should hold the data-dir instance lock ({@link acquireInstanceLock}) first.
+ */
+export function openDatabase(dataDir, options = {}) {
+    const paths = dataPaths(dataDir);
+    mkdirSync(paths.dataDir, { recursive: true });
+    const existed = existsSync(paths.database) && statSync(paths.database).size > 0;
+    const db = new DatabaseSync(paths.database);
+    try {
+        configureConnection(db, options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS);
+        const migration = migrate(db, {
+            migrations: options.migrations ?? MIGRATIONS,
+            backupDir: existed ? paths.backupsDir : null,
+            clock: options.clock ?? systemClock,
+            logger: options.logger ?? noopLogger,
+        });
+        return { db, path: paths.database, migration, close: () => db.close() };
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
+}
+/** Apply connection pragmas. */
+export function configureConnection(db, busyTimeoutMs = DEFAULT_BUSY_TIMEOUT_MS) {
+    db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.trunc(busyTimeoutMs))}`);
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA synchronous = NORMAL');
+}
+/** Current schema version (0 if `schema_migrations` does not exist yet). */
+export function schemaVersion(db) {
+    const table = get(db, `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'`);
+    if (!table)
+        return 0;
+    const row = get(db, 'SELECT MAX(version) AS v FROM schema_migrations');
+    return Number(row?.v ?? 0);
+}
+/** Apply all pending migrations, each in its own transaction. Idempotent. */
+export function migrate(db, options) {
+    validateMigrations(options.migrations);
+    db.exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
+    version    INTEGER PRIMARY KEY,
+    name       TEXT NOT NULL,
+    applied_at TEXT NOT NULL
+  )`);
+    const applied = new Set(all(db, 'SELECT version FROM schema_migrations').map((r) => Number(r.version)));
+    const fromVersion = applied.size === 0 ? 0 : Math.max(...applied);
+    const known = options.migrations.length === 0 ? 0 : Math.max(...options.migrations.map((m) => m.version));
+    if (fromVersion > known) {
+        throw new MigrationError(`Database schema version ${fromVersion} is newer than this build supports (${known}); refusing to start`, { fromVersion, known });
+    }
+    const pending = options.migrations.filter((m) => !applied.has(m.version));
+    let backupPath = null;
+    if (pending.length > 0 && options.backupDir !== null) {
+        backupPath = backupDatabase(db, options.backupDir, fromVersion, options.clock);
+        options.logger.info('database backup written before migration', { backupPath, fromVersion });
+    }
+    for (const migration of pending) {
+        try {
+            transaction(db, () => {
+                migration.up(db);
+                run(db, 'INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?)', [
+                    migration.version,
+                    migration.name,
+                    options.clock.now().toISOString(),
+                ]);
+            });
+        }
+        catch (err) {
+            throw new MigrationError(`Migration ${migration.version} (${migration.name}) failed`, { version: migration.version, backupPath }, err);
+        }
+        options.logger.info('database migration applied', { version: migration.version, name: migration.name });
+    }
+    return {
+        fromVersion,
+        toVersion: schemaVersion(db),
+        applied: pending.map((m) => m.version),
+        backupPath,
+    };
+}
+/**
+ * Write a consistent copy of the database (`VACUUM INTO`, safe in WAL mode)
+ * to `<backupDir>/adispatchd-<version>-<ts>.sqlite`. Returns its path.
+ */
+export function backupDatabase(db, backupDir, version, clock) {
+    mkdirSync(backupDir, { recursive: true });
+    const base = `adispatchd-${version}-${formatCompactTimestamp(clock.now(), true)}`;
+    let target = path.join(backupDir, `${base}.sqlite`);
+    for (let i = 1; existsSync(target); i++)
+        target = path.join(backupDir, `${base}-${i}.sqlite`);
+    db.prepare('VACUUM INTO ?').run(target);
+    return target;
+}
+function validateMigrations(migrations) {
+    let previous = 0;
+    for (const m of migrations) {
+        if (!Number.isInteger(m.version) || m.version <= previous) {
+            throw new MigrationError('Migrations must have strictly increasing positive integer versions', {
+                version: m.version,
+            });
+        }
+        previous = m.version;
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/persistence/database.js.map

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

package/dist/persistence/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Persistence-specific errors. All extend {@link OrchestratorError} so callers
+ * (API: 409/404 mapping) can react on the stable `code`.
+ */
+import { OrchestratorError } from '../core/index.js';
+/** An active lock for `(workflowId, lockKey)` already exists (HTTP 409). */
+export declare class LockConflictError extends OrchestratorError {
+    readonly workflowId: string;
+    readonly lockKey: string;
+    /** Run currently holding the lock. */
+    readonly holderRunId: string;
+    constructor(workflowId: string, lockKey: string, holderRunId: string);
+}
+/** Reservation refused because an active retry block exists (only with `failIfBlocked`). */
+export declare class BlockedError extends OrchestratorError {
+    readonly blockId: number;
+    constructor(workflowId: string, itemKey: string | null, blockId: number);
+}
+/** An active block already exists for the workflow/scope. */
+export declare class BlockExistsError extends OrchestratorError {
+    readonly blockId: number;
+    constructor(blockId: number);
+}
+/** A run status transition that the state machine (core `canTransition`) does not allow. */
+export declare class InvalidTransitionError extends OrchestratorError {
+    constructor(message: string, details: Record<string, unknown>);
+}
+/** A referenced row does not exist. */
+export declare class NotFoundError extends OrchestratorError {
+    constructor(entity: string, id: string | number);
+}
+/** Another orchestrator instance holds the data-dir instance lock (Spec §21). */
+export declare class InstanceLockedError extends OrchestratorError {
+    constructor(lockPath: string, holder: Record<string, unknown> | null, cause?: unknown);
+}
+/** Schema migration failed or the database schema is newer than this build. */
+export declare class MigrationError extends OrchestratorError {
+    constructor(message: string, details?: Record<string, unknown>, cause?: unknown);
+}

package/dist/persistence/errors.js

@@ -0,0 +1,67 @@
+/**
+ * Persistence-specific errors. All extend {@link OrchestratorError} so callers
+ * (API: 409/404 mapping) can react on the stable `code`.
+ */
+import { OrchestratorError } from '../core/index.js';
+/** An active lock for `(workflowId, lockKey)` already exists (HTTP 409). */
+export class LockConflictError extends OrchestratorError {
+    workflowId;
+    lockKey;
+    /** Run currently holding the lock. */
+    holderRunId;
+    constructor(workflowId, lockKey, holderRunId) {
+        super('lock_conflict', `Workflow '${workflowId}' already has an active run for '${lockKey}' (${holderRunId})`, {
+            details: { workflowId, lockKey, holderRunId },
+        });
+        this.workflowId = workflowId;
+        this.lockKey = lockKey;
+        this.holderRunId = holderRunId;
+    }
+}
+/** Reservation refused because an active retry block exists (only with `failIfBlocked`). */
+export class BlockedError extends OrchestratorError {
+    blockId;
+    constructor(workflowId, itemKey, blockId) {
+        super('blocked', `Workflow '${workflowId}' is blocked for '${itemKey ?? '<workflow>'}' (block ${blockId})`, {
+            details: { workflowId, itemKey, blockId },
+        });
+        this.blockId = blockId;
+    }
+}
+/** An active block already exists for the workflow/scope. */
+export class BlockExistsError extends OrchestratorError {
+    blockId;
+    constructor(blockId) {
+        super('block_exists', `An active block already exists (block ${blockId})`, { details: { blockId } });
+        this.blockId = blockId;
+    }
+}
+/** A run status transition that the state machine (core `canTransition`) does not allow. */
+export class InvalidTransitionError extends OrchestratorError {
+    constructor(message, details) {
+        super('invalid_transition', message, { details });
+    }
+}
+/** A referenced row does not exist. */
+export class NotFoundError extends OrchestratorError {
+    constructor(entity, id) {
+        super('not_found', `${entity} '${String(id)}' not found`, { details: { entity, id } });
+    }
+}
+/** Another orchestrator instance holds the data-dir instance lock (Spec §21). */
+export class InstanceLockedError extends OrchestratorError {
+    constructor(lockPath, holder, cause) {
+        const who = holder && typeof holder.pid === 'number' ? ` (pid ${holder.pid})` : '';
+        super('instance_locked', `Another orchestrator instance is running on this data directory${who}: ${lockPath}`, {
+            details: { lockPath, holder },
+            cause,
+        });
+    }
+}
+/** Schema migration failed or the database schema is newer than this build. */
+export class MigrationError extends OrchestratorError {
+    constructor(message, details, cause) {
+        super('migration_error', message, { ...(details ? { details } : {}), cause });
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/persistence/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/persistence/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,4EAA4E;AAC5E,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;IAC7C,UAAU,CAAS;IACnB,OAAO,CAAS;IACzB,sCAAsC;IAC7B,WAAW,CAAS;IAE7B,YAAY,UAAkB,EAAE,OAAe,EAAE,WAAmB;QAClE,KAAK,CAAC,eAAe,EAAE,aAAa,UAAU,oCAAoC,OAAO,MAAM,WAAW,GAAG,EAAE;YAC7G,OAAO,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,OAAO,YAAa,SAAQ,iBAAiB;IACxC,OAAO,CAAS;IAEzB,YAAY,UAAkB,EAAE,OAAsB,EAAE,OAAe;QACrE,KAAK,CAAC,SAAS,EAAE,aAAa,UAAU,qBAAqB,OAAO,IAAI,YAAY,YAAY,OAAO,GAAG,EAAE;YAC1G,OAAO,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE;SAC1C,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,6DAA6D;AAC7D,MAAM,OAAO,gBAAiB,SAAQ,iBAAiB;IAC5C,OAAO,CAAS;IAEzB,YAAY,OAAe;QACzB,KAAK,CAAC,cAAc,EAAE,yCAAyC,OAAO,GAAG,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;QACrG,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,4FAA4F;AAC5F,MAAM,OAAO,sBAAuB,SAAQ,iBAAiB;IAC3D,YAAY,OAAe,EAAE,OAAgC;QAC3D,KAAK,CAAC,oBAAoB,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACpD,CAAC;CACF;AAED,uCAAuC;AACvC,MAAM,OAAO,aAAc,SAAQ,iBAAiB;IAClD,YAAY,MAAc,EAAE,EAAmB;QAC7C,KAAK,CAAC,WAAW,EAAE,GAAG,MAAM,KAAK,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACzF,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,mBAAoB,SAAQ,iBAAiB;IACxD,YAAY,QAAgB,EAAE,MAAsC,EAAE,KAAe;QACnF,MAAM,GAAG,GAAG,MAAM,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,KAAK,CAAC,iBAAiB,EAAE,kEAAkE,GAAG,KAAK,QAAQ,EAAE,EAAE;YAC7G,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;YAC7B,KAAK;SACN,CAAC,CAAC;IACL,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,cAAe,SAAQ,iBAAiB;IACnD,YAAY,OAAe,EAAE,OAAiC,EAAE,KAAe;QAC7E,KAAK,CAAC,iBAAiB,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAChF,CAAC;CACF"}

package/dist/persistence/events.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Structured run events (Spec §9.3, §12, §15 SSE). Every event has a
+ * globally monotonic `id` (SQLite AUTOINCREMENT: never reused after deletion
+ * of committed rows – usable as SSE `Last-Event-ID`) and a per-run `sequence`.
+ *
+ * Caveat: the ID of an insert that is rolled back may be handed out again.
+ * Therefore an event (and its ID) must only be published to live consumers
+ * (event bus / SSE) after the surrounding transaction committed – use
+ * `Repositories.afterCommit` / `afterCommit(db, cb)`. Persisted IDs are then
+ * strictly increasing in commit order (single writer connection).
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { Clock, ExecutorDiagnostic, WorkerEvent } from '../core/index.js';
+/**
+ * Who produced the event: `worker` = `@@ADISPATCH_EVENT` line (untrusted, informative),
+ * `orchestrator` = status transitions and executor diagnostics.
+ */
+export type EventOrigin = 'worker' | 'orchestrator';
+/** Event type of orchestrator-side run status transitions. Payload: {@link RunStatusEventPayload}. */
+export declare const RUN_STATUS_EVENT = "run.status";
+/** Prefix of executor diagnostic event types, e.g. `diagnostic.log_truncated` (Spec §12 note on log/DB inconsistencies). */
+export declare const DIAGNOSTIC_EVENT_PREFIX = "diagnostic.";
+/** Payload of a {@link RUN_STATUS_EVENT}. */
+export interface RunStatusEventPayload {
+    from: string | null;
+    to: string;
+    [key: string]: unknown;
+}
+/** A persisted run event. */
+export interface RunEventRecord {
+    /** Global, strictly increasing event ID. */
+    id: number;
+    runId: string;
+    /** 1-based, strictly increasing per run. */
+    sequence: number;
+    timestamp: string;
+    origin: EventOrigin;
+    type: string;
+    payload: Record<string, unknown>;
+}
+/** Options for {@link EventRepository.append}. */
+export interface AppendEventOptions {
+    origin?: EventOrigin;
+    at?: Date;
+}
+/** Repository for `run_events`. */
+export declare class EventRepository {
+    private readonly db;
+    private readonly clock;
+    constructor(db: DatabaseSync, clock: Clock);
+    /**
+     * Append an event. Worker `status` events with a string `message` also
+     * update `runs.status_message` (same transaction).
+     */
+    append(runId: string, type: string, payload: Record<string, unknown>, options?: AppendEventOptions): RunEventRecord;
+    /** Persist a structured worker event (origin `worker`). */
+    appendWorkerEvent(runId: string, event: WorkerEvent): RunEventRecord;
+    /** Persist an executor diagnostic as `diagnostic.<type>` (origin `orchestrator`). */
+    appendDiagnostic(runId: string, diagnostic: ExecutorDiagnostic): RunEventRecord;
+    /** Events with `id > afterId` in ID order (SSE replay). Optionally restricted to one run. */
+    listSince(afterId: number, options?: {
+        runId?: string;
+        limit?: number;
+    }): RunEventRecord[];
+    /** Events of one run in sequence order. */
+    listForRun(runId: string, options?: {
+        afterSequence?: number;
+        limit?: number;
+    }): RunEventRecord[];
+    /** Highest event ID ever assigned (0 if none); does not decrease when events are deleted. */
+    latestId(): number;
+}

package/dist/persistence/events.js

@@ -0,0 +1,83 @@
+import { NotFoundError } from './errors.js';
+import { all, get, iso, run, transaction } from './sqlite.js';
+/** Event type of orchestrator-side run status transitions. Payload: {@link RunStatusEventPayload}. */
+export const RUN_STATUS_EVENT = 'run.status';
+/** Prefix of executor diagnostic event types, e.g. `diagnostic.log_truncated` (Spec §12 note on log/DB inconsistencies). */
+export const DIAGNOSTIC_EVENT_PREFIX = 'diagnostic.';
+/** Repository for `run_events`. */
+export class EventRepository {
+    db;
+    clock;
+    constructor(db, clock) {
+        this.db = db;
+        this.clock = clock;
+    }
+    /**
+     * Append an event. Worker `status` events with a string `message` also
+     * update `runs.status_message` (same transaction).
+     */
+    append(runId, type, payload, options = {}) {
+        const origin = options.origin ?? 'orchestrator';
+        const at = iso(options.at ?? this.clock.now());
+        return transaction(this.db, () => {
+            if (!get(this.db, 'SELECT 1 FROM runs WHERE id = ?', [runId]))
+                throw new NotFoundError('run', runId);
+            const seqRow = get(this.db, 'SELECT COALESCE(MAX(sequence), 0) + 1 AS s FROM run_events WHERE run_id = ?', [runId]);
+            const sequence = Number(seqRow?.s ?? 1);
+            const res = run(this.db, 'INSERT INTO run_events (run_id, sequence, timestamp, origin, type, payload_json) VALUES (?, ?, ?, ?, ?, ?)', [runId, sequence, at, origin, type, JSON.stringify(payload)]);
+            if (origin === 'worker' && type === 'status' && typeof payload.message === 'string') {
+                run(this.db, 'UPDATE runs SET status_message = ?, updated_at = ? WHERE id = ?', [payload.message, at, runId]);
+            }
+            return { id: res.lastInsertRowid, runId, sequence, timestamp: at, origin, type, payload };
+        });
+    }
+    /** Persist a structured worker event (origin `worker`). */
+    appendWorkerEvent(runId, event) {
+        return this.append(runId, event.type, event.data, { origin: 'worker', at: event.at });
+    }
+    /** Persist an executor diagnostic as `diagnostic.<type>` (origin `orchestrator`). */
+    appendDiagnostic(runId, diagnostic) {
+        const payload = { message: diagnostic.message };
+        if (diagnostic.stream)
+            payload.stream = diagnostic.stream;
+        if (diagnostic.details)
+            payload.details = diagnostic.details;
+        return this.append(runId, `${DIAGNOSTIC_EVENT_PREFIX}${diagnostic.type}`, payload, { at: diagnostic.at });
+    }
+    /** Events with `id > afterId` in ID order (SSE replay). Optionally restricted to one run. */
+    listSince(afterId, options = {}) {
+        const params = [afterId];
+        let sql = 'SELECT * FROM run_events WHERE id > ?';
+        if (options.runId !== undefined) {
+            sql += ' AND run_id = ?';
+            params.push(options.runId);
+        }
+        sql += ' ORDER BY id ASC LIMIT ?';
+        params.push(options.limit ?? 1000);
+        return all(this.db, sql, params).map(toEvent);
+    }
+    /** Events of one run in sequence order. */
+    listForRun(runId, options = {}) {
+        return all(this.db, 'SELECT * FROM run_events WHERE run_id = ? AND sequence > ? ORDER BY sequence ASC LIMIT ?', [
+            runId,
+            options.afterSequence ?? 0,
+            options.limit ?? 10_000,
+        ]).map(toEvent);
+    }
+    /** Highest event ID ever assigned (0 if none); does not decrease when events are deleted. */
+    latestId() {
+        return Number(get(this.db, `SELECT seq FROM sqlite_sequence WHERE name = 'run_events'`)?.seq ?? 0);
+    }
+}
+function toEvent(row) {
+    return {
+        id: Number(row.id),
+        runId: String(row.run_id),
+        sequence: Number(row.sequence),
+        timestamp: String(row.timestamp),
+        origin: row.origin,
+        type: String(row.type),
+        payload: JSON.parse(String(row.payload_json)),
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/persistence/events.js.map

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

package/dist/persistence/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Component `persistence` – public API (WI-03).
+ * Other components import from this module only.
+ */
+export { openPersistence, createRepositories, type Persistence, type Repositories } from './persistence.js';
+export { openDatabase, migrate, schemaVersion, backupDatabase, configureConnection, DEFAULT_BUSY_TIMEOUT_MS, type OpenDatabaseOptions, type OpenedDatabase, type MigrationResult, type MigrateOptions, } from './database.js';
+export { MIGRATIONS, type Migration } from './schema.js';
+export { acquireInstanceLock, INSTANCE_LOCK_FILES, type InstanceLock, type InstanceLockHolder } from './instance-lock.js';
+export { lockKeyFor, blockScopeKey, type LockKeyInput } from './lock-keys.js';
+export { RunRepository, finalizationTarget, type RunRecord, type ReserveRunInput, type RunUpdate, type BlockPolicy, type BeginFinalizationOptions, type FinalizationResult, type RunListQuery, type RunPage, type LockRecord, } from './runs.js';
+export { EventRepository, RUN_STATUS_EVENT, DIAGNOSTIC_EVENT_PREFIX, type EventOrigin, type RunEventRecord, type RunStatusEventPayload, type AppendEventOptions, } from './events.js';
+export { ActionRepository, ACTION_STATUS_TRANSITIONS, type ActionJournalEntry, type RunActionRecord, type ActionAttemptRecord, type FailedActionRecord, } from './actions.js';
+export { BlockRepository, type BlockRecord, type CreateBlockInput, type FailureCounterState, } from './blocks.js';
+export { NotificationRepository, type NotificationRecord, type NotificationDeliveryRecord, type DeliveryAttemptOutcome, type DeliveryState, } from './notifications.js';
+export { CronFiringRepository, type CronFiringRecord, type CronDecision, type RecordCronFiringInput, } from './cron-firings.js';
+export { RetentionRepository, type RunRetentionCategory, type RunRetentionCandidate } from './retention.js';
+export { LockConflictError, BlockedError, BlockExistsError, InvalidTransitionError, NotFoundError, InstanceLockedError, MigrationError, } from './errors.js';
+export { transaction, afterCommit } from './sqlite.js';

package/dist/persistence/index.js

@@ -0,0 +1,19 @@
+/**
+ * Component `persistence` – public API (WI-03).
+ * Other components import from this module only.
+ */
+export { openPersistence, createRepositories } from './persistence.js';
+export { openDatabase, migrate, schemaVersion, backupDatabase, configureConnection, DEFAULT_BUSY_TIMEOUT_MS, } from './database.js';
+export { MIGRATIONS } from './schema.js';
+export { acquireInstanceLock, INSTANCE_LOCK_FILES } from './instance-lock.js';
+export { lockKeyFor, blockScopeKey } from './lock-keys.js';
+export { RunRepository, finalizationTarget, } from './runs.js';
+export { EventRepository, RUN_STATUS_EVENT, DIAGNOSTIC_EVENT_PREFIX, } from './events.js';
+export { ActionRepository, ACTION_STATUS_TRANSITIONS, } from './actions.js';
+export { BlockRepository, } from './blocks.js';
+export { NotificationRepository, } from './notifications.js';
+export { CronFiringRepository, } from './cron-firings.js';
+export { RetentionRepository } from './retention.js';
+export { LockConflictError, BlockedError, BlockExistsError, InvalidTransitionError, NotFoundError, InstanceLockedError, MigrationError, } from './errors.js';
+export { transaction, afterCommit } from './sqlite.js';
+//# sourceMappingURL=index.js.map

package/dist/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAuC,MAAM,kBAAkB,CAAC;AAC5G,OAAO,EACL,YAAY,EACZ,OAAO,EACP,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,uBAAuB,GAKxB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAkB,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAA8C,MAAM,oBAAoB,CAAC;AAC1H,OAAO,EAAE,UAAU,EAAE,aAAa,EAAqB,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EACL,aAAa,EACb,kBAAkB,GAUnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,uBAAuB,GAKxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,yBAAyB,GAK1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,GAIhB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,GAKvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,GAIrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAyD,MAAM,gBAAgB,CAAC;AAC5G,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACnB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/persistence/instance-lock.d.ts

@@ -0,0 +1,26 @@
+import { type Clock } from '../core/index.js';
+/** File names inside the data dir that copy/backup/cleanup routines must never open. */
+export declare const INSTANCE_LOCK_FILES: readonly ['adispatchd.lock', 'adispatchd.lock.json'];
+/** A held instance lock. */
+export interface InstanceLock {
+    /** Path of the lock file. */
+    readonly path: string;
+    /** True until {@link release} was called. */
+    readonly held: boolean;
+    /** Release the lock (idempotent). Also released automatically on process exit. */
+    release(): void;
+}
+/** Diagnostic holder information. */
+export interface InstanceLockHolder {
+    pid: number;
+    hostname: string;
+    acquiredAt: string;
+}
+/**
+ * Acquire the exclusive instance lock for `dataDir` (creates the directory if
+ * needed). Throws {@link InstanceLockedError} immediately if another live
+ * instance – in this or another process – holds it.
+ */
+export declare function acquireInstanceLock(dataDir: string, options?: {
+    clock?: Clock;
+}): InstanceLock;

package/dist/persistence/instance-lock.js

@@ -0,0 +1,117 @@
+/**
+ * Data-dir instance lock (Spec §21): only one orchestrator per data directory.
+ *
+ * Approach: an OS-level advisory lock held by SQLite. `adispatchd.lock` is a
+ * tiny SQLite database opened with `locking_mode=EXCLUSIVE`; after the first
+ * write transaction SQLite keeps the EXCLUSIVE file lock (POSIX `fcntl` on
+ * Unix, `LockFileEx` on Windows) until the connection closes. The operating
+ * system drops such locks automatically when the process exits – also on
+ * SIGKILL/crash – so there is no "stale lock" that needs heuristic detection:
+ * a lock left by a dead process is simply free again, and a live holder can
+ * never be overridden (no PID/start-time guessing that could admit two
+ * instances). SQLite also tracks locks per inode inside one process, so a
+ * second acquisition from the same process is refused as well.
+ *
+ * Holder information (pid, host, start time) is written into the lock
+ * database and mirrored to `adispatchd.lock.json` for diagnostics only; it
+ * never decides who owns the lock.
+ *
+ * The connection is kept strongly reachable in a module-level set until
+ * `release()`: otherwise dropping the returned handle would let the garbage
+ * collector close the connection and silently free the OS lock.
+ *
+ * Limitations / rules:
+ * - Advisory `fcntl` locks are unreliable on some network file systems (NFS
+ *   without lock daemon) – the data dir must be on a local file system.
+ * - POSIX `fcntl` locks belong to the process and are dropped when the process
+ *   closes ANY file descriptor of that file. Therefore the holding process must
+ *   never open `adispatchd.lock` otherwise (no `readFileSync`, `fs.cp`,
+ *   copying the data dir, ...). Backup/copy/cleanup routines must exclude
+ *   `adispatchd.lock` (and `adispatchd.lock.json`); `backupDatabase` only
+ *   reads `adispatchd.sqlite` via SQLite. Opening it through `node:sqlite`
+ *   in the same process is safe (SQLite shares lock state per inode).
+ */
+import { readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import { DatabaseSync } from 'node:sqlite';
+import { dataPaths, systemClock } from '../core/index.js';
+import { InstanceLockedError } from './errors.js';
+/** Connections holding a lock; strong references prevent GC from closing them. */
+const HELD = new Set();
+/** File names inside the data dir that copy/backup/cleanup routines must never open. */
+export const INSTANCE_LOCK_FILES = ['adispatchd.lock', 'adispatchd.lock.json'];
+/**
+ * Acquire the exclusive instance lock for `dataDir` (creates the directory if
+ * needed). Throws {@link InstanceLockedError} immediately if another live
+ * instance – in this or another process – holds it.
+ */
+export function acquireInstanceLock(dataDir, options = {}) {
+    const paths = dataPaths(dataDir);
+    mkdirSync(paths.dataDir, { recursive: true });
+    const lockPath = paths.instanceLock;
+    const infoPath = `${lockPath}.json`;
+    const db = new DatabaseSync(lockPath);
+    const holder = {
+        pid: process.pid,
+        hostname: os.hostname(),
+        acquiredAt: (options.clock ?? systemClock).now().toISOString(),
+    };
+    try {
+        db.exec('PRAGMA busy_timeout = 0');
+        db.exec('PRAGMA locking_mode = EXCLUSIVE');
+        db.exec('BEGIN EXCLUSIVE');
+        db.exec('CREATE TABLE IF NOT EXISTS holder (pid INTEGER NOT NULL, hostname TEXT NOT NULL, acquired_at TEXT NOT NULL)');
+        db.exec('DELETE FROM holder');
+        db.prepare('INSERT INTO holder (pid, hostname, acquired_at) VALUES (?, ?, ?)').run(holder.pid, holder.hostname, holder.acquiredAt);
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        try {
+            db.close();
+        }
+        catch {
+            // ignore
+        }
+        if (err instanceof Error && /locked|busy/i.test(err.message)) {
+            throw new InstanceLockedError(lockPath, readHolderInfo(infoPath), err);
+        }
+        throw err;
+    }
+    try {
+        writeFileSync(infoPath, `${JSON.stringify(holder)}\n`, { mode: 0o600 });
+    }
+    catch {
+        // diagnostics only
+    }
+    HELD.add(db);
+    let held = true;
+    return {
+        path: lockPath,
+        get held() {
+            return held;
+        },
+        release() {
+            if (!held)
+                return;
+            held = false;
+            try {
+                rmSync(infoPath, { force: true });
+            }
+            catch {
+                // diagnostics only
+            }
+            HELD.delete(db);
+            db.close();
+        },
+    };
+}
+function readHolderInfo(infoPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(infoPath, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=instance-lock.js.map

package/dist/persistence/instance-lock.js.map

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

package/dist/persistence/lock-keys.d.ts

@@ -0,0 +1,16 @@
+import type { TriggerType } from '../core/index.js';
+/** Inputs determining a run's lock key. */
+export interface LockKeyInput {
+    triggerType: TriggerType;
+    runId: string;
+    sourceItemKey?: string | null;
+    /** Cron slot; required for `schedule` runs without item. */
+    scheduledFor?: Date | string | null;
+}
+/** Compute the lock key for a run (see module docs). */
+export declare function lockKeyFor(input: LockKeyInput): string;
+/**
+ * Internal non-null scope key for failure counters/blocks: the item key, or
+ * `''` for workflow scope (sourceless runs).
+ */
+export declare function blockScopeKey(itemKey: string | null | undefined): string;