@netscript/plugin-sagas-core

Saga DSL, runtime ports, adapters, telemetry, config, and testing primitives for NetScript sagas plugins. This page is written against the package's public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

Sagas are the honest answer to distributed transactions: a sequence of steps, each with a compensation, driven by messages that may arrive twice or out of order. defineSaga builds a frozen, typed definition — state, handlers, compensations, signals, queries — and the runtime drives it through explicit ports for storage, transport, clock, and idempotency. Nothing is global: applications inject their own durability, and tests inject deterministic in-memory doubles.

This is the core that the deployable @netscript/plugin-sagas plugin binds to a NetScript host. Use it directly for custom hosts, libraries, and tests.

Exports

The package publishes twenty-one entrypoints. The root path carries the userland DSL; the remaining subpaths expose the layers a host, adapter author, or test harness composes.

Export counts are the symbol counts deno doc reports for each entrypoint; subpaths overlap where a type is re-exported through more than one layer.

The stores subpath exposes isPrismaSagaStoreClient(value) for the canonical-store delegate contract shared by API and runner bootstrap validation. Query delegates remain a separate API requirement. resolveSagaStoreBackend accepts an optional defaultBackend used only when neither environment nor appsettings selects a backend; invalid configured values always fail. Runner backend selection controls canonical state; Prisma selection keeps replay reservations and applied keys in a separate KV handle that is closed on shutdown.

Root surface (@netscript/plugin-sagas-core)

Defining a saga

Cascaded messages

A handler is a pure projection: it returns cascaded messages rather than performing effects. These constructors keep their existing cascade meanings. Opted-in ordinary transition handlers can also return the explicit pure worker effects documented below.

Signals and queries

Correlation and identity

Policies

Handlers are synchronous

A saga handler is synchronous and returns cascaded messages; it does not await. That is what makes replay deterministic and what keeps the compensation path a pure function of the transcript. Work that must happen outside the handler — enqueueing a worker job, calling a service — is expressed as a cascaded message the runtime dispatches, or through the explicit @netscript/plugin-sagas-core/integration/workers helpers.

spawn() is present in the surface but rejects: child-saga spawn cascades are unsupported, and calling it raises rather than silently succeeding. Its return type is never, so a handler that returns spawn(...) does not type-check into the cascade union by accident.

Composing a runtime

@netscript/plugin-sagas-core/runtime exposes createSagaRuntime, which takes explicit ports rather than reaching for globals. The store, transport, clock, and idempotency edges are all injected, so the same definitions run against Redis or Garnet in production (@netscript/plugin-sagas-core/transports) and against in-memory doubles in tests (@netscript/plugin-sagas-core/testing).

@netscript/plugin-sagas-core/presets collapses the common case: startSagas composes a runtime and starts it, and startSagaHandlers binds a definition set to an already-composed runtime.

Related pages

• @netscript/plugin-sagas — the deployable plugin that binds this core to a NetScript host.
• @netscript/plugin-workers-core — the worker primitives the integration/workers helpers dispatch to.
• @netscript/plugin-streams-core — the producer behind the projected instance stream.

Back to the reference overview.

Checked command sink

createSagaCommandOutboxSink adapts the existing SagaPublisherPort through publishSagaOrThrow. It forwards stable outbox message/idempotency identity, correlation and W3C context, checks type and acceptance time, and returns only normalized identity/time. Rejected, unavailable, mismatched and malformed results cannot settle. The supplied publisher owns transport timeout; cancellation is cooperative around its awaited call. A post-publication crash can redeliver the same identity, so consumer side effects require independent idempotency. Construction starts no work and requires no permissions; supplied publishers own their permissions.

Atomic worker-command effects

Select .durableWorkerCommands() on the saga definition. Registration refuses KV and the legacy unbound Prisma store before any handler/storage work; the test memory store and named bound PostgreSQL store satisfy the capability. send() stays an internal saga-message cascade. Worker effects are valid only in ordinary top-level transitions; compensation and nested scheduled cascades retain their existing ledger.

Selected schema validation and bounded canonical I-JSON encoding precede all transition writes. Non-JSON prototypes/accessors and schema transformations changing canonical identity are refused. Stable versioned SHA-256 command identities include saga id, instance id, next version and original effect ordinal. State CAS, correlation, history, outbound intents and hashed inbound marker share one commit. Failed work retains retry eligibility; committed replay writes nothing. The marker is limited to this protocol and does not close general Prisma idempotency parity debt.

Migrate the shipped saga runtime/replay models and command outbox before selecting PostgreSQL. The host supplies the real generated interactive callback and owns resources; the database bound writer reuses the existing command-outbox append SQL. Configure the generic relay's worker sink topic map with the same selected definition id; routing is explicit host policy. The relay handles leases, bounded retries, drain, checked receipts and settlement. Delivery is at least once; one effective application additionally requires durable worker idempotency.

The generated-client consumer example is packages/plugin-sagas-core/tests/fixtures/transition-store/saga-relay-cohort.ts.template. It uses the generic command-outbox relay and worker sink with the producer, native worker dispatcher, persisted Deno KV execution/applied state, first-party worker stream producer and file-backed Durable Streams server. Progress survives storage/server restart; completion uses publishSagaOrThrow(). No progress event is mirrored into command outbox rows. The example demonstrates source integration; deploy the capability only when the producer and its command-outbox relay prerequisites are available together in the application's pinned release.

KV retention

Topic groups declare retention.completedDays (default 7) and retention.archiveToDb (default false). Open pending, running, and compensating instances retain canonical state, correlations, transition history, applied replay keys, and the KV query projection until they become terminal. activeDays is a legacy active-window hint; it does not expire live replay data.

Terminal completed, failed, cancelled, and compensated instances expire after completedDays, measured from the terminal timestamp. Canonical state, forward and reverse correlations, new terminal transitions, and saga_instances query documents use KV expireIn. The saga service applies the same deadline to earlier transitions and applied keys in atomic pages of at most 10 entries (12 checks and 11 mutations including state and cursor), conservatively bounded for Deno KV's mutation byte budget even for full-size values. A persistent sagas/retention cursor resumes that work after restart and is deleted once all history has received its TTL. Low-level KvSagaStore callers must drive cleanupRetention(); it returns whether work remains. The shipped durable runtime drains backlog without a polling delay, backs off from 100 ms to 30 seconds while idle, and logs/retries transient sweep failures with exponential backoff. Retention failures do not prevent runtime startup. A backlog can delay migration of historical keys, so backend expiry alone is guaranteed only after their terminal deadline has been assigned. No API read or owner app session drives cleanup.

Transport reservations already use their separate deduplication TTL. With a KV query projection, archiveToDb: true explicitly enables the optional Prisma archive for that saga group and requires a host Prisma client. The default archiveToDb: false skips it, keeping KV-only installs DB-free. With Sagas.Projection.Backend: prisma, the Prisma query model remains required runtime state so listInstances, getInstance, and stream hydration stay populated independently of archival.

Migration: KvSagaAppliedKeyStore.activeTtlMs is deprecated and no longer expires open replay markers. Configure completedRetentionDays to match the canonical terminal window instead. Markers survive open instances and receive their deadline only after terminal state.

The default saga runner stores new scheduled cascades in the existing KV polling queue under queue:pending/sagas-scheduled; ready messages still use the configured delivery provider. Each scheduled cascade carries its originating durable instance id separately from the destination correlation. Pending, running, and compensating instances keep their timers. Terminal transitions, including sagaComplete() alongside schedule(), still enqueue follow-ups. Timers remain eligible for delivery until the origin's completedAt (or terminal updatedAt) plus completedDays deadline, regardless of their destination. After that deadline, or once canonical state has expired, pending and due timers are cancelled. SagaQueueScheduler.retentionDrops counts every successful pending key deletion and every due-message drop; lost CAS races do not increase it. A cancellable scheduler binds canonical state and its retention policy before startup; the existing background retention loop inspects at most 101 pending keys and cancels at most 100 per pass. A persistent queue cursor resumes across restart and prevents an active prefix from starving terminal cleanup. Cancellation uses per-key CAS, so it does not remove a concurrently rewritten message. Backlog is drained without an idle delay; idle and failure waits use the existing 100 ms to 30 second backoff. Cleanup requires no API read or owner session. Due timers check canonical state before forwarding to the delivery queue; an already forwarded/in-flight delivery remains subject to the engine's existing terminal checks.

Custom runner delivery queues preserve their existing native-delay behavior unless the host supplies scheduledQueue with the cancelPending capability. Low-level SagaQueueScheduler callers supply that queue, bind the canonical store with matching completedRetentionDays, and drive cleanupRetention(). Without a bound store or cancellation capability, startup logs a warning and uses the ready queue's native delays. This preserves injected-engine and custom-factory runner configurations. Cleanup before binding returns false; a second start is rejected. The independent core SagaScheduler uses KvSagaSchedulerStore from ./stores for bounded retention. Bind canonical state and the matching completedRetentionDays policy before startup; low-level callers drive cleanupRetention() from a background service loop. The shipped durable runtime drives this hook for an injected scheduler. A pass inspects at most ten records and persists its cursor across restart. Pending, claimed, dispatched, and failed records receive KV TTL anchored to the origin's terminal deadline; expired scoped records are deleted with CAS. Open instances and all unscoped records, including new schedules without an origin, survive without TTL. Due delivery checks canonical origin state; missing state cancels scoped records. Replay keyed by origin, message idempotency key (or message id), and scheduled time does not renew the deadline or replace outcomes. Unkeyed schedules have distinct identities. Claim leases recover after 30 seconds; stale claim outcomes cannot replace newer claims or recreate deleted records. The host owns the KV adapter and injects the same clock into scheduler and adapter. A time-ordered due index honors the caller's batch limit and atomically re-keys claims to their lease deadline; retained outcomes never delay due work. Adapter-private claim tokens survive deadline updates, and empty claims make no KV writes. Custom stores need the optional cancellation and cleanup capabilities when binding retention. All core schedulers, including unbound ones, use content-hashed replay identities; unbound schedulers do not enforce originating-instance retention. No database archive or app read drives this path. KV canonical reads are batched in native pages of at most ten keys. Only explicitly scoped new messages are cancellation candidates; legacy unscoped queue messages and native-provider delayed entries need separate migration.

Terminal records written before the retention policy was installed still need a migration/backfill. This leaf proves new scoped delayed-message cancellation; legacy saga/trigger terminal-family backfill, new and legacy unscoped schedules, and native-provider delayed messages remain separate acceptance scope for issue #2109.

Exports: discovery metadata

The @netscript/plugin-sagas-core/discovery entrypoint (./src/builders/discovery.ts) exports NETSCRIPT_CONTRIBUTION_BUILDERS. Pass these immutable patterns through the plugin SDK additionalBuilders option. The CLI composes first-party metadata before walking the project, so single-plugin updates succeed regardless of workers/streams order.