@cat-factory/orchestration 0.313.2 → 0.314.1

package/dist/modules/execution/step-fold.logic.d.ts

@@ -1,4 +1,4 @@
-import { type AgentJobHandle, type PipelineStep } from '@cat-factory/kernel';
+import { type AgentJobHandle, type DelegationHandle, type PipelineStep, type RunDelegation } from '@cat-factory/kernel';
 import type { DispatchToolServers } from '@cat-factory/contracts';
 /**
  * Rebuild the job handle a settled/running POLL addresses, from the step alone.
@@ -20,7 +20,52 @@ import type { DispatchToolServers } from '@cat-factory/contracts';
  *  - `initiatedByUserId` — the quota-cycle counters' fallback target for a PERSONAL
  *    (individual-usage) run, which leases no pooled token; absent, the target is null.
  */
-export declare function pollHandleFor(step: PipelineStep, workspaceId: string, executionId: string): AgentJobHandle;
+export declare function pollHandleFor(step: PipelineStep, workspaceId: string, executionId: string, 
+/**
+ * The run's block. A PARAMETER rather than something read off the step, like `workspaceId` and
+ * `executionId` beside it, and load-bearing for the same reason they are: the delegated arm
+ * re-resolves its executor's credentials on every poll, and a lookup a per-service credential
+ * store cannot scope returns nothing, so the step polls for its whole life with an empty bag.
+ */
+blockId: string): AgentJobHandle;
+/**
+ * The delegation record the step's IN-FLIGHT job belongs to, or undefined when the job in flight is
+ * not that record's.
+ *
+ * The ONE question every reader of `step.delegated` actually has, and asking `if (step.delegated)`
+ * instead is the shape that gets it wrong. A step whose own work was delegated can still dispatch a
+ * CONTAINER job afterwards (a helper round, a re-run under an overriding kind, a PR-review `fix`
+ * resolution), and the delegation record outlives that by design: its attempt log is the evidence
+ * for why the step is being re-run, and `resetStepForRerun` clears `jobId` and deliberately not the
+ * record. So a bare truthiness test routes that container job's poll to an external system, folds
+ * its phase onto external work that finished hours ago, and settles the external record on the
+ * container's outcome: three different systems' facts written onto one another.
+ *
+ * Keyed on the correlation key rather than on the record's status because the status is what the
+ * fold is about to CHANGE; the key is what says whose job this is, which is exactly why it is
+ * persisted (see `runDelegationSchema.correlationKey`).
+ */
+export declare function inFlightDelegation(step: PipelineStep): RunDelegation | undefined;
+/**
+ * The job id a re-entering advance may RE-ATTACH to, or undefined when there is nothing to
+ * re-attach to and the step must dispatch.
+ *
+ * Every dispatch site guards on "does this step already hold a job", and `step.jobId` alone is the
+ * wrong question for a delegated one. The claim is committed BEFORE `start()` is called, so a
+ * process that dies in between (a workerd isolate kill, a pg-boss worker restart, a deploy drain)
+ * leaves a job id addressing work that may never have been started. Read as a live handle, the
+ * replay skips its whole dispatch block and polls: the executor is asked to recover a run by
+ * correlation, answers "not yet" for ever because nothing was ever queued, and the step is failed
+ * as a TIMEOUT once the poll budget is spent, hours later and naming the wrong fault.
+ *
+ * A claim still `starting` is exactly that state and nothing else: {@link stampDelegationDispatch}
+ * moves it to `running` the moment the executor answers, and {@link failDelegationDispatch} drops
+ * the job id when it throws. So the honest answer is "no live job", and the site re-dispatches
+ * under the SAME correlation key (the dispatch epoch has not moved), which is precisely what the
+ * port's idempotency requirement is for: `start` recognises its own run, or starts the one that
+ * never began.
+ */
+export declare function liveJobId(step: PipelineStep): string | undefined;
 /**
  * Persist the attribution a DISPATCH knows and the poll site cannot re-derive: the resolved
  * model, plus (for a subscription-harness job) the leased pool row and the run's initiator,
@@ -143,6 +188,177 @@ export declare function recordInlineToolServers(step: PipelineStep, resolved: Di
  * that dispatched holds a `string` rather than re-reading the now-optional `step.jobId`.
  */
 export declare function recordDispatchedJob(step: PipelineStep, handle: AgentJobHandle, dispatchedKind: string): string;
+/**
+ * Open the delegation record for a dispatch about to happen: the CLAIM, committed BEFORE the
+ * external executor is called.
+ *
+ * This is the whole idempotency story for a delegated step, and the deadliest trap in the flow.
+ * Both durable drivers replay, and an executor asked to start twice produces two external runs and
+ * two pull requests for one task. So the engine takes the claim-before-effect half of the bargain
+ * the port asks the executor for: it writes `starting` with the correlation key as the step's job
+ * id, persists it, and only then dispatches. A replay finds the job id, re-attaches instead of
+ * dispatching, and the poll asks the executor to recover its own run by that key.
+ *
+ * The attempt log APPENDS. A re-run's earlier attempts and their URLs are the evidence for why the
+ * step is being re-run, and the platform holds nothing else about work that happened elsewhere.
+ * It does NOT append when the claim being re-opened is the SAME one, still unanswered: a dispatch
+ * that died between the claim and `start()` is re-driven under the same correlation key (see
+ * {@link liveJobId}), and the external system was asked once or not at all. Counted as a second
+ * attempt, a process that keeps dying would fill the step's evidence log with rounds that never
+ * reached anybody's runner.
+ */
+export declare function claimDelegation(step: PipelineStep, input: {
+    executor: string;
+    correlationKey: string;
+    startedAt: number;
+    poll: {
+        intervalMs: number;
+        maxDurationMs: number;
+    };
+}): void;
+/**
+ * Fold a dispatch that THREW onto the step's delegation claim, and drop the handle so the next
+ * advance dispatches rather than polls.
+ *
+ * The handle goes because the claim's job id says "there is an external run to poll", which after
+ * a throw is exactly what nobody knows. Cleared, a replayed advance re-dispatches under the SAME
+ * correlation key (the failed attempt recorded no dispatch, so the epoch has not moved) and the
+ * executor's own idempotency re-attaches to the run if one did start. Left set, the engine polls
+ * a job that may never have existed until the budget is spent and reports a timeout instead of
+ * the dispatch failure that actually happened.
+ *
+ * Whether the CLAIM survives is decided by the caller, and the two answers are different facts:
+ *
+ *  - `contacted: false`: the dispatch failed before the executor's system was reached (no repo
+ *    linked, no executor registered). Nothing is running anywhere, so the record SETTLES as
+ *    failed, and a teardown that asked the executor to cancel would raise a false alarm about
+ *    external work that never started.
+ *  - `contacted: true`: the executor was called and the call threw. The run may be queued, may be
+ *    running, may not exist; only the executor can tell. The claim stays OPEN so the teardown
+ *    names it, asks the executor to cancel by correlation key, and records whether that worked.
+ *    A settled record is invisible to `liveDelegations`, which is how a lost response left a live
+ *    external run to finish and open a pull request on a task the board reported as failed.
+ */
+export declare function failDelegationDispatch(step: PipelineStep, failure: {
+    error: string;
+    contacted: boolean;
+}): void;
+/**
+ * Fold a RUNNING delegated poll onto the step, returning whether anything changed: the delegated
+ * sibling of {@link applyContainerRunning}.
+ *
+ * Separate from it rather than one fold over both, because the two records share no field beyond a
+ * status whose vocabularies differ. There is no container id to learn and no address to reach, and
+ * the two things that DO arrive late here (the external id and the URL, for a system that returns
+ * neither at start) have no counterpart there.
+ *
+ * The id is folded ONE WAY: a poll that reports none leaves the recorded one standing. An executor
+ * recovers its id once, and re-deriving it on every poll is what the fold exists to stop (the
+ * bounded correlation scan a busy repository eventually pushes the run off the end of).
+ */
+export declare function applyDelegationRunning(step: PipelineStep, update: {
+    externalId?: string;
+    url?: string;
+    phase?: string;
+}): boolean;
+/**
+ * Every DELEGATED unit this run still has running somewhere else, as the handles their executors
+ * address them by.
+ *
+ * Read over EVERY step rather than the current one: a run parks on one step at a time, but a
+ * delegated step that failed into a retry, or one the run advanced past while its external work
+ * was still winding down, is exactly the work a teardown must still name. A record that already
+ * settled is excluded, because asking an executor to cancel a finished run is a request it has no
+ * good answer to and the record would then claim a cancellation that did not happen.
+ */
+export declare function liveDelegations(instance: {
+    id: string;
+    blockId: string;
+    steps: readonly PipelineStep[];
+}, 
+/**
+ * The workspace the run belongs to. A PARAMETER, because an instance does not carry one and the
+ * handle requires it: the executor re-resolves its credentials to cancel, and a handle built
+ * with a placeholder resolves an empty bag, so every cancel fails on a missing credential and
+ * the record then reports work as possibly-still-running that the executor could have stopped.
+ * Taken here rather than patched on by the caller so there is nothing to forget.
+ */
+workspaceId: string): DelegationHandle[];
+/**
+ * Mark every live delegation `cancelled`, recording WHETHER the external work actually stopped.
+ *
+ * The distinction is the whole point. An executor that declares no `cancel` leaves its run alive:
+ * it will finish, open its pull request and bill its tokens long after the platform has recorded
+ * this run as stopped. Writing `cancelled` with nothing beside it would render a clean teardown
+ * over exactly that, and the person who stopped the run is the one who needs to know to go and
+ * stop it themselves.
+ *
+ * An unreported handle (the executor answered nothing) is treated as NOT cancelled, which is the
+ * fail-safe reading: "we asked" and "it stopped" are different facts and only the executor can
+ * turn the first into the second.
+ */
+export declare function applyDelegationCancellation(instance: {
+    steps: readonly PipelineStep[];
+}, report: readonly {
+    correlationKey: string;
+    cancelled: boolean;
+    note?: string;
+}[] | undefined): boolean;
+/**
+ * Settle the delegation record on a terminal outcome, recording WHAT happened on the attempt the
+ * claim opened.
+ *
+ * `outcome` is the executor's own words rather than a platform classification, because this record
+ * is read by a person deciding whether to go and open the external logs, and "the workflow was
+ * cancelled upstream" tells them something `failed` does not.
+ */
+export declare function settleDelegation(step: PipelineStep, settlement: {
+    status: 'done' | 'failed' | 'cancelled';
+    outcome?: string | undefined;
+    url?: string | undefined;
+    note?: string | undefined;
+    /**
+     * The branch the work LANDED on, when the executor reported one. The product of a step whose
+     * executor pushed without opening a pull request, and recorded here because the platform holds
+     * nothing else about it: dropped, such a run settles as done with nothing to show for it.
+     */
+    branch?: string | undefined;
+}): void;
+/**
+ * Settle the step's own DELEGATION on the job that just finished, whichever disposition it
+ * reached, or do nothing when the job that finished was not the delegated one.
+ *
+ * Its own function rather than a guard plus a call at the settle site, because the whole rule is
+ * the guard: the record outlives the work it describes (its attempt log is the evidence for a
+ * re-run), so a CONTAINER job run later on the same step would overwrite a `failed` or `cancelled`
+ * external outcome with `done`, and that record is the entire account of work that happened
+ * somewhere else.
+ *
+ * It takes the whole settled update, and BOTH dispositions, because a step's delegated job is not
+ * always its own work: a gate's `ci-fixer`, an `on-call`, a tester's `fixer` and a failed
+ * deployer's `deploy-fixer` all ride the same `step.jobId`, and the round they finish is routed
+ * away from the completion path entirely (see `SettledHelperRouter`). Settling only the success
+ * case, only on that path, left every delegated helper's record reading `running` for ever: the
+ * teardown then asks its executor to cancel a run that finished, the spend-gap fold skips it as
+ * still in flight, and the step card says "running externally" over a job that is long done.
+ *
+ * `branch` is folded here because it is the product of an executor that pushed without opening a
+ * pull request: a case the port names as legitimate, and one where dropping the branch settles the
+ * run as done with nothing to show for it.
+ */
+export declare function settleDelegatedJob(step: PipelineStep, update: {
+    state: 'done';
+    delegated?: {
+        url?: string;
+        branch?: string;
+    };
+} | {
+    state: 'failed';
+    error: string;
+    delegated?: {
+        url?: string;
+    };
+}): void;
 export declare function applyContainerRunning(step: PipelineStep, update: {
     phase?: string;
     container?: {

package/dist/modules/execution/step-fold.logic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-fold.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/step-fold.logic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAC1F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAYjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,cAAc,CAUhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,cAAc,EACtB,cAAc,EAAE,MAAM,GACrB,IAAI,CAwBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE;IAAE,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GAAG,MAAM,EAAE,CAM3F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE;IAAE,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,EAC5C,cAAc,EAAE,MAAM,GACrB,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE;IAAE,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,EAC5C,cAAc,EAAE,MAAM,GACrB;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAG5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,mBAAmB,GAAG,SAAS,EACzC,cAAc,EAAE,MAAM,GACrB,IAAI,CAEN;AAkBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,cAAc,EACtB,cAAc,EAAE,MAAM,GACrB,MAAM,CAKR;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACpE,OAAO,CAkBT;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,YAAY,CAAC,UAAU,CAAC,GAC/B,OAAO,CAKT;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAI3F"}
+{"version":3,"file":"step-fold.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/step-fold.logic.ts"],"names":[],"mappings":"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"}