@cat-factory/orchestration 0.327.0 → 0.329.0

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

@@ -0,0 +1,51 @@
+import type { Clock, ExecutionInstance, ExecutionRepository, Logger, WorkRunner } from '@cat-factory/kernel';
+import type { AdvanceResult } from './advance.js';
+import type { RunStateMachine } from './RunStateMachine.js';
+import type { StepGraph } from './StepGraph.js';
+export interface CredentialWaitControllerDeps {
+    stateMachine: RunStateMachine;
+    stepGraph: StepGraph;
+    executionRepository: ExecutionRepository;
+    clock: Clock;
+    workRunner: WorkRunner;
+    logger?: Logger;
+}
+/**
+ * Parks a run whose personal-subscription credential lapsed, and resumes it.
+ *
+ * A run on an individual-usage model leases its initiator's credential at every dispatch, from an
+ * activation with a fixed lifetime. Whatever advanced the run to that dispatch (a human answering
+ * a review, a background re-review converging, a timer) is irrelevant here: the lease is refused,
+ * and the step parks on the generic approval with `credentialWait` set, instead of failing the run.
+ * The person answers it with {@link resume}, which re-mints the activation from their personal
+ * password before re-dispatching.
+ *
+ * {@link guard} is the ONE place the refusal is recognised. The engine routes every call that can
+ * dispatch (advance and the three poll entry points) through it, so no dispatch site and no
+ * run-advancing route has to remember to check the credential itself.
+ */
+export declare class CredentialWaitController {
+    private readonly deps;
+    private readonly log;
+    constructor(deps: CredentialWaitControllerDeps);
+    /**
+     * Run one engine call that may dispatch a step, parking the run when the dispatch's lease was
+     * refused. Anything else (a result or a throw) passes through untouched.
+     */
+    guard(workspaceId: string, executionId: string, work: () => Promise<AdvanceResult>): Promise<AdvanceResult>;
+    /**
+     * Park the run's current step on a credential wait. Answers `null` when the run is no longer
+     * live (stopped or settled while the dispatch was failing), so the caller keeps the original
+     * outcome rather than parking a run nobody is driving.
+     */
+    private park;
+    /**
+     * Resume a step parked on a lapsed credential: re-mint the activation through `renew`, clear the
+     * park and wake the driver, which re-dispatches the SAME step. The park and the caller are
+     * checked before `renew` runs, so a run that is not parked (already resumed, stopped) never gets
+     * a fresh credential minted for it, and nobody but the initiator mints one the lease would not
+     * read.
+     */
+    resume(workspaceId: string, executionId: string, actorUserId: string | null, renew: () => Promise<void>): Promise<ExecutionInstance>;
+}
+//# sourceMappingURL=CredentialWaitController.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CredentialWaitController.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/CredentialWaitController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,iBAAiB,EACjB,mBAAmB,EACnB,MAAM,EACN,UAAU,EACX,MAAM,qBAAqB,CAAA;AAU5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AA6C/C,MAAM,WAAW,4BAA4B;IAC3C,YAAY,EAAE,eAAe,CAAA;IAC7B,SAAS,EAAE,SAAS,CAAA;IACpB,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,KAAK,EAAE,KAAK,CAAA;IACZ,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAwB;IAGvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAE5B,YAA6B,IAAI,EAAE,4BAA4B,EAE9D;IAED;;;OAGG;IACG,KAAK,CACT,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,GACjC,OAAO,CAAC,aAAa,CAAC,CAYxB;IAED;;;;OAIG;YACW,IAAI;IA6BlB;;;;;;OAMG;IACG,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAiC5B;CACF"}

package/dist/modules/execution/CredentialWaitController.js

@@ -0,0 +1,140 @@
+import { isCredentialWaitParked, mayResumeCredentialWait } from '@cat-factory/contracts';
+import { ConflictError, CredentialRequiredError, ForbiddenError, assertFound, getErrorReason, noopLogger, } from '@cat-factory/kernel';
+/**
+ * The `details.reason` a lease refusal carries. Every dispatch that runs on a personal
+ * subscription leases the run's activation, and the lease is the one authority on whether that
+ * activation is still live, so this reason is what the park keys on rather than a prediction of
+ * which steps will need a credential.
+ */
+const LAPSED_REASON = 'password_required';
+/** Whether a thrown error is a step's lease being refused for a lapsed credential. */
+function isLapseError(error) {
+    return error instanceof CredentialRequiredError && getErrorReason(error) === LAPSED_REASON;
+}
+/**
+ * Whether a settled step result is the same refusal, after an async dispatch site classified the
+ * throw into a `preflight` failure (see `classifyDispatchFailure`).
+ */
+function isLapseResult(result) {
+    return (result.kind === 'job_failed' &&
+        result.failureKind === 'preflight' &&
+        result.reason === LAPSED_REASON);
+}
+/**
+ * The approval id of a LIVE credential park, or null. Only a `blocked` run counts: a run stopped
+ * while parked keeps the step exactly as it stood, and resuming it would re-mint a credential for
+ * a run nobody is driving.
+ */
+function parkedApprovalId(instance) {
+    const step = instance.steps[instance.currentStep];
+    if (instance.status !== 'blocked' || !step || !isCredentialWaitParked(step))
+        return null;
+    return step.approval.id;
+}
+function notParked() {
+    return new ConflictError('This run is not waiting on a personal subscription credential.', 'credential_wait_not_parked');
+}
+/**
+ * Parks a run whose personal-subscription credential lapsed, and resumes it.
+ *
+ * A run on an individual-usage model leases its initiator's credential at every dispatch, from an
+ * activation with a fixed lifetime. Whatever advanced the run to that dispatch (a human answering
+ * a review, a background re-review converging, a timer) is irrelevant here: the lease is refused,
+ * and the step parks on the generic approval with `credentialWait` set, instead of failing the run.
+ * The person answers it with {@link resume}, which re-mints the activation from their personal
+ * password before re-dispatching.
+ *
+ * {@link guard} is the ONE place the refusal is recognised. The engine routes every call that can
+ * dispatch (advance and the three poll entry points) through it, so no dispatch site and no
+ * run-advancing route has to remember to check the credential itself.
+ */
+export class CredentialWaitController {
+    deps;
+    log;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.logger ?? noopLogger;
+    }
+    /**
+     * Run one engine call that may dispatch a step, parking the run when the dispatch's lease was
+     * refused. Anything else (a result or a throw) passes through untouched.
+     */
+    async guard(workspaceId, executionId, work) {
+        let result;
+        try {
+            result = await work();
+        }
+        catch (error) {
+            if (!isLapseError(error))
+                throw error;
+            const parked = await this.park(workspaceId, executionId);
+            if (!parked)
+                throw error;
+            return parked;
+        }
+        if (!isLapseResult(result))
+            return result;
+        return (await this.park(workspaceId, executionId)) ?? result;
+    }
+    /**
+     * Park the run's current step on a credential wait. Answers `null` when the run is no longer
+     * live (stopped or settled while the dispatch was failing), so the caller keeps the original
+     * outcome rather than parking a run nobody is driving.
+     */
+    async park(workspaceId, executionId) {
+        let decisionId = null;
+        const instance = await this.deps.stateMachine.mutateInstance(workspaceId, executionId, (inst) => {
+            decisionId = null;
+            const step = inst.steps[inst.currentStep];
+            if (!step || (inst.status !== 'running' && inst.status !== 'paused'))
+                return;
+            step.credentialWait = { raisedAt: this.deps.clock.now() };
+            decisionId = this.deps.stateMachine.openDecisionPark(step, "The run's personal subscription credential lapsed.");
+            inst.status = 'blocked';
+        });
+        if (!decisionId)
+            return null;
+        await this.deps.stateMachine.updateBlockProgress(workspaceId, instance, 'blocked');
+        this.log.info('run parked: personal subscription credential lapsed', {
+            workspaceId,
+            runId: executionId,
+            stepIndex: instance.currentStep,
+        });
+        await this.deps.stateMachine.emitInstance(workspaceId, instance);
+        await this.deps.stateMachine.ensureWaitingNotification(workspaceId, instance);
+        return { kind: 'awaiting_decision', decisionId };
+    }
+    /**
+     * Resume a step parked on a lapsed credential: re-mint the activation through `renew`, clear the
+     * park and wake the driver, which re-dispatches the SAME step. The park and the caller are
+     * checked before `renew` runs, so a run that is not parked (already resumed, stopped) never gets
+     * a fresh credential minted for it, and nobody but the initiator mints one the lease would not
+     * read.
+     */
+    async resume(workspaceId, executionId, actorUserId, renew) {
+        const current = assertFound(await this.deps.executionRepository.get(workspaceId, executionId), 'Execution', executionId);
+        if (!parkedApprovalId(current))
+            throw notParked();
+        if (!mayResumeCredentialWait(current.initiatedBy, actorUserId)) {
+            throw new ForbiddenError('Only the person who started this run can renew its personal subscription credential.', { reason: 'credential_wait_not_initiator' });
+        }
+        await renew();
+        let approvalId = '';
+        const instance = await this.deps.stateMachine.mutateInstance(workspaceId, executionId, (inst) => {
+            const parked = parkedApprovalId(inst);
+            if (!parked)
+                throw notParked();
+            approvalId = parked;
+            const step = inst.steps[inst.currentStep];
+            step.credentialWait = null;
+            step.approval = null;
+            this.deps.stepGraph.startStep(step);
+            inst.status = 'running';
+        });
+        await this.deps.stateMachine.updateBlockProgress(workspaceId, instance, 'in_progress');
+        await this.deps.stateMachine.emitInstance(workspaceId, instance);
+        await this.deps.workRunner.signalDecision(workspaceId, instance.id, approvalId, 'approved');
+        return instance;
+    }
+}
+//# sourceMappingURL=CredentialWaitController.js.map

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

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