@planu/cli 4.13.0 → 4.14.1

package/dist/engine/execution/operation-journal.js

@@ -0,0 +1,260 @@
+import { BoundaryFailure } from '../../errors/error-taxonomy.js';
+const ACTIVE_STATES = ['intent', 'prepared'];
+const ALL_STATES = [
+    ...ACTIVE_STATES,
+    'committed',
+    'acknowledged',
+    'rolled-back',
+    'quarantined',
+];
+function parseEntry(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const legacy = value;
+    if (typeof legacy.operation !== 'string' ||
+        typeof legacy.idempotencyKey !== 'string' ||
+        typeof legacy.requestDigest !== 'string' ||
+        typeof legacy.state !== 'string' ||
+        !ALL_STATES.includes(legacy.state) ||
+        typeof legacy.createdAt !== 'string' ||
+        typeof legacy.updatedAt !== 'string') {
+        throw new BoundaryFailure('Corrupt', 'operation journal read', 'Quarantine the invalid journal record before recovering operations.');
+    }
+    return {
+        ...legacy,
+        schemaVersion: 2,
+        recoveryAttempts: legacy.recoveryAttempts ?? 0,
+    };
+}
+/** Durable, monotonic command journal backed by the canonical runtime database. */
+export class OperationJournal {
+    database;
+    projectId;
+    workspaceId;
+    constructor(database, projectId, workspaceId = 'default') {
+        this.database = database;
+        this.projectId = projectId;
+        this.workspaceId = workspaceId;
+    }
+    get(operation, idempotencyKey) {
+        const record = this.database.getRecord(this.projectId, this.workspaceId, 'mutation', this.recordKey(operation, idempotencyKey));
+        return parseEntry(record?.value);
+    }
+    list(operation) {
+        const prefix = operation ? `op:v2:${Buffer.from(operation).toString('base64url')}:` : 'op:v2:';
+        return this.database
+            .listRecords(this.projectId, this.workspaceId, 'mutation')
+            .filter((record) => record.key.startsWith(prefix))
+            .map((record) => parseEntry(record.value))
+            .filter((entry) => entry !== undefined);
+    }
+    begin(operation, idempotencyKey, requestDigest, recovery) {
+        return this.database.transaction(() => {
+            const existing = this.get(operation, idempotencyKey);
+            if (existing) {
+                if (existing.requestDigest !== requestDigest) {
+                    throw new BoundaryFailure('Conflict', 'operation begin', 'Use a new idempotency key for a different request.');
+                }
+                return existing;
+            }
+            const now = new Date().toISOString();
+            const entry = {
+                schemaVersion: 2,
+                operation,
+                idempotencyKey,
+                requestDigest,
+                state: 'intent',
+                ...(recovery ?? {}),
+                recoveryAttempts: 0,
+                createdAt: now,
+                updatedAt: now,
+            };
+            this.put(entry);
+            return entry;
+        });
+    }
+    setRecoveryPayload(operation, idempotencyKey, payloadVersion, payload) {
+        if (!Number.isSafeInteger(payloadVersion) || payloadVersion < 1) {
+            throw new Error('[Planu] Recovery payload version must be a positive integer');
+        }
+        return this.database.transaction(() => {
+            const current = this.require(operation, idempotencyKey);
+            if (!ACTIVE_STATES.includes(current.state)) {
+                throw new BoundaryFailure('Conflict', 'recovery payload update', 'Do not modify recovery payload after a terminal transition.');
+            }
+            const next = {
+                ...current,
+                payloadVersion,
+                payload,
+                updatedAt: new Date().toISOString(),
+            };
+            this.put(next);
+            return next;
+        });
+    }
+    restartRolledBack(operation, idempotencyKey) {
+        return this.database.transaction(() => {
+            const current = this.require(operation, idempotencyKey);
+            if (current.state !== 'rolled-back') {
+                return current;
+            }
+            const next = {
+                ...current,
+                state: 'intent',
+                payload: undefined,
+                payloadVersion: undefined,
+                recoveryReason: undefined,
+                updatedAt: new Date().toISOString(),
+            };
+            this.put(next);
+            return next;
+        });
+    }
+    prepared(operation, idempotencyKey) {
+        return this.advance(operation, idempotencyKey, 'prepared');
+    }
+    committed(operation, idempotencyKey, result) {
+        return this.commitWithOutbox(operation, idempotencyKey, result);
+    }
+    commitWithOutbox(operation, idempotencyKey, result, outbox) {
+        return this.database.transaction(() => {
+            const current = this.require(operation, idempotencyKey);
+            if (current.state === 'committed' || current.state === 'acknowledged') {
+                return current;
+            }
+            if (current.state !== 'prepared') {
+                throw new BoundaryFailure('Conflict', 'operation commit', 'Commit only a prepared operation.');
+            }
+            if (result === undefined) {
+                throw new Error('[Planu] Committed operation requires a persisted result');
+            }
+            const next = this.next(current, 'committed', { result });
+            this.put(next);
+            if (outbox) {
+                this.database.enqueueOutbox({
+                    projectId: this.projectId,
+                    workspaceId: this.workspaceId,
+                    topic: outbox.topic,
+                    payload: {
+                        schemaVersion: 1,
+                        operation,
+                        idempotencyKey,
+                        body: outbox.payload,
+                    },
+                });
+            }
+            return next;
+        });
+    }
+    acknowledged(operation, idempotencyKey) {
+        return this.advance(operation, idempotencyKey, 'acknowledged');
+    }
+    resolveRecovery(operation, idempotencyKey, decision) {
+        return this.database.transaction(() => {
+            const current = this.require(operation, idempotencyKey);
+            return this.applyRecovery(current, decision);
+        });
+    }
+    resolveRecoveryIfCurrent(snapshot, decision) {
+        return this.database.transaction(() => {
+            const current = this.require(snapshot.operation, snapshot.idempotencyKey);
+            if (current.state !== snapshot.state ||
+                current.updatedAt !== snapshot.updatedAt ||
+                current.recoveryAttempts !== snapshot.recoveryAttempts ||
+                current.requestDigest !== snapshot.requestDigest) {
+                return current;
+            }
+            return this.applyRecovery(current, decision);
+        });
+    }
+    applyRecovery(current, decision) {
+        if (!ACTIVE_STATES.includes(current.state)) {
+            return current;
+        }
+        if (decision.action === 'commit') {
+            if (current.state !== 'prepared' || decision.result === undefined) {
+                throw new Error('[Planu] Recovery commit requires a prepared operation and result');
+            }
+            const next = this.next(current, 'committed', { result: decision.result });
+            this.put(next);
+            if (decision.outbox) {
+                this.database.enqueueOutbox({
+                    projectId: this.projectId,
+                    workspaceId: this.workspaceId,
+                    topic: decision.outbox.topic,
+                    payload: {
+                        schemaVersion: 1,
+                        operation: current.operation,
+                        idempotencyKey: current.idempotencyKey,
+                        body: decision.outbox.payload,
+                    },
+                });
+            }
+            return next;
+        }
+        const state = decision.action === 'rollback' ? 'rolled-back' : 'quarantined';
+        const next = this.next(current, state, { recoveryReason: decision.reason });
+        this.put(next);
+        return next;
+    }
+    advance(operation, idempotencyKey, target) {
+        return this.database.transaction(() => {
+            const current = this.require(operation, idempotencyKey);
+            if (current.state === target) {
+                return current;
+            }
+            const valid = (current.state === 'intent' && target === 'prepared') ||
+                (current.state === 'committed' && target === 'acknowledged');
+            if (!valid) {
+                throw new BoundaryFailure('Conflict', 'operation transition', `Transition ${current.state} only through the declared state machine.`);
+            }
+            const next = this.next(current, target);
+            this.put(next);
+            return next;
+        });
+    }
+    next(current, state, values = {}) {
+        return {
+            ...current,
+            ...values,
+            state,
+            recoveryAttempts: state === 'rolled-back' || state === 'quarantined'
+                ? current.recoveryAttempts + 1
+                : current.recoveryAttempts,
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    require(operation, idempotencyKey) {
+        const entry = this.get(operation, idempotencyKey);
+        if (!entry) {
+            throw new BoundaryFailure('NotFound', 'operation journal lookup', 'Persist the operation intent before advancing it.');
+        }
+        return entry;
+    }
+    put(entry) {
+        this.database.putRecord({
+            projectId: this.projectId,
+            workspaceId: this.workspaceId,
+            kind: 'mutation',
+            key: this.recordKey(entry.operation, entry.idempotencyKey),
+            value: entry,
+        });
+    }
+    recordKey(operation, idempotencyKey) {
+        return `op:v2:${Buffer.from(operation).toString('base64url')}:${Buffer.from(idempotencyKey).toString('base64url')}`;
+    }
+}
+/** Reconciles stale intents using one operation-specific, deterministic strategy. */
+export async function recoverOperationJournal(input) {
+    const recovered = [];
+    for (const entry of input.journal.list(input.operation)) {
+        if (!ACTIVE_STATES.includes(entry.state) || entry.updatedAt > input.staleBefore) {
+            continue;
+        }
+        const decision = await input.decide(entry);
+        recovered.push(input.journal.resolveRecoveryIfCurrent(entry, decision));
+    }
+    return recovered;
+}
+//# sourceMappingURL=operation-journal.js.map

package/dist/engine/execution/outbox-worker.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeDatabase } from '../../storage/runtime-db.js';
+import type { OutboxDeliveryContext } from '../../types/outbox-worker.js';
+export type { OutboxDeliveryContext } from '../../types/outbox-worker.js';
+/**
+ * Durable outbox dispatcher. The sink must deduplicate `deliveryKey`; this stable key closes the
+ * unavoidable crash window between an external acknowledgement and the local delivered marker.
+ */
+export declare class TransactionalOutboxWorker {
+    private readonly database;
+    private readonly projectId;
+    private readonly workspaceId;
+    private readonly workerId;
+    private readonly leaseMs;
+    private readonly maxAttempts;
+    constructor(database: RuntimeDatabase, projectId: string, workspaceId: string, workerId: string, leaseMs?: number, maxAttempts?: number);
+    drain(deliver: (context: OutboxDeliveryContext) => Promise<void>, options?: {
+        readonly now?: string;
+        readonly clock?: () => Date;
+        readonly limit?: number;
+        readonly topics?: readonly string[];
+    }): Promise<{
+        readonly delivered: number;
+        readonly skipped: number;
+    }>;
+    private claim;
+    private fail;
+    private complete;
+    private deliveryKey;
+    private fenceKey;
+}
+//# sourceMappingURL=outbox-worker.d.ts.map

package/dist/engine/execution/outbox-worker.js

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto';
+import { BoundaryFailure } from '../../errors/error-taxonomy.js';
+function parseFence(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const fence = value;
+    if (fence.schemaVersion !== 1 ||
+        typeof fence.workerId !== 'string' ||
+        !Number.isSafeInteger(fence.fencingToken) ||
+        typeof fence.leaseExpiresAt !== 'string' ||
+        typeof fence.state !== 'string' ||
+        !['leased', 'failed', 'dead-letter', 'delivered'].includes(fence.state)) {
+        throw new BoundaryFailure('Corrupt', 'outbox fence read', 'Quarantine the invalid fence record before retrying delivery.');
+    }
+    return fence;
+}
+/**
+ * Durable outbox dispatcher. The sink must deduplicate `deliveryKey`; this stable key closes the
+ * unavoidable crash window between an external acknowledgement and the local delivered marker.
+ */
+export class TransactionalOutboxWorker {
+    database;
+    projectId;
+    workspaceId;
+    workerId;
+    leaseMs;
+    maxAttempts;
+    constructor(database, projectId, workspaceId, workerId, leaseMs = 30_000, maxAttempts = 3) {
+        this.database = database;
+        this.projectId = projectId;
+        this.workspaceId = workspaceId;
+        this.workerId = workerId;
+        this.leaseMs = leaseMs;
+        this.maxAttempts = maxAttempts;
+        if (!workerId.trim()) {
+            throw new Error('[Planu] Outbox worker id is required');
+        }
+        if (!Number.isSafeInteger(leaseMs) || leaseMs < 1 || leaseMs > 300_000) {
+            throw new Error('[Planu] Outbox leaseMs must be an integer between 1 and 300000');
+        }
+        if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 100) {
+            throw new Error('[Planu] Outbox maxAttempts must be an integer between 1 and 100');
+        }
+    }
+    async drain(deliver, options = {}) {
+        const clock = options.clock ?? (() => new Date());
+        const now = currentIso(clock, options.now);
+        let delivered = 0;
+        let skipped = 0;
+        const pending = this.database.listOutbox(this.projectId, this.workspaceId, {
+            pendingOnly: true,
+            limit: options.limit,
+            topics: options.topics,
+        });
+        for (const message of pending) {
+            const fence = this.claim(message, now);
+            if (!fence) {
+                skipped += 1;
+                continue;
+            }
+            try {
+                await deliver({
+                    deliveryKey: this.deliveryKey(message),
+                    fencingToken: fence.fencingToken,
+                    topic: message.topic,
+                    payload: message.payload,
+                });
+            }
+            catch {
+                const failure = new BoundaryFailure('DependencyUnavailable', 'outbox delivery', 'Retry with the stable delivery key after the dependency recovers.');
+                this.fail(message, fence, failure, currentIso(clock, options.now));
+                throw failure;
+            }
+            if (!this.complete(message, fence, currentIso(clock, options.now))) {
+                throw new BoundaryFailure('Conflict', 'outbox delivery commit', 'Another worker owns the lease; retry with the stable delivery key.');
+            }
+            delivered += 1;
+        }
+        return { delivered, skipped };
+    }
+    claim(message, now) {
+        return this.database.transaction(() => {
+            const key = this.fenceKey(message.id);
+            const existing = parseFence(this.database.getRecord(this.projectId, this.workspaceId, 'mutation', key)?.value);
+            if (existing?.state === 'delivered') {
+                this.database.markOutboxDelivered(this.projectId, this.workspaceId, message.id, now);
+                return undefined;
+            }
+            if (existing?.state === 'dead-letter') {
+                return undefined;
+            }
+            if (existing?.state === 'leased' && existing.leaseExpiresAt > now) {
+                return undefined;
+            }
+            const fence = {
+                schemaVersion: 1,
+                workerId: this.workerId,
+                fencingToken: (existing?.fencingToken ?? 0) + 1,
+                leaseExpiresAt: new Date(Date.parse(now) + this.leaseMs).toISOString(),
+                state: 'leased',
+                attempts: (existing?.attempts ?? 0) + 1,
+            };
+            this.database.putRecord({
+                projectId: this.projectId,
+                workspaceId: this.workspaceId,
+                kind: 'mutation',
+                key,
+                value: fence,
+                updatedAt: now,
+            });
+            return fence;
+        });
+    }
+    fail(message, fence, error, now) {
+        return this.database.transaction(() => {
+            const key = this.fenceKey(message.id);
+            const current = parseFence(this.database.getRecord(this.projectId, this.workspaceId, 'mutation', key)?.value);
+            if (current?.state === 'delivered') {
+                this.database.markOutboxDelivered(this.projectId, this.workspaceId, message.id, now);
+                return true;
+            }
+            if (current?.state !== 'leased' ||
+                current.workerId !== this.workerId ||
+                current.fencingToken !== fence.fencingToken) {
+                return false;
+            }
+            const attempts = current.attempts ?? 1;
+            this.database.putRecord({
+                projectId: this.projectId,
+                workspaceId: this.workspaceId,
+                kind: 'mutation',
+                key,
+                value: {
+                    ...current,
+                    state: attempts >= this.maxAttempts ? 'dead-letter' : 'failed',
+                    leaseExpiresAt: now,
+                    lastError: error instanceof BoundaryFailure
+                        ? error.message
+                        : new BoundaryFailure('Internal', 'outbox failure recording', 'Inspect local diagnostics and retry safely.').message,
+                },
+                updatedAt: now,
+            });
+            return true;
+        });
+    }
+    complete(message, fence, now) {
+        return this.database.transaction(() => {
+            const key = this.fenceKey(message.id);
+            const current = parseFence(this.database.getRecord(this.projectId, this.workspaceId, 'mutation', key)?.value);
+            if (current?.state === 'delivered') {
+                this.database.markOutboxDelivered(this.projectId, this.workspaceId, message.id, now);
+                return true;
+            }
+            if (current?.state !== 'leased' ||
+                current.workerId !== this.workerId ||
+                current.fencingToken !== fence.fencingToken ||
+                current.leaseExpiresAt <= now) {
+                return false;
+            }
+            const marked = this.database.markOutboxDelivered(this.projectId, this.workspaceId, message.id, now);
+            if (!marked) {
+                return false;
+            }
+            this.database.putRecord({
+                projectId: this.projectId,
+                workspaceId: this.workspaceId,
+                kind: 'mutation',
+                key,
+                value: { ...current, state: 'delivered' },
+                updatedAt: now,
+            });
+            return true;
+        });
+    }
+    deliveryKey(message) {
+        const identity = JSON.stringify([this.projectId, this.workspaceId, message.id]);
+        return `outbox:v1:${createHash('sha256').update(identity).digest('hex')}`;
+    }
+    fenceKey(id) {
+        return `outbox-fence:${String(id)}`;
+    }
+}
+function currentIso(clock, lowerBound) {
+    const current = clock().getTime();
+    const minimum = lowerBound === undefined ? Number.NEGATIVE_INFINITY : Date.parse(lowerBound);
+    if (!Number.isFinite(current) || (lowerBound !== undefined && !Number.isFinite(minimum))) {
+        throw new BoundaryFailure('Corrupt', 'outbox clock', 'Provide a valid clock and ISO timestamp.');
+    }
+    return new Date(Math.max(current, minimum)).toISOString();
+}
+//# sourceMappingURL=outbox-worker.js.map

package/dist/engine/execution/validate-job-executor.d.ts

@@ -0,0 +1,24 @@
+import { DurableJobRuntime } from './job-runtime.js';
+import { type DurableJobRecord } from '../../storage/runtime-db.js';
+import type { ValidateJobExecutorOptions, ValidateJobRecoveryOptions } from '../../types/durable-validation.js';
+/** Executes accepted validate jobs directly against the validation core, never through MCP. */
+export declare class ValidateJobExecutor {
+    private readonly runtime;
+    private readonly workerId;
+    private readonly options;
+    constructor(runtime: DurableJobRuntime, workerId?: string, options?: ValidateJobExecutorOptions);
+    runOnce(projectId: string, workspaceId?: string): Promise<readonly DurableJobRecord[]>;
+    runUntilIdle(projectId: string, workspaceId?: string): Promise<void>;
+    private execute;
+    private runClaimedValidation;
+    private startHeartbeat;
+    private persistProgress;
+    private issueReceipt;
+    private preparePublicationLease;
+    private persistReceiptArtifacts;
+}
+/** Schedules background execution after the submit response can be flushed. */
+export declare function scheduleValidateJobExecution(projectId: string, workspaceId?: string): void;
+/** Re-enqueues accepted/checkpointed validate work discovered after a process restart. */
+export declare function recoverValidateJobsAtStartup(options?: ValidateJobRecoveryOptions): void;
+//# sourceMappingURL=validate-job-executor.d.ts.map