@dsh-enhanced/assistant-automations 0.1.24 → 0.1.31

package/lib/store.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { isAbsolute, resolve } from 'node:path';
 import { dueOccurrences, nextOccurrence, previousOccurrence, validateSchedule, } from './schedule.js';
 import { AutomationDatabaseError, openAutomationDatabase } from './sqlite.js';
+import { canonicalExternalEventEnvelope, externalEventDigest, parseExternalEventEnvelope } from './external-event.js';
 import { isHostAutomationDefinition, legacyAutomationExecutionDiagnostic } from './types.js';
 export class AutomationStoreError extends Error {
     code;
@@ -552,6 +553,25 @@ function parseEvidence(row) {
     return Object.freeze(value);
 }
 function occurrence(row) {
+    let externalEvent;
+    if ((row.external_event_json === null) !== (row.external_event_digest === null)) {
+        throw new AutomationStoreError('invalid-state', 'external event provenance columns must be paired');
+    }
+    if (row.external_event_json !== null && row.external_event_digest !== null) {
+        try {
+            externalEvent = parseExternalEventEnvelope(JSON.parse(row.external_event_json));
+        }
+        catch {
+            throw new AutomationStoreError('invalid-state', 'external event provenance is invalid');
+        }
+        if (externalEventDigest(externalEvent) !== row.external_event_digest) {
+            throw new AutomationStoreError('invalid-state', 'external event provenance digest does not match');
+        }
+        if (row.trigger_kind !== 'external' || externalEvent.deduplicationKey !== row.trigger_key
+            || externalEvent.target.automationId !== row.automation_id || externalEvent.event.occurredAt !== row.scheduled_at) {
+            throw new AutomationStoreError('invalid-state', 'external event provenance does not bind its occurrence');
+        }
+    }
     return Object.freeze({
         id: row.id,
         automationId: row.automation_id,
@@ -563,6 +583,7 @@ function occurrence(row) {
         dryRun: row.dry_run === 1,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
+        ...(externalEvent === undefined ? {} : { externalEvent, externalEventDigest: row.external_event_digest }),
     });
 }
 function task(row) {
@@ -1826,9 +1847,15 @@ export class AutomationStore {
     }
     ingestExternal(input) {
         const eventId = text(input.externalEventId, 'externalEventId', 1_000);
-        if (!Number.isSafeInteger(input.occurredAt)) {
-            throw new AutomationStoreError('invalid-definition', 'occurredAt must be a safe integer');
+        if (!Number.isSafeInteger(input.occurredAt) || input.occurredAt < 0) {
+            throw new AutomationStoreError('invalid-definition', 'occurredAt must be a non-negative safe integer');
+        }
+        const envelope = input.envelope === undefined ? undefined : parseExternalEventEnvelope(input.envelope);
+        if (envelope !== undefined && (envelope.deduplicationKey !== eventId
+            || envelope.target.automationId !== input.automationId || envelope.event.occurredAt !== input.occurredAt)) {
+            throw new AutomationStoreError('invalid-definition', 'external event envelope does not bind this ingest input');
         }
+        const envelopeDigest = envelope === undefined ? undefined : externalEventDigest(envelope);
         return this.transaction(() => {
             const automation = this.get(input.automationId);
             if (automation === undefined)
@@ -1842,8 +1869,10 @@ export class AutomationStore {
                 scheduledAt: input.occurredAt,
                 status: 'pending',
                 dryRun: false,
+                ...(envelope === undefined ? {} : { externalEvent: envelope, externalEventDigest: envelopeDigest }),
             });
-            if (!inserted.created && inserted.value.scheduledAt !== input.occurredAt) {
+            if (!inserted.created && (inserted.value.scheduledAt !== input.occurredAt
+                || inserted.value.externalEventDigest !== envelopeDigest)) {
                 throw new AutomationStoreError('idempotency-conflict', 'external event id was reused with another timestamp');
             }
             return inserted.value;
@@ -1934,6 +1963,72 @@ export class AutomationStore {
         }
         throw new AutomationStoreError('invalid-state', 'automation run has an invalid execution mode');
     }
+    /**
+     * Durable, pre-prompt binding to an immutable task attempt.  A recorded
+     * binding means the prompt boundary is treated as crossed even if a process
+     * dies immediately afterwards; recovery must never replay its side effects.
+     */
+    bindTaskAcceptance(input) {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u.test(input.contractId)
+            || !/^[a-f0-9]{64}$/u.test(input.contractDigest)
+            || !Number.isSafeInteger(input.dispatchedAt) || input.dispatchedAt < 0
+            || !Number.isSafeInteger(input.owner.principalVersion) || input.owner.principalVersion < 1
+            || !Number.isSafeInteger(input.bindingVersion) || input.bindingVersion < 1
+            || !Number.isSafeInteger(input.bindingGeneration) || input.bindingGeneration < 1) {
+            throw new AutomationStoreError('invalid-definition', 'acceptance binding is invalid');
+        }
+        const required = [input.scope.workspace, input.scope.preset, input.owner.principalRecordId, input.bindingId];
+        if (required.some(value => typeof value !== 'string' || value.trim() === '' || Buffer.byteLength(value, 'utf8') > 4_096)) {
+            throw new AutomationStoreError('invalid-definition', 'acceptance binding text is invalid');
+        }
+        this.transaction(() => {
+            const taskRow = this.database.prepare('SELECT * FROM automation_tasks WHERE id = ?').get(input.taskId);
+            if (taskRow === undefined || !['claimed', 'running'].includes(taskRow.status) || taskRow.attempt_count < 1) {
+                throw new AutomationStoreError('invalid-state', 'acceptance task is not an active attempt');
+            }
+            const snapshot = this.getTaskExecutionSnapshot(input.taskId);
+            const occurrenceRow = this.database.prepare('SELECT * FROM automation_occurrences WHERE id = ?').get(taskRow.occurrence_id);
+            if (snapshot === undefined || isHostAutomationDefinition(snapshot.definition) || occurrenceRow?.dry_run !== 0
+                || snapshot.definition.workspace !== input.scope.workspace || snapshot.definition.agentPreset !== input.scope.preset) {
+                throw new AutomationStoreError('invalid-state', 'acceptance does not match immutable production task');
+            }
+            const existing = this.database.prepare('SELECT * FROM automation_task_acceptance WHERE task_id = ?').get(input.taskId);
+            if (existing !== undefined) {
+                throw new AutomationStoreError('invalid-state', existing.submitted === 1
+                    ? 'accepted task prompt may not be submitted again'
+                    : 'acceptance binding already exists');
+            }
+            this.database.prepare(`INSERT INTO automation_task_acceptance(
+        task_id, contract_id, contract_digest, workspace, preset, principal_record_id,
+        principal_version, binding_id, binding_version, binding_generation, dispatched_at, submitted
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1)`).run(input.taskId, input.contractId, input.contractDigest, input.scope.workspace, input.scope.preset, input.owner.principalRecordId, input.owner.principalVersion, input.bindingId, input.bindingVersion, input.bindingGeneration, input.dispatchedAt);
+        });
+    }
+    inspectAcceptedExecution(contract) {
+        const row = this.database.prepare(`SELECT acceptance.*, run.* FROM automation_task_acceptance acceptance
+      LEFT JOIN automation_runs run ON run.task_id = acceptance.task_id
+      WHERE acceptance.contract_id = ?`).get(contract.id);
+        if (row === undefined || row.contract_digest !== contract.digest || row.workspace !== contract.scope.workspace
+            || row.preset !== contract.scope.preset || row.principal_record_id !== contract.owner.principalRecordId
+            || row.principal_version !== contract.owner.principalVersion || contract.task.kind !== 'automation-run'
+            || contract.task.ref !== `run-${row.task_id}`)
+            return null;
+        if (row.id === undefined || row.status === undefined || row.created_at === undefined || row.diagnostic_json === undefined)
+            return null;
+        const snapshot = this.getRunExecutionSnapshot(row.id);
+        if (snapshot === undefined || isHostAutomationDefinition(snapshot.definition)
+            || snapshot.definition.workspace !== row.workspace || snapshot.definition.agentPreset !== row.preset
+            || this.getRunExecutionMode(row.id) !== 'production')
+            return null;
+        const status = row.status === 'timed_out' ? 'timed-out' : row.status;
+        const quiescent = row.quiescent === 1;
+        return Object.freeze({ contractId: row.contract_id, contractDigest: row.contract_digest,
+            dispatchedAt: row.dispatched_at, status, quiescent, completedAt: row.created_at, executionRef: row.id });
+    }
+    markAcceptedTaskQuiescent(taskId, quiescent) {
+        this.database.prepare(`UPDATE automation_task_acceptance SET quiescent = ? WHERE task_id = ?`)
+            .run(quiescent ? 1 : 0, taskId);
+    }
     /**
      * Re-prove the exact production tuple immediately before an effect sink.
      * Legacy rows, mutable current definitions, and a mode flag alone are never
@@ -2160,6 +2255,7 @@ export class AutomationStore {
             const candidates = this.database.prepare(`
         SELECT task.* FROM automation_tasks task
         JOIN automation_definitions definition ON definition.id = task.automation_id
+        JOIN automation_occurrences occurrence ON occurrence.id = task.occurrence_id
         WHERE task.status = 'scheduled' AND (
           definition.status = 'active'
           OR (
@@ -2168,7 +2264,7 @@ export class AutomationStore {
             AND ${pausedGrowthTaskAdmission('task', 'definition')}
           )
         )
-        ORDER BY task.created_at, task.id LIMIT 100
+        ORDER BY occurrence.scheduled_at ASC, occurrence.trigger_key ASC, task.id ASC LIMIT 100
       `).all(growthAutomationOwner);
             for (const candidate of candidates) {
                 const result = this.claimTaskInTransaction(candidate, input, input.hostAvailability);
@@ -2178,6 +2274,50 @@ export class AutomationStore {
             return undefined;
         });
     }
+    /**
+     * Make cancel-previous visible even when the coordinator has no free local
+     * runner slot.  The cancellation request is fenced by the duty lease and is
+     * committed with the still-scheduled successor as its durable cause; a
+     * later tick claims that successor only after the prior lease is released.
+     */
+    requestCancellationForSupersededTasks(input) {
+        return this.transaction(() => {
+            this.requireDuty(input.ownerId, input.fencingToken, input.now);
+            const successors = this.database.prepare(`
+        SELECT task.*
+        FROM automation_tasks task
+        JOIN automation_definitions definition ON definition.id = task.automation_id
+        WHERE task.status = 'scheduled'
+          AND task.attempt_count = 0
+          AND (
+            definition.status = 'active'
+            OR (
+              definition.status = 'paused'
+              AND definition.system_owner = ?
+              AND ${pausedGrowthTaskAdmission('task', 'definition')}
+            )
+          )
+          AND json_extract(definition.definition_json, '$.overlap') = 'cancel-previous'
+      `).all(growthAutomationOwner);
+            return [...new Set(successors.flatMap(task => this.requestCancellationForNewerOccurrenceInTransaction(task, input.now)))];
+        });
+    }
+    /** Bound queue-one backlog while its active predecessor still owns a slot. */
+    coalesceQueuedTasks(input) {
+        return this.transaction(() => {
+            this.requireDuty(input.ownerId, input.fencingToken, input.now);
+            const automations = this.database.prepare(`
+        SELECT DISTINCT task.automation_id, occurrence.dry_run, task.occurrence_id
+        FROM automation_tasks task
+        JOIN automation_definitions definition ON definition.id = task.automation_id
+        JOIN automation_occurrences occurrence ON occurrence.id = task.occurrence_id
+        WHERE task.status IN ('claimed', 'running')
+          AND definition.status = 'active'
+          AND json_extract(definition.definition_json, '$.overlap') = 'queue-one'
+      `).all();
+            return automations.flatMap(row => this.coalesceQueueOneInTransaction(row.automation_id, row.occurrence_id, input.now));
+        });
+    }
     claimTask(input) {
         this.validateLease(input.now, input.leaseMs);
         return this.transaction(() => {
@@ -2854,9 +2994,14 @@ export class AutomationStore {
                     throw new AutomationStoreError('invalid-state', 'expired task has no matching execution attempt');
                 }
                 const snapshot = automationSnapshot(attempt, row.automation_id);
+                const accepted = this.database.prepare('SELECT submitted FROM automation_task_acceptance WHERE task_id = ?')
+                    .get(row.id);
                 const retry = row.status === 'running'
                     && snapshot?.definition.retrySafety === 'idempotent'
-                    && row.attempt_count <= snapshot.definition.maxRetries;
+                    && row.attempt_count <= snapshot.definition.maxRetries
+                    // Accepted task prompts are side-effect capable.  A lease/restart
+                    // can recover their terminal unknown receipt but cannot replay them.
+                    && accepted?.submitted !== 1;
                 const target = row.status === 'claimed' || retry ? 'scheduled' : 'unknown';
                 const attemptStatus = row.status === 'claimed' ? 'lost' : 'unknown';
                 this.database.prepare(`
@@ -3019,10 +3164,16 @@ export class AutomationStore {
         const active = this.database.prepare(`
       SELECT * FROM automation_tasks
       WHERE automation_id = ? AND id != ? AND status IN ('claimed', 'running')
+        AND (SELECT dry_run FROM automation_occurrences WHERE id = automation_tasks.occurrence_id)
+          = (SELECT dry_run FROM automation_occurrences WHERE id = ?)
       ORDER BY created_at, id
-    `).all(row.automation_id, row.id);
-        if (active.length > 0 && automation.definition.overlap === 'queue-one')
+    `).all(row.automation_id, row.id, row.occurrence_id);
+        if (active.length > 0 && automation.definition.overlap === 'queue-one') {
+            const superseded = this.coalesceQueueOneInTransaction(row.automation_id, row.occurrence_id, input.now);
+            if (superseded.includes(row.id))
+                return this.getTask(row.id);
             return undefined;
+        }
         if (active.length > 0 && automation.definition.overlap === 'skip') {
             this.database.prepare(`
         UPDATE automation_tasks SET status = 'cancelled', cancel_requested = 1, updated_at = ? WHERE id = ?
@@ -3033,10 +3184,12 @@ export class AutomationStore {
             return this.getTask(row.id);
         }
         if (active.length > 0 && automation.definition.overlap === 'cancel-previous') {
-            this.database.prepare(`
-        UPDATE automation_tasks SET cancel_requested = 1, updated_at = ?
-        WHERE automation_id = ? AND id != ? AND status IN ('claimed', 'running')
-      `).run(input.now, row.automation_id, row.id);
+            this.requestCancellationForNewerOccurrenceInTransaction(row, input.now);
+            // A cancellation is cooperative and fenced. Do not claim the
+            // successor until every active predecessor has actually released its
+            // lease/slot; otherwise maxConcurrency > 1 and direct claims can run
+            // both sides of a purported replacement concurrently.
+            return undefined;
         }
         const attemptNumber = row.attempt_count + 1;
         const attemptId = `attempt-${row.id}-${attemptNumber}`;
@@ -3056,6 +3209,72 @@ export class AutomationStore {
     `).run(attemptId, row.id, attemptNumber, input.ownerId, input.fencingToken, snapshot.hash, snapshot.json, input.now, input.now);
         return this.getTask(row.id);
     }
+    /**
+     * Request cancellation only when a fresh successor is strictly later than
+     * an active occurrence. Equal timestamps have no causal order, and retry
+     * rows retain their existing occurrence rather than superseding it.
+     */
+    requestCancellationForNewerOccurrenceInTransaction(successor, now) {
+        if (successor.attempt_count !== 0)
+            return [];
+        const successorOccurrence = this.database.prepare(`
+      SELECT scheduled_at, dry_run FROM automation_occurrences WHERE id = ?
+    `).get(successor.occurrence_id);
+        if (successorOccurrence === undefined) {
+            throw new AutomationStoreError('invalid-state', 'scheduled successor has no occurrence');
+        }
+        const active = this.database.prepare(`
+      SELECT task.id
+      FROM automation_tasks task
+      JOIN automation_occurrences occurrence ON occurrence.id = task.occurrence_id
+      WHERE task.automation_id = ?
+        AND task.id != ?
+        AND task.status IN ('claimed', 'running')
+        AND occurrence.dry_run = ?
+        AND occurrence.scheduled_at < ?
+      ORDER BY occurrence.scheduled_at ASC, task.id ASC
+    `).all(successor.automation_id, successor.id, successorOccurrence.dry_run, successorOccurrence.scheduled_at);
+        for (const task of active) {
+            this.database.prepare(`
+        UPDATE automation_tasks SET cancel_requested = 1, updated_at = ?
+        WHERE id = ? AND status IN ('claimed', 'running')
+      `).run(now, task.id);
+        }
+        return active.map(task => task.id);
+    }
+    /**
+     * Keep the latest not-yet-attempted occurrence only. A scheduled retry
+     * already has attempt history and must remain auditable/recoverable, so
+     * occurrence coalescing never changes it.
+     */
+    coalesceQueueOneInTransaction(automationId, occurrenceId, now) {
+        const occurrence = this.database.prepare(`SELECT dry_run FROM automation_occurrences WHERE id = ?`)
+            .get(occurrenceId);
+        if (occurrence === undefined)
+            throw new AutomationStoreError('invalid-state', 'queue-one task has no occurrence');
+        const pending = this.database.prepare(`
+      SELECT task.*
+      FROM automation_tasks task
+      JOIN automation_occurrences occurrence ON occurrence.id = task.occurrence_id
+      WHERE task.automation_id = ? AND task.status = 'scheduled' AND task.attempt_count = 0
+        AND occurrence.dry_run = ?
+      ORDER BY occurrence.scheduled_at DESC, occurrence.trigger_key DESC, task.id DESC
+    `).all(automationId, occurrence.dry_run);
+        const superseded = pending.slice(1);
+        for (const task of superseded) {
+            this.database.prepare(`
+        UPDATE automation_tasks
+        SET status = 'cancelled', cancel_requested = 1, updated_at = ?
+        WHERE id = ? AND status = 'scheduled' AND attempt_count = 0
+      `).run(now, task.id);
+            this.database.prepare(`
+        UPDATE automation_occurrences
+        SET status = 'skipped', reason = 'overlap-queue-one-coalesced', updated_at = ?
+        WHERE id = ? AND status = 'pending'
+      `).run(now, task.occurrence_id);
+        }
+        return superseded.map(task => task.id);
+    }
     exactHostAvailability(decisions, automationId, definitionHash, stage) {
         const exact = decisions?.filter(decision => decision.automationId === automationId
             && decision.definitionHash === definitionHash && decision.stage === stage) ?? [];
@@ -3184,9 +3403,9 @@ export class AutomationStore {
         const now = this.now();
         this.database.prepare(`
       INSERT INTO automation_occurrences(
-        id, automation_id, trigger_kind, trigger_key, scheduled_at, status, reason, dry_run, created_at, updated_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(id, input.automationId, input.triggerKind, input.triggerKey, input.scheduledAt, input.status, input.reason ?? null, input.dryRun ? 1 : 0, now, now);
+        id, automation_id, trigger_kind, trigger_key, scheduled_at, status, reason, dry_run, external_event_json, external_event_digest, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.automationId, input.triggerKind, input.triggerKey, input.scheduledAt, input.status, input.reason ?? null, input.dryRun ? 1 : 0, input.externalEvent === undefined ? null : canonicalExternalEventEnvelope(input.externalEvent), input.externalEventDigest ?? null, now, now);
         if (input.status === 'pending') {
             this.database.prepare(`
         INSERT INTO automation_tasks(