@lostgradient/weft 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Weft
 
-A Bun-native durable execution engine. Current launch version: `0.2.0`.
+A Bun-native durable execution engine. Current release: `0.3.0`.
 
 Install the library from npm as `@lostgradient/weft`:
 
@@ -43,12 +43,12 @@ Weft is a ground-up rethink: what would durable execution look like if you desig
 
 ## Stability Tiers
 
-Weft is launching as `0.2.0`, not `1.0`. The table below is the current adoption guidance, not a permanent compatibility guarantee. Surfaces marked **candidate-stable** are expected to carry the 1.0 support promise if the [Tier-0 Behavioral Contract](documentation/architecture/tier-0-behavioral-contract.md) does not force a public-shape change. Tier-0 work may still add error codes, duplicate-response shapes, or storage-capability failures before those surfaces graduate.
+Weft is still pre-1.0. The table below is the current adoption guidance, not a permanent compatibility guarantee. Surfaces marked **candidate-stable** are expected to carry the 1.0 support promise if the [Tier-0 Behavioral Contract](documentation/architecture/tier-0-behavioral-contract.md) does not force a public-shape change. Tier-0 work may still add error codes, duplicate-response shapes, or storage-capability failures before those surfaces graduate.
 
-| Tier                          | Surfaces                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | What to expect                                                                                                             |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Candidate-stable, provisional | Engine core, [`TestEngine`](documentation/guides/testing.md), Bun SQLite, Node SQLite, LMDB, [`RemoteWorker`](documentation/guides/remote-workers.md), [`serve()`](documentation/guides/server.md) and `/v1` REST, exported public error codes                                                                                                                                                                                                                                                                    | Suitable for serious trials. Pin the package version and read release notes before upgrading until the 1.0 contract lands. |
-| Experimental                  | [Browser runtime](documentation/guides/service-worker.md), [MCP](documentation/reference/api-server.md#mcp-server), IndexedDB, WebExtension, HTTP and compressed storage, Turso pending conformance proof, CLI commands beyond `serve` and `doctor` when running Weft from source or a standalone binary, [OpenTelemetry](documentation/guides/observability.md) metric names, externally supplied dashboard mounting, [`ctx.step()`](documentation/guides/workflows.md#getting-started-without-generators) sugar | API shape, storage guarantees, diagnostics, or compatibility behavior may change without a deprecation window before 1.0.  |
+| Tier                          | Surfaces                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | What to expect                                                                                                             |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| Candidate-stable, provisional | Engine core, [`TestEngine`](documentation/guides/testing.md), Bun SQLite, Node SQLite, LMDB, [`RemoteWorker`](documentation/guides/remote-workers.md), [`serve()`](documentation/guides/server.md) and `/v1` REST, source/binary CLI commands `serve`, `doctor`, `version`, `--version`, and `-v`, exported public error codes                                                                                                                                                                                                                   | Suitable for serious trials. Pin the package version and read release notes before upgrading until the 1.0 contract lands. |
+| Experimental                  | [Browser runtime](documentation/guides/service-worker.md), [MCP](documentation/reference/api-server.md#mcp-server), IndexedDB, WebExtension, HTTP and compressed storage, Turso pending conformance proof, CLI commands beyond `serve`, `doctor`, `version`, `--version`, and `-v` when running Weft from source or a standalone binary, [OpenTelemetry](documentation/guides/observability.md) metric names, externally supplied dashboard mounting, [`ctx.step()`](documentation/guides/workflows.md#getting-started-without-generators) sugar | API shape, storage guarantees, diagnostics, or compatibility behavior may change without a deprecation window before 1.0.  |
 
 If a surface is not named here, treat it as experimental. Stability is about compatibility and operational guarantees; it is not a statement that every candidate-stable surface is appropriate for every deployment.
 
@@ -94,6 +94,14 @@ That's the core loop: `workflow({ name })` is a **chained builder** that co-loca
 
 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`:
+
+```typescript
+const handle = await engine.start('welcome', { name: 'Steve' }, { services: { crmClient } });
+```
+
+Inside inline workflows, read that value from `ctx.services` and narrow it to your application type. Weft never writes the service object into checkpoints; it persists only a presence marker so `Engine.create({ resolveWorkflowServices })` can rebuild the service value during fresh-process recovery before the generator advances. Do not use `services` for durable data, and do not pass it in Worker execution mode — non-serializable values cannot cross to a Worker.
+
 > [!NOTE]
 > The chained builder also accepts `.signals({...})`, `.updates({...})`, `.queries({...})`, and `.searchAttributes({...})`. Each can be called at most once before `.execute(fn)`; the type system flips a phantom flag so a duplicate call fails to typecheck, and the runtime mirrors the same invariant. These maps don't introduce new runtime gating — they're type hints that thread into `ctx.run()`, `ctx.waitForSignal()`, `ctx.waitForUpdate()`, and friends so your editor autocompletes and your code typechecks. The underlying dispatch paths are unchanged.
 
@@ -120,6 +128,7 @@ Because recovery never re-executes the workflow from the beginning, your workflo
 | **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.            |
 | **Shared state**     | A compare-and-swap (CAS) durable mutable primitive for safe concurrent reads and writes across workflows.                     |
+| **Idempotent start** | A stable `idempotencyKey` that makes retried starts return the existing run instead of creating duplicates.                   |
 
 ## Features
 
@@ -188,6 +197,21 @@ for await (const event of tail) {
 
 The tail is single-consumer and stops on terminal workflow events or `tail.close()`. In runtimes without a built-in WebSocket, or where authenticated WebSockets need headers the platform constructor cannot send, provide `HttpClientOptions.webSocketFactory`.
 
+### 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.
+
+```typescript
+const handle = await engine.startOrSignal(
+  'approval',
+  { orderId: 'order-123' },
+  { name: 'payment', payload: { status: 'succeeded' } },
+  { idempotencyKey: 'payment-webhook-order-123' },
+);
+```
+
+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.
+
 ### Search Attributes
 
 Attach indexed metadata to a workflow at runtime, then list and filter on it.
@@ -268,6 +292,7 @@ A small `Storage` interface over string keys and `Uint8Array` values: five requi
 - **`NodeSQLiteStorage`** (subpath `@lostgradient/weft/storage/sqlite/node`) for an explicit Node.js SQLite override via `better-sqlite3`
 - **`LMDBStorage`** (subpath `@lostgradient/weft/storage/lmdb`) for embedded high-throughput workloads
 - **`TursoStorage`** (subpath `@lostgradient/weft/storage/turso`) for distributed libSQL deployments
+- **`NeonStorage`** (subpath `@lostgradient/weft/storage/neon`) for durable remote Neon/Postgres deployments
 - **`IndexedDBStorage`** (subpath `@lostgradient/weft/storage/indexeddb`) for browser environments
 - **`WebExtensionStorage`** (subpath `@lostgradient/weft/storage/web-extension`) for extension contexts using `browser.storage` or `chrome.storage`
 - **`HTTPStorage`** (subpath `@lostgradient/weft/storage/http`) for remote storage over Weft's HTTP storage routes
@@ -275,6 +300,8 @@ A small `Storage` interface over string keys and `Uint8Array` values: five requi
 
 Bring your own backend by implementing the interface—five methods is enough.
 
+Production recovery needs one engine process per durable store. Use a local durable adapter (`SQLiteStorage` or `LMDBStorage`) when the service owns its disk, or `NeonStorage` when the deployment wants managed Postgres durability and point-in-time restore. In either case, validate the store at boot with `assertDurableStorageForRecovery()` and enforce the singleton topology in infrastructure; the [singleton service deployment guide](documentation/guides/singleton-service-deployment.md) covers the checklist and the optional warn-only second-instance detector.
+
 For long-running workflows, `history.retentionWindow` can compact old event-log records behind the latest checkpoint while preserving verification through a durable watermark. `history.maxEvents` remains a lifetime circuit breaker even after compaction. Use `payloadSize.maxBytes` when operators need an admission-time cap on workflow inputs, signal payloads, and activity results before those values reach storage.
 
 ### Server Mode
@@ -372,39 +399,36 @@ For chaos testing, `withChaos()` wraps activities with configurable transient fa
 Every error Weft throws extends `WeftError`, so a single `instanceof` check catches them all, and each carries a stable string `code` equal to its class name:
 
 ```typescript
-import { isWeftError, isWeftErrorCode } from '@lostgradient/weft';
+import { isWeftError } from '@lostgradient/weft';
 
 try {
   await engine.start('checkout', { orderId: 'order-1' }, { id: 'order-1' });
 } catch (error) {
   if (!isWeftError(error)) throw error; // not ours — rethrow
 
-  if (isWeftErrorCode(error.code)) {
-    switch (error.code) {
-      case 'WorkflowAlreadyExistsError':
-        // idempotent retry — already running
-        break;
-      case 'WorkflowNotRegisteredError':
-        throw error; // a programming error, not a runtime condition
-      default:
-        console.error(`[${error.code}] ${error.message}`);
-    }
+  switch (error.code) {
+    case 'WorkflowAlreadyExistsError':
+      // idempotent retry — already running
+      break;
+    case 'WorkflowNotRegisteredError':
+      throw error; // a programming error, not a runtime condition
+    default:
+      console.error(`[${error.code}] ${error.message}`);
   }
 }
 ```
 
-`isWeftError` is an `instanceof` check — the right tool in the common case where the error came from the same module instance. If an error can reach you across a realm or a duplicate module load (multiple copies of `@lostgradient/weft` in one process), `instanceof` is unreliable; skip `isWeftError` and branch on `error.code` directly, since the string `code` survives those boundaries:
+`isWeftError` is an `instanceof` check — the right tool in the common case where the error came from the same module instance. If an error can reach you across a realm or a duplicate module load (multiple copies of `@lostgradient/weft` in one process), `instanceof` is unreliable; use `isWeftErrorLike` to narrow the caught value structurally:
 
 ```typescript
-import { isWeftErrorCode } from '@lostgradient/weft';
+import { isWeftErrorLike } from '@lostgradient/weft';
 
 function isAlreadyRunning(error: unknown): boolean {
-  const code = (error as { code?: unknown }).code;
-  return isWeftErrorCode(code) && code === 'WorkflowAlreadyExistsError';
+  return isWeftErrorLike(error) && error.code === 'WorkflowAlreadyExistsError';
 }
 ```
 
-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` returns `false` for them — so internal codes may change between releases without breaking your types.
+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
 
@@ -418,6 +442,7 @@ Storage backends and adapters are exported under subpaths so they only load when
 import { SQLiteStorage } from '@lostgradient/weft/storage/sqlite';
 import { LMDBStorage } from '@lostgradient/weft/storage/lmdb';
 import { TursoStorage } from '@lostgradient/weft/storage/turso';
+import { NeonStorage } from '@lostgradient/weft/storage/neon';
 import { IndexedDBStorage } from '@lostgradient/weft/storage/indexeddb';
 import { WebExtensionStorage } from '@lostgradient/weft/storage/web-extension';
 import { HTTPStorage } from '@lostgradient/weft/storage/http';

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

@@ -1,5 +1,5 @@
 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.streams.chunks", "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.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 = {
     readonly attributes?: ReadonlyArray<SharedGtGteKey_896a0c41>;
@@ -540,6 +540,26 @@ export type CatalogOperationTypes = {
         };
         readonly faults: 'Conflict';
     };
+    'weft.workflows.startorsignal': {
+        readonly input: {
+            readonly executionTimeout?: unknown;
+            readonly id?: unknown;
+            readonly idempotencyKey?: unknown;
+            readonly input?: unknown;
+            readonly searchAttributes?: unknown;
+            readonly signalId?: string;
+            readonly signalName: string;
+            readonly signalPayload?: unknown;
+            readonly startAfter?: unknown;
+            readonly startAt?: unknown;
+            readonly tags?: unknown;
+            readonly type: unknown;
+        };
+        readonly output: {
+            readonly id: string;
+        };
+        readonly faults: 'Conflict';
+    };
     'weft.workflows.streams.chunks': {
         readonly input: {
             readonly after?: unknown;
@@ -551,6 +571,13 @@ export type CatalogOperationTypes = {
         };
         readonly faults: never;
     };
+    'weft.workflows.suspend': {
+        readonly input: {
+            readonly workflowId: string;
+        };
+        readonly output: unknown;
+        readonly faults: 'Unprocessable';
+    };
     'weft.workflows.tags.add': {
         readonly input: {
             readonly tags?: unknown;

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

@@ -48,7 +48,9 @@ export const CATALOG_OPERATION_NAMES = [
   "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",