@cat-factory/orchestration 0.123.4 → 0.123.6

package/dist/modules/execution/FollowUpGateController.js

@@ -0,0 +1,317 @@
+import { ConflictError, NotFoundError } from '@cat-factory/kernel';
+import { followUpsToSendBack, hasPendingFollowUps, renderFollowUpRework, shouldLoopCoder, } from './followUp.logic.js';
+/**
+ * The Follow-up companion gate (the future-looking Coder), extracted out of
+ * {@link RunDispatcher}: the Coder streams forward-looking items (loose ends / side-tasks /
+ * questions) which accrue on its `step.followUps` live (see the dispatcher's poll fold). At
+ * the Coder's completion the run parks while any item is undecided, then loops the Coder for
+ * the items the human queued / answered (within the loop budget) before the following steps
+ * may start. Also owns the human-action API (file / queue / answer / dismiss) the execution
+ * controller reaches through the dispatcher's thin pass-throughs. Pure code movement from the
+ * dispatcher; no behaviour changes.
+ */
+export class FollowUpGateController {
+    executionRepository;
+    blockRepository;
+    contextBuilder;
+    stepGraph;
+    runStateMachine;
+    workRunner;
+    idGenerator;
+    clock;
+    notificationService;
+    ticketTrackerProvider;
+    constructor(deps) {
+        this.executionRepository = deps.executionRepository;
+        this.blockRepository = deps.blockRepository;
+        this.contextBuilder = deps.contextBuilder;
+        this.stepGraph = deps.stepGraph;
+        this.runStateMachine = deps.runStateMachine;
+        this.workRunner = deps.workRunner;
+        this.idGenerator = deps.idGenerator;
+        this.clock = deps.clock;
+        this.notificationService = deps.notificationService;
+        this.ticketTrackerProvider = deps.ticketTrackerProvider;
+    }
+    /**
+     * Append the items the harness streamed since the last poll onto the Coder step's
+     * follow-up state as fresh `pending` items. A no-op when the companion is off or nothing
+     * was streamed. Returns whether anything was added (so the poller persists + emits).
+     */
+    appendStreamedFollowUps(step, streamed) {
+        if (!step.followUps?.enabled || !streamed || streamed.length === 0)
+            return false;
+        const now = this.clock.now();
+        for (const s of streamed) {
+            const title = (s.title ?? '').trim();
+            if (!title)
+                continue;
+            step.followUps.items.push({
+                id: this.idGenerator.next('fu'),
+                kind: s.kind === 'question' ? 'question' : 'follow_up',
+                title,
+                detail: s.detail ?? '',
+                ...(s.suggestedAction ? { suggestedAction: s.suggestedAction } : {}),
+                status: 'pending',
+                createdAt: now,
+                updatedAt: now,
+            });
+        }
+        return true;
+    }
+    /**
+     * The Follow-up companion gate, evaluated when the Coder step completes: park the run on
+     * a durable decision while any item is undecided; else loop the Coder for the queued /
+     * answered items (within the budget); else fall through (return undefined) so the normal
+     * advance/finish logic runs. Returns an {@link AdvanceResult} only when it parks or loops.
+     */
+    async evaluateFollowUpGate(workspaceId, instance, step) {
+        const state = step.followUps;
+        if (!state?.enabled)
+            return undefined;
+        if (hasPendingFollowUps(state)) {
+            await this.raiseFollowUpPending(workspaceId, instance, state);
+            return this.runStateMachine.parkStepOnDecision(workspaceId, instance, step);
+        }
+        if (shouldLoopCoder(state)) {
+            this.loopCoderForFollowUps(instance, step);
+            await this.runStateMachine.updateBlockProgress(workspaceId, instance, 'in_progress');
+            await this.runStateMachine.casPersist(workspaceId, instance);
+            await this.runStateMachine.emitInstance(workspaceId, instance);
+            return { kind: 'continue' };
+        }
+        return undefined;
+    }
+    /**
+     * Reset the Coder step and fold the human's queued follow-ups / answered questions into
+     * its rework so the next pass extends the prior work. Marks those items `sentToCoder` so
+     * a later completion doesn't re-loop them, and counts the loop against the budget. Shared
+     * by the at-completion path ({@link evaluateFollowUpGate}) and the parked-resume path.
+     */
+    loopCoderForFollowUps(instance, step) {
+        const state = step.followUps;
+        const sending = followUpsToSendBack(state);
+        const feedback = renderFollowUpRework(sending);
+        for (const item of sending) {
+            item.sentToCoder = true;
+            item.updatedAt = this.clock.now();
+        }
+        state.loops = (state.loops ?? 0) + 1;
+        // Reset the step for a fresh dispatch; `step.followUps` is intentionally preserved
+        // (resetStepForRerun doesn't touch it) so the surfaced items survive the loop.
+        this.stepGraph.resetStepForRerun(step);
+        step.rework = { previousProposal: '', feedback };
+        this.stepGraph.startStep(step);
+        if (instance.status === 'blocked')
+            instance.status = 'running';
+    }
+    /** Raise the "follow-ups need decisions" inbox card when the Coder parks on undecided items. */
+    async raiseFollowUpPending(workspaceId, instance, state) {
+        if (!this.notificationService)
+            return;
+        const block = await this.blockRepository.get(workspaceId, instance.blockId);
+        if (!block)
+            return;
+        const pending = state.items.filter((i) => i.status === 'pending').length;
+        await this.notificationService.raise(workspaceId, {
+            type: 'followup_pending',
+            blockId: block.id,
+            executionId: instance.id,
+            title: `"${block.title}" surfaced ${pending} follow-up${pending === 1 ? '' : 's'} to decide`,
+            body: 'The Coder flagged forward-looking follow-ups / questions. Open the task to file ' +
+                'each as an issue, send it back to the Coder, answer it, or dismiss it — the ' +
+                'pipeline continues once every item is decided.',
+            payload: { pipelineName: instance.pipelineName, findingCount: pending },
+        });
+    }
+    /**
+     * The run's "active" follow-up companion step for a read with no item context (the GET /
+     * the inbox-card open). A pipeline may carry MORE THAN ONE follow-up-enabled Coder step,
+     * so this must not blindly pick the first: prefer the step the run is currently on (a Coder
+     * parked on its follow-up gate), else the latest enabled step that has surfaced items, else
+     * the first enabled one.
+     */
+    activeFollowUpStep(instance) {
+        const current = instance.steps[instance.currentStep];
+        if (current?.followUps?.enabled)
+            return { step: current, index: instance.currentStep };
+        for (let i = instance.steps.length - 1; i >= 0; i--) {
+            const s = instance.steps[i];
+            if (s.followUps?.enabled && s.followUps.items.length > 0)
+                return { step: s, index: i };
+        }
+        const index = instance.steps.findIndex((s) => s.followUps?.enabled);
+        return index >= 0 ? { step: instance.steps[index], index } : undefined;
+    }
+    /** Read a run's live follow-up companion state (the active Coder step's items), or null. */
+    async getFollowUps(workspaceId, executionId) {
+        const instance = await this.executionRepository.get(workspaceId, executionId);
+        if (!instance)
+            throw new NotFoundError('Execution', executionId);
+        return this.activeFollowUpStep(instance)?.step.followUps ?? null;
+    }
+    /**
+     * Locate the run + the Coder step that OWNS the addressed item + the item, throwing 404
+     * when absent. Routes by item id (not "the first enabled step") so a pipeline carrying more
+     * than one follow-up-enabled Coder step decides each item on the step that surfaced it —
+     * otherwise a later Coder's items 404 and its gate can never be cleared.
+     */
+    async loadFollowUpItem(workspaceId, executionId, itemId) {
+        const instance = await this.executionRepository.get(workspaceId, executionId);
+        if (!instance)
+            throw new NotFoundError('Execution', executionId);
+        const index = instance.steps.findIndex((s) => s.followUps?.enabled && s.followUps.items.some((i) => i.id === itemId));
+        if (index < 0)
+            throw new NotFoundError('Follow-up item', itemId);
+        const step = instance.steps[index];
+        const item = step.followUps.items.find((i) => i.id === itemId);
+        return { instance, step, index, item };
+    }
+    /** File a `follow_up` item as a tracker issue (GitHub / Jira), recording the ticket ref. */
+    async fileFollowUp(workspaceId, executionId, itemId) {
+        // Snapshot read for validation + frame resolution before the non-idempotent ticket
+        // creation; the item's ticket refs are then recorded under CAS in applyFollowUpDecision.
+        const { instance, item } = await this.loadFollowUpItem(workspaceId, executionId, itemId);
+        if (item.kind !== 'follow_up') {
+            throw new ConflictError('Only follow-up items can be filed as issues');
+        }
+        if (!this.ticketTrackerProvider) {
+            throw new ConflictError('No issue tracker is configured for this workspace');
+        }
+        const frameId = (await this.contextBuilder.resolveServiceFrameId(workspaceId, instance.blockId)) ??
+            instance.blockId;
+        const body = [
+            item.detail,
+            item.suggestedAction ? `\n\nSuggested approach: ${item.suggestedAction}` : '',
+        ]
+            .join('')
+            .trim();
+        const ticket = await this.ticketTrackerProvider.createTicket({
+            workspaceId,
+            frameId,
+            title: item.title,
+            body: body || item.title,
+        });
+        if (!ticket) {
+            throw new ConflictError('No issue tracker is configured for this workspace');
+        }
+        return this.applyFollowUpDecision(workspaceId, executionId, itemId, (target) => {
+            // Re-validated on the fresh snapshot inside the CAS (the ticket was already created above).
+            if (target.kind !== 'follow_up') {
+                throw new ConflictError('Only follow-up items can be filed as issues');
+            }
+            target.status = 'filed';
+            target.ticketExternalId = ticket.externalId;
+            target.ticketUrl = ticket.url;
+            target.updatedAt = this.clock.now();
+        });
+    }
+    /** Queue a `follow_up` item to send back to the Coder on its next pass. */
+    async queueFollowUp(workspaceId, executionId, itemId) {
+        return this.applyFollowUpDecision(workspaceId, executionId, itemId, (item) => {
+            if (item.kind !== 'follow_up') {
+                throw new ConflictError('Only follow-up items can be sent back to the Coder');
+            }
+            item.status = 'queued';
+            item.sentToCoder = false;
+            item.updatedAt = this.clock.now();
+        });
+    }
+    /** Answer a `question` item; the answer is folded into the Coder's next pass. */
+    async answerFollowUp(workspaceId, executionId, itemId, answer) {
+        return this.applyFollowUpDecision(workspaceId, executionId, itemId, (item) => {
+            if (item.kind !== 'question') {
+                throw new ConflictError('Only question items can be answered');
+            }
+            item.status = 'answered';
+            item.answer = answer;
+            item.sentToCoder = false;
+            item.updatedAt = this.clock.now();
+        });
+    }
+    /** Dismiss a follow-up / question item without acting on it. */
+    async dismissFollowUp(workspaceId, executionId, itemId) {
+        return this.applyFollowUpDecision(workspaceId, executionId, itemId, (item) => {
+            item.status = 'dismissed';
+            item.updatedAt = this.clock.now();
+        });
+    }
+    /**
+     * Apply a human follow-up item decision and, when the run is PARKED on this step's follow-up
+     * gate with every item now decided, drive it forward — loop the Coder for the queued/answered
+     * items, hand off to a co-located approval gate, or advance past the gate — all under
+     * OPTIMISTIC CONCURRENCY. A follow-up decision can race the driver's running-poll fold (which
+     * appends newly-streamed items) or another decision on a sibling item, so it RE-READS +
+     * RE-APPLIES on a lost CAS race instead of clobbering — the human-action dual of the driver's
+     * abort-and-redrive (race-audit 2.2). The item mutation + the in-memory gate transition run
+     * INSIDE the CAS callback (idempotent, re-runnable on reload); the non-idempotent side effects
+     * (notifications, `signalDecision`, emit) run once AFTER, on the winning snapshot. `decide`
+     * validates + mutates the item, throwing a `ConflictError`/`NotFoundError` that propagates
+     * immediately (a domain error is not retried).
+     */
+    async applyFollowUpDecision(workspaceId, executionId, itemId, decide) {
+        // Captured inside the (re-runnable) callback for the last winning attempt; the
+        // non-idempotent side effects below act on them.
+        let outcome = 'record';
+        let index = -1;
+        let loopDecisionId;
+        const persisted = await this.runStateMachine.mutateInstance(workspaceId, executionId, (fresh) => {
+            outcome = 'record';
+            loopDecisionId = undefined;
+            index = fresh.steps.findIndex((s) => s.followUps?.enabled && s.followUps.items.some((i) => i.id === itemId));
+            if (index < 0)
+                throw new NotFoundError('Follow-up item', itemId);
+            const step = fresh.steps[index];
+            decide(step.followUps.items.find((i) => i.id === itemId));
+            const parkedHere = fresh.status === 'blocked' &&
+                step.approval?.status === 'pending' &&
+                fresh.currentStep === index;
+            // Still collecting decisions (or the run isn't parked on this gate): only record it.
+            if (!parkedHere || hasPendingFollowUps(step.followUps))
+                return;
+            // Every item decided and the run is parked here: loop the Coder for the send-back items,
+            // hand off to a co-located approval gate, or advance past the gate.
+            if (shouldLoopCoder(step.followUps)) {
+                loopDecisionId = step.approval.id;
+                this.loopCoderForFollowUps(fresh, step);
+                outcome = 'loop';
+                return;
+            }
+            const isFinalStep = index === fresh.steps.length - 1;
+            if (step.requiresApproval && !isFinalStep && step.approval?.status === 'pending') {
+                // The follow-up park reused `step.approval`; advancing here would silently SKIP the
+                // approval. Refresh the proposal and hand off to the standard approval gate (the
+                // follow-up card is cleared + the "waiting for input" card re-raised below), preserving
+                // the follow-up-before-approval ordering recordStepResult established across the park.
+                step.approval = { ...step.approval, proposal: step.output ?? '' };
+                outcome = 'handoff';
+                return;
+            }
+            this.runStateMachine.advanceRunPastGate(fresh, index);
+            outcome = 'advance';
+        });
+        // Non-idempotent side effects on the winning snapshot (the CAS write is the source of truth,
+        // so nothing re-persists here). The settled paths first clear the follow-up waiting card.
+        if (outcome === 'record') {
+            await this.runStateMachine.emitInstance(workspaceId, persisted);
+        }
+        else {
+            await this.runStateMachine.clearWaitingNotification(workspaceId, persisted);
+            if (outcome === 'loop') {
+                await this.runStateMachine.updateBlockProgress(workspaceId, persisted, 'in_progress');
+                await this.workRunner.signalDecision(workspaceId, persisted.id, loopDecisionId, 'approved');
+                await this.runStateMachine.emitInstance(workspaceId, persisted);
+            }
+            else if (outcome === 'handoff') {
+                await this.runStateMachine.ensureWaitingNotification(workspaceId, persisted);
+                await this.runStateMachine.emitInstance(workspaceId, persisted);
+            }
+            else {
+                // advance: block writes + `signalDecision('approved')` + emit — the approveStep template.
+                await this.runStateMachine.settleAdvancedGate(workspaceId, persisted, index);
+            }
+        }
+        return persisted.steps[index].followUps;
+    }
+}
+//# sourceMappingURL=FollowUpGateController.js.map

package/dist/modules/execution/FollowUpGateController.js.map

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

package/dist/modules/execution/RunAdmission.d.ts

@@ -0,0 +1,204 @@
+import type { Block, BlockRepository, ExecutionRepository, ModelRef, PipelineStep, ProviderCapabilities, ResolveBinaryArtifactStore, WorkspaceRepository } from '@cat-factory/kernel';
+import type { AgentKindRegistry } from '@cat-factory/agents';
+import type { EnvironmentProvisioningService } from '@cat-factory/integrations';
+import type { SpendService } from '@cat-factory/spend';
+import { type PipelineShape } from '../pipelines/pipelineShape.js';
+import type { AgentContextBuilder } from './AgentContextBuilder.js';
+import type { WorkspaceSettingsService } from '../settings/WorkspaceSettingsService.js';
+/** Collaborators + optional facade seams the admission preflights read. */
+export interface RunAdmissionDeps {
+    workspaceRepository: WorkspaceRepository;
+    blockRepository: BlockRepository;
+    executionRepository: ExecutionRepository;
+    contextBuilder: AgentContextBuilder;
+    agentKindRegistry: AgentKindRegistry;
+    spend: SpendService;
+    /** Optional — see the matching {@link ExecutionServiceDependencies} docs; each guard is a
+     *  pass-through when its seam is unwired (tests / unconfigured facades). */
+    environmentProvisioning?: EnvironmentProvisioningService;
+    workspaceSettingsService?: WorkspaceSettingsService;
+    resolveBinaryArtifactStore?: ResolveBinaryArtifactStore;
+    resolveProviderCapabilities?: (workspaceId: string, initiatedBy?: string | null) => Promise<ProviderCapabilities>;
+    inlineHarnessRef?: (ref: ModelRef) => boolean;
+    resolveWorkspaceModelDefault?: (workspaceId: string, agentKind: string, modelPresetId?: string) => Promise<string | undefined>;
+    assertAgentBackendConfigured?: (workspaceId: string) => Promise<void>;
+}
+/**
+ * The run ADMISSION preflights — every config/resource precondition a run must satisfy
+ * before it is allowed to START, RETRY or RESTART, extracted out of `ExecutionService`
+ * so the engine's public lifecycle methods stay readable while the guard family grows.
+ * All checks are read-only and run BEFORE any side effects, each throwing an actionable
+ * {@link ConflictError}. The shared entry point is {@link assertRunnable}; the start-only
+ * concurrency/dependency gates ({@link assertWithinTaskLimit}, {@link assertDependenciesMet})
+ * are separate because a retry/restart deliberately skips them.
+ */
+export declare class RunAdmission {
+    private readonly workspaceRepository;
+    private readonly blockRepository;
+    private readonly executionRepository;
+    private readonly contextBuilder;
+    private readonly agentKindRegistry;
+    private readonly spend;
+    private readonly environmentProvisioning?;
+    private readonly workspaceSettingsService?;
+    private readonly resolveBinaryArtifactStore?;
+    private readonly resolveProviderCapabilities?;
+    private readonly inlineHarnessRef?;
+    private readonly resolveWorkspaceModelDefault?;
+    private readonly assertAgentBackendConfigured?;
+    constructor(deps: RunAdmissionDeps);
+    /**
+     * The config/resource preconditions a run must satisfy to START, RETRY **or** RESTART:
+     * everything that depends on the workspace environment + the steps being run, and NOT on
+     * whether this is a fresh run or a replacement. All three entry points call this so they
+     * can't drift — a guard added to one but silently missing from the other is exactly how a
+     * subscription-only preset slipped past retry and failed mid-run against the routing default.
+     * All checks are read-only and run BEFORE any side effects, each throwing an actionable
+     * {@link ConflictError}.
+     *
+     * The `shape` is the effective chain that will run, NOT the current pipeline definition: a
+     * fresh start passes the pipeline, while a retry/restart passes the STORED steps (via
+     * {@link runnableShapeOf}) so the guard validates exactly what re-executes — a pipeline
+     * edited out of band since the run started can't falsely refuse (or silently skip a check
+     * for) a step that isn't actually being re-driven.
+     *
+     * The concurrency (task-limit) and dependency gates are deliberately NOT here — they are
+     * start-only (a retry replaces the failed run rather than adding a new concurrent one, and a
+     * re-drive of an already-started task isn't re-gated on its dependencies).
+     */
+    assertRunnable(workspaceId: string, block: Block, shape: PipelineShape, initiatedBy: string | null | undefined): Promise<void>;
+    /**
+     * The {@link PipelineShape} a retry/restart re-drives: the stored run's steps ARE the enabled,
+     * ordered chain that will run again, so {@link assertRunnable} validates exactly what
+     * re-executes rather than the current pipeline definition (which may have been edited out of
+     * band since the run started). Disabled steps were already filtered out at start, so every
+     * stored step is enabled.
+     */
+    runnableShapeOf(steps: readonly PipelineStep[]): PipelineShape;
+    /**
+     * Refuse a task start while any of its dependencies is unfinished. A task may only run
+     * once every block it `dependsOn` has reached `done` (its PR merged). No-ops for
+     * non-task blocks and for tasks with no dependencies. Throws a {@link ConflictError}
+     * (→ 409, shown as a toast) naming the unfinished blockers so the human knows why.
+     */
+    assertDependenciesMet(workspaceId: string, block: Block): Promise<void>;
+    /**
+     * Augment a workspace's block list (in place) with any dependency blocks referenced by
+     * `depIds` that aren't already present — a `dependsOn` edge can point at a task homed in a
+     * DIFFERENT workspace (a shared/mounted service). Resolved via the cross-workspace
+     * {@link BlockRepository.findByIds} (one batched query, not a point-read per id), so a
+     * shared-service blocker is evaluated by its real status instead of being silently treated
+     * as satisfied (missing ⇒ done). Returns the same (now-augmented) array for chaining.
+     */
+    augmentWithCrossWorkspaceDeps(blocks: Block[], depIds: string[]): Promise<Block[]>;
+    /**
+     * Enforce the workspace's per-service running-task limit before a task run starts.
+     * No-ops unless the settings module is wired, the block is a task, and a limit mode
+     * is active. Counts the tasks under the same service frame that already have a live
+     * run (running / blocked / paused) — bucketed by task type when the mode is
+     * `per_type`, else shared across all types — and throws a {@link ConflictError} (→ 409,
+     * shown as a toast) when the cap is reached. The starting block is excluded from the
+     * count (its prior run is about to be replaced).
+     */
+    assertWithinTaskLimit(workspaceId: string, block: Block): Promise<void>;
+    /**
+     * Whether a model id will incur metered monetary cost for THIS workspace. Non-metered:
+     * a subscription model whose vendor is connected ("subscriptions always win"), or a
+     * local-runner model (keyless, on the user's own endpoint). Everything else — including
+     * env-default routing (an absent id) and Cloudflare Workers AI — is treated as metered.
+     * Shared with {@link RunDispatcher.currentStepIsNonMetered} so the up-front budget gate
+     * and the mid-run spend gate can't classify a model differently.
+     */
+    modelIdIsMetered(id: string | undefined, caps: ProviderCapabilities): boolean;
+    /**
+     * Guard a run start when the pipeline carries a VISUAL step (`tester-ui` /
+     * `visual-confirmation`): such a step exercises a rendered UI, so it only makes sense where
+     * there is a UI to drive — a `type: 'frontend'` frame (it owns the app under test) or a frame
+     * a `frontend` frame links to (the linked frontend is the UI a change to that service is
+     * validated through). On any other frame (a service with no linked frontend, a `library` /
+     * `document` repo) a `tester-ui` step would have nothing to drive, so refuse the start with an
+     * actionable {@link ConflictError} (`visual_pipeline_no_frontend`). The frontend surfaces the
+     * SAME rule (via the shared `frameAllowsVisualPipeline`) so it only offers these pipelines
+     * where they can run; this is the server-side guarantee. A non-visual pipeline passes through.
+     * The workspace block list is read ONCE (for the frontend→service links), never per-frame.
+     */
+    private assertPipelineFrameTypeAllowed;
+    /**
+     * Guard a Tester pipeline's start on the service frame's declared provisioning being runnable.
+     * The Tester needs SOME way to stand its system up: `infraless` (or none declared) runs with no
+     * infra; `docker-compose`/`kubernetes`/`custom` are all provisioned by the single Deployer step
+     * through a workspace handler, so one must resolve for the service's type. A `frontend` frame is
+     * gated instead on having a live service under test. Throws an actionable {@link ConflictError}
+     * (`tester_infra_unsupported` for the frontend case, `provision_type_unhandled` for a missing
+     * handler); passes through when the provisioning seam is unwired (tests / no environment
+     * integration), like the other optional start guards. `initiatedBy` is threaded into
+     * `canProvision` so the run initiator's local per-user handler OVERRIDES resolve exactly as they
+     * do at provision time (and as the Deployer-config gate does) — else a valid override-only local
+     * setup would be falsely refused here while the deployer would actually provision it.
+     */
+    private assertTesterInfraConfigured;
+    /**
+     * Fail fast when a `docker-compose`/`kubernetes`/`custom` service's chain would dead-end at an
+     * env-consumer (tester / human-test / playwright) because no enabled `deployer` provisions the
+     * environment before it — the exact silent dead-end this initiative fixes (the tester picks
+     * ephemeral mode from the provision type but finds no coordinates). The pure ordering check lives
+     * in {@link needsDeployerBeforeConsumer}; here we resolve the service's provision type (only when a
+     * consumer is present, so consumer-less chains skip the read) and translate a positive verdict
+     * into an actionable {@link ConflictError}. Pass-through for infraless/frontend services and for
+     * chains with a deployer before the first consumer.
+     */
+    private assertDeployerBeforeConsumer;
+    /**
+     * Guard a pipeline that INCLUDES an enabled `deployer` step on its ephemeral-environment config
+     * being FULL + CORRECT on BOTH sides of the "what/where ÷ how" split, so a misconfigured
+     * environment fails LOUDLY at start with a fixable pointer instead of mid-run: a `kubernetes` /
+     * `custom` service silently failing its async provision, or a `docker-compose` one whose deployer
+     * NO-OPS because no handler resolves (the exact silent dead-ends this initiative closes). It
+     * checks, in order of the fix a human would make:
+     *   1. the SERVICE's provisioning config is complete for its declared type (manifest source /
+     *      compose path / custom-manifest id) — else `deployer_service_provisioning_incomplete`;
+     *   2. a WORKSPACE handler resolves for the type — else `provision_type_unhandled` (the same
+     *      reason the Tester gate raises; a MISSING/ambiguous handler, not a broken one);
+     *   3. (bonus, best-effort) the resolved deployment integration's live connection PROBES green —
+     *      else `deployer_connection_test_failed`, carrying the provider's failure detail.
+     * Each `ConflictError` carries a machine-readable reason + details the SPA deep-links off to the
+     * exact fix surface. Pass-through for `infraless`/undeclared services (the deployer stands nothing
+     * up) and when the environment seam is unwired (tests / no-env deployments), like the other
+     * optional start guards.
+     */
+    private assertDeployerConfigured;
+    /**
+     * Guard a pipeline's start when it carries an agent kind that RELIES on binary-artifact
+     * storage (the {@link BINARY_STORAGE_TRAIT}, e.g. the UI Tester, which uploads its
+     * screenshots there). Such a run would otherwise dispatch and then fail/degrade with no
+     * place to store its artifacts, so refuse it up-front with a clear, actionable
+     * `binary_storage_unconfigured` conflict the SPA turns into a "configure storage" prompt.
+     * The check is trait-driven so it stays universal: a future artifact-producing kind just
+     * carries the trait. Pass-through when no store resolver is wired (tests/conformance with
+     * no storage) — matching the other optional start guards.
+     */
+    private assertBinaryStorageConfigured;
+    /**
+     * Guard a pipeline's start on having a usable provider for every step's canonical
+     * model. The model a step runs is resolved by the same precedence the dispatch path
+     * uses (block pin → workspace per-kind default); each canonical id must have a usable
+     * provider given what's configured — a direct API key for its provider, a connected
+     * subscription vendor, or the opt-in Cloudflare lib enabled. Env-routing defaults (the
+     * last fallback, with no catalog id) are operator-level and not gated, matching the
+     * personal-credential gate. A throw aborts the start cleanly before any side effects.
+     * Skipped when no capability resolver is wired (tests / unconfigured facades).
+     */
+    private assertProvidersConfiguredForPipeline;
+    /**
+     * Refuse to START / RETRY a run when the workspace has reached its spend budget AND the
+     * pipeline has at least one budget-METERED step. A `0` (or exhausted) budget is a
+     * deliberate "no paid spend" setting, but it must surface as a clear, up-front error here
+     * rather than a silent mid-run pause. Steps that incur no metered cost — a connected
+     * subscription model, or a keyless local-runner model — are exempt, so a workspace that
+     * runs ONLY local/subscription models starts normally even at a `0` budget. Best-effort:
+     * with no capability resolver wired (tests/unconfigured) it is skipped and the mid-run
+     * gate still guards. Before any side effects, matching the other start guards.
+     */
+    private assertBudgetAllowsPipeline;
+}
+//# sourceMappingURL=RunAdmission.d.ts.map

package/dist/modules/execution/RunAdmission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunAdmission.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/RunAdmission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,eAAe,EACf,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACpB,MAAM,qBAAqB,CAAA;AAiB5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAA;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAgBzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAA;AAEvF,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,eAAe,EAAE,eAAe,CAAA;IAChC,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,cAAc,EAAE,mBAAmB,CAAA;IACnC,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB;gFAC4E;IAC5E,uBAAuB,CAAC,EAAE,8BAA8B,CAAA;IACxD,wBAAwB,CAAC,EAAE,wBAAwB,CAAA;IACnD,0BAA0B,CAAC,EAAE,0BAA0B,CAAA;IACvD,2BAA2B,CAAC,EAAE,CAC5B,WAAW,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,KACxB,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAClC,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAA;IAC7C,4BAA4B,CAAC,EAAE,CAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,MAAM,KACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAChC,4BAA4B,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtE;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAmB;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAC,CAAgC;IACzE,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAA0B;IACpE,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAC,CAA4B;IACxE,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAGX;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAA4B;IAC9D,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAId;IAChC,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAwC;IAEtF,YAAY,IAAI,EAAE,gBAAgB,EAcjC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACG,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,OAAO,CAAC,IAAI,CAAC,CA4Df;IAED;;;;;;OAMG;IACH,eAAe,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,aAAa,CAW7D;IAED;;;;;OAKG;IACG,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E;IAED;;;;;;;OAOG;IACG,6BAA6B,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAQvF;IAED;;;;;;;;OAQG;IACG,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CA+D5E;IAED;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAO5E;IAED;;;;;;;;;;;OAWG;YACW,8BAA8B;IAqB5C;;;;;;;;;;;;OAYG;YACW,2BAA2B;IAmDzC;;;;;;;;;OASG;YACW,4BAA4B;IAyB1C;;;;;;;;;;;;;;;;;OAiBG;YACW,wBAAwB;IA8FtC;;;;;;;;;OASG;YACW,6BAA6B;IAgB3C;;;;;;;;;OASG;YACW,oCAAoC;IAqFlD;;;;;;;;;OASG;YACW,0BAA0B;CA+BzC"}