@planu/cli 4.13.0 → 4.14.1

package/dist/storage/runtime-db.js

@@ -0,0 +1,1054 @@
+/* eslint-disable max-lines -- runtime schema, migrations and transactional operations remain co-located for auditability */
+import { mkdirSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+const CURRENT_SCHEMA_VERSION = 4;
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_CONNECTIONS = 4;
+const openConnections = new Map();
+export const DURABLE_JOB_STATES = [
+    'accepted',
+    'running',
+    'checkpointed',
+    'cancelled',
+    'failed',
+    'dead-letter',
+    'completed',
+];
+export class RuntimeDatabaseCorruptionError extends Error {
+    databasePath;
+    detail;
+    constructor(databasePath, detail) {
+        super(`[Planu] Runtime database failed integrity check: ${detail}`);
+        this.databasePath = databasePath;
+        this.detail = detail;
+        this.name = 'RuntimeDatabaseCorruptionError';
+    }
+}
+export class RuntimeDatabaseResourceExhaustedError extends Error {
+    databasePath;
+    maxConnections;
+    constructor(databasePath, maxConnections) {
+        super(`[Planu] Runtime database connection limit reached (${String(maxConnections)})`);
+        this.databasePath = databasePath;
+        this.maxConnections = maxConnections;
+        this.name = 'RuntimeDatabaseResourceExhaustedError';
+    }
+}
+function requireIdentifier(value, label) {
+    if (!value || value.length > 128 || !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value)) {
+        throw new Error(`[Planu] Invalid ${label}`);
+    }
+}
+function parseJson(raw) {
+    if (typeof raw !== 'string') {
+        throw new Error('[Planu] Runtime database contains invalid JSON');
+    }
+    return JSON.parse(raw);
+}
+function stringifyJson(value) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+        throw new Error('[Planu] Runtime value is not JSON serializable');
+    }
+    return serialized;
+}
+/** A bounded (one connection), transactional SQLite runtime store. */
+export class RuntimeDatabase {
+    path;
+    schemaVersion = CURRENT_SCHEMA_VERSION;
+    database;
+    connectionKey;
+    closed = false;
+    inTransaction = false;
+    // eslint-disable-next-line complexity -- constructor owns fail-safe acquisition and rollback
+    constructor(options) {
+        if (!options.path.trim()) {
+            throw new Error('[Planu] Runtime database path is required');
+        }
+        const busyTimeoutMs = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+        if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 0 || busyTimeoutMs > 60_000) {
+            throw new Error('[Planu] busyTimeoutMs must be an integer between 0 and 60000');
+        }
+        if (options.path !== ':memory:' && !isAbsolute(options.path)) {
+            throw new Error('[Planu] Runtime database path must be absolute');
+        }
+        const maxConnections = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
+        if (!Number.isSafeInteger(maxConnections) || maxConnections < 1 || maxConnections > 32) {
+            throw new Error('[Planu] maxConnections must be an integer between 1 and 32');
+        }
+        this.path = options.path === ':memory:' ? options.path : resolve(options.path);
+        this.connectionKey =
+            this.path === ':memory:' ? `${this.path}:${randomConnectionKey()}` : this.path;
+        const currentConnections = openConnections.get(this.connectionKey) ?? 0;
+        if (currentConnections >= maxConnections) {
+            throw new RuntimeDatabaseResourceExhaustedError(this.path, maxConnections);
+        }
+        openConnections.set(this.connectionKey, currentConnections + 1);
+        let database;
+        try {
+            if (this.path !== ':memory:') {
+                mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            }
+            database = new DatabaseSync(this.path, {
+                timeout: busyTimeoutMs,
+                enableForeignKeyConstraints: true,
+                enableDoubleQuotedStringLiterals: false,
+                allowExtension: false,
+            });
+            this.database = database;
+            this.database.exec('PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL;');
+            this.migrate();
+            if (options.checkIntegrity !== false) {
+                this.assertIntegrity();
+            }
+        }
+        catch (error) {
+            database?.close();
+            this.releaseConnection();
+            if (error instanceof Error && /malformed|not a database|disk image/i.test(error.message)) {
+                throw new RuntimeDatabaseCorruptionError(this.path, error.message);
+            }
+            throw error;
+        }
+    }
+    releaseConnection() {
+        const count = openConnections.get(this.connectionKey) ?? 0;
+        if (count <= 1) {
+            openConnections.delete(this.connectionKey);
+        }
+        else {
+            openConnections.set(this.connectionKey, count - 1);
+        }
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new Error('[Planu] Runtime database is closed');
+        }
+    }
+    // eslint-disable-next-line max-lines-per-function -- versioned DDL is intentionally auditable in one transaction
+    migrate() {
+        const row = this.database.prepare('PRAGMA user_version').get();
+        if (row.user_version > CURRENT_SCHEMA_VERSION) {
+            throw new Error(`[Planu] Runtime schema ${String(row.user_version)} is newer than supported`);
+        }
+        if (row.user_version === 0) {
+            this.database.exec(`
+        BEGIN IMMEDIATE;
+        CREATE TABLE runtime_records (
+          project_id TEXT NOT NULL,
+          workspace_id TEXT NOT NULL,
+          kind TEXT NOT NULL CHECK (kind IN ('mutation', 'index', 'audit-state')),
+          record_key TEXT NOT NULL,
+          value_json TEXT NOT NULL,
+          source_digest TEXT,
+          updated_at TEXT NOT NULL,
+          PRIMARY KEY (project_id, workspace_id, kind, record_key)
+        ) STRICT;
+        CREATE TABLE jobs (
+          id TEXT NOT NULL,
+          project_id TEXT NOT NULL,
+          workspace_id TEXT NOT NULL,
+          state TEXT NOT NULL CHECK (state IN ('accepted', 'running', 'checkpointed', 'cancelled', 'failed', 'dead-letter', 'completed')),
+          payload_json TEXT NOT NULL,
+          checkpoint_json TEXT,
+          result_json TEXT,
+          error_message TEXT,
+          attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+          max_attempts INTEGER NOT NULL DEFAULT 3 CHECK (max_attempts >= 1),
+          cancel_requested INTEGER NOT NULL DEFAULT 0 CHECK (cancel_requested IN (0, 1)),
+          lease_owner TEXT,
+          lease_expires_at TEXT,
+          fencing_token INTEGER NOT NULL DEFAULT 0 CHECK (fencing_token >= 0),
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          PRIMARY KEY (project_id, workspace_id, id)
+        ) STRICT;
+        CREATE TABLE outbox (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          project_id TEXT NOT NULL,
+          workspace_id TEXT NOT NULL,
+          topic TEXT NOT NULL,
+          payload_json TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          delivered_at TEXT
+        ) STRICT;
+        CREATE TABLE audit_log (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          project_id TEXT NOT NULL,
+          workspace_id TEXT NOT NULL,
+          event_type TEXT NOT NULL,
+          payload_json TEXT NOT NULL,
+          created_at TEXT NOT NULL
+        ) STRICT;
+        CREATE INDEX jobs_project_state ON jobs(project_id, workspace_id, state);
+        CREATE INDEX jobs_lease_expiry ON jobs(state, lease_expires_at);
+        CREATE INDEX outbox_pending ON outbox(project_id, workspace_id, delivered_at, id);
+        CREATE INDEX audit_project_time ON audit_log(project_id, workspace_id, created_at);
+        PRAGMA user_version = 4;
+        COMMIT;
+      `);
+        }
+        if (row.user_version === 1) {
+            this.database.exec(`
+        BEGIN IMMEDIATE;
+        CREATE TABLE jobs_v2 (
+          id TEXT NOT NULL,
+          project_id TEXT NOT NULL,
+          workspace_id TEXT NOT NULL,
+          state TEXT NOT NULL CHECK (state IN ('pending', 'running', 'completed', 'failed', 'cancelled')),
+          payload_json TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          PRIMARY KEY (project_id, workspace_id, id)
+        ) STRICT;
+        INSERT INTO jobs_v2 SELECT id, project_id, workspace_id, state, payload_json, created_at, updated_at FROM jobs;
+        DROP TABLE jobs;
+        ALTER TABLE jobs_v2 RENAME TO jobs;
+        CREATE TABLE outbox_v2 (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          project_id TEXT NOT NULL,
+          workspace_id TEXT NOT NULL,
+          topic TEXT NOT NULL,
+          payload_json TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          delivered_at TEXT
+        ) STRICT;
+        INSERT INTO outbox_v2 (id, project_id, workspace_id, topic, payload_json, created_at, delivered_at)
+          SELECT id, '__legacy__', 'global', topic, payload_json, created_at, delivered_at FROM outbox;
+        DROP TABLE outbox;
+        ALTER TABLE outbox_v2 RENAME TO outbox;
+        CREATE INDEX jobs_project_state ON jobs(project_id, workspace_id, state);
+        CREATE INDEX outbox_pending ON outbox(project_id, workspace_id, delivered_at, id);
+        PRAGMA user_version = 2;
+        COMMIT;
+      `);
+        }
+        const migrated = this.database.prepare('PRAGMA user_version').get();
+        if (migrated.user_version === 2) {
+            this.database.exec(`
+        BEGIN IMMEDIATE;
+        CREATE TABLE jobs_v3 (
+          id TEXT NOT NULL,
+          project_id TEXT NOT NULL,
+          workspace_id TEXT NOT NULL,
+          state TEXT NOT NULL CHECK (state IN ('accepted', 'running', 'checkpointed', 'cancelled', 'failed', 'dead-letter', 'completed')),
+          payload_json TEXT NOT NULL,
+          checkpoint_json TEXT,
+          result_json TEXT,
+          error_message TEXT,
+          attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+          max_attempts INTEGER NOT NULL DEFAULT 3 CHECK (max_attempts >= 1),
+          cancel_requested INTEGER NOT NULL DEFAULT 0 CHECK (cancel_requested IN (0, 1)),
+          lease_owner TEXT,
+          lease_expires_at TEXT,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          PRIMARY KEY (project_id, workspace_id, id)
+        ) STRICT;
+        INSERT INTO jobs_v3
+          (id, project_id, workspace_id, state, payload_json, created_at, updated_at)
+        SELECT id, project_id, workspace_id,
+          CASE state
+            WHEN 'pending' THEN 'accepted'
+            WHEN 'running' THEN 'checkpointed'
+            ELSE state
+          END,
+          payload_json, created_at, updated_at
+        FROM jobs;
+        DROP TABLE jobs;
+        ALTER TABLE jobs_v3 RENAME TO jobs;
+        CREATE INDEX jobs_project_state ON jobs(project_id, workspace_id, state);
+        CREATE INDEX jobs_lease_expiry ON jobs(state, lease_expires_at);
+        PRAGMA user_version = 3;
+        COMMIT;
+      `);
+        }
+        const current = this.database.prepare('PRAGMA user_version').get();
+        if (current.user_version === 3) {
+            this.database.exec(`
+        BEGIN IMMEDIATE;
+        ALTER TABLE jobs ADD COLUMN fencing_token INTEGER NOT NULL DEFAULT 0 CHECK (fencing_token >= 0);
+        UPDATE jobs SET
+          state = CASE
+            WHEN cancel_requested = 1 THEN 'cancelled'
+            WHEN attempts >= max_attempts THEN 'dead-letter'
+            ELSE 'checkpointed'
+          END,
+          error_message = CASE
+            WHEN attempts >= max_attempts THEN 'Lease expired after maximum attempts'
+            ELSE error_message
+          END,
+          lease_owner = NULL,
+          lease_expires_at = NULL
+        WHERE state = 'running';
+        PRAGMA user_version = 4;
+        COMMIT;
+      `);
+        }
+    }
+    assertIntegrity() {
+        this.assertOpen();
+        const rows = this.database.prepare('PRAGMA quick_check').all();
+        const failures = rows.map((row) => row.quick_check).filter((value) => value !== 'ok');
+        if (failures.length > 0) {
+            throw new RuntimeDatabaseCorruptionError(this.path, failures.join('; '));
+        }
+    }
+    journalMode() {
+        this.assertOpen();
+        const row = this.database.prepare('PRAGMA journal_mode').get();
+        return row.journal_mode;
+    }
+    transaction(operation) {
+        this.assertOpen();
+        if (this.inTransaction) {
+            throw new Error('[Planu] Nested runtime transactions are not supported');
+        }
+        this.database.exec('BEGIN IMMEDIATE');
+        this.inTransaction = true;
+        try {
+            const result = operation();
+            this.database.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.database.exec('ROLLBACK');
+            throw error;
+        }
+        finally {
+            this.inTransaction = false;
+        }
+    }
+    /** Run a consistent read-only snapshot without acquiring an immediate writer lock. */
+    snapshot(operation) {
+        this.assertOpen();
+        if (this.inTransaction) {
+            throw new Error('[Planu] Nested runtime transactions are not supported');
+        }
+        this.database.exec('BEGIN');
+        this.inTransaction = true;
+        try {
+            const result = operation();
+            this.database.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.database.exec('ROLLBACK');
+            throw error;
+        }
+        finally {
+            this.inTransaction = false;
+        }
+    }
+    putRecord(record) {
+        this.assertOpen();
+        requireIdentifier(record.projectId, 'projectId');
+        requireIdentifier(record.workspaceId, 'workspaceId');
+        requireIdentifier(record.key, 'record key');
+        const valueJson = stringifyJson(record.value);
+        this.database
+            .prepare(`
+        INSERT INTO runtime_records
+          (project_id, workspace_id, kind, record_key, value_json, source_digest, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(project_id, workspace_id, kind, record_key) DO UPDATE SET
+          value_json = excluded.value_json,
+          source_digest = excluded.source_digest,
+          updated_at = excluded.updated_at
+        WHERE excluded.updated_at >= runtime_records.updated_at
+      `)
+            .run(record.projectId, record.workspaceId, record.kind, record.key, valueJson, record.sourceDigest ?? null, record.updatedAt ?? new Date().toISOString());
+    }
+    getRecord(projectId, workspaceId, kind, key) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(key, 'record key');
+        const row = this.database
+            .prepare(`
+        SELECT project_id, workspace_id, kind, record_key, value_json, source_digest, updated_at
+        FROM runtime_records
+        WHERE project_id = ? AND workspace_id = ? AND kind = ? AND record_key = ?
+      `)
+            .get(projectId, workspaceId, kind, key);
+        return row ? mapRuntimeRecordRow(row) : undefined;
+    }
+    listRecords(projectId, workspaceId, kind) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        const rows = (kind
+            ? this.database
+                .prepare(`SELECT project_id, workspace_id, kind, record_key, value_json, source_digest, updated_at
+             FROM runtime_records
+             WHERE project_id = ? AND workspace_id = ? AND kind = ?
+             ORDER BY record_key`)
+                .all(projectId, workspaceId, kind)
+            : this.database
+                .prepare(`SELECT project_id, workspace_id, kind, record_key, value_json, source_digest, updated_at
+             FROM runtime_records
+             WHERE project_id = ? AND workspace_id = ?
+             ORDER BY kind, record_key`)
+                .all(projectId, workspaceId));
+        return rows.map(mapRuntimeRecordRow);
+    }
+    enqueueJob(input) {
+        this.assertOpen();
+        requireIdentifier(input.id, 'job id');
+        requireIdentifier(input.projectId, 'projectId');
+        requireIdentifier(input.workspaceId, 'workspaceId');
+        const maxAttempts = input.maxAttempts ?? 3;
+        if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 100) {
+            throw new Error('[Planu] maxAttempts must be an integer between 1 and 100');
+        }
+        const now = new Date().toISOString();
+        this.database
+            .prepare(`
+        INSERT INTO jobs
+          (id, project_id, workspace_id, state, payload_json, max_attempts, created_at, updated_at)
+        VALUES (?, ?, ?, 'accepted', ?, ?, ?, ?)
+      `)
+            .run(input.id, input.projectId, input.workspaceId, stringifyJson(input.payload), maxAttempts, now, now);
+    }
+    getJob(projectId, workspaceId, id) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(id, 'job id');
+        const row = this.database
+            .prepare(`SELECT * FROM jobs WHERE project_id = ? AND workspace_id = ? AND id = ?`)
+            .get(projectId, workspaceId, id);
+        return row ? mapJobRow(row) : undefined;
+    }
+    listJobs(projectId, workspaceId) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        const rows = this.database
+            .prepare(`SELECT * FROM jobs WHERE project_id = ? AND workspace_id = ? ORDER BY created_at, id`)
+            .all(projectId, workspaceId);
+        return rows.map(mapJobRow);
+    }
+    listRunnableJobScopes() {
+        this.assertOpen();
+        return this.database
+            .prepare(`SELECT DISTINCT project_id AS projectId, workspace_id AS workspaceId
+         FROM jobs WHERE state IN ('accepted', 'checkpointed', 'running')
+         ORDER BY project_id, workspace_id`)
+            .all();
+    }
+    claimJob(input) {
+        this.assertOpen();
+        validateLeaseInput(input);
+        const now = input.now ?? new Date().toISOString();
+        const expiresAt = new Date(Date.parse(now) + input.leaseMs).toISOString();
+        return this.transaction(() => {
+            this.recoverExpiredJobs(now, input.projectId, input.workspaceId);
+            const result = this.database
+                .prepare(`UPDATE jobs
+           SET state = 'running', attempts = attempts + 1, fencing_token = fencing_token + 1, lease_owner = ?,
+               lease_expires_at = ?, updated_at = ?
+           WHERE project_id = ? AND workspace_id = ? AND id = ?
+             AND state IN ('accepted', 'checkpointed') AND cancel_requested = 0
+             AND attempts < max_attempts`)
+                .run(input.workerId, expiresAt, now, input.projectId, input.workspaceId, input.id);
+            return result.changes === 1
+                ? this.getJob(input.projectId, input.workspaceId, input.id)
+                : undefined;
+        });
+    }
+    renewJobLease(input) {
+        this.assertOpen();
+        validateLeaseInput(input);
+        const now = input.now ?? new Date().toISOString();
+        const expiresAt = new Date(Date.parse(now) + input.leaseMs).toISOString();
+        const result = this.database
+            .prepare(`UPDATE jobs SET lease_expires_at = ?, updated_at = ?
+         WHERE project_id = ? AND workspace_id = ? AND id = ?
+           AND state = 'running' AND lease_owner = ? AND fencing_token = ? AND cancel_requested = 0
+           AND lease_expires_at > ?`)
+            .run(expiresAt, now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
+        return result.changes === 1;
+    }
+    recordJobProgress(input) {
+        this.requireLeasedJob(input);
+        const now = input.now ?? new Date().toISOString();
+        const result = this.database
+            .prepare(`UPDATE jobs SET checkpoint_json = ?, updated_at = ?
+         WHERE project_id = ? AND workspace_id = ? AND id = ?
+           AND state = 'running' AND lease_owner = ? AND fencing_token = ? AND cancel_requested = 0
+           AND lease_expires_at > ?`)
+            .run(stringifyJson(input.checkpoint), now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
+        if (result.changes !== 1) {
+            throw new Error('[Planu] Job lease was lost before checkpoint');
+        }
+        return requireJobRecord(this.getJob(input.projectId, input.workspaceId, input.id), input.id);
+    }
+    checkpointJob(input) {
+        return this.finishLeasedUpdate(input, 'checkpointed', {
+            checkpointJson: stringifyJson(input.checkpoint),
+        });
+    }
+    completeJob(input) {
+        return this.finishLeasedUpdate(input, 'completed', {
+            resultJson: stringifyJson(input.result),
+        });
+    }
+    failJob(input) {
+        if (!input.error.trim() || input.error.length > 4_096) {
+            throw new Error('[Planu] job error must contain between 1 and 4096 characters');
+        }
+        const current = this.requireLeasedJob(input);
+        const state = current.attempts >= current.maxAttempts ? 'dead-letter' : 'failed';
+        return this.finishLeasedUpdate(input, state, { errorMessage: input.error });
+    }
+    retryJob(projectId, workspaceId, id) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(id, 'job id');
+        const now = new Date().toISOString();
+        const result = this.database
+            .prepare(`UPDATE jobs SET state = 'accepted', error_message = NULL, updated_at = ?
+         WHERE project_id = ? AND workspace_id = ? AND id = ?
+           AND state = 'failed' AND cancel_requested = 0 AND attempts < max_attempts`)
+            .run(now, projectId, workspaceId, id);
+        if (result.changes !== 1) {
+            throw new Error('[Planu] Job is not retryable');
+        }
+        return requireJobRecord(this.getJob(projectId, workspaceId, id), id);
+    }
+    restartJob(projectId, workspaceId, id) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(id, 'job id');
+        const now = new Date().toISOString();
+        this.transaction(() => {
+            const current = this.getJob(projectId, workspaceId, id);
+            if (!current ||
+                !['accepted', 'checkpointed', 'failed', 'dead-letter', 'cancelled', 'completed'].includes(current.state)) {
+                throw new Error('[Planu] Job is not restartable');
+            }
+            this.archiveCheckpointBeforeRestart(projectId, workspaceId, id, now);
+            const result = this.database
+                .prepare(`UPDATE jobs SET state = 'accepted', attempts = 0, cancel_requested = 0,
+             checkpoint_json = NULL, result_json = NULL, error_message = NULL,
+             lease_owner = NULL, lease_expires_at = NULL, updated_at = ?
+           WHERE project_id = ? AND workspace_id = ? AND id = ?
+             AND state IN ('accepted', 'checkpointed', 'failed', 'dead-letter', 'cancelled', 'completed')`)
+                .run(now, projectId, workspaceId, id);
+            if (result.changes !== 1) {
+                throw new Error('[Planu] Job is not restartable');
+            }
+        });
+        return requireJobRecord(this.getJob(projectId, workspaceId, id), id);
+    }
+    restartJobWithPayload(projectId, workspaceId, id, payload) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(id, 'job id');
+        const now = new Date().toISOString();
+        this.transaction(() => {
+            const current = this.getJob(projectId, workspaceId, id);
+            if (!current ||
+                !['failed', 'dead-letter', 'cancelled', 'completed'].includes(current.state)) {
+                throw new Error('[Planu] Job payload is not replaceable while work is active');
+            }
+            this.archiveCheckpointBeforeRestart(projectId, workspaceId, id, now);
+            const result = this.database
+                .prepare(`UPDATE jobs SET state = 'accepted', attempts = 0, cancel_requested = 0,
+             payload_json = ?, checkpoint_json = NULL, result_json = NULL, error_message = NULL,
+             lease_owner = NULL, lease_expires_at = NULL, updated_at = ?
+           WHERE project_id = ? AND workspace_id = ? AND id = ?
+             AND state IN ('failed', 'dead-letter', 'cancelled', 'completed')`)
+                .run(stringifyJson(payload), now, projectId, workspaceId, id);
+            if (result.changes !== 1) {
+                throw new Error('[Planu] Job payload is not replaceable while work is active');
+            }
+        });
+        return requireJobRecord(this.getJob(projectId, workspaceId, id), id);
+    }
+    cancelJob(projectId, workspaceId, id) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(id, 'job id');
+        const current = this.getJob(projectId, workspaceId, id);
+        if (!current) {
+            throw new Error(`[Planu] Job ${id} was not found`);
+        }
+        if (current.state === 'completed' ||
+            current.state === 'cancelled' ||
+            current.state === 'dead-letter') {
+            return current;
+        }
+        const now = new Date().toISOString();
+        this.database
+            .prepare(`UPDATE jobs SET state = 'cancelled', cancel_requested = 1,
+           lease_owner = NULL, lease_expires_at = NULL, updated_at = ?
+         WHERE project_id = ? AND workspace_id = ? AND id = ?`)
+            .run(now, projectId, workspaceId, id);
+        return requireJobRecord(this.getJob(projectId, workspaceId, id), id);
+    }
+    archiveCheckpointBeforeRestart(projectId, workspaceId, id, restartedAt) {
+        const current = this.getJob(projectId, workspaceId, id);
+        if (current?.checkpoint === undefined) {
+            return;
+        }
+        this.putRecord({
+            projectId,
+            workspaceId,
+            kind: 'audit-state',
+            key: `job-attempt:${id.slice(0, 64)}:${process.hrtime.bigint().toString()}`,
+            value: {
+                operationId: id,
+                attempts: current.attempts,
+                previousState: current.state,
+                checkpoint: current.checkpoint,
+                restartedAt,
+            },
+        });
+    }
+    recoverExpiredJobs(now = new Date().toISOString(), projectId, workspaceId) {
+        this.assertOpen();
+        const scope = projectId && workspaceId ? ' AND project_id = ? AND workspace_id = ?' : '';
+        if ((projectId && !workspaceId) || (!projectId && workspaceId)) {
+            throw new Error('[Planu] projectId and workspaceId must be provided together');
+        }
+        if (projectId && workspaceId) {
+            requireIdentifier(projectId, 'projectId');
+            requireIdentifier(workspaceId, 'workspaceId');
+        }
+        const statement = this.database.prepare(`UPDATE jobs
+       SET state = CASE
+         WHEN cancel_requested = 1 THEN 'cancelled'
+         WHEN attempts >= max_attempts THEN 'dead-letter'
+         ELSE 'checkpointed'
+       END,
+       error_message = CASE WHEN attempts >= max_attempts THEN 'Lease expired after maximum attempts' ELSE error_message END,
+       lease_owner = NULL, lease_expires_at = NULL, updated_at = ?
+       WHERE state = 'running' AND lease_expires_at <= ?${scope}`);
+        const result = projectId && workspaceId
+            ? statement.run(now, now, projectId, workspaceId)
+            : statement.run(now, now);
+        return Number(result.changes);
+    }
+    requireLeasedJob(input) {
+        validateLeaseInput(input);
+        const current = this.getJob(input.projectId, input.workspaceId, input.id);
+        if (current?.state !== 'running' ||
+            current.leaseOwner !== input.workerId ||
+            current.fencingToken !== requireFencingToken(input)) {
+            throw new Error('[Planu] Job lease is stale or not owned by this worker');
+        }
+        const now = input.now ?? new Date().toISOString();
+        if (!current.leaseExpiresAt || current.leaseExpiresAt <= now) {
+            throw new Error('[Planu] Job lease has expired');
+        }
+        return current;
+    }
+    finishLeasedUpdate(input, state, values) {
+        this.requireLeasedJob(input);
+        const now = input.now ?? new Date().toISOString();
+        const result = this.database
+            .prepare(`UPDATE jobs SET state = ?, checkpoint_json = COALESCE(?, checkpoint_json),
+           result_json = COALESCE(?, result_json), error_message = ?,
+           lease_owner = NULL, lease_expires_at = NULL, updated_at = ?
+         WHERE project_id = ? AND workspace_id = ? AND id = ?
+           AND state = 'running' AND lease_owner = ? AND fencing_token = ?
+           AND lease_expires_at > ? AND cancel_requested = 0`)
+            .run(state, values.checkpointJson ?? null, values.resultJson ?? null, values.errorMessage ?? null, now, input.projectId, input.workspaceId, input.id, input.workerId, requireFencingToken(input), now);
+        if (result.changes !== 1) {
+            throw new Error('[Planu] Job lease was lost before commit');
+        }
+        return requireJobRecord(this.getJob(input.projectId, input.workspaceId, input.id), input.id);
+    }
+    enqueueOutbox(input) {
+        this.assertOpen();
+        requireIdentifier(input.projectId, 'projectId');
+        requireIdentifier(input.workspaceId, 'workspaceId');
+        requireIdentifier(input.topic, 'outbox topic');
+        const result = this.database
+            .prepare('INSERT INTO outbox (project_id, workspace_id, topic, payload_json, created_at) VALUES (?, ?, ?, ?, ?)')
+            .run(input.projectId, input.workspaceId, input.topic, stringifyJson(input.payload), new Date().toISOString());
+        return Number(result.lastInsertRowid);
+    }
+    listOutbox(projectId, workspaceId, options = {}) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        const limit = options.limit ?? 100;
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1_000) {
+            throw new Error('[Planu] outbox limit must be an integer between 1 and 1000');
+        }
+        const pendingClause = options.pendingOnly === false ? '' : ' AND delivered_at IS NULL';
+        const topics = options.topics ?? [];
+        for (const topic of topics) {
+            requireIdentifier(topic, 'outbox topic');
+        }
+        const topicsClause = topics.length > 0 ? ` AND topic IN (${topics.map(() => '?').join(', ')})` : '';
+        const rows = this.database
+            .prepare(`SELECT id, project_id, workspace_id, topic, payload_json, created_at, delivered_at
+         FROM outbox
+         WHERE project_id = ? AND workspace_id = ?${pendingClause}${topicsClause}
+         ORDER BY id LIMIT ?`)
+            .all(projectId, workspaceId, ...topics, limit);
+        return rows.map(mapOutboxRow);
+    }
+    listPendingOutboxScopes() {
+        this.assertOpen();
+        return this.database
+            .prepare(`SELECT DISTINCT project_id AS projectId, workspace_id AS workspaceId
+         FROM outbox WHERE delivered_at IS NULL ORDER BY project_id, workspace_id`)
+            .all();
+    }
+    markOutboxDelivered(projectId, workspaceId, id, deliveredAt = new Date().toISOString()) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        if (!Number.isSafeInteger(id) || id < 1) {
+            throw new Error('[Planu] outbox id must be a positive integer');
+        }
+        if (!Number.isFinite(Date.parse(deliveredAt))) {
+            throw new Error('[Planu] deliveredAt must be a valid ISO date');
+        }
+        const result = this.database
+            .prepare(`UPDATE outbox SET delivered_at = ?
+         WHERE id = ? AND project_id = ? AND workspace_id = ? AND delivered_at IS NULL`)
+            .run(deliveredAt, id, projectId, workspaceId);
+        return result.changes === 1;
+    }
+    appendAudit(input) {
+        this.assertOpen();
+        requireIdentifier(input.projectId, 'projectId');
+        requireIdentifier(input.workspaceId, 'workspaceId');
+        requireIdentifier(input.eventType, 'event type');
+        const result = this.database
+            .prepare(`
+        INSERT INTO audit_log (project_id, workspace_id, event_type, payload_json, created_at)
+        VALUES (?, ?, ?, ?, ?)
+      `)
+            .run(input.projectId, input.workspaceId, input.eventType, stringifyJson(input.payload), new Date().toISOString());
+        return Number(result.lastInsertRowid);
+    }
+    listAudit(projectId, workspaceId, options = {}) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        const afterId = options.afterId ?? 0;
+        const limit = options.limit ?? 100;
+        if (!Number.isSafeInteger(afterId) || afterId < 0) {
+            throw new Error('[Planu] audit afterId must be a non-negative integer');
+        }
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1_000) {
+            throw new Error('[Planu] audit limit must be an integer between 1 and 1000');
+        }
+        const rows = this.database
+            .prepare(`SELECT id, project_id, workspace_id, event_type, payload_json, created_at
+         FROM audit_log
+         WHERE project_id = ? AND workspace_id = ? AND id > ?
+         ORDER BY id LIMIT ?`)
+            .all(projectId, workspaceId, afterId, limit);
+        return rows.map(mapAuditRow);
+    }
+    /** Recover every authoritative mutable family for one isolated workspace. */
+    recoverWorkspace(projectId, workspaceId) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        requireIdentifier(workspaceId, 'workspaceId');
+        this.recoverExpiredJobs(new Date().toISOString(), projectId, workspaceId);
+        return this.snapshot(() => {
+            const outbox = this.database
+                .prepare(`SELECT id, project_id, workspace_id, topic, payload_json, created_at, delivered_at
+           FROM outbox WHERE project_id = ? AND workspace_id = ? ORDER BY id`)
+                .all(projectId, workspaceId);
+            const audit = this.database
+                .prepare(`SELECT id, project_id, workspace_id, event_type, payload_json, created_at
+           FROM audit_log WHERE project_id = ? AND workspace_id = ? ORDER BY id`)
+                .all(projectId, workspaceId);
+            return {
+                schemaVersion: CURRENT_SCHEMA_VERSION,
+                projectId,
+                workspaceId,
+                records: this.listRecords(projectId, workspaceId),
+                jobs: this.listJobs(projectId, workspaceId),
+                outbox: outbox.map(mapOutboxRow),
+                audit: audit.map(mapAuditRow),
+            };
+        });
+    }
+    exportProject(projectId) {
+        this.assertOpen();
+        requireIdentifier(projectId, 'projectId');
+        return this.snapshot(() => this.exportProjectSnapshot(projectId));
+    }
+    exportProjectSnapshot(projectId) {
+        const records = this.database
+            .prepare('SELECT project_id, workspace_id, kind, record_key, value_json, source_digest, updated_at FROM runtime_records WHERE project_id = ? ORDER BY workspace_id, kind, record_key')
+            .all(projectId);
+        const mapRows = (rows) => rows.map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [
+            key,
+            key.endsWith('_json') && value !== null ? parseJson(value) : value,
+        ])));
+        const mappedRecords = records.map((row) => ({
+            projectId: String(row.project_id),
+            workspaceId: String(row.workspace_id),
+            kind: row.kind,
+            key: String(row.record_key),
+            value: parseJson(row.value_json),
+            sourceDigest: typeof row.source_digest === 'string' ? row.source_digest : undefined,
+            updatedAt: String(row.updated_at),
+        }));
+        const jobs = this.database
+            .prepare('SELECT * FROM jobs WHERE project_id = ? ORDER BY workspace_id, id')
+            .all(projectId);
+        const outbox = this.database
+            .prepare('SELECT * FROM outbox WHERE project_id = ? ORDER BY workspace_id, id')
+            .all(projectId);
+        const audit = this.database
+            .prepare('SELECT * FROM audit_log WHERE project_id = ? ORDER BY workspace_id, id')
+            .all(projectId);
+        return {
+            schemaVersion: 1,
+            projectId,
+            records: mappedRecords,
+            jobs: mapRows(jobs),
+            outbox: mapRows(outbox),
+            audit: mapRows(audit),
+        };
+    }
+    // eslint-disable-next-line complexity -- portable job validation is intentionally explicit
+    importJob(job) {
+        requireIdentifier(String(job.id), 'job id');
+        requireIdentifier(String(job.workspace_id), 'workspaceId');
+        const importedState = String(job.state);
+        const attempts = job.attempts === undefined ? 0 : Number(job.attempts);
+        const maxAttempts = job.max_attempts === undefined ? 3 : Number(job.max_attempts);
+        const fencingToken = job.fencing_token === undefined ? 0 : Number(job.fencing_token);
+        if (!Number.isSafeInteger(attempts) ||
+            attempts < 0 ||
+            !Number.isSafeInteger(maxAttempts) ||
+            maxAttempts < 1 ||
+            maxAttempts > 100 ||
+            !Number.isSafeInteger(fencingToken) ||
+            fencingToken < 0) {
+            throw new Error('[Planu] Runtime bundle contains invalid job attempts');
+        }
+        const importedRunning = importedState === 'running';
+        const state = importedState === 'pending'
+            ? 'accepted'
+            : importedRunning
+                ? job.cancel_requested === 1
+                    ? 'cancelled'
+                    : attempts >= maxAttempts
+                        ? 'dead-letter'
+                        : 'checkpointed'
+                : importedState;
+        if (!DURABLE_JOB_STATES.includes(state)) {
+            throw new Error('[Planu] Runtime bundle contains invalid job state');
+        }
+        this.database
+            .prepare(`INSERT INTO jobs
+          (id, project_id, workspace_id, state, payload_json, checkpoint_json, result_json,
+           error_message, attempts, max_attempts, cancel_requested, lease_owner,
+           lease_expires_at, fencing_token, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(project_id, workspace_id, id) DO UPDATE SET
+           state = excluded.state, payload_json = excluded.payload_json,
+           checkpoint_json = excluded.checkpoint_json, result_json = excluded.result_json,
+           error_message = excluded.error_message, attempts = excluded.attempts,
+           max_attempts = excluded.max_attempts, cancel_requested = excluded.cancel_requested,
+           lease_owner = excluded.lease_owner, lease_expires_at = excluded.lease_expires_at,
+           fencing_token = MAX(jobs.fencing_token, excluded.fencing_token),
+           updated_at = excluded.updated_at
+         WHERE jobs.state != 'running' AND excluded.updated_at >= jobs.updated_at
+           AND NOT (
+             jobs.state IN ('cancelled', 'failed', 'dead-letter', 'completed')
+             AND excluded.state IN ('accepted', 'running', 'checkpointed')
+           )`)
+            .run(String(job.id), String(job.project_id), String(job.workspace_id), state, stringifyJson(job.payload_json), job.checkpoint_json === null || job.checkpoint_json === undefined
+            ? null
+            : stringifyJson(job.checkpoint_json), job.result_json === null || job.result_json === undefined
+            ? null
+            : stringifyJson(job.result_json), typeof job.error_message === 'string' ? job.error_message : null, attempts, maxAttempts, job.cancel_requested === 1 ? 1 : 0, !importedRunning && typeof job.lease_owner === 'string' ? job.lease_owner : null, !importedRunning && typeof job.lease_expires_at === 'string' ? job.lease_expires_at : null, fencingToken, String(job.created_at), String(job.updated_at));
+    }
+    assertLedgerIdAvailable(table, id, projectId, workspaceId) {
+        const existing = this.database
+            .prepare(`SELECT project_id, workspace_id FROM ${table} WHERE id = ?`)
+            .get(id);
+        if (existing && (existing.project_id !== projectId || existing.workspace_id !== workspaceId)) {
+            throw new Error(`[Planu] Runtime bundle ${table} id collides with another project`);
+        }
+    }
+    importOutbox(item, projectId) {
+        const id = Number(item.id);
+        if (!Number.isSafeInteger(id) || id < 1) {
+            throw new Error('[Planu] Runtime bundle contains invalid outbox id');
+        }
+        const workspaceId = String(item.workspace_id);
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(String(item.topic), 'outbox topic');
+        this.assertLedgerIdAvailable('outbox', id, projectId, workspaceId);
+        this.database
+            .prepare(`INSERT INTO outbox
+          (id, project_id, workspace_id, topic, payload_json, created_at, delivered_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           topic = excluded.topic,
+           payload_json = excluded.payload_json,
+           delivered_at = excluded.delivered_at
+         WHERE outbox.project_id = excluded.project_id
+           AND outbox.workspace_id = excluded.workspace_id`)
+            .run(id, projectId, workspaceId, String(item.topic), stringifyJson(item.payload_json), String(item.created_at), typeof item.delivered_at === 'string' ? item.delivered_at : null);
+    }
+    importAudit(event, projectId) {
+        const id = Number(event.id);
+        if (!Number.isSafeInteger(id) || id < 1) {
+            throw new Error('[Planu] Runtime bundle contains invalid audit id');
+        }
+        const workspaceId = String(event.workspace_id);
+        requireIdentifier(workspaceId, 'workspaceId');
+        requireIdentifier(String(event.event_type), 'event type');
+        this.assertLedgerIdAvailable('audit_log', id, projectId, workspaceId);
+        this.database
+            .prepare(`INSERT INTO audit_log
+          (id, project_id, workspace_id, event_type, payload_json, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           event_type = excluded.event_type,
+           payload_json = excluded.payload_json
+         WHERE audit_log.project_id = excluded.project_id
+           AND audit_log.workspace_id = excluded.workspace_id`)
+            .run(id, projectId, workspaceId, String(event.event_type), stringifyJson(event.payload_json), String(event.created_at));
+    }
+    importProject(bundle) {
+        requireIdentifier(bundle.projectId, 'projectId');
+        const foreignProject = [
+            ...bundle.records.map((item) => item.projectId),
+            ...bundle.jobs.map((item) => String(item.project_id)),
+            ...bundle.outbox.map((item) => String(item.project_id)),
+            ...bundle.audit.map((item) => String(item.project_id)),
+        ].find((projectId) => projectId !== bundle.projectId);
+        if (foreignProject) {
+            throw new Error('[Planu] Runtime bundle contains cross-project data');
+        }
+        this.transaction(() => {
+            for (const record of bundle.records) {
+                this.putRecord(record);
+            }
+            for (const job of bundle.jobs) {
+                this.importJob(job);
+            }
+            for (const item of bundle.outbox) {
+                this.importOutbox(item, bundle.projectId);
+            }
+            for (const event of bundle.audit) {
+                this.importAudit(event, bundle.projectId);
+            }
+        });
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        try {
+            this.database.close();
+        }
+        finally {
+            this.releaseConnection();
+            this.closed = true;
+        }
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+let inMemoryConnectionSequence = 0;
+function randomConnectionKey() {
+    inMemoryConnectionSequence += 1;
+    return String(inMemoryConnectionSequence);
+}
+function validateLeaseInput(input) {
+    requireIdentifier(input.id, 'job id');
+    requireIdentifier(input.projectId, 'projectId');
+    requireIdentifier(input.workspaceId, 'workspaceId');
+    requireIdentifier(input.workerId, 'worker id');
+    if (!Number.isSafeInteger(input.leaseMs) || input.leaseMs < 100 || input.leaseMs > 300_000) {
+        throw new Error('[Planu] leaseMs must be an integer between 100 and 300000');
+    }
+    if (input.now !== undefined && !Number.isFinite(Date.parse(input.now))) {
+        throw new Error('[Planu] lease timestamp must be a valid ISO date');
+    }
+}
+function requireFencingToken(input) {
+    const token = input.fencingToken;
+    if (token === undefined || !Number.isSafeInteger(token) || token < 1) {
+        throw new Error('[Planu] Job lease requires a positive fencing token');
+    }
+    return token;
+}
+function optionalJson(value) {
+    return typeof value === 'string' ? parseJson(value) : undefined;
+}
+function mapRuntimeRecordRow(row) {
+    return {
+        projectId: row.project_id,
+        workspaceId: row.workspace_id,
+        kind: row.kind,
+        key: row.record_key,
+        value: parseJson(row.value_json),
+        sourceDigest: row.source_digest ?? undefined,
+        updatedAt: row.updated_at,
+    };
+}
+function mapOutboxRow(row) {
+    return {
+        id: Number(row.id),
+        projectId: String(row.project_id),
+        workspaceId: String(row.workspace_id),
+        topic: String(row.topic),
+        payload: parseJson(row.payload_json),
+        createdAt: String(row.created_at),
+        deliveredAt: typeof row.delivered_at === 'string' ? row.delivered_at : undefined,
+    };
+}
+function mapAuditRow(row) {
+    return {
+        id: Number(row.id),
+        projectId: String(row.project_id),
+        workspaceId: String(row.workspace_id),
+        eventType: String(row.event_type),
+        payload: parseJson(row.payload_json),
+        createdAt: String(row.created_at),
+    };
+}
+function requireJobRecord(job, id) {
+    if (!job) {
+        throw new Error(`[Planu] Job ${id} disappeared after a committed update`);
+    }
+    return job;
+}
+function mapJobRow(row) {
+    return {
+        id: String(row.id),
+        projectId: String(row.project_id),
+        workspaceId: String(row.workspace_id),
+        state: row.state,
+        payload: parseJson(row.payload_json),
+        checkpoint: optionalJson(row.checkpoint_json),
+        result: optionalJson(row.result_json),
+        error: typeof row.error_message === 'string' ? row.error_message : undefined,
+        attempts: Number(row.attempts),
+        maxAttempts: Number(row.max_attempts),
+        cancelRequested: row.cancel_requested === 1,
+        leaseOwner: typeof row.lease_owner === 'string' ? row.lease_owner : undefined,
+        fencingToken: Number(row.fencing_token),
+        leaseExpiresAt: typeof row.lease_expires_at === 'string' ? row.lease_expires_at : undefined,
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+    };
+}
+//# sourceMappingURL=runtime-db.js.map