Durable sagas

A saga is the answer to the question every retry loop dodges: what happens between step three and step four when the process dies? In NetScript a saga is an explicit, message-driven state machine — you declare the state it carries, the messages it reacts to, and the effects each handler emits. It is authored with a single fluent builder, persisted to a durable store, and served by the sagas plugin on port :8092. The model is closer to Temporal than to a job queue, but it lives in plain TypeScript inside your workspace — no separate cluster to operate.

This is the third capability in the continuous-app thread. The background jobs capability ended with a job, create-user-settings, that publishes a UserSettingsCreated message. Here that message stops being fire-and-forget: a saga consumes it, advances its own state, and emits a sagaComplete(...) effect that the runtime records as a first-class outcome — and persists durably so the instance survives a process restart.

What it is

A saga is a durable, message-driven state machine: a typed state object plus a set of handlers, one per message type, that advance that state and return an effect ledger. The runtime persists state between every message, so an instance that is mid-flight when the process restarts resumes exactly where it left off. Unlike a background job — a single idempotent unit — a saga correlates many messages into one long-running instance and gives compensation (the undo of an already-applied step) a first-class place in the model. Read the conceptual companion, the

The durability model , for why state must outlive the process and how effect-based outcomes differ from a retry loop.

Learn → · Do →

Minimal example — an order saga with compensation

The runnable shape you grow into: a real state type, multiple .on(...) handlers, and a .compensate(...) branch that unwinds an already-charged payment when fulfillment fails. The first handler reserves stock and emits a send(...) effect to charge payment; the failure path returns sagaCompensate(...) so the engine routes the matching compensation handler, which refunds and then fails the instance.

// plugins/sagas/order-saga.ts
import {
  defineSaga,
  sagaComplete,
  sagaCompensate,
  sagaFail,
  send,
} from '@netscript/plugin-sagas-core';

// The state is the source of truth that survives across messages and crashes.
type OrderState = Readonly<{
  status: 'awaiting-payment' | 'awaiting-fulfillment' | 'completed' | 'refunded';
  orderId?: string;
  paymentId?: string;
}>;

type OrderPlaced = Readonly<{ orderId: string }>;
type PaymentCaptured = Readonly<{ orderId: string; paymentId: string }>;
type FulfillmentFailed = Readonly<{ orderId: string; reason: string }>;

export const orderSaga = defineSaga('order-saga')
  // Durability tier: where the runtime checkpoints state between messages.
  .durability('t1')
  // Typed initial state, seeded once at instance creation.
  .state<OrderState>({ status: 'awaiting-payment' })
  // Handler 1: an order was placed — record it and ask the payment service to charge.
  .on<'OrderPlaced', OrderPlaced>('OrderPlaced', (saga, event) => {
    saga.state = { ...saga.state, orderId: event.payload.orderId };
    // `send` is an effect: dispatch a command to another target, not a direct call.
    return [send({ kind: 'service', id: 'payments' }, { orderId: event.payload.orderId }, {})];
  })
  // Handler 2: payment captured — advance toward fulfillment.
  .on<'PaymentCaptured', PaymentCaptured>('PaymentCaptured', (saga, event) => {
    saga.state = {
      ...saga.state,
      status: 'awaiting-fulfillment',
      paymentId: event.payload.paymentId,
    };
    return [];
  })
  // Handler 3: fulfillment failed AFTER we charged — request the compensation branch.
  .on<'FulfillmentFailed', FulfillmentFailed>('FulfillmentFailed', (saga, event) => {
    return [sagaCompensate({ type: 'FulfillmentFailed', payload: event.payload }, event.payload.reason)];
  })
  // Compensation: undo the already-applied payment, then fail the instance.
  .compensate<'FulfillmentFailed', FulfillmentFailed>('FulfillmentFailed', (saga, event) => {
    saga.state = { ...saga.state, status: 'refunded' };
    return [
      send({ kind: 'service', id: 'payments' }, { refund: saga.state.paymentId }, {}),
      sagaFail(`order ${event.payload.orderId} unfulfilled: ${event.payload.reason}`),
    ];
  })
  .build();

export default orderSaga;

Key types first

Before the options, the primary interfaces the DSL works in. SagaState is the base shape your typed state must satisfy; SagaContext is the read-only context passed to every handler; SagaDefinition is the frozen object build() returns and the runtime registers.

The builder API

A saga is built with defineSaga(id) and a typestate chain: .state() must come before any handler, and .build() requires at least one handler. These are the methods on the returned SagaBuilder.

// plugins/sagas/<your-saga>.ts
import { defineSaga, sagaComplete } from '@netscript/plugin-sagas-core';

type State = Readonly<{ status: string; processedAt?: string }>;

// Build a saga: id -> durability tier -> typed state -> message handlers -> build().
export const userSettingsSaga = defineSaga('user-settings-saga')
  .durability('t1')
  .state<State>({ status: 'pending' })
  .on<'UserSettingsCreated', { userId: string }>(
    'UserSettingsCreated',
    (saga, event, context) => {
      // Advance the saga's own state, then emit completion as a recorded outcome.
      saga.state = {
        ...saga.state,
        status: 'completed',
        processedAt: context.now.toISOString(),
      };
      return [sagaComplete({
        userId: event.payload.userId,
        processedAt: context.now.toISOString(),
      })];
    },
  )
  .build();

export default userSettingsSaga;

// netscript.config.ts (excerpt)
import { defineSagaConfig } from '@netscript/plugin-sagas-core/config';

// The config-time entry the scaffolder + CLI read. SEPARATE from the runtime
// definition that defineSaga(...).build() produces.
export const orderSagaEntry = defineSagaConfig('order-saga', './plugins/sagas/order-saga.ts')
  .name('Order saga')
  .description('Reserve, charge, fulfill — with a compensation branch.')
  .topic('orders')
  .tags(['orders', 'checkout'])
  .build();

Effect helpers

A handler's only side effect is the array of cascaded messages it returns. These helpers (@netscript/plugin-sagas-core) construct the named effects. Every kind in CASCADED_MESSAGE_KINDS (send | scheduled | spawn | complete | fail | compensate) has a constructor.

createParallelQueue — fan-out and concurrent processing

Saga handlers stay synchronous and pure; the transport layer that carries cascaded messages and feeds fan-out work is where you tune concurrency. createParallelQueue (from

@netscript/queue ) is the primitive for that: it wraps a base queue so a single listener processes several messages at once. It is the right tool when a saga spawns many independent children or pushes I/O-bound side work (API calls, DB writes) that should run in parallel rather than one at a time. The concurrency option is the whole story — 1 is plain sequential, anything higher enables parallel processing.

// plugins/sagas/fan-out.ts — process saga side-effects concurrently
import { createParallelQueue, QueueProvider } from '@netscript/queue';

type NotifyMessage = Readonly<{ orderId: string; channel: 'email' | 'sms' }>;

// Four messages processed at a time on a single listener — for I/O-bound fan-out
// (notifications, webhook calls) a saga emits as it advances.
const notifications = createParallelQueue<NotifyMessage>('order-notifications', {
  concurrency: 4,
  provider: QueueProvider.Redis,
});

await notifications.listen(async (message) => {
  // These run up to 4 at a time, not serially.
  await deliverNotification(message.orderId, message.channel);
});

Choosing a durable store backend

Authoring a saga decides what it does. The durable store backend decides where its runtime state lives between messages and across crashes. NetScript ships two backends, and the choice is explicit and mandatory — the runtime refuses to start without one.

• kv — durable saga state in Deno KV (the orchestration store stood up by Aspire). Zero extra schema; the natural default for a single-service app and for local development.
• prisma — durable saga state in your scaffolded relational database via Prisma (Postgres by default; equally mysql / mssql / sqlite, since the store writes through your project's Prisma client — it is not Postgres-specific). The PrismaSagaStore writes the dedicated runtime tables saga_runtime_state, saga_runtime_transition, and saga_runtime_correlation. Reach for this when you want the saga's own write path in your relational database alongside the rest of your data, with SQL-level inspection of in-flight state and transition history.

You select the backend with the NETSCRIPT_SAGA_STORE environment variable (kv | prisma) or the appsettings key sagas.store.backend. The plugin service resolves this on startup via resolveSagaStoreBackend(...), which throws if neither is set — there is no silent default in the resolver, by design, so a deployment can never guess wrong about where durable state lands. (Calling createDurableSagaRuntime(...) directly without a backend falls back to the KV store; the mandatory-selection guarantee comes from the resolver the service runs at startup.)

The factory that owns these resources is createDurableSagaRuntime(...) from the @netscript/plugin-sagas/runtime subpath. It resolves a SagaStorePort, builds the native runtime over it, and hands you back a dispose() that closes the store (and the KV handle it opened).

import { createDurableSagaRuntime } from '@netscript/plugin-sagas/runtime';

// Deno KV durable store — the default for local/single-service apps.
// Selected at deploy time by NETSCRIPT_SAGA_STORE=kv (or appsettings sagas.store.backend=kv).
const { runtime, store, dispose } = await createDurableSagaRuntime({
  backend: 'kv',
  // kv is opened for you if you don't inject one (openSagaRuntimeKv()).
});

// ... register saga definitions on `runtime`, process messages ...

await dispose(); // closes the KV-backed store + handle

import { createDurableSagaRuntime } from '@netscript/plugin-sagas/runtime';
import { PrismaClient } from './generated/prisma/client.ts';

// Postgres/Prisma durable store — writes saga_runtime_* tables.
// Selected at deploy time by NETSCRIPT_SAGA_STORE=prisma.
const prisma = new PrismaClient();
const { runtime, store, dispose } = await createDurableSagaRuntime({
  backend: 'prisma',
  prisma, // REQUIRED for prisma — omitting it throws.
});

// ... register saga definitions, process messages — transitions land in
// saga_runtime_state / saga_runtime_transition / saga_runtime_correlation ...

await dispose();

import {
  createDurableSagaRuntime,
  resolveSagaStoreBackend,
} from '@netscript/plugin-sagas/runtime';

// Read the backend from the environment (or appsettings) — throws if unset.
const backend = resolveSagaStoreBackend({
  env: Deno.env.toObject(),
  // appsettings: loadedAppsettings, // sagas.store.backend
});

const runtime = await createDurableSagaRuntime({
  backend,
  prisma: backend === 'prisma' ? prismaClient : undefined,
});

The HTTP publisher — createSagaPublisher

A message reaches a saga through a publisher. createSagaPublisher (from @netscript/plugin-sagas/runtime) returns a SagaPublisherPort whose publish(...) POSTs to the sagas API publish endpoint, discovering the service URL from the Aspire environment by default. The workers create-user-settings job uses exactly this to emit UserSettingsCreated across the plugin boundary.

The port returns a typed receipt rather than throwing: publish(...) resolves a SagaPublisherResult — either { published: true, ... } (a SagaPublisherReceipt) or { published: false, reason, retryable } (a SagaPublisherRejected). publishMany(...) takes a mode: 'sequential' | 'parallel' so a batch can fan out.

// plugins/workers/jobs/create-user-settings.ts (core, verbatim from the scaffold)
import { createSagaPublisher } from '@netscript/plugin-sagas/runtime';
import { createSuccessResult, defineJobHandler } from '@netscript/plugin-workers-core';
import { z } from 'zod';

const PayloadSchema = z.object({ userId: z.string().min(1) });
const sagaPublisher = createSagaPublisher<UserRegistrationMessage>();

const handler = defineJobHandler(async (ctx) => {
  const { userId } = PayloadSchema.parse(ctx.payload ?? {});
  // This is the message the saga below consumes — a typed receipt comes back.
  await sagaPublisher.publish({ type: 'UserSettingsCreated', payload: { userId } });
  return createSuccessResult({ userId, settingsCreated: true });
});

export default Object.assign(handler, { id: 'create-user-settings' });

// plugins/sagas/user-settings-saga.ts
import { defineSaga, sagaComplete } from '@netscript/plugin-sagas-core';

type State = Readonly<{ status: string; processedAt?: string }>;

export const userSettingsSaga = defineSaga('user-settings-saga')
  .durability('t1')
  .state<State>({ status: 'pending' })
  .on<'UserSettingsCreated', { userId: string }>(
    'UserSettingsCreated',
    (saga, event, context) => {
      saga.state = { ...saga.state, status: 'completed', processedAt: context.now.toISOString() };
      return [sagaComplete({ userId: event.payload.userId, processedAt: context.now.toISOString() })];
    },
  )
  .build();

Extension points

The current scaffold uses the curated defaults, but the core package exposes the seams the plugin is composed from. Each is a subpath of @netscript/plugin-sagas-core — cite the sub-path in prose and look it up under sagas (e.g. reference/sagas/presets, reference/sagas/transports).

Endpoints and ports

The sagas plugin runs an oRPC API service on :8092. It lists registered sagas and inspects running instances; the registry is backed by Deno KV. These are the routes the live scaffold serves — see sagas for the full generated surface.

The continuous-app choreography

The thread that ties the capabilities together is real and it compiles. The workers plugin's create-user-settings job calls a saga publisher and emits UserSettingsCreated; this saga's .on('UserSettingsCreated', ...) handler consumes it and emits sagaComplete(...). One message crosses the plugin boundary, and both halves are type-checked against the same message type.

After both plugins are running under Aspire, trigger the workers job (POST :8091/api/v1/workers/jobs/create-user-settings/trigger) and watch the saga appear at GET :8092/api/v1/sagas/instances — the message crossed the boundary and a durable instance recorded its completion. Whether that durable instance lives in Deno KV or in your saga_runtime_* Postgres tables is exactly the NETSCRIPT_SAGA_STORE choice above.

Production notes

Why a saga, and why not

Reference →