@astrale-os/sdk 0.6.0-beta.41 → 0.6.0-beta.43

package/dist/execution/workflows/failure.d.ts

@@ -1,5 +1,5 @@
 import type { DurableEngine } from './engine.js';
-/** Failure code of an Execution whose Workflow did not catch a Step that spent its retry budget. */
+/** Failure code of an Execution whose Workflow did not catch a Step that failed for good. */
 export declare const STEP_EXHAUSTED = "STEP_EXHAUSTED";
 /** A Kernel refusal as the wire names it: its protocol code and, when given, its reason code. */
 export interface KernelRefusal {
@@ -26,14 +26,31 @@ export declare class StepRetryAfter extends Error {
     constructor(delayMs: number, cause?: unknown);
 }
 /**
- * Encode a declared business error of `definition`, or a Step that spent its retry budget, as a
- * terminal engine failure, or return undefined for any other error, which the engine retries.
+ * Encode what a Workflow did not catch as the Execution's failure: a Step's recipe failure ends it
+ * with `STEP_EXHAUSTED`, naming the recipe and a `QueryError`'s code, never its details, which a
+ * read as the executor may fill with what the Execution's reader may not read; an S12 refusal names
+ * only Classes, so its message says what to declare. Anything else is encoded as
+ * `terminalFailure` encodes it. Inside a Step, a recipe failure caught from an earlier Step and
+ * thrown again fails that Step, as `queryFailure` encodes it.
+ */
+export declare function uncaughtFailure(engine: DurableEngine, cause: unknown, definition: object): Error | undefined;
+/**
+ * Encode a declared business error of `definition`, a recipe's it re-declares included, or a Step
+ * that spent its retry budget, as a terminal engine failure, or return undefined for any other
+ * error, which the engine retries.
  */
 export declare function terminalFailure(engine: DurableEngine, cause: unknown, definition: object): Error | undefined;
+/**
+ * Encode a recipe's failure as the Step's terminal failure, or return undefined for any other
+ * error. A read that met data it cannot answer, a query the Host cannot serve, or a recipe S12
+ * refuses is not retried. A refused read is a failed attempt as any Kernel refusal: retried,
+ * unless the Kernel refused it for good.
+ */
+export declare function queryFailure(engine: DurableEngine, cause: unknown): Error | undefined;
 /**
  * What a journaled Step failed with, as the Workflow sees it: its declared business error, rebuilt
- * through the definition's own factory, or `StepExhausted` once the engine spent its retry budget
- * or the Step threw an exhaustion caught from an earlier Step. A replay throws what the live run
- * threw.
+ * through the definition's own factory, its recipe's `QueryError` or S12 refusal, or
+ * `StepExhausted` once the engine spent its retry budget or the Step threw an exhaustion caught
+ * from an earlier Step. A replay throws what the live run threw.
  */
 export declare function replayedFailure(engine: DurableEngine, cause: unknown, definition: object, step: string): Error | undefined;

package/dist/execution/workflows/failure.js

@@ -1,8 +1,14 @@
 import { declaredErrorFactory, declaredErrorOf } from '../../application/error/index.js';
+import { UndeclaredCrossing } from '../../application/query/execution/crossings.js';
+import { isQueryError, QueryError } from '../../application/query/execution/error.js';
 import { ResponseError } from '../../platform/client/index.js';
 /** Metadata key the Kernel reads a declared failure from (`backend/restate` outcome decoding). */
 const FAILURE = 'astrale.failure';
-/** Failure code of an Execution whose Workflow did not catch a Step that spent its retry budget. */
+/** Metadata key of a Step's recipe failure, which only the Workflow reads back. */
+const QUERY_FAILURE = 'astrale.query';
+/** The Step each recipe failure the Workflow sees failed: uncaught, it ends the Execution. */
+const queryFailures = new WeakMap();
+/** Failure code of an Execution whose Workflow did not catch a Step that failed for good. */
 export const STEP_EXHAUSTED = 'STEP_EXHAUSTED';
 /** The longest delay a Step attempt may ask for, as the Kernel bounds a `retryAfterMs` hint. */
 const MAXIMUM_RETRY_AFTER_MS = 3_600_000;
@@ -85,22 +91,39 @@ const STATUS = {
     UNSUPPORTED: 422,
 };
 /**
- * Encode a declared business error of `definition`, or a Step that spent its retry budget, as a
- * terminal engine failure, or return undefined for any other error, which the engine retries.
+ * Encode what a Workflow did not catch as the Execution's failure: a Step's recipe failure ends it
+ * with `STEP_EXHAUSTED`, naming the recipe and a `QueryError`'s code, never its details, which a
+ * read as the executor may fill with what the Execution's reader may not read; an S12 refusal names
+ * only Classes, so its message says what to declare. Anything else is encoded as
+ * `terminalFailure` encodes it. Inside a Step, a recipe failure caught from an earlier Step and
+ * thrown again fails that Step, as `queryFailure` encodes it.
+ */
+export function uncaughtFailure(engine, cause, definition) {
+    const step = cause instanceof Error ? queryFailures.get(cause) : undefined;
+    if (step === undefined)
+        return terminalFailure(engine, cause, definition);
+    if (cause instanceof UndeclaredCrossing) {
+        return stepFailure(engine, `Workflow Step ${step} failed: ${cause.message}`, {
+            step,
+            query: { recipe: cause.recipe },
+        });
+    }
+    const { code, recipe } = cause;
+    return stepFailure(engine, `Workflow Step ${step} failed: ${code} from ${recipe}.`, {
+        step,
+        query: { code, recipe },
+    });
+}
+/**
+ * Encode a declared business error of `definition`, a recipe's it re-declares included, or a Step
+ * that spent its retry budget, as a terminal engine failure, or return undefined for any other
+ * error, which the engine retries.
  */
 export function terminalFailure(engine, cause, definition) {
     if (cause instanceof StepExhausted) {
-        return new engine.TerminalError(cause.message, {
-            metadata: {
-                [FAILURE]: JSON.stringify({
-                    code: STEP_EXHAUSTED,
-                    message: cause.message,
-                    details: {
-                        step: cause.step,
-                        ...(cause.refusal === undefined ? {} : { refusal: cause.refusal }),
-                    },
-                }),
-            },
+        return stepFailure(engine, cause.message, {
+            step: cause.step,
+            ...(cause.refusal === undefined ? {} : { refusal: cause.refusal }),
         });
     }
     const declared = declaredErrorOf(cause, definition);
@@ -118,17 +141,54 @@ export function terminalFailure(engine, cause, definition) {
         },
     });
 }
+function stepFailure(engine, message, details) {
+    return new engine.TerminalError(message, {
+        metadata: { [FAILURE]: JSON.stringify({ code: STEP_EXHAUSTED, message, details }) },
+    });
+}
+/**
+ * Encode a recipe's failure as the Step's terminal failure, or return undefined for any other
+ * error. A read that met data it cannot answer, a query the Host cannot serve, or a recipe S12
+ * refuses is not retried. A refused read is a failed attempt as any Kernel refusal: retried,
+ * unless the Kernel refused it for good.
+ */
+export function queryFailure(engine, cause) {
+    let failure;
+    if (cause instanceof UndeclaredCrossing)
+        failure = { recipe: cause.recipe, message: cause.message };
+    else if (isQueryError(cause) && cause.code !== 'REFUSED') {
+        const { code, recipe, message, details } = cause;
+        failure = { code, recipe, message, details };
+    }
+    else
+        return undefined;
+    return new engine.TerminalError(cause.message, {
+        metadata: { [QUERY_FAILURE]: JSON.stringify(failure) },
+    });
+}
 /**
  * What a journaled Step failed with, as the Workflow sees it: its declared business error, rebuilt
- * through the definition's own factory, or `StepExhausted` once the engine spent its retry budget
- * or the Step threw an exhaustion caught from an earlier Step. A replay throws what the live run
- * threw.
+ * through the definition's own factory, its recipe's `QueryError` or S12 refusal, or
+ * `StepExhausted` once the engine spent its retry budget or the Step threw an exhaustion caught
+ * from an earlier Step. A replay throws what the live run threw.
  */
 export function replayedFailure(engine, cause, definition, step) {
     if (!(cause instanceof engine.TerminalError) || cause instanceof engine.CancelledError) {
         return undefined;
     }
-    const encoded = cause.metadata?.[FAILURE];
+    const metadata = cause.metadata;
+    const query = metadata?.[QUERY_FAILURE];
+    if (query !== undefined) {
+        const failure = JSON.parse(query);
+        // Only a `QueryError` has a code.
+        const error = failure.code === undefined
+            ? new UndeclaredCrossing(failure.recipe, failure.message)
+            : new QueryError(failure.code, failure.recipe, failure.details);
+        error.message = failure.message;
+        queryFailures.set(error, step);
+        return error;
+    }
+    const encoded = metadata?.[FAILURE];
     // The Step's own code turns every terminal failure into a declared one or a failed attempt; a
     // bare one is an engine's budget.
     if (encoded === undefined)

package/dist/execution/workflows/receiver.d.ts

@@ -1,4 +1,5 @@
 import type { IntegrationClientFactory, Integrations } from '../../application/integration/index.js';
+import type { DeclaredClass } from '../../application/query/execution/crossings.js';
 import type { RuntimeWorkflow } from '../../application/runtime/workflows.js';
 import type { Domain } from '../../platform/schema/index.js';
 import type { Identity } from '../identity/index.js';
@@ -17,6 +18,8 @@ export interface DurableReceiver {
 export declare function createDurableReceiver(input: {
     readonly workflows: readonly RuntimeWorkflow[];
     readonly domain: Domain;
+    /** The Class requirements the Domain's build declares, which a Step's recipe reads are checked against. */
+    readonly declared?: readonly DeclaredClass[];
     readonly identity: Identity;
     readonly serving: AdmittedDurableServing;
     /** Integration clients of the initialized Runtime, which every Step holds. */

package/dist/execution/workflows/receiver.js

@@ -19,6 +19,7 @@ export function createDurableReceiver(input) {
     const steps = sessionSteps({
         executor: executor.bind(input.identity),
         domain: input.domain,
+        declared: input.declared ?? [],
         integrations: input.integrations,
     });
     const declared = new Map(input.workflows

package/dist/execution/workflows/run.js

@@ -1,10 +1,10 @@
 import { declaredErrorFactory } from '../../application/error/index.js';
 import { acceptStepId } from '../../application/workflow/step/index.js';
 import { acceptStepOutput } from '../../application/workflow/step/output.js';
-import { validateOutput } from '../invocation/result/index.js';
+import { reportUndeclaredRecipeError, validateOutput } from '../invocation/result/index.js';
 import { BACKOFF, UNAVAILABLE, failedAttemptError, failedAttemptOf, nextAttempt, } from './attempts.js';
 import { decodeEnvelope } from './envelope.js';
-import { replayedFailure, StepExhausted, StepRetryAfter, terminalFailure } from './failure.js';
+import { queryFailure, replayedFailure, StepExhausted, StepRetryAfter, terminalFailure, uncaughtFailure, } from './failure.js';
 import { stepServing } from './options.js';
 import { keySequence } from './steps.js';
 const MAXIMUM_SLEEP_MS = 365 * 24 * 60 * 60_000;
@@ -43,7 +43,7 @@ async function run(input, context, raw) {
         output = await definition.run(durable);
     }
     catch (cause) {
-        throw terminalFailure(engine, cause, definition) ?? cause;
+        throw uncaughtFailure(engine, cause, definition) ?? cause;
     }
     return validateOutput(workflow.callable, output);
 }
@@ -130,8 +130,12 @@ function durableContext(input, context, envelope) {
                 }
             }
             catch (cause) {
-                throw (terminalFailure(engine, cause, definition) ??
-                    failedAttemptError(engine, cause, startedAt, now(), step?.repeatsEffects() ?? false));
+                const terminal = terminalFailure(engine, cause, definition) ?? queryFailure(engine, cause);
+                if (terminal !== undefined)
+                    throw terminal;
+                // Retried as any failed attempt, and logged: the Workflow does not re-declare it.
+                reportUndeclaredRecipeError(cause, workflow.address);
+                throw failedAttemptError(engine, cause, startedAt, now(), step?.repeatsEffects() ?? false);
             }
             finally {
                 clearTimeout(timer);
@@ -206,8 +210,8 @@ function durableContext(input, context, envelope) {
             }
             const returned = declare(Object.freeze({
                 run: (id, execute) => declaration(id, execute),
-                query: (id, query, value) => declaration(id, (authority) => authority.query(query, value)),
-                mutate: (id, mutation, value) => declaration(id, (authority) => authority.mutate(mutation, value)),
+                query: (id, query, value, options) => declaration(id, (authority) => authority.query(query, value, options)),
+                mutate: (id, mutation, value, options) => declaration(id, (authority) => authority.mutate(mutation, value, options)),
             }));
             if (!Array.isArray(returned) ||
                 returned.length !== declared.size ||
@@ -285,8 +289,8 @@ function durableContext(input, context, envelope) {
         error: declaredErrorFactory(definition),
         step: Object.freeze({
             run: step,
-            query: (id, query, value) => step(id, (authority) => authority.query(query, value)),
-            mutate: (id, mutation, value) => step(id, (authority) => authority.mutate(mutation, value)),
+            query: (id, query, value, options) => step(id, (authority) => authority.query(query, value, options)),
+            mutate: (id, mutation, value, options) => step(id, (authority) => authority.mutate(mutation, value, options)),
             parallel,
         }),
         async sleep(durationMs) {

package/dist/execution/workflows/steps.d.ts

@@ -1,4 +1,5 @@
 import type { IntegrationClientFactory, Integrations } from '../../application/integration/index.js';
+import type { DeclaredClass } from '../../application/query/execution/crossings.js';
 import type { DurableExecution, DurableStepAuthority } from '../../application/workflow/index.js';
 import type { BoundClientSession } from '../../platform/client/session/index.js';
 import type { Domain } from '../../platform/schema/index.js';
@@ -29,6 +30,8 @@ export type StepAuthorities = (attempt: StepAttempt) => StepAuthorityBinding;
 export declare function sessionSteps(input: {
     readonly executor: Executor;
     readonly domain: Domain;
+    /** The Class requirements the Domain's build declares: a recipe's reads are checked against them. */
+    readonly declared: readonly DeclaredClass[];
     readonly integrations: IntegrationClientFactory<Integrations>;
 }): StepAuthorities;
 /**

package/dist/execution/workflows/steps.js

@@ -8,7 +8,7 @@ import { stepCalls } from './integrations.js';
  * an Action over the keyed Session, and the Runtime's Integration clients over the same keys.
  */
 export function sessionSteps(input) {
-    const { executor, domain, integrations } = input;
+    const { executor, domain, declared, integrations } = input;
     return ({ execution, next, lifetime }) => {
         const session = executor(execution.kernel, execution.id, lifetime);
         try {
@@ -19,7 +19,7 @@ export function sessionSteps(input) {
             });
             const auth = bindIntegrationAuthentication(lifetime, bound);
             const authority = Object.freeze({
-                ...bindCapabilities(domain, { self }),
+                ...bindCapabilities(domain, { self }, declared),
                 integrations: integrations(stepCalls({ next, lifetime, auth })),
             });
             return Object.freeze({

package/dist/platform/schema/kernel-compiled.d.ts

@@ -0,0 +1,2 @@
+/** Generated from the Kernel Schema of @astrale-os/kernel-core 1.0.0-beta.24, reduced to its Classes. Regenerate with pnpm sync:kernel-schema. */
+export declare const kernelCompiledSchema: string;