@lostgradient/weft 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Weft
 
-A Bun-native durable execution engine. Current release: `0.3.0`.
+A Bun-native durable execution engine. Current release: `0.4.0`.
 
 Install the library from npm as `@lostgradient/weft`:
 
@@ -16,7 +16,7 @@ The CLI binaries remain unscoped: package installs place `weft` and `weft-mcp` o
 
 Imagine you're building an e-commerce checkout: charge the customer's credit card, reserve inventory, send a confirmation email, schedule shipping. What happens if your server crashes between step one and step two? The customer has been charged, but the inventory was never reserved. You can't just re-run the whole flow—you'd double-charge them.
 
-**Durable execution** solves this. You write a normal-looking function and the runtime guarantees it will complete—even if the process crashes and restarts a hundred times along the way. Each step is checkpointed so recovery picks up exactly where it stopped.
+**Durable execution** solves this. You write a normal-looking function around durable boundaries; with durable storage, Weft checkpoints those boundaries and automatically resumes persisted work after a process restart. The exact guarantee, including the current activity crash-window limit, is spelled out in [Durability Guarantee](documentation/architecture/durability-guarantee.md).
 
 Temporal is the most prominent durable execution engine, built in 2019 with Go, gRPC, and Cassandra. It works. But we can do better with modern tools.
 
@@ -56,6 +56,17 @@ The public path to 1.0 is tracked in the [roadmap to 1.0](documentation/roadmap-
 
 The browser surfaces graduate on a specific, mechanical criterion: the IndexedDB and WebExtension adapters and the Service Worker runtime stay experimental until their real-browser smoke tests are green in a **required** CI gate. The [browser-surface promotion gate](documentation/roadmap-to-1.0.md#browser-surface-promotion-gate) documents how the `browser-smoke` CI job flips from non-blocking to required, and why real-browser coverage — not fake-IndexedDB or stubbed-`chrome.storage` unit tests — is the evidence that moves them to stable.
 
+## Durability Guarantee
+
+Weft's durability promise is checkpoint-level and explicit:
+
+- Every `yield*` boundary is persisted before the workflow advances to the next durable step.
+- `Engine.create()` recovers by default after registering workflow definitions, so fresh processes resume persisted running workflows without a separate boot hook.
+- Recovery resumes from the last checkpoint position instead of replaying the workflow from the beginning.
+- External activity side effects still need idempotency keys, provider lookup, or verifier logic. Without that, a crash after the external side effect but before Weft commits the activity result can dispatch the activity again.
+
+The full [Durability Guarantee](documentation/architecture/durability-guarantee.md) separates what is guaranteed today from the Tier-0 activity-reconciliation work that narrows the remaining crash window.
+
 ## Hello, World
 
 The smallest useful Weft program has four moving pieces: a storage backend, a named activity, a named workflow, and a handle that waits for the result.
@@ -92,6 +103,8 @@ That's the core loop: `workflow({ name })` is a **chained builder** that co-loca
 
 `Engine.create()` does the registration dance for you: it constructs the engine and registers each workflow in the `workflows` map, pulling in all the activities each workflow declares. It then **recovers by default** — `engine.recoverAll()` runs after registration, so any workflows still running from a previous process pick up where they left off. That's the point of durable storage, so you don't have to ask for it. Pass `recover: false` to opt out (handy for tests, for `ScopedStorage`-isolated engines, or when you want to inspect a store before migrating it). Durability is separate: each step is persisted before it commits no matter what `recover` is set to — `recover` only decides whether _this_ engine resumes that persisted work on boot. Run a single engine per durable store; pointing two at the same store is not yet coordinated and can double-resume a workflow.
 
+Passing an explicitly empty workflow map is the same default-registry boot shape as omitting `workflows`: `Engine.create({ workflows: {} })` recovers after registration and returns an engine whose TypeScript type is compatible with default-registry consumers such as `serve({ engine })`. Use a non-empty `workflows` map when you want TypeScript to narrow `engine.start(...)` to the registered names.
+
 If you'd rather wire things up by hand — useful for tests, isolating engines onto separate storage scopes via `ScopedStorage`, or adding new workflows after the engine starts up — `new Engine({ storage })`, `engine.register(workflow)` or `engine.registerWorkflows({ ... })`, and `await engine.recoverAll()` are the underlying primitives. Each `engine.register(workflow)` call returns the engine with that workflow's name and types baked in, so `engine.start('welcome', ...)` autocompletes immediately.
 
 When a workflow needs a live host capability that cannot be checkpointed, pass it as per-run `services`:
@@ -123,7 +136,7 @@ Because recovery never re-executes the workflow from the beginning, your workflo
 | **Checkpoint**       | A serialized snapshot of a workflow's position and local variables, written at every yield.                                   |
 | **Signal**           | A fire-and-forget message sent _into_ a running workflow. Workflows pause at `ctx.waitForSignal()` until one arrives.         |
 | **Update**           | A request-response message sent into a running workflow. The caller blocks until the workflow returns a result.               |
-| **Query**            | A read-only peek at a running workflow's state. Never mutates anything.                                                       |
+| **Query**            | A read-only request sent with `engine.query()` or `handle.query()` to inspect workflow state without mutating it.             |
 | **Search attribute** | Indexed metadata on a workflow (customer ID, region, status) set via `ctx.setAttribute()` and queryable through the list API. |
 | **Worker**           | A process or thread that executes activities. Inline by default; can run remote over WebSocket.                               |
 | **Interceptor**      | A composable hook that wraps context operations for tracing, validation, encryption, or any cross-cutting concern.            |
@@ -134,7 +147,9 @@ Because recovery never re-executes the workflow from the beginning, your workflo
 
 ### Durable Workflows
 
-Generator functions with automatic checkpointing at every `yield*` boundary. Activities, sleeps, signals, queries, updates, parallel execution via `ctx.all()`, race semantics via `ctx.race()`, memoization via `ctx.memo()`, sagas via `ctx.saga()`, child workflows, and forks.
+Generator functions with automatic checkpointing at every `yield*` boundary. Activities, sleeps, signals, condition gates with `ctx.waitUntil()`, queries, updates, structured logs with `ctx.log`, parallel execution via `ctx.all()`, race semantics via `ctx.race()`, memoization via `ctx.memo()`, sagas via `ctx.saga()`, child workflows, and forks. `ctx.all()` and `ctx.race()` can branch over activities, sleeps, and signal waits; use `ctx.race([ctx.waitForSignal(name), ctx.sleep(timeout)])` for signal timeouts instead of placing an unbounded signal wait directly in `ctx.all()`.
+
+Every workflow context exposes `ctx.workflowId` and `ctx.workflowType`. `workflowType` is the registered name from `workflow({ name })`, so shared workflow code can log, tag, or branch on the current workflow type without closing over definition-site state.
 
 ```typescript
 const checkout = workflow({ name: 'checkout' })
@@ -180,9 +195,28 @@ const handle = await engine.start('approval', { orderId: 'order-123' });
 await engine.signal(handle.id, approvalSignal, { approved: true });
 ```
 
+For state that changes through synchronous updates, use `ctx.waitUntil(predicate, timeout?)` as a durable condition gate. It re-checks a pure predicate when `ctx.onUpdate()` handlers mutate workflow-local state, or when the optional timeout fires. It is inline-only because the predicate closure stays in the engine process; signals do not re-drive it because signals are pull-based messages consumed by `ctx.waitForSignal()`.
+
+```typescript partial
+const quorum = workflow({ name: 'quorum' })
+  .updates({
+    vote: update<void, number>('vote'),
+  })
+  .execute(async function* (ctx) {
+    let votes = 0;
+    ctx.onUpdate('vote', () => {
+      votes += 1;
+      return votes;
+    });
+
+    const reached = yield* ctx.waitUntil(() => votes >= 3, '1h');
+    return reached ? 'accepted' : 'expired';
+  });
+```
+
 ### Live Workflow Events
 
-Workflow handles expose lifecycle events through `addEventListener`, and client handles can open a live tail for progress UIs or operators. `LocalClient` reads from the in-process engine stream; `HttpClient` uses the per-workflow `/v1/workflows/:id/watch` WebSocket channel with history catch-up on connect and reconnect, so `addEventListener`, `client.tail(id)`, and `handle.tail()` are push-based rather than a polling loop.
+Workflow handles expose lifecycle events through `addEventListener`, and client handles can open a live tail for progress UIs or operators. `LocalClient` reads from the in-process engine stream; `HttpClient` uses the per-workflow `/v1/workflows/:id/watch` WebSocket channel with history catch-up on connect and reconnect, so `addEventListener`, `client.tail(id)`, and `handle.tail()` are push-based rather than a polling loop. JSON-RPC clients can subscribe over WebSocket with `weft.workflows.subscribe` for one workflow or `weft.events.subscribe` for the fleet-wide event feed. Client code that receives a workflow id from another process can call `client.getHandle(id)` to re-attach a `ClientHandle` or get `null` when the run does not exist.
 
 ```typescript
 const handle = await client.start('checkout', order);
@@ -199,15 +233,17 @@ The tail is single-consumer and stops on terminal workflow events or `tail.close
 
 ### Idempotent Starts and Signal-With-Start
 
-Retried webhooks and queue deliveries should not double-start workflows. Pass a stable `idempotencyKey` to `engine.start()` to make every retry return a handle for the same run. Use `engine.startOrSignal()` when the first event should create the workflow and later events should signal the existing non-terminal run.
+Retried webhooks and queue deliveries should not double-start workflows. Pass a stable `idempotencyKey` to `engine.start()` to make every retry return a handle for the same run. Use `engine.startOrSignal()` when the first event should create the workflow and later events should signal the existing non-terminal run. The call returns `{ handle, outcome }`, where `outcome` is `'started'` for the caller that created the run and `'signalled'` for callers that delivered to, or converged onto, an existing run.
 
 ```typescript
-const handle = await engine.startOrSignal(
+const { handle, outcome } = await engine.startOrSignal(
   'approval',
   { orderId: 'order-123' },
   { name: 'payment', payload: { status: 'succeeded' } },
   { idempotencyKey: 'payment-webhook-order-123' },
 );
+
+console.log(handle.id, outcome); // outcome is 'started' or 'signalled'
 ```
 
 The idempotency mapping intentionally outlives terminal cleanup. If retention removes the workflow record, the key is spent and future calls return a conflict instead of starting a replacement.
@@ -239,10 +275,14 @@ const orders = await engine.list({
 
 Workflow visibility extends the same list surface with operator filters for `idPrefix`, failure categories, created/updated/deadline ranges, and status arrays. Use `engine.aggregate()` or `GET /api/v1/workflows/aggregate` for grouped counts by status, type, failure category, or a search attribute. Existing Bun SQLite deployments should run the [workflow visibility backfill](documentation/guides/workflow-visibility-backfill.md) before relying on the indexed fast path for older workflows.
 
+Failure-category filters use the current execution taxonomy only: `application`, `timeout`, `cancellation`, `resource`, and `system`. Older category names from pre-1.0 experiments are dropped during decode and are not expanded in list or aggregate filters.
+
 ### Human-in-the-Loop Review
 
 Weft can pause a workflow at any checkpoint and surface a decision payload to a human reviewer. The workflow resumes with the reviewer's decision—no polling, no special infrastructure.
 
+As of June 12, 2026, [Temporal's public human-approval example](https://docs.temporal.io/ai-cookbook/human-in-the-loop-python) models approval with Signals, and [Inngest's TypeScript docs](https://www.inngest.com/docs/reference/typescript/v4/functions/step-wait-for-event) model approval waits with `step.waitForEvent()`. Weft makes the review itself a durable workflow operation: [`ctx.review()`](src/core/context/durable-operations.ts) creates a stored review request, exposes review list/get/decision APIs, emits review events, and resumes the workflow with the submitted decision.
+
 ```typescript
 import { Engine, workflow } from '@lostgradient/weft';
 import { SQLiteStorage } from '@lostgradient/weft/storage/sqlite';
@@ -280,7 +320,7 @@ const paymentWorkflow = workflow({ name: 'payment' })
   });
 ```
 
-If the process crashes between the approval decision arriving and `chargeCard` executing, the engine resumes from the last checkpoint—the charge runs exactly once. The reviewer's decision is persisted as part of the checkpoint; there is no resubmission.
+If the process crashes after the approval decision is checkpointed, the reviewer is not asked again. The `chargeCard` activity is still an at-least-once side effect: if the payment provider accepts the charge and the process crashes before Weft commits the activity result, recovery can run `chargeCard` again. Pass an idempotency key, provider transaction lookup, or equivalent verifier to the payment provider; the [activities guide](documentation/guides/activities.md#per-call-options) explains that boundary in more detail.
 
 ### Pluggable Storage
 
@@ -320,7 +360,7 @@ await using server = serve({ engine, port: 7233 });
 // server.url is e.g. "http://0.0.0.0:7233"
 ```
 
-Endpoints under `/api/v1/` cover the full lifecycle: start workflows, list, signal, update, query, cancel, fork, and stream events. Content negotiation supports JSON and MessagePack. The server can also mount an externally supplied dashboard shell at known page routes; see the [server guide](documentation/guides/server.md#external-dashboard-mounting) for the hosting contract.
+Endpoints under `/api/v1/` cover the full lifecycle: start workflows, list, signal, update, query, cancel, fork, and stream events. JSON-RPC over WebSocket also exposes workflow and fleet event subscriptions for operator UIs that need live state without polling. Content negotiation supports JSON and MessagePack. The server can also mount an externally supplied dashboard shell at known page routes; see the [server guide](documentation/guides/server.md#external-dashboard-mounting) for the hosting contract.
 
 ### Remote Workers
 
@@ -350,6 +390,8 @@ The core engine runs inside a Web Worker, with a Service Worker acting as the du
 
 Built-in event system (`EventTarget`-based, so it composes with everything), W3C `traceparent` propagation, and OpenTelemetry-compatible metrics. Composable interceptors layer cross-cutting concerns—tracing, validation, encryption—without any of them knowing about each other.
 
+Schedules also emit `schedule:fired` on the live engine each time a schedule actually launches a workflow run. The event carries `scheduleId`, `workflowId`, `firedAt`, and the scheduled `occurrence` when one is retained, so in-process dispatchers can react to cadence without polling schedule state.
+
 ```typescript
 import { createObservabilityInterceptors, createOpenTelemetryMetrics } from '@lostgradient/weft';
 
@@ -364,6 +406,8 @@ const engine = new Engine({
 });
 ```
 
+Inside workflow code, `ctx.log` emits structured console records with `workflowId`, `workflowType`, `level`, and `timestamp` attached. Caller attributes are nested under `attributes`, so they cannot overwrite the envelope. Logs at already-restored checkpoint positions are suppressed on recovery; logs at the live frontier still emit, and in worker mode the destination is the worker process console.
+
 ### Testing
 
 `TestEngine` swaps the production engine in tests and gives you a virtual clock. `engine.advanceTime('1 hour')` jumps timers forward without waiting; `engine.mock(activity, fake)` swaps in fake activity implementations with type-checked signatures, call recording, and per-call overrides.
@@ -428,6 +472,16 @@ function isAlreadyRunning(error: unknown): boolean {
 }
 ```
 
+When the same producer might run through either `LocalClient` or `HttpClient`, use `isWeftFault(error, code)` for a specific branch. It matches same-process `WeftError` instances and HTTP-wrapped errors whose REST response carried the originating public `weftCode`.
+
+```typescript
+import { isWeftFault } from '@lostgradient/weft';
+
+function isMissingWorkflow(error: unknown): boolean {
+  return isWeftFault(error, 'WorkflowNotFoundError');
+}
+```
+
 The exported `WeftErrorCode` union lists every code that belongs to a public, exported error class; those codes are stable contract and safe to `switch` on exhaustively. Errors that are internal to Weft also extend `WeftError` but carry codes intentionally left out of `WeftErrorCode` — `isWeftErrorCode` and `isWeftErrorLike` return `false` for them — so internal codes may change between releases without breaking your types.
 
 ## Installation
@@ -466,21 +520,22 @@ const welcome = workflow({ name: 'welcome' }).execute(
 engine.register(welcome);
 ```
 
-Each `ctx.step()` is a checkpoint boundary. The engine compiles step-style workflows to generator form at registration time. When you need durable timers, signals, or parallel execution, switch to the generator API.
+Each `ctx.step()` is a checkpoint boundary. Completed steps replay from storage after crash recovery instead of re-running, and `compileStepWorkflow(...)` compiles the step-style function into the generator form the engine runs internally. Await each step before starting the next. When you need durable timers, signals, parallel execution, or worker-mode isolation, switch to the generator API.
 
 ## Weft vs. Temporal
 
-| Concept                | Temporal                                      | Weft                                                                       |
-| ---------------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
-| Core mental model      | Replay determinism                            | Generators pause and resume                                                |
-| Workflow language      | Go, Java, TypeScript, Python, .NET, Ruby, PHP | TypeScript only (activities can be any language via `RemoteWorker`)        |
-| Activity invocation    | `proxyActivities()` + type import             | `yield* ctx.run('activityName', input)` (declared in `.activities({...})`) |
-| Timer                  | Deterministic `workflow.sleep()`              | `yield* ctx.sleep("1 hour")`                                               |
-| Signal                 | `setHandler` + `condition`                    | `yield* ctx.waitForSignal(name)`                                           |
-| Versioning             | `patched()` / `deprecatePatch()`              | Deploy new code (migration optional)                                       |
-| Long-running workflows | `continueAsNew()`                             | None needed (checkpoint size is bounded by live state, not history length) |
-| Dev environment        | Docker Compose + Temporal server              | `bun add @lostgradient/weft`                                               |
-| Bundling               | Webpack for workflow sandbox                  | None                                                                       |
+| Concept                | Temporal                                                                                                                       | Weft                                                                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| Core mental model      | Replay determinism                                                                                                             | Generators pause and resume                                                                        |
+| Workflow language      | Go, Java, TypeScript, Python, .NET, Ruby, PHP                                                                                  | TypeScript only (activities can be any language via `RemoteWorker`)                                |
+| Activity invocation    | `proxyActivities()` + type import                                                                                              | `yield* ctx.run('activityName', input)` (declared in `.activities({...})`)                         |
+| Timer                  | Deterministic `workflow.sleep()`                                                                                               | `yield* ctx.sleep("1 hour")`                                                                       |
+| Signal                 | `setHandler` + `condition`                                                                                                     | `yield* ctx.waitForSignal(name)`                                                                   |
+| Human review           | Signals/queries/updates as [message-passing primitives](https://docs.temporal.io/develop/typescript/workflows/message-passing) | `yield* ctx.review(...)` with [durable review request](src/core/review/index.ts) and decision APIs |
+| Versioning             | `patched()` / `deprecatePatch()`                                                                                               | Stored and registered versions are strict recovery guards                                          |
+| Long-running workflows | `continueAsNew()`                                                                                                              | None needed (checkpoint size is bounded by live state, not history length)                         |
+| Dev environment        | Docker Compose + Temporal server                                                                                               | `bun add @lostgradient/weft`                                                                       |
+| Bundling               | Webpack for workflow sandbox                                                                                                   | None                                                                                               |
 
 > Weft is for teams whose primary backend language is TypeScript. If you need workflows in multiple languages, [Temporal](https://temporal.io) is the right answer. For the design rationale, see [ADR 0001 — Workflows Are TypeScript-Only by Design](documentation/contributing/architecture-decisions/0001-workflows-typescript-only.md).
 >
@@ -505,9 +560,9 @@ Guides:
 
 Architecture and reference:
 
-- [Design Philosophy](documentation/architecture/design-philosophy.md), [Checkpoint vs. Replay](documentation/architecture/checkpoint-versus-replay.md), [Web Standards](documentation/architecture/web-standards.md)
-- [Browser Runtime](documentation/architecture/browser-runtime.md), [Web Workers](documentation/architecture/web-workers.md), [Single Binary](documentation/architecture/single-binary.md)
-- [API Reference](documentation/reference/) (Engine, Context, Storage, Server, Workers, Testing, Events, Interceptors, Observability, CLI, Configuration, Types)
+- [Design Philosophy](documentation/architecture/design-philosophy.md), [Durability Guarantee](documentation/architecture/durability-guarantee.md), [Checkpoint vs. Replay](documentation/architecture/checkpoint-versus-replay.md), [Web Standards](documentation/architecture/web-standards.md)
+- [Temporal Comparison](documentation/architecture/temporal-comparison.md), [Inngest Comparison](documentation/architecture/inngest-comparison.md), [Browser Runtime](documentation/architecture/browser-runtime.md), [Web Workers](documentation/architecture/web-workers.md), [Single Binary](documentation/architecture/single-binary.md)
+- [API Reference](documentation/reference/) (Engine, Context, Storage, Server, Workers, Testing, Events, Errors, Interceptors, Observability, CLI, Configuration, Types)
 
 Contributing:
 

package/dist/cli/conformance.js

@@ -139,7 +139,13 @@ async function dispatchAndWait(server, storage, operationId, activityName, input
   await waitForResolvedStatus(storage, operationId, expectedStatus, timeoutMs);
 }
 async function runConformanceChecks(command, timeoutMs) {
-  const storage = new MemoryStorage, engine = new Engine({ storage }), server = serve({ engine, port: 0, hostname: "127.0.0.1" }), checks = [];
+  const storage = new MemoryStorage, engine = new Engine({ storage }), server = serve({
+    engine,
+    port: 0,
+    hostname: "127.0.0.1",
+    workerReconnectGracePeriodMs: 100,
+    workerShutdownTimeoutMs: timeoutMs
+  }), checks = [];
   let worker;
   try {
     worker = startWorker(command, server);

package/dist/cli/generated/operation-client.generated.d.ts

@@ -1,8 +1,9 @@
 import { type CatalogWeftClient, type WeftClientConnection } from '../operation-client-runtime.ts';
-export declare const CATALOG_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.system.metrics", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.drain", "weft.workers.list", "weft.workers.resume", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
+export declare const CATALOG_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.system.metrics", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.drain", "weft.workers.list", "weft.workers.resume", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
 export type CatalogOperationName = (typeof CATALOG_OPERATION_NAMES)[number];
-type SharedAttributesConfirmationTo_f933f774 = {
+type SharedAttributesBulkConcurrenc_73ecbca6 = {
     readonly attributes?: ReadonlyArray<SharedGtGteKey_896a0c41>;
+    readonly bulkConcurrency?: number;
     readonly confirmationToken?: string;
     readonly createdAt?: SharedGtGteLt_d9a61361;
     readonly dryRun?: boolean;
@@ -104,7 +105,7 @@ export type CatalogOperationTypes = {
     'weft.reviews.list': {
         readonly input: {
             readonly reviewType?: string;
-            readonly status?: string;
+            readonly status?: 'pending' | 'completed';
             readonly workflowId?: string;
         };
         readonly output: {
@@ -126,6 +127,7 @@ export type CatalogOperationTypes = {
             readonly every?: unknown;
             readonly id?: unknown;
             readonly input?: unknown;
+            readonly jitter?: unknown;
             readonly overlap?: unknown;
             readonly type: unknown;
         };
@@ -198,7 +200,7 @@ export type CatalogOperationTypes = {
                 readonly oldestEnqueuedAt: unknown;
                 readonly oldestQueuedAgeMs: unknown;
                 readonly queue: string;
-                readonly schedulingPolicy: string;
+                readonly schedulingPolicy: 'priority' | 'fifo' | 'lifo';
                 readonly waitingPollers: number;
             }>;
         };
@@ -217,24 +219,29 @@ export type CatalogOperationTypes = {
         readonly output: {
             readonly items: ReadonlyArray<{
                 readonly activityName?: string;
+                readonly deadLetterReason?: string;
+                readonly deadLetteredAt?: number;
                 readonly evidence: ReadonlyArray<string>;
                 readonly executionLatencyMs?: number;
                 readonly heartbeatAgeMs?: number;
-                readonly kind: string;
-                readonly lastRequeueReason?: string;
+                readonly kind: 'stuck-queued' | 'stale-inflight' | 'retry-storm' | 'all-workers-at-capacity' | 'dead-lettered';
+                readonly lastRequeueReason?: 'visibility-timeout' | 'worker-disconnect';
                 readonly operationId?: string;
                 readonly queue?: string;
                 readonly queueLatencyMs?: number;
                 readonly requeueCount: number;
                 readonly resolutionReason?: string;
+                readonly retryAttempts?: number;
                 readonly retryCount: number;
-                readonly state: string;
+                readonly state: 'queued' | 'inflight' | 'resolved' | 'capacity' | 'dead-lettered';
+                readonly storageError?: string;
                 readonly workerId?: string;
                 readonly workflowId?: string;
             }>;
             readonly limit: number;
             readonly summary: {
                 readonly allWorkersAtCapacity: number;
+                readonly deadLettered: number;
                 readonly retryStorms: number;
                 readonly staleInflight: number;
                 readonly stuckQueued: number;
@@ -282,7 +289,7 @@ export type CatalogOperationTypes = {
                 readonly drainedWorkers: number;
                 readonly drainingWorkers: number;
                 readonly gitSha: unknown;
-                readonly health: string;
+                readonly health: 'active' | 'draining' | 'drained';
                 readonly inFlight: number;
                 readonly oldestStartedAt: unknown;
                 readonly runtimeVersion: unknown;
@@ -297,7 +304,7 @@ export type CatalogOperationTypes = {
                 readonly connectedAt: number;
                 readonly deploymentName?: string;
                 readonly gitSha?: string;
-                readonly health: string;
+                readonly health: 'active' | 'draining' | 'drained';
                 readonly heartbeatAgeMs: number;
                 readonly id: string;
                 readonly inFlight: number;
@@ -306,7 +313,7 @@ export type CatalogOperationTypes = {
                 readonly runtimeVersion?: string;
                 readonly startedAt: number;
             }>;
-            readonly routingPolicy: string;
+            readonly routingPolicy: 'least-loaded' | 'round-robin' | 'fair-share';
         };
         readonly faults: never;
     };
@@ -366,18 +373,24 @@ export type CatalogOperationTypes = {
         readonly faults: never;
     };
     'weft.workflows.bulk.cancel': {
-        readonly input: SharedAttributesConfirmationTo_f933f774;
+        readonly input: SharedAttributesBulkConcurrenc_73ecbca6;
         readonly output: unknown;
         readonly faults: never;
     };
     'weft.workflows.bulk.delete': {
-        readonly input: SharedAttributesConfirmationTo_f933f774;
+        readonly input: SharedAttributesBulkConcurrenc_73ecbca6;
         readonly output: unknown;
         readonly faults: 'Unprocessable';
     };
+    'weft.workflows.bulk.retryfailed': {
+        readonly input: SharedAttributesBulkConcurrenc_73ecbca6;
+        readonly output: unknown;
+        readonly faults: never;
+    };
     'weft.workflows.bulk.signal': {
         readonly input: {
             readonly attributes?: ReadonlyArray<SharedGtGteKey_896a0c41>;
+            readonly bulkConcurrency?: number;
             readonly confirmationToken?: string;
             readonly createdAt?: SharedGtGteLt_d9a61361;
             readonly dryRun?: boolean;
@@ -399,10 +412,11 @@ export type CatalogOperationTypes = {
     };
     'weft.workflows.bulk.tags': {
         readonly input: {
+            readonly bulkConcurrency?: number;
             readonly confirmationToken?: string;
             readonly dryRun?: boolean;
             readonly filter?: SharedAttributesCreatedAtExecu_c9ba5dc6;
-            readonly operation: string;
+            readonly operation: 'add' | 'remove';
             readonly requestId?: string;
             readonly tags: ReadonlyArray<string>;
         };
@@ -557,6 +571,7 @@ export type CatalogOperationTypes = {
         };
         readonly output: {
             readonly id: string;
+            readonly outcome: 'started' | 'signalled';
         };
         readonly faults: 'Conflict';
     };

package/dist/cli/generated/operation-client.generated.js

@@ -32,6 +32,7 @@ export const CATALOG_OPERATION_NAMES = [
   "weft.workflows.attributes.set",
   "weft.workflows.bulk.cancel",
   "weft.workflows.bulk.delete",
+  "weft.workflows.bulk.retryfailed",
   "weft.workflows.bulk.signal",
   "weft.workflows.bulk.tags",
   "weft.workflows.cancel",

package/dist/cli/help-text.d.ts

@@ -4,7 +4,7 @@ export declare const CONFORMANCE_HELP_TEXT = "\nweft conformance - Run RemoteWor
 export declare const DOCTOR_HELP_TEXT = "\nweft doctor - Run diagnostics on the Weft database\n\nUsage: weft doctor [options]\n\nOptions:\n  -d, --database <path>   Database file path (default: ./weft.db)\n  -j, --json              Output results as JSON\n  -h, --help              Show this help message\n";
 export declare const VERSION_CHECK_HELP_TEXT = "\nweft version:check - Check workflow version compatibility\n\nUsage: weft version:check [options]\n\nOptions:\n  -d, --database <path>     Database file path (default: ./weft.db)\n  -w, --workflows <path>    Path to workflows module\n  -j, --json                Output results as JSON\n  -h, --help                Show this help message\n";
 export declare const TIMELINE_HELP_TEXT = "\nweft timeline - Inspect workflow timeline and replay history\n\nUsage:\n  weft timeline <workflowId> [options]\n  weft timeline <workflowId> --diff <fromStep> <toStep> [options]\n\nOptions:\n  -d, --database <path>     Database file path (default: ./weft.db)\n      --step <step>         Show replay details for one checkpoint step\n      --diff                Diff two checkpoint steps (requires two positional step numbers)\n  -h, --help                Show this help message\n";
-export declare const SCHEDULE_HELP_TEXT = "\nweft schedule - Manage recurring schedules\n\nUsage:\n  weft schedule list [options]\n  weft schedule create <workflowType> <cronExpression> [options]\n  weft schedule create <workflowType> --every <duration> [options]\n  weft schedule pause <scheduleId> [options]\n  weft schedule resume <scheduleId> [options]\n  weft schedule cancel <scheduleId> [options]\n\nProvide a cron expression positional OR an --every interval (e.g. \"30s\", \"1h\"),\nbut not both. Interval schedules fire one period after creation, then every\nperiod after that.\n\nOptions:\n  -d, --database <path>     Database file path (default: ./weft.db)\n  -s, --storage <backend>   Storage backend: sqlite, lmdb (default: sqlite)\n  -w, --workflows <path>    Path to workflow registrations module (required for create)\n      --every <duration>    Interval cadence for create (e.g. 30s, 5m, 1h); mutually exclusive with the cron positional\n      --input <json>        JSON input payload for create (default: null)\n      --id <id>             Custom schedule id for create\n      --overlap <policy>    Overlap policy: skip, queue, cancel-running, allow\n      --backfill            Run missed ticks on recovery\n  -j, --json                Output results as JSON\n  -h, --help                Show this help message\n";
+export declare const SCHEDULE_HELP_TEXT = "\nweft schedule - Manage recurring schedules\n\nUsage:\n  weft schedule list [options]\n  weft schedule create <workflowType> <cronExpression> [options]\n  weft schedule create <workflowType> --every <duration> [options]\n  weft schedule pause <scheduleId> [options]\n  weft schedule resume <scheduleId> [options]\n  weft schedule cancel <scheduleId> [options]\n\nProvide a cron expression positional OR an --every interval (e.g. \"30s\", \"1h\"),\nbut not both. Interval schedules fire one period after creation, then every\nperiod after that.\n\nOptions:\n  -d, --database <path>     Database file path (default: ./weft.db)\n  -s, --storage <backend>   Storage backend: sqlite, lmdb (default: sqlite)\n  -w, --workflows <path>    Path to workflow registrations module (required for create)\n      --every <duration>    Interval cadence for create (e.g. 30s, 5m, 1h); mutually exclusive with the cron positional\n      --input <json>        JSON input payload for create (default: null)\n      --id <id>             Custom schedule id for create\n      --overlap <policy>    Overlap policy: skip, queue, cancel-running, allow\n      --backfill            Run missed ticks on recovery\n      --jitter <duration>   Deterministic dispatch jitter for create (e.g. 30s, 5m)\n  -j, --json                Output results as JSON\n  -h, --help                Show this help message\n";
 export declare const VALIDATE_HELP_TEXT = "\nweft validate - Lint workflow registrations for design-time anti-patterns\n\nUsage: weft validate <entry.ts>... [options]\n\nArguments:\n  <entry.ts>...           One or more TypeScript modules or glob patterns that\n                          resolve to workflow registrations and/or activity\n                          definitions.\n\nOptions:\n  -j, --json              Output results as JSON\n  -h, --help              Show this help message\n\nExit codes:\n  0   No errors (warnings may be present)\n  1   One or more errors detected\n  2   Entry file could not be loaded (takes precedence over validation errors)\n\nJSON output:\n  { entries, valid, hasLoadErrors, hasValidationErrors }\n\nChecks performed:\n  unbounded-retry               Activity retry.maxAttempts is Infinity\n  stateful-without-compensator  Non-idempotent activity has no compensate fn\n";
 export declare const SERVER_HELP_TEXT = "\nweft server - Inspect a running server's health and operation surface\n\nUsage:\n  weft server health [options]\n  weft server info [options]\n\nOptions:\n      --server <url>       Server URL (default: WEFT_ADDR, profile, run lockfile, or localhost)\n      --token <token>      Bearer token (default: WEFT_TOKEN)\n      --profile <name>     Profile from ~/.weft/config\n      --wait               (health) Poll until the server is reachable\n      --wait-timeout <ms>  (health) Maximum time to wait, in milliseconds (default: 30000)\n  -j, --json               Emit machine-readable JSON output\n  -q, --quiet              Suppress success/error text (use the exit code)\n  -h, --help               Show this help message\n\nExit codes:\n  0   Healthy\n  1   Unreachable / unhealthy\n  2   Connection error\n";
 export declare const WORKFLOW_HELP_TEXT = "\nweft workflow - List, inspect, start, signal, and cancel workflows on a server\n\nUsage:\n  weft workflow ls [--type <type>] [--status <status>] [--limit <n>] [options]\n  weft workflow get <workflow-id> [options]\n  weft workflow events <workflow-id> [options]\n  weft workflow start <workflow-type> [--input <json> | --input-file <path|->] [--id <id>] [options]\n  weft workflow cancel <workflow-id> [--yes] [--dry-run] [options]\n  weft workflow signal <workflow-id> <signal-name> [--input <json> | --input-file <path|->] [options]\n\nOptions:\n      --server <url>       Server URL (default: WEFT_ADDR, profile, run lockfile, or localhost)\n      --token <token>      Bearer token (default: WEFT_TOKEN)\n      --profile <name>     Profile from ~/.weft/config\n      --type <type>        (ls) Filter by workflow type\n      --status <status>    (ls) Filter by workflow status\n      --limit <n>          (ls) Maximum number of rows\n      --input <json>       (start/signal) JSON input payload\n      --input-file <path>  (start/signal) Read JSON input from a file, or '-' for stdin\n      --id <id>            (start) Explicit workflow id\n  -y, --yes                (cancel) Confirm without prompting\n      --dry-run            (cancel) Print affected count without cancelling\n  -j, --json               Emit machine-readable output (NDJSON for lists)\n  -q, --quiet              Print ids only / suppress success text\n  -h, --help               Show this help message\n\nExit codes:\n  0   Success\n  1   Operation failed or destructive operation was not confirmed\n  2   Connection error\n  3   Usage or input error\n  4   Operation unavailable on this server (version skew)\n";

package/dist/cli/help-text.js

@@ -123,6 +123,7 @@ Options:
       --id <id>             Custom schedule id for create
       --overlap <policy>    Overlap policy: skip, queue, cancel-running, allow
       --backfill            Run missed ticks on recovery
+      --jitter <duration>   Deterministic dispatch jitter for create (e.g. 30s, 5m)
   -j, --json                Output results as JSON
   -h, --help                Show this help message
 `, VALIDATE_HELP_TEXT = `

package/dist/cli/operation-catalog-snapshot.d.ts

@@ -23,6 +23,14 @@ export type CatalogOperationSnapshot = {
     readonly tags: ReadonlyArray<string>;
     readonly destructive: boolean;
     readonly access: CatalogAccessSnapshot;
+    readonly parameterizedAccess?: {
+        readonly discriminator: string;
+        readonly defaultValue?: string;
+        readonly variants: ReadonlyArray<{
+            readonly value: string;
+            readonly access: CatalogAccessSnapshot;
+        }>;
+    };
     readonly transports: TransportAvailability;
     readonly producibleFaults: ReadonlyArray<FaultCode>;
     readonly inputSchema: Record<string, unknown>;

package/dist/cli/operation-catalog-snapshot.js

@@ -22,6 +22,7 @@ function operationToSnapshot(operation) {
     tags: [...operation.tags].toSorted(compareStrings),
     destructive: operation.destructive ?? !1,
     access: accessToSnapshot(operation.access),
+    ...operation.parameterizedAccess === void 0 ? {} : { parameterizedAccess: parameterizedAccessToSnapshot(operation.parameterizedAccess) },
     transports: { ...operation.transports },
     producibleFaults: [...operation.producibleFaults ?? []].toSorted(compareStrings),
     inputSchema: normalizeJsonObject(definitionSchemaToJsonSchema(operation.inputSchema, "input")),
@@ -29,6 +30,16 @@ function operationToSnapshot(operation) {
     ...eventSchema === void 0 ? {} : { eventSchema: normalizeJsonObject(definitionSchemaToJsonSchema(eventSchema, "output")) }
   };
 }
+function parameterizedAccessToSnapshot(hint) {
+  return {
+    discriminator: hint.discriminator,
+    ...hint.defaultValue === void 0 ? {} : { defaultValue: hint.defaultValue },
+    variants: hint.variants.map((variant) => ({
+      value: variant.value,
+      access: accessToSnapshot(variant.access)
+    })).toSorted((left, right) => compareStrings(left.value, right.value))
+  };
+}
 function accessToSnapshot(access) {
   if (access.kind === "public")
     return { kind: "public" };

package/dist/cli/parse-schedule-arguments.js

@@ -13,6 +13,7 @@ function parseScheduleCliValues(args) {
       id: { type: "string" },
       overlap: { type: "string" },
       backfill: { type: "boolean", default: !1 },
+      jitter: { type: "string" },
       help: { type: "boolean", short: "h", default: !1 },
       json: { type: "boolean", short: "j", default: !1 }
     },
@@ -79,7 +80,8 @@ function buildScheduleCreateOptionalFields(values) {
   const overlap = parseScheduleOverlapPolicy(values.overlap);
   return {
     ...values.id !== void 0 ? { id: values.id } : {},
-    ...overlap !== void 0 ? { overlap } : {}
+    ...overlap !== void 0 ? { overlap } : {},
+    ...values.jitter !== void 0 ? { jitter: values.jitter } : {}
   };
 }
 function buildScheduleCreateCommand(values, positionals) {

package/dist/cli/schedule.js

@@ -67,7 +67,8 @@ async function executeScheduleCreate(options, engine, loadRegistrationsFromModul
   const spec = options.every !== void 0 ? { every: options.every } : options.cronExpression, handle = await engine.schedule(options.workflowType, parsedInput.value, spec, {
     ...options.id !== void 0 ? { id: options.id } : {},
     ...options.overlap !== void 0 ? { overlap: options.overlap } : {},
-    ...options.backfill ? { backfill: !0 } : {}
+    ...options.backfill ? { backfill: !0 } : {},
+    ...options.jitter !== void 0 ? { jitter: options.jitter } : {}
   }), schedule = await handle.describe();
   return {
     stdout: formatScheduleCommandOutput(schedule, options.json, `Created schedule ${handle.id}`),

package/dist/cli/types.d.ts

@@ -84,6 +84,7 @@ export type CliCommand = {
     id?: string;
     overlap?: ScheduleOverlapPolicy;
     backfill: boolean;
+    jitter?: string;
     help: boolean;
     json: boolean;
 } | {