@usearazzo/runner 1.0.1-alpha.20 → 1.0.1-alpha.22

package/types/runner.d.ts

@@ -369,11 +369,12 @@ export declare interface ArazzoWorkflowLocator {
  * The `type` declared on a source description is not trusted (it may be
  * absent or wrong); a source is classified by what it actually parses to,
  * the same convention the OpenAPI operation locator follows. Source
- * documents are acquired from the registry on demand. Whether the resolved
- * document *defines* the workflow is deliberately left to the caller, which
- * owns the timing of that check (eager for a `dependsOn` list validated
- * before any prerequisite runs, lazy for a sub-workflow step resolved per
- * attempt).
+ * documents are acquired from the registry on demand. A reference to a
+ * workflow the resolved document does not define is rejected here, so every
+ * returned locator names an existing workflow; a caller controls when that
+ * check happens by when it normalizes (eagerly for a `dependsOn` list
+ * validated before any prerequisite runs, lazily for a sub-workflow step
+ * resolved on its first attempt).
  * @public
  */
 export declare class ArazzoWorkflowLocatorNormalizer extends SourceDescriptionsLocatorNormalizer {
@@ -382,7 +383,9 @@ export declare class ArazzoWorkflowLocatorNormalizer extends SourceDescriptionsL
      * Resolves a reference — a plain workflowId or a
      * `$sourceDescriptions.{name}.{workflowId}` expression, as written — to the
      * canonical locator: the Arazzo document that owns the target workflow,
-     * and the bare id within it.
+     * and the bare id within it. Rejects a workflow that document does not
+     * define as `workflow-not-found`, attributed to the referencing context
+     * like every other error raised here.
      */
     normalize(reference: string, document: ArazzoDocument, context: WorkflowReferenceContext): Promise<ArazzoWorkflowLocator>;
 }
@@ -534,7 +537,45 @@ export declare class CriterionEvaluationError extends CriterionError {
 }
 
 /**
- * Evaluates an Arazzo Criterion Object to a boolean.
+ * The outcome of one criterion a step evaluated: one of its `successCriteria`,
+ * or one of the `criteria` of an action it considered.
+ * @public
+ */
+export declare interface CriterionEvaluationRecord {
+    /**
+     * The criterion's `condition`, as written.
+     */
+    readonly condition: string;
+    /**
+     * Whether the condition is met.
+     */
+    readonly met: boolean;
+    /**
+     * The `name` of the action declaring the criterion — present only on an
+     * action criterion.
+     */
+    readonly actionName?: string;
+    /**
+     * Why the condition could not be evaluated — present only then, with `met`
+     * `false`.
+     */
+    readonly diagnostic?: {
+        /**
+         * Machine-readable: the `reason` of the error that failed the criterion, a
+         * `CriterionErrorReason` value or `'unavailable-expression'` for an
+         * HTTP-exchange expression in a step that calls a workflow.
+         */
+        readonly code?: CriterionErrorReason | 'unavailable-expression';
+        /**
+         * Human-readable: names the condition or expression and, for a syntax
+         * error, what is wrong with it; never request or response data.
+         */
+        readonly message: string;
+    };
+}
+
+/**
+ * Evaluates an Arazzo Criterion Object to a {@link CriterionOutcome}.
  *
  * Dispatches on the criterion's `type` (defaulting to `simple` when omitted):
  * - `simple` — evaluates the condition directly, resolving the runtime
@@ -554,12 +595,13 @@ export declare class CriterionEvaluationError extends CriterionError {
  * the 1.1.0 rule to every document, which accepts more but never evaluates a
  * query under the wrong dialect.
  *
- * A condition that cannot be evaluated fails the criterion (`false`), as
+ * A condition that cannot be evaluated fails the criterion (`met: false`), as
  * Arazzo 1.1.0 requires: a syntax error in the condition, a context the
  * condition cannot apply to (non-XML data for `xpath`), or an XPath evaluation
  * error. The type-specific evaluators report these as a
- * {@link CriterionEvaluationError}, which this facade absorbs; any other error
- * they raise propagates. A criterion that is malformed as written still throws: a
+ * {@link CriterionEvaluationError}, which this facade returns as the
+ * outcome's `error` so the caller can report it; any other error they raise
+ * propagates. A criterion that is malformed as written still throws: a
  * missing `condition`, an unknown or unreadable `type`, an unsupported
  * expression `version`, or a `context` that is missing or not a runtime
  * expression.
@@ -574,13 +616,14 @@ export declare class CriterionEvaluator {
     #private;
     constructor(options?: CriterionEvaluatorOptions);
     /**
-     * Evaluates a criterion element, returning whether the condition is met.
+     * Evaluates a criterion element, returning whether the condition is met and,
+     * when it cannot be evaluated, why.
      *
      * `resolve` turns a runtime expression into a value: for `simple` it resolves
      * the expressions embedded in the condition; for the other types it resolves
      * the criterion's `context` expression that the condition is applied to.
      */
-    evaluate(criterion: CriterionElement, resolve: CriterionContextResolver): boolean;
+    evaluate(criterion: CriterionElement, resolve: CriterionContextResolver): CriterionOutcome;
 }
 
 /**
@@ -611,14 +654,32 @@ export declare interface CriterionEvaluatorOptions {
 }
 
 /**
- * Determines whether a single criterion is met.
+ * The outcome of evaluating one criterion.
+ * @public
+ */
+export declare interface CriterionOutcome {
+    /**
+     * Whether the condition is met. `false` when it evaluates to false or cannot
+     * be evaluated; only in the latter case is {@link CriterionOutcome.error}
+     * present, saying why.
+     */
+    readonly met: boolean;
+    /**
+     * Why the condition could not be evaluated: present only when it was not.
+     */
+    readonly error?: CriterionEvaluationError;
+}
+
+/**
+ * Determines whether a single criterion of an action is met. Receives the
+ * action declaring the criterion, so a caller can attribute the outcome to it.
  *
  * Bridged to a criterion evaluator
- * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve)`); an
+ * (`(criterion) => criterionEvaluator.evaluate(criterion, resolve).met`); an
  * unresolvable/failing criterion is `false`, not an error.
  * @public
  */
-export declare type CriterionPredicate = (criterion: CriterionElement) => boolean;
+export declare type CriterionPredicate = (criterion: CriterionElement, action: SelectedAction) => boolean;
 
 /** @public */
 export declare class DocumentLoadError extends ArazzoRunnerError {
@@ -1929,6 +1990,16 @@ export declare interface StepExecutionResult {
      * matching action. Empty when none matched.
      */
     readonly matchedActions: readonly SelectedAction[];
+    /**
+     * The outcome of each of the step's `successCriteria`, in list order.
+     */
+    readonly successCriteria: readonly CriterionEvaluationRecord[];
+    /**
+     * The outcome of each criterion of the actions the step considered — its
+     * `onSuccess` actions when it succeeded, its `onFailure` actions otherwise —
+     * in list order.
+     */
+    readonly actionCriteria: readonly CriterionEvaluationRecord[];
 }
 
 /**
@@ -1996,19 +2067,23 @@ export declare class StepExecutor {
      */
     assertSuccessCriteria(step: StepElement, workflowId?: string): void;
     /**
-     * Evaluates the step's `successCriteria`; all criteria must pass. A step with
-     * no criteria succeeds on a received response. An unreadable
-     * `successCriteria` throws, see {@link StepExecutor.assertSuccessCriteria}.
+     * Evaluates the step's `successCriteria`, returning one record per criterion
+     * in list order; the step succeeds when every record is met. Every criterion
+     * is evaluated, so the records explain each unmet one, not only the first. A
+     * step with no criteria returns no records and succeeds on a received
+     * response. An unreadable `successCriteria` throws, see
+     * {@link StepExecutor.assertSuccessCriteria}.
      *
      * Public for the same reason as {@link StepExecutor.selectActions}: a step
      * targeting a `workflowId` is run by the workflow executor and never reaches
      * {@link StepExecutor.execute}, but its criteria are still the author's
      * assertion about the step and must be evaluated somewhere.
      */
-    evaluateCriteria(step: StepElement, context: RuntimeExpressionContext): boolean;
+    evaluateCriteria(step: StepElement, context: RuntimeExpressionContext): CriterionEvaluationRecord[];
     /**
      * Selects every matching `onSuccess` / `onFailure` action for the outcome, in
-     * list order, gating each action's criteria against the context.
+     * list order, gating each action's criteria against the context, and records
+     * the outcome of every action criterion evaluated.
      *
      * The step's own list is the whole story here: a step that declares none of
      * its own already carries the workflow-level defaults, inherited by
@@ -2026,7 +2101,7 @@ export declare class StepExecutor {
      * {@link StepExecutor.execute}. Both callers reach the criteria evaluator and
      * the expression context through this one method rather than wiring their own.
      */
-    selectActions(step: StepElement, successful: boolean, context: RuntimeExpressionContext): SelectedAction[];
+    selectActions(step: StepElement, successful: boolean, context: RuntimeExpressionContext): Pick<StepExecutionResult, 'matchedActions' | 'actionCriteria'>;
 }
 
 /**
@@ -2104,6 +2179,17 @@ export declare interface StepRunRecord {
      * fractional and is unaffected by system clock changes.
      */
     readonly durationMs: number;
+    /**
+     * The outcome of each of the step's `successCriteria` in its last attempt, in
+     * list order — why the step succeeded or failed.
+     */
+    readonly successCriteria: readonly CriterionEvaluationRecord[];
+    /**
+     * The outcome of each criterion of the actions the last attempt considered —
+     * its `onSuccess` actions when it succeeded, its `onFailure` actions
+     * otherwise — in list order: why an action matched or did not.
+     */
+    readonly actionCriteria: readonly CriterionEvaluationRecord[];
     /**
      * The sub-workflow runs this step produced, in attempt order — present only on
      * a step targeting a `workflowId`.