@canhta/dsh-autopilot 0.1.0-alpha.1

package/lib/admission/delivery-control.js

@@ -0,0 +1,294 @@
+import { createHash } from 'node:crypto';
+import { MAX_AUTOMATIC_EXTERNAL_ATTEMPTS, STATE_KEY } from './constants.js';
+import { sanitizeDeliveryError } from './deliveries.js';
+import { boundedExternalRetry } from './policy.js';
+import { stateSchema } from './state.js';
+export class DeliveryControl {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async claim(deliveryId) {
+        const owner = crypto.randomUUID();
+        let claimed;
+        let superseded;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const located = locate(current.runs, deliveryId);
+            if (located === undefined)
+                throw new Error(`delivery "${deliveryId}" does not exist`);
+            const { run, delivery } = located;
+            if (delivery.kind === 'tracker-projection' && delivery.status === 'retired') {
+                throw new SupersededProjectionError(delivery);
+            }
+            if (delivery.status === 'succeeded' ||
+                delivery.status === 'retired' ||
+                delivery.status === 'exhausted' ||
+                delivery.status === 'permanent-failure') {
+                throw new Error(`delivery "${deliveryId}" is not retryable`);
+            }
+            if (delivery.status === 'in-flight')
+                throw new Error(`delivery "${deliveryId}" already has an owner`);
+            if (delivery.nextRetryAt !== undefined && Date.parse(delivery.nextRetryAt) > Date.now()) {
+                throw new Error(`delivery "${deliveryId}" retry is not due`);
+            }
+            const next = structuredClone(current);
+            const nextRun = next.runs[located.runIndex];
+            const nextDelivery = nextRun?.deliveries[located.deliveryIndex];
+            if (nextRun === undefined || nextDelivery === undefined)
+                throw new Error('delivery disappeared during claim');
+            if (nextDelivery.kind === 'tracker-projection') {
+                if (isSupersededProjection(current.runs, nextDelivery)) {
+                    const retired = retireProjection(nextDelivery);
+                    nextRun.deliveries = nextRun.deliveries.map((candidate, index) => index === located.deliveryIndex ? retired : candidate);
+                    next.revision += 1;
+                    superseded = retired;
+                    return stateSchema.parse(next);
+                }
+                if (hasOlderInFlightProjection(current.runs, nextDelivery)) {
+                    throw new Error(`delivery "${deliveryId}" is waiting for an older issue projection to settle`);
+                }
+                retireOlderProjections(next.runs, nextDelivery);
+            }
+            const claimRun = next.runs[located.runIndex];
+            const claimDelivery = claimRun?.deliveries[located.deliveryIndex];
+            if (claimRun === undefined || claimDelivery === undefined)
+                throw new Error('delivery disappeared before claim');
+            const updated = {
+                ...claimDelivery,
+                revision: claimDelivery.revision + 1,
+                status: 'in-flight',
+                attempts: claimDelivery.attempts + 1,
+                owner,
+                nextRetryAt: undefined,
+                exhaustedFrom: undefined,
+                lastError: undefined,
+            };
+            claimRun.deliveries = claimRun.deliveries.map((candidate, index) => index === located.deliveryIndex ? updated : candidate);
+            next.revision += 1;
+            stateSchema.parse(next);
+            claimed = { runId: run.runId, delivery: updated, owner };
+            return next;
+        });
+        if (superseded !== undefined)
+            throw new SupersededProjectionError(superseded);
+        if (claimed === undefined)
+            throw new Error(`delivery "${deliveryId}" was not claimed`);
+        return structuredClone(claimed);
+    }
+    assertOwner(runId, deliveryId, owner) {
+        const run = this.dependencies.state().runs.find((candidate) => candidate.runId === runId);
+        const delivery = run?.deliveries.find((candidate) => candidate.id === deliveryId);
+        if (delivery?.status !== 'in-flight' || delivery.owner !== owner) {
+            throw new Error(`delivery "${deliveryId}" owner is retired`);
+        }
+    }
+    succeed(runId, deliveryId, owner, receipt) {
+        return this.updateOwned(runId, deliveryId, owner, (delivery) => ({
+            ...delivery,
+            revision: delivery.revision + 1,
+            status: 'succeeded',
+            owner: undefined,
+            receiptId: receipt.receiptId,
+            receivedAt: receipt.receivedAt,
+        }));
+    }
+    fail(runId, deliveryId, owner, error, status, retryAfterMs) {
+        return this.updateOwned(runId, deliveryId, owner, (delivery) => {
+            const exhausted = status !== 'permanent-failure' && delivery.attempts >= MAX_AUTOMATIC_EXTERNAL_ATTEMPTS;
+            return {
+                ...delivery,
+                revision: delivery.revision + 1,
+                status: exhausted ? 'exhausted' : status,
+                owner: undefined,
+                lastError: sanitizeDeliveryError(error),
+                nextRetryAt: !exhausted && status === 'retryable-failure'
+                    ? new Date(Date.now() + boundedExternalRetry(retryAfterMs, delivery.attempts)).toISOString()
+                    : undefined,
+                exhaustedFrom: exhausted ? status : undefined,
+            };
+        });
+    }
+    async retry(deliveryId) {
+        let updated;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const located = locate(current.runs, deliveryId);
+            if (located === undefined)
+                throw new Error(`delivery "${deliveryId}" does not exist`);
+            if (located.delivery.status === 'succeeded' || located.delivery.status === 'retired') {
+                throw new Error(`delivery "${deliveryId}" cannot be retried`);
+            }
+            if (located.delivery.status === 'in-flight')
+                throw new Error(`delivery "${deliveryId}" already has an owner`);
+            const next = structuredClone(current);
+            const nextRun = next.runs[located.runIndex];
+            if (nextRun === undefined)
+                throw new Error('delivery run disappeared during retry');
+            updated = {
+                ...located.delivery,
+                revision: located.delivery.revision + 1,
+                status: 'pending',
+                nextRetryAt: undefined,
+                exhaustedFrom: undefined,
+                lastError: undefined,
+            };
+            nextRun.deliveries = nextRun.deliveries.map((candidate, index) => index === located.deliveryIndex ? updated : candidate);
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (updated === undefined)
+            throw new Error(`delivery "${deliveryId}" retry was not committed`);
+        return structuredClone(updated);
+    }
+    /** Retire one failed mutable projection and atomically persist a revisioned replacement for current lifecycle state. */
+    async repairProjection(deliveryId) {
+        let replacement;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const located = locate(current.runs, deliveryId);
+            if (located?.delivery.kind !== 'tracker-projection') {
+                throw new Error(`delivery "${deliveryId}" is not a tracker projection`);
+            }
+            if (!['permanent-failure', 'retryable-failure', 'exhausted'].includes(located.delivery.status)) {
+                throw new Error(`delivery "${deliveryId}" is not a settled failed projection`);
+            }
+            const target = located.delivery;
+            const issueProjections = current.runs.flatMap((run) => run.deliveries.filter((candidate) => candidate.kind === 'tracker-projection' && sameProjectionTarget(candidate, target)));
+            if (issueProjections.some((candidate) => candidate.status === 'in-flight') ||
+                issueProjections.some((candidate) => candidate.payload.runRevision > target.payload.runRevision)) {
+                throw new Error(`delivery "${deliveryId}" was superseded or still has an in-flight issue projection`);
+            }
+            const next = structuredClone(current);
+            const run = next.runs[located.runIndex];
+            const obsolete = run?.deliveries[located.deliveryIndex];
+            if (run === undefined || obsolete?.kind !== 'tracker-projection') {
+                throw new Error('tracker projection disappeared during repair');
+            }
+            const desiredState = projectionStateFor(run.state);
+            const trackerDeliveryId = `tracker:${createHash('sha256')
+                .update(`${obsolete.payload.deliveryId}\0repair\0${String(current.revision + 1)}`)
+                .digest('hex')
+                .slice(0, 40)}`;
+            replacement = {
+                id: `delivery:${createHash('sha256').update(trackerDeliveryId).digest('hex').slice(0, 40)}`,
+                eventId: obsolete.eventId,
+                revision: 1,
+                status: 'pending',
+                attempts: 0,
+                kind: 'tracker-projection',
+                providerId: obsolete.providerId,
+                payload: {
+                    ...obsolete.payload,
+                    deliveryId: trackerDeliveryId,
+                    runRevision: current.revision + 1,
+                    desiredState,
+                },
+            };
+            run.deliveries = run.deliveries.map((candidate, index) => index === located.deliveryIndex
+                ? {
+                    ...obsolete,
+                    revision: obsolete.revision + 1,
+                    status: 'retired',
+                    nextRetryAt: undefined,
+                    exhaustedFrom: undefined,
+                }
+                : candidate);
+            run.deliveries.push(replacement);
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (replacement === undefined)
+            throw new Error(`delivery "${deliveryId}" repair was not committed`);
+        return structuredClone(replacement);
+    }
+    async updateOwned(runId, deliveryId, owner, mutate) {
+        let updated;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const next = structuredClone(current);
+            const run = next.runs.find((candidate) => candidate.runId === runId);
+            const index = run?.deliveries.findIndex((candidate) => candidate.id === deliveryId) ?? -1;
+            const delivery = run?.deliveries[index];
+            if (run === undefined || delivery?.status !== 'in-flight' || delivery.owner !== owner) {
+                throw new Error(`delivery "${deliveryId}" owner is retired`);
+            }
+            updated = mutate(delivery);
+            run.deliveries = run.deliveries.map((candidate, candidateIndex) => candidateIndex === index ? updated : candidate);
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (updated === undefined)
+            throw new Error(`delivery "${deliveryId}" update was not committed`);
+        return structuredClone(updated);
+    }
+}
+export class SupersededProjectionError extends Error {
+    delivery;
+    constructor(delivery) {
+        super(`delivery "${delivery.id}" was superseded before dispatch`);
+        this.delivery = delivery;
+        this.name = 'SupersededProjectionError';
+    }
+}
+function isSupersededProjection(runs, target) {
+    return runs.some((run) => run.deliveries.some((candidate) => candidate.kind === 'tracker-projection' &&
+        candidate.id !== target.id &&
+        sameProjectionTarget(candidate, target) &&
+        candidate.payload.runRevision > target.payload.runRevision));
+}
+function hasOlderInFlightProjection(runs, target) {
+    return runs.some((run) => run.deliveries.some((candidate) => candidate.kind === 'tracker-projection' &&
+        candidate.id !== target.id &&
+        sameProjectionTarget(candidate, target) &&
+        candidate.payload.runRevision < target.payload.runRevision &&
+        candidate.status === 'in-flight'));
+}
+function retireOlderProjections(runs, target) {
+    for (const [index, run] of runs.entries()) {
+        runs[index] = {
+            ...run,
+            deliveries: run.deliveries.map((candidate) => candidate.kind === 'tracker-projection' &&
+                sameProjectionTarget(candidate, target) &&
+                candidate.payload.runRevision < target.payload.runRevision &&
+                !['succeeded', 'retired'].includes(candidate.status)
+                ? retireProjection(candidate)
+                : candidate),
+        };
+    }
+}
+function retireProjection(projection) {
+    const { exhaustedFrom: _exhaustedFrom, lastError: _lastError, nextRetryAt: _nextRetryAt, owner: _owner, ...retained } = projection;
+    return { ...retained, revision: projection.revision + 1, status: 'retired' };
+}
+function sameProjectionTarget(left, right) {
+    return (left.providerId === right.providerId &&
+        left.payload.bindingId === right.payload.bindingId &&
+        left.payload.issueId === right.payload.issueId);
+}
+function projectionStateFor(state) {
+    switch (state) {
+        case 'queued':
+            return 'queued';
+        case 'implementing':
+        case 'pausing':
+        case 'publishing':
+            return 'implementing';
+        case 'paused':
+            return 'paused';
+        case 'blocked':
+            return 'blocked';
+        case 'failed':
+            return 'failed';
+        case 'completed':
+            return 'completed';
+        case 'cancelled':
+            throw new Error('cancelled runs have no default tracker projection');
+    }
+}
+function locate(runs, deliveryId) {
+    for (const [runIndex, run] of runs.entries()) {
+        const deliveryIndex = run.deliveries.findIndex((candidate) => candidate.id === deliveryId);
+        const delivery = run.deliveries[deliveryIndex];
+        if (delivery !== undefined)
+            return { run, delivery, runIndex, deliveryIndex };
+    }
+    return undefined;
+}
+//# sourceMappingURL=delivery-control.js.map

package/lib/admission/delivery-control.js.map

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

package/lib/admission/execution-control.d.ts

@@ -0,0 +1,29 @@
+import type { AgentExecutionComposition, ExecutionOutcome, GitExecutionSnapshot, ImplementingRun, PausingRun, RunId, RunUsageSettlement, TerminalRun } from './model.js';
+import type { AdmissionDependencies } from './ports.js';
+export declare class ExecutionControl {
+    private readonly dependencies;
+    constructor(dependencies: AdmissionDependencies);
+    /**
+     * Atomically claim the highest-priority queued run and reserve its configured allowance.
+     * Returns undefined when the scheduler is not enabled or the queue is empty. Otherwise, explicit execution paths,
+     * positive caps, and the selected native DSH composition are required. The claim stores immutable
+     * run/Session/worktree/composition identities and its reservation
+     * together; disabled execution, uncertain usage, insufficient capacity, invalid configuration, or durable-write
+     * failure rejects without a partial claim. The method accepts no cancellation signal and does not start external work.
+     */
+    claimNext(agent: AgentExecutionComposition, expectedRunId?: RunId): Promise<ImplementingRun | undefined>;
+    /**
+     * Persist exact Git facts for an implementing or pausing run before Agent creation and again after execution.
+     * The run must exist, remain allocated, and not require recovery. Invalid evidence or durable-write failure
+     * rejects without changing the prior snapshot. The atomic record update accepts no cancellation signal.
+     */
+    recordWorktree(runId: RunId, git: GitExecutionSnapshot): Promise<ImplementingRun | PausingRun>;
+    /**
+     * Atomically transition an implementing run to its structured terminal state and settle its reservation.
+     * Verified outcomes require recorded Git facts. Known usage within both retained limits releases the reservation and
+     * increments settled usage; missing, invalid, or excessive usage produces a failed outcome, retains the obligation,
+     * and stops later authorization. Validation or durable-write failure leaves the prior snapshot unchanged. The method
+     * accepts no cancellation signal.
+     */
+    settle(runId: RunId, outcome: ExecutionOutcome, usage: RunUsageSettlement): Promise<TerminalRun>;
+}

package/lib/admission/execution-control.js

@@ -0,0 +1,177 @@
+import { codeHostProviderId } from '../code-host.js';
+import { validateExecutionSettings } from '../config.js';
+import { MAX_OUTCOME_TEXT_BYTES, STATE_KEY } from './constants.js';
+import { appendLifecycleDeliveries, publicationIntent } from './deliveries.js';
+import { assertStateSize, compareQueuedRuns, executionFor, truncateUtf8, usageUncertaintyReason, validUsageSettlement, } from './policy.js';
+import { executionSchema, outcomeSchema, stateSchema } from './state.js';
+export class ExecutionControl {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    /**
+     * Atomically claim the highest-priority queued run and reserve its configured allowance.
+     * Returns undefined when the scheduler is not enabled or the queue is empty. Otherwise, explicit execution paths,
+     * positive caps, and the selected native DSH composition are required. The claim stores immutable
+     * run/Session/worktree/composition identities and its reservation
+     * together; disabled execution, uncertain usage, insufficient capacity, invalid configuration, or durable-write
+     * failure rejects without a partial claim. The method accepts no cancellation signal and does not start external work.
+     */
+    async claimNext(agent, expectedRunId) {
+        const settings = this.dependencies.settings();
+        let claimed;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            if (current.scheduler.mode !== 'enabled')
+                return current;
+            validateExecutionSettings(settings);
+            if (current.budget.usageUncertain) {
+                throw new Error('deployment token usage is uncertain; reconcile it before dispatch');
+            }
+            const queued = current.runs.filter((run) => run.state === 'queued').sort(compareQueuedRuns)[0];
+            if (queued === undefined)
+                return current;
+            if (expectedRunId !== undefined && queued.runId !== expectedRunId)
+                return current;
+            const codeHost = this.dependencies.codeHost;
+            if (codeHost === undefined)
+                throw new Error('code-host binding registry is unavailable');
+            const codeHostBinding = codeHost.binding(codeHostProviderId(settings.codeHostProvider));
+            if (current.budget.settledTokens + current.budget.reservedTokens + settings.runTokenAllowance >
+                settings.deploymentTokenCap) {
+                throw new Error('deployment token cap cannot cover the configured run allowance');
+            }
+            const next = structuredClone(current);
+            const index = next.runs.findIndex((run) => run.runId === queued.runId);
+            if (index < 0)
+                throw new Error('queued run disappeared during its atomic claim');
+            const claimedWithoutDeliveries = {
+                ...queued,
+                state: 'implementing',
+                execution: executionFor(queued, settings, codeHostBinding, agent),
+                budget: {
+                    capTokens: settings.perRunTokenCap,
+                    allowanceTokens: settings.runTokenAllowance,
+                    reservedTokens: settings.runTokenAllowance,
+                    settledTokens: 0,
+                    usageUncertain: false,
+                },
+            };
+            claimed = {
+                ...claimedWithoutDeliveries,
+                deliveries: appendLifecycleDeliveries(claimedWithoutDeliveries, settings, 'started', current.revision + 1, claimedWithoutDeliveries.execution.startedAt),
+            };
+            next.runs[index] = claimed;
+            next.budget.reservedTokens += settings.runTokenAllowance;
+            next.revision += 1;
+            const parsed = stateSchema.parse(next);
+            assertStateSize(parsed);
+            return parsed;
+        });
+        return claimed === undefined ? undefined : structuredClone(claimed);
+    }
+    /**
+     * Persist exact Git facts for an implementing or pausing run before Agent creation and again after execution.
+     * The run must exist, remain allocated, and not require recovery. Invalid evidence or durable-write failure
+     * rejects without changing the prior snapshot. The atomic record update accepts no cancellation signal.
+     */
+    async recordWorktree(runId, git) {
+        const parsedGit = executionSchema.shape.git.unwrap().parse(git);
+        let recorded;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const next = structuredClone(current);
+            const index = next.runs.findIndex((run) => run.runId === runId);
+            const run = next.runs[index];
+            if (run?.state !== 'implementing' && run?.state !== 'pausing') {
+                throw new Error(`run "${runId}" is not implementing or pausing`);
+            }
+            if (run.execution.recovery !== undefined)
+                throw new Error(`run "${runId}" requires explicit recovery`);
+            const nextRun = {
+                ...run,
+                execution: { ...run.execution, git: parsedGit },
+            };
+            recorded = nextRun;
+            next.runs[index] = nextRun;
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (recorded === undefined)
+            throw new Error(`run "${runId}" worktree facts were not recorded`);
+        return structuredClone(recorded);
+    }
+    /**
+     * Atomically transition an implementing run to its structured terminal state and settle its reservation.
+     * Verified outcomes require recorded Git facts. Known usage within both retained limits releases the reservation and
+     * increments settled usage; missing, invalid, or excessive usage produces a failed outcome, retains the obligation,
+     * and stops later authorization. Validation or durable-write failure leaves the prior snapshot unchanged. The method
+     * accepts no cancellation signal.
+     */
+    async settle(runId, outcome, usage) {
+        const parsedOutcome = outcomeSchema.parse(outcome);
+        let settled;
+        await this.dependencies.table().update(STATE_KEY, (current) => {
+            const next = structuredClone(current);
+            const index = next.runs.findIndex((run) => run.runId === runId);
+            const run = next.runs[index];
+            if (run?.state !== 'implementing')
+                throw new Error(`run "${runId}" is not implementing`);
+            if (run.execution.git === undefined && parsedOutcome.kind === 'verified') {
+                throw new Error(`verified run "${runId}" has no recorded worktree facts`);
+            }
+            const usageKnown = validUsageSettlement(run, usage);
+            const reservedTokens = usageKnown ? 0 : run.budget.reservedTokens;
+            const settledTokens = usageKnown ? run.budget.settledTokens + usage.tokens : run.budget.settledTokens;
+            const terminalOutcome = usageKnown
+                ? parsedOutcome
+                : {
+                    kind: 'failed',
+                    summary: 'Provider token usage could not be settled safely.',
+                    evidence: [
+                        usage.kind === 'uncertain'
+                            ? truncateUtf8(usage.reason, MAX_OUTCOME_TEXT_BYTES) ||
+                                'provider did not supply a usage uncertainty reason'
+                            : 'reported usage exceeded the reserved allowance',
+                    ],
+                };
+            const settledWithoutDeliveries = {
+                ...run,
+                state: terminalOutcome.kind === 'verified' ? 'publishing' : terminalOutcome.kind,
+                execution: structuredClone(run.execution),
+                budget: {
+                    ...run.budget,
+                    reservedTokens,
+                    settledTokens,
+                    usageUncertain: !usageKnown,
+                    ...(usageKnown ? {} : { usageUncertaintyReason: usageUncertaintyReason(run, usage) }),
+                },
+                outcome: terminalOutcome,
+                completedAt: new Date().toISOString(),
+                deliveries: run.deliveries,
+            };
+            const settledWithoutPublication = terminalOutcome.kind === 'verified'
+                ? settledWithoutDeliveries
+                : {
+                    ...settledWithoutDeliveries,
+                    deliveries: appendLifecycleDeliveries(settledWithoutDeliveries, this.dependencies.settings(), terminalOutcome.kind, current.revision + 1, new Date().toISOString()),
+                };
+            const terminalRun = terminalOutcome.kind === 'verified'
+                ? { ...settledWithoutPublication, publication: publicationIntent(settledWithoutPublication) }
+                : settledWithoutPublication;
+            settled = terminalRun;
+            next.runs[index] = terminalRun;
+            if (usageKnown) {
+                next.budget.reservedTokens -= run.budget.reservedTokens;
+                next.budget.settledTokens += usage.tokens;
+            }
+            else {
+                next.budget.usageUncertain = true;
+            }
+            next.revision += 1;
+            return stateSchema.parse(next);
+        });
+        if (settled === undefined)
+            throw new Error(`run "${runId}" was not settled`);
+        return structuredClone(settled);
+    }
+}
+//# sourceMappingURL=execution-control.js.map

package/lib/admission/execution-control.js.map

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

package/lib/admission/index.d.ts

@@ -0,0 +1,4 @@
+export * from './model.js';
+export * from './run-fence.js';
+export * from './service.js';
+export type { OperatorCommandKind, OperatorCommandRecord } from './state.js';

package/lib/admission/index.js

@@ -0,0 +1,4 @@
+export * from './model.js';
+export * from './run-fence.js';
+export * from './service.js';
+//# sourceMappingURL=index.js.map

package/lib/admission/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/admission/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA"}