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

package/dist/testing/index.d.ts

@@ -10,5 +10,5 @@ export { dataset, isDatasetReference } from './reference.js';
 export type { DatasetReference } from './reference.js';
 export { isTests, tests } from './tests.js';
 export type { Tests, TestsInput } from './tests.js';
-export { createTestEngine } from './durable/index.js';
-export type { TestEngine, TestEngineOptions, TestExecution, TestJournalEntry, TestStartOptions, TestStepCapabilities, } from './durable/index.js';
+export { createTestWorkflowEngine } from './durable/index.js';
+export type { TestExecution, TestJournalEntry, TestStartOptions, TestStepCapabilities, TestWorkflowEngine, TestWorkflowEngineOptions, } from './durable/index.js';

package/dist/testing/index.js

@@ -6,4 +6,4 @@ export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset,
 export { loadDataset, loadDatasets } from './load.js';
 export { dataset, isDatasetReference } from './reference.js';
 export { isTests, tests } from './tests.js';
-export { createTestEngine } from './durable/index.js';
+export { createTestWorkflowEngine } from './durable/index.js';

package/dist/tooling/linter/implementations/source/workflows.js

@@ -6,7 +6,6 @@ const STEP_METHODS = new Set(['run', 'query', 'mutate']);
 // Members only a durable Workflow context has: using one proves the Workflow durable.
 const DURABLE_CONTEXT_MEMBERS = new Set([
     'awaitSignal',
-    'awaitExecution',
     'cancelled',
     'exhausted',
     'retryAfter',

package/docs/durable-workflows.md

@@ -50,9 +50,8 @@ export const remind = defineWorkflow<typeof schema>()(
 | `awaitSignal(name)` | Waits for the value `Execution.signal({ name, value })` delivers once under `name`, sent before or during the wait. |
 | `awaitSignal(name, { timeoutMs })` | Waits at most `timeoutMs`: `{ kind: 'signal', value }` or `{ kind: 'timeout' }`. |
 | `cancelled(error)` | Whether `error` is the engine's cooperative cancellation; catch it to compensate. |
-| `exhausted(error)` | Whether `error` is a Step that spent its retry budget; catch it to take another path. |
-| `retryAfter(ms, cause?)` | The failure to throw inside a Step whose next attempt must wait `ms` (at most one hour), as an HTTP `Retry-After` asks. |
-| `awaitExecution(ref)` | Waits durably for another Execution by journaled polling of its `result`. A poll has no Step budget: while the Kernel cannot answer, the run is retried until it pauses. |
+| `exhausted(error)` | Whether `error` is a Step that spent its retry budget, or that the Kernel refused for good; catch it to take another path. |
+| `retryAfter(ms, cause?)` | The failure to throw inside a Step whose next attempt must wait `ms` (at most one hour), as an HTTP `Retry-After` asks. It spends an attempt. |
 | `error(code, details)` | Declared business errors, as for any Workflow; they become the `failed` outcome. |
 
 A durable run acts as its Domain, never as its caller: the Workflow and its Steps have no `caller`,
@@ -82,10 +81,10 @@ This requires a Kernel that keeps Mutation receipts. An older Kernel refuses the
 
 Step ids are unique within a run. Steps and waits run one after another: the engine follows one
 awaited operation at a time, and loses track of a run that awaits several together through
-`Promise.all`, `allSettled`, `race` or `any`. A Step, `sleep`, `awaitSignal` or `awaitExecution`
-started while another runs is therefore refused with a `TypeError`, which pauses the run as any
-error between Steps does. Independent reads may share one Step, whose Kernel calls are ordinary
-calls that `Promise.all` may combine:
+`Promise.all`, `allSettled`, `race` or `any`. A Step, `sleep` or `awaitSignal` started while
+another runs is therefore refused with a `TypeError`, which pauses the run as any error between
+Steps does. Independent reads may share one Step, whose Kernel calls are ordinary calls that
+`Promise.all` may combine:
 
 ```ts
 const [invoice, reminders] = await step.run('read-invoice', ({ query }) =>
@@ -147,7 +146,7 @@ reads the output. Three changes it cannot see:
 - A caller that ignores the output, such as a View that refreshes after the call, compiles unchanged
   but refreshes before the Execution ends. Follow the Execution, and refresh when it ends.
 
-`createTestEngine` (see [Testing](#testing)) shows the first two: a refusal path ends
+`createTestWorkflowEngine` (see [Testing](#testing)) shows the first two: a refusal path ends
 `STEP_EXHAUSTED`, with what the last attempt threw in `failure`, and code whose path differs on
 replay fails with `JournalMismatch`.
 
@@ -192,16 +191,16 @@ receipt, even though its precondition no longer holds.
 
 ## Testing
 
-`createTestEngine` from `@astrale-os/sdk/testing` runs a durable Workflow in memory with the
-receiver a Host serves; only the engine is simulated. Each Step journals its result, every attempt
-replays the journal, timers follow a virtual clock, signals are buffered, a failing Step is retried
-within its budget and then fails into the Workflow, a run failing outside any Step is retried until it
-pauses, and cancellation is cooperative.
+`createTestWorkflowEngine` from `@astrale-os/sdk/testing` runs a durable Workflow in memory with
+the receiver a Host serves; only the engine is simulated. Each Step journals its result, every
+attempt replays the journal, timers follow a virtual clock, signals are buffered, a failing Step is
+retried within its budget and then fails into the Workflow, a run failing outside any Step is
+retried until it pauses, and cancellation is cooperative.
 
 ```ts
-import { createTestEngine } from '@astrale-os/sdk/testing'
+import { createTestWorkflowEngine } from '@astrale-os/sdk/testing'
 
-const engine = createTestEngine()
+const engine = createTestWorkflowEngine()
 const execution = await engine.start(remind, {
   schema: Billing,                      // the resolved Schema
   input: { note: 'soon' },
@@ -232,10 +231,12 @@ await execution.replay()                // the journal alone reaches the same ou
 | `journal`, `attempts` | The recorded entries, each Step with the times it ran, and the attempts of the run. |
 
 A Workflow whose code between Steps is not deterministic fails its next attempt with
-`JournalMismatch` and pauses. Retries do not wait out a backoff, but the backoff a retry skips, or the
-delay its failure asks for, counts toward the Step's `maxDurationMs`. Code should await only Steps and
-the context's own operations; the engine counts a run as waiting once it waits on a timer or a signal
-and nothing else runs.
+`JournalMismatch` and pauses. A retry after an attempt that spent the Step's budget does not wait
+out its backoff, but the backoff it skips, or the delay its `retryAfter` asks for, counts toward the
+Step's `maxDurationMs`. A wait for the platform, after a Kernel refusal that prescribes a delay or an
+unreachable Kernel, is a timer: the run is `waiting` until `advance` reaches it. Code should await only
+Steps and the context's own operations; the engine counts a run as waiting once it waits on a timer or
+a signal and nothing else runs.
 
 ## Signals
 
@@ -256,8 +257,22 @@ not settle on the engine.
 ## Retry budgets and timeouts
 
 A declared business error ends the Execution as `failed { family, code, message, details }`, with no
-retry. Any other error a Step throws fails that attempt, and the engine attempts the Step again within
-its retry budget. A Step that spends its budget throws into the Workflow; uncaught, the Execution
+retry. Any other error a Step throws fails that attempt. What follows depends on what the attempt
+failed on, read from the Kernel answer or the transport failure the error is, or carries as a `cause`:
+
+| The attempt failed on | The Step |
+| --- | --- |
+| The platform: a Kernel refusal that prescribes a delay (`CAPACITY_EXHAUSTED`, `SERVER_DRAINING`, `INSTANCE_MAINTENANCE`) or a stale snapshot; a Kernel or Release discovery that does not answer (a network failure, HTTP `429`, `502` or `503`) to a request that did not leave, or to a Query or a keyed call; `OUTCOME_UNKNOWN` to a Query or a keyed call | Waits, and is attempted again without spending its budget, for as long as the platform stays unavailable within its `maxDurationMs`. |
+| A request the Kernel never accepts as sent: `PARSE_ERROR`, `INVALID_REQUEST`, `METHOD_NOT_ALLOWED`, `UNSUPPORTED`, an expectation or a callable fingerprint that no longer matches, a stale maintenance session | Fails at once. |
+| Anything else: the Step's code, a Provider, `retryAfter`, a deadline, any other Kernel refusal, an unkeyed call whose outcome is unknown | Spends an attempt, and is attempted again within its budget. |
+
+A Query, a Mutation and an `invoke` of a durable callable repeat no effect when sent again, the last
+two by their key, so the Step waits out their unavailability. An unkeyed `invoke` that may have
+reached the Kernel may have run: sending it again is the Step's own risk, and spends an attempt. So
+does any failure of an attempt that sent one, since the next attempt sends it again: an outage never
+repeats an unkeyed `invoke` beyond the Step's budget.
+
+A Step that spends its budget, or fails at once, throws into the Workflow; uncaught, the Execution
 ends `failed` with code `STEP_EXHAUSTED`:
 
 ```ts
@@ -292,30 +307,39 @@ try {
 
 | `retry` field | Meaning | Bounds |
 | --- | --- | --- |
-| `maxAttempts` | Attempts, the first one included. | 1 to 1,000 |
-| `maxDurationMs` | Time from the first attempt after which a failed attempt is not retried; an attempt already scheduled still runs. | 1 ms to 365 days |
+| `maxAttempts` | Attempts that may fail on the Step's own account, the first one included. A wait for the platform spends none. | 1 to 1,000 |
+| `maxDurationMs` | Time from the first attempt after which a failed attempt is not retried, whatever it failed on; an attempt already scheduled still runs. The only bound on waiting for the platform. | 1 ms to 365 days |
 | `initialIntervalMs` | Delay before the first retry, doubled on each failure. | 1 ms to one hour |
-| `maxIntervalMs` | Longest delay between two attempts. | `initialIntervalMs` to one day |
+| `maxIntervalMs` | Longest backoff between two attempts. | `initialIntervalMs` to one day |
 
 The limits, `maxAttempts` and `maxDurationMs`, go together: a Step that declares either replaces both
 limits of the deployment, and the one it omits does not bound it. The budget is spent at the first
-limit reached. An interval the Step leaves out is the deployment's. `timeoutMs` bounds one attempt,
-its Kernel calls included, from one second to ten minutes: past it, the attempt fails, what it holds
-is aborted, and the failure counts toward the budget. Each Workflow service declares to the engine
-an abort timeout of fifteen minutes, so a Step's own timeout always ends its attempt before the
-engine would cut it.
-
-A Kernel refusal that prescribes a delay (capacity, draining, maintenance) waits that delay before
-the next attempt, instead of the backoff. Throw `retryAfter(ms, cause)` inside a Step for the same
-behavior, for instance on an HTTP `429` with `Retry-After`. Both attempts count toward the budget.
+limit reached; a Step without `maxDurationMs` waits for the platform until it answers or the run is
+cancelled. An interval the Step leaves out is the deployment's. `timeoutMs` bounds one attempt, its
+Kernel calls included, from one second to ten minutes: past it, the attempt fails, what it holds is
+aborted, and the failure spends an attempt. Each Workflow service declares to the engine an abort
+timeout of fifteen minutes, so a Step's own timeout always ends its attempt before the engine would
+cut it.
+
+An attempt after a failure of the Step's own waits its backoff, which doubles with each such
+failure. An attempt after a platform failure waits the longer of the delay the Kernel prescribes and a
+backoff that doubles with each platform failure since the Step's last own failure. Under the default
+intervals, a Step reaches an unavailable Kernel at most once a minute after its first minute: an hour
+of outage costs about 65 attempts and 260 journal entries, and none of its budget. Throw
+`retryAfter(ms, cause)` inside a Step to wait exactly `ms`, for instance on an HTTP `429` with
+`Retry-After`; that attempt spends the budget, since only the Step knows whether its cause clears.
 
 A run that fails outside any Step keeps the engine's pause. An input or receiver the code cannot
 read, an output the Schema refuses, a journal whose Steps the code no longer takes, or an error
 thrown between two Steps fails every attempt; after the deployment's `maxAttempts` the Execution is
-`paused` until `Execution.resume()` or `Execution.cancel()`. `resume` attempts the run again with
-the code served at its URL: it helps only once that code can replay the journal. A run that fails
-again before it awaits anything never sees a cooperative cancel; `cancel({ force: true })`, which
-the owner Domain holds, ends it without compensation.
+`paused` until `Execution.resume()` or `Execution.cancel()`. A deployment the engine cannot reach
+counts the same way, inside a Step or not, since its attempt of the run fails before any Workflow code
+runs: with the default intervals, the run pauses after about fourteen minutes. `resume` attempts the
+run again with the code served at its URL: it helps only once that code answers and can replay the
+journal. A cooperative `cancel` attempts the run again, under the same `maxAttempts`: a run that
+reaches an await sees the cancellation and may compensate (`cancelled(error)`); a run that fails again
+before it awaits anything pauses again, and the Kernel then ends it `cancelled`, without compensation.
+`cancel({ force: true })`, which the owner Domain holds, ends a run at once, without compensation.
 
 ## Redeployments
 
@@ -330,14 +354,17 @@ refuses a journal whose Steps no longer match, in order and by id, and pauses th
 same Steps continues the run. Renaming, reordering or removing a Step that runs have journaled is
 therefore an incompatible change in place, and no option of the Workflow declares it.
 
-**Keep the Schema additive while runs are in flight.** A Step calls the Kernel as installed when it calls,
-not when its run started: a Class, Function or Edge the run uses and a later install
-removed or narrowed refuses its calls until the Step spends its budget, with `STEP_EXHAUSTED`.
+**Keep the Schema additive while runs are in flight.** A Step calls the Kernel as installed when it
+calls, not when its run started: a Class, Function or Edge the run uses and a later install removed or
+narrowed refuses its calls, and the Step ends `STEP_EXHAUSTED`, at once when the Kernel can never
+accept the request, such as a callable whose fingerprint changed, otherwise once it spends its budget.
+The install itself only delays the Step, which waits out its maintenance without spending its budget.
 Remove them once the runs that use them have ended.
 
 **Do not retire a Release, or remove a durable callable, while runs are in flight.** A retired
 Release no longer answers its URL: its runs no longer progress, a signal to them times out, and a
-cooperative `cancel` leaves them `paused`; only `cancel({ force: true })` ends them. A durable
+cooperative `cancel` ends them `cancelled`, without compensation, once the engine has spent their
+attempts; `cancel({ force: true })` ends them at once. A durable
 callable a new install no longer declares has its runs cancelled by the Kernel, without
 compensation, within minutes.
 
@@ -387,7 +414,7 @@ loaded engine can still be supplied synchronously.
 | Option | Default |
 | --- | --- |
 | `retentionMs` | 7 days; at least the Host minimum (one day by default). |
-| `retry` | The budget of every Step that declares none: 20 attempts from 1 s to 60 s. `maxAttempts` also bounds a run failing outside any Step, which then pauses. The Host caps them. |
+| `retry` | The budget of every Step that declares none: 10 attempts from 1 s to 60 s, and no duration limit. `maxAttempts` also bounds a run failing outside any Step, which then pauses: 20 attempts when `retry` declares none. The Host caps them. |
 | `stepTimeoutMs` | 60 s per Step attempt that declares no `timeoutMs`, including its Kernel calls; ten minutes at most. |
 
 The provider receives the durable `Request`. Its route identifies the HTTPS Kernel whose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.6.0-beta.40",
+  "version": "0.6.0-beta.41",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",