# NetScript documentation — full corpus

> Deno-native, polyglot backend framework, pre-1.0 (0.0.1-beta.11). This file concatenates the Markdown twin of every documentation page for AI ingestion.

# One contract. A whole production backend.

NetScript is the enterprise-grade meta-framework for Deno: contract-first, end-to-end typed, cloud-agnostic. One unified API from typed services and durable workflows to orchestration, observability, and deploy — one toolchain shared by you and the coding agent you work with.

[Quickstart](https://rickylabs.github.io/netscript/netscript/quickstart/) [Browse the reference](https://rickylabs.github.io/netscript/netscript/reference/) [GitHub](https://github.com/rickylabs/netscript)

> Beta
>
> NetScript is in beta (
>
> 0.0.1-beta.11
>
> ) and moving quickly — pin your versions.

## The contract is the product

Define it once; the typed service and every typed client derive from it — server and callers cannot drift apart. The tabs below come straight from a workspace scaffolded by `netscript init my-app --db postgres --service` (abridged).

```ts
// contracts/versions/v1/users.contract.ts — scaffolded for you.
// One entity schema fans out into a whole CRUD contract.
// (@database/zod is emitted by `netscript db generate` in tab 4.)
import { createCrudContract } from '@netscript/contracts/crud';
import { UserCreateInput, UserSchema, UserUpdateInput } from '@database/zod';

export const UsersCrudContractV1 = createCrudContract({
  resource: 'users',
  entitySchema: UserSchema,
  createSchema: UserCreateInput,
  updateSchema: UserUpdateInput,
});
```

```ts
// Runnable once the database types exist (`netscript db generate`, tab 4).
// One preset wires CORS, request logging, OpenAPI JSON, Scalar docs,
// RPC (served at /api/rpc/*), service info, and health endpoints —
// instead of ~40 lines of Hono setup.
import { defineService } from '@netscript/service';
import { router } from './router.ts';

const service = await defineService(router, {
  name: 'users',
  port: 3000,
});

await service.stop();
```

```sh
# Install the netscript command from JSR (Deno 2.9+)
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11

# Scaffold the workspace shown in tabs 1-2: contracts + the typed
# users service + Postgres + Aspire orchestration.
# Postgres is the recommended engine (mysql, mssql, sqlite also supported).
netscript init my-app --db postgres --service

# Prefer to keep .NET Aspire out of the loop? Opt out:
netscript init my-app --db postgres --service --no-aspire
```

```sh
# Aspire is step 2: it brings up Postgres and the cache first
cd my-app/aspire
aspire restore   # one-time: downloads the AppHost SDK modules
aspire start     # starts everything and prints the dashboard URL

# Open the dashboard; once postgres reports healthy, initialize it
# from the workspace root:
cd ..
netscript db init --name init
netscript db generate   # emits @database/zod, used by tabs 1-2
netscript db seed
```

## One contract, four moves

**Contract → service → plugins → platform.** You author the contract; `defineService` turns it into a running Hono + oRPC app; plugins add durable capabilities behind the same contract style; `@netscript/aspire` provisions and connects the infrastructure — Aspire SDK behind an adapter, no .NET type in any public signature. Service locations resolve at call time from orchestrator-injected environment variables: the same client code runs against local processes, containers, and deployed endpoints. No registry, no config file.

![A NetScript workspace: contracts define services; services, workers, sagas, triggers, streams, and auth plugins register against a host; the AppHost materializes each as an Aspire resource alongside Postgres, Redis, and the dashboard.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/architecture-overview.svg)

*The whole system in one picture: contracts at the center, plugins contributing to a host, and the AppHost bringing every resource up together.*

Observability is not an add-on: telemetry stitches scheduler → queue → worker → RPC → SSE spans into one distributed trace using Deno's built-in OTLP exporter — zero OpenTelemetry SDK dependency by default — and the Aspire dashboard shows every resource, trace, and log in one place.

## Batteries no frontend framework ships

Durable jobs, compensating sagas, trigger ingress, replayable streams, pluggable auth, an in-process AI surface — first-party plugins, in the box, not an integration project.

NetScript does not try to be everything: right tool for the right job, reached through the plugin system. A plugin is a validated manifest that can contribute across every layer — CLI verbs, scaffolded code, runtime services, storage, stream topics, telemetry, Aspire resources — and the host materializes whatever it declares. The mechanism behind the six first-party plugins is how a team extends the framework for its own needs, on the same rails. One command, four plugin files scaffolded and twelve Aspire helpers regenerated:

```sh
netscript plugin install worker --name workers
# Installed worker plugin "workers" on port 8091.
# Created 4 plugin files.
# Regenerated 12 Aspire helper files.
```

[workers  Durable jobs and workflows; tasks in 4 runtimes (Deno, PowerShell, Python, shell) with at-least-once delivery keyed on idempotencyKey.](https://rickylabs.github.io/netscript/netscript/background-processing/)

[sagas  Durable multi-step workflows with compensation — saga state persists, so a crash mid-flow resumes instead of stranding half-applied effects.](https://rickylabs.github.io/netscript/netscript/durable-workflows/)

[triggers  Webhook, scheduled, and file-watch ingress with ack-then-process semantics, idempotency, retry, and dead-lettering.](https://rickylabs.github.io/netscript/netscript/durable-workflows/)

[streams  Durable, replayable typed topics with no database required — the common pipe the other plugins publish to.](https://rickylabs.github.io/netscript/netscript/durable-workflows/)

[auth  One auth API with swappable backends (kv-oauth, workos, better-auth), auth schema, and durable session streams.](https://rickylabs.github.io/netscript/netscript/identity-access/)

[ai  An app-owned, in-process chat/tool/agent surface — the agent loop runs inside your server process, no AI gateway, no extra network hop.](https://rickylabs.github.io/netscript/netscript/ai/)

## Ship anywhere

One app model, the whole spectrum: a single compiled binary on one machine, or a multi-cloud distributed infrastructure — and, coming next, a native desktop app on a consumer machine. Cloud-agnostic by design.

`netscript deploy <target> <op>` is one thin router over target adapters sharing a canonical lifecycle (`plan`, `up`, `down`, with `status`/`logs` on the targets that honour them — `netscript deploy list` inventories the installed targets; check `netscript deploy <target> --help` for the exact operations each one ships). Shipped lanes today: Docker and Compose, Linux and Windows OS services from a single compiled binary, Deno Deploy with a preflight guard, Kubernetes and Azure (Container Apps, App Service, AKS) delegating to Aspire, and Cloud Run. Cloud auth stays operator-owned — NetScript mints no credentials and hand-authors no Helm/Bicep/Kubernetes manifests.

> Coming next — native desktop lane
>
> A native desktop deploy target is landing: native installers per OS, Ed25519-signed update manifests, and update-ready events surfaced through an SDK seam. See
>
> Build a desktop frontend
>
> .

## Built for devs working with agents

Not a framework for agents instead of developers — a framework for developers who work with one. The properties that make NetScript easy for you to adopt, review, and debug — one unified API, typed end to end, reference docs generated from source — are exactly what make it legible to a coding agent. High-risk operations like deploy, init, and db reset stay behind an explicit deny list (deny beats allow; unmatched commands are denied). The CLI is the hands, the skills are the playbook, MCP is the eyes; one command wires all three in:

```sh
# Auto-detects the agent host, writes the MCP config (.mcp.json for
# Claude Code, .vscode/mcp.json for VS Code), and installs the skill
# bundle — all pinned to the installed CLI version.
netscript agent init
```

[MCP is the eyes  13 token-bounded tools over stdio: app status, run inspection, recent errors, performance analysis, doctor, and docs search. Every result is capped server-side (50 items, 2,000 characters per string) so telemetry never floods the context window.](https://rickylabs.github.io/netscript/netscript/ai/mcp/)

[Skills are the playbook  agent init installs three content-hashed skills shipped with the same release as the CLI, so the playbook always matches the binary.](https://rickylabs.github.io/netscript/netscript/reference/ai/skills/)

[The CLI is the hands  The MCP execute_command tool shells the real CLI through a default-deny policy gate: 17 allowed command prefixes, 6 explicit denies, deny beats allow, anything unmatched is denied.](https://rickylabs.github.io/netscript/netscript/ai/)

## Build real systems, not just CRUD

[Web Layer  Fresh pages, route contracts, forms, islands, streaming, and UI integration.](https://rickylabs.github.io/netscript/netscript/web-layer/)

[Services & SDK  oRPC services, shared contracts, OpenAPI, Scalar, and typed clients.](https://rickylabs.github.io/netscript/netscript/services-sdk/)

[Background Processing  Workers, queues, cron, polyglot runtimes, and task permissions.](https://rickylabs.github.io/netscript/netscript/background-processing/)

[Durable Workflows  Sagas, triggers, streams, retries, and stateful multi-step work.](https://rickylabs.github.io/netscript/netscript/durable-workflows/)

[Data & Persistence  Database setup, migrations, multiple datasources, KV, and adapters.](https://rickylabs.github.io/netscript/netscript/data-persistence/)

[Identity & Access  Principals, sessions, auth backends, roles, scopes, and claims.](https://rickylabs.github.io/netscript/netscript/identity-access/)

[Orchestration & Runtime  Aspire AppHost, plugin resources, runtime config, deployment, and lifecycle.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/)

[Observability  OpenTelemetry trace context, structured logs, and the Aspire dashboard.](https://rickylabs.github.io/netscript/netscript/observability/)

[AI & Agents  MCP server, agent skills, the in-process AI engine, and durable chat.](https://rickylabs.github.io/netscript/netscript/ai/)

## Who it is for

Full-stack TypeScript engineers

Stay in TypeScript from the database to the UI, with contracts that catch integration breaks before they ship.

Platform engineers

Standardize internal services on one coherent Deno baseline — multi-resource wiring, a real dashboard, pluggable auth, and tracing already in place.

Plugin authors

Extend the framework by registering workers, sagas, triggers, auth backends, and streams. No host edits, no forks.

Devs working with agents

netscript agent init gives your agent MCP eyes, a skills playbook, and a policy-gated CLI — high-risk operations like deploy, init, and db reset stay behind an explicit deny list.

## Start the learning path

1. [Quickstart](https://rickylabs.github.io/netscript/netscript/quickstart/)
2. [Architecture overview](https://rickylabs.github.io/netscript/netscript/concepts/)
3. [Glossary](https://rickylabs.github.io/netscript/netscript/glossary/)
4. [Choose a pillar](https://rickylabs.github.io/netscript/netscript/web-layer/)

[API reference  Generated from source via deno doc — every package, every public symbol.](https://rickylabs.github.io/netscript/netscript/reference/)

[Source on GitHub  Read the framework, file issues, follow the road to stable.](https://github.com/rickylabs/netscript)

[Packages on JSR  The @netscript/* family, installable with deno add.](https://jsr.io/@netscript)

_Canonical: https://rickylabs.github.io/netscript/_

---

# AI

The NetScript AI stack is a set of composable seams for building agentic chat and tool-calling surfaces on the same contracts-first, hexagonal foundation as the rest of the framework. It is deliberately layered: a provider-agnostic **engine** at the design center, an **MCP client stack** that turns external MCP servers into agent tools, a **durable-chat runtime** that turns a Fresh route into a chat whose history survives reload and reconnect, and an app-owned **chat UI** you copy into your workspace and keep. Each layer stands on its own and each is published — you can adopt one without pulling in the others.

That layering is the build-efficiency argument: whether the next slice of your app is written by you or generated by an agent, each capability is one published seam away — install it, wire the port, and the vocabulary already matches the layer above — instead of a bespoke integration to design before the feature work starts.

> What ships in 0.0.1-beta.11
>
> All four layers are published on JSR and installable now: the
>
> engine
>
> (
>
> @netscript/ai
>
> —
>
> deno add jsr:@netscript/ai
>
> ), the
>
> MCP client stack
>
> (its
>
> ./mcp
>
> subpath), the
>
> durable-chat runtime
>
> (
>
> @netscript/fresh/ai
>
> +
>
> @netscript/fresh/ai/sandbox
>
> ), and the
>
> chat UI
>
> (the
>
> @netscript/fresh-ui
>
> ai
>
> copy-registry collection, installed with
>
> netscript ui:add ai
>
> ). The AI plugin pair (
>
> @netscript/plugin-ai
>
> ,
>
> @netscript/plugin-ai-core
>
> ) is published at the same version.

## The story: a chat that stops being a demo

The first version of an AI feature is usually a chat box holding its transcript in component state — and it works until it meets reality. A reload mid-answer loses the in-flight tool call. The answer needs a chart, and now model output is being glued into the DOM by hand. The agent needs a capability that lives behind an external MCP server, and suddenly you are writing a protocol client. Each failure lands on a different layer of this stack, and each layer answers exactly one of them:

- **history that survives** — the [durable-chat runtime](https://rickylabs.github.io/netscript/ai/durable-chat/) backs the session with a durable stream and one projection reducer, so reload, reconnect, and multi-tab replay all converge on the same transcript;
- **model-authored UI without raw HTML** — the [chat UI](https://rickylabs.github.io/netscript/ai/chat-ui/) renders `render_ui` payloads through a curated block vocabulary with depth limits and safe fallbacks;
- **external capabilities as ordinary tools** — the [MCP client stack](https://rickylabs.github.io/netscript/ai/mcp/) pools servers, injects auth, and registers remote tools into the same registry the agent loop dispatches;
- **one vocabulary underneath** — the [engine](https://rickylabs.github.io/netscript/ai/engine/) owns the contracts all of the above speak, so the layers compose instead of adapting to each other.

## The two planes — never build chat on the wrong primitive

NetScript models real-time state in two distinct planes, and the single most common mistake is reaching for the wrong one. A **StreamDB shape** and a **durable chat session** look adjacent — both are live and durable — but they answer different questions.

**Two planes — pick by what you are modeling**

| Axis | StreamDB shapes (data) | Durable chat sessions (AI chat) |
| --- | --- | --- |
| Unit | A collection / row shape | One chat session (append-only chunk log) |
| Identity | Keyed by row id inside a named shape | Keyed by `sessionId` — one stream per chat |
| Write model | CRUD mutations reconciled into the shape | Append-only sanitized chunks |
| What survives | The current materialized rows | The full replayable log (messages + tool cards) |
| Read primitive | `useLiveQuery` over a shape | `resolveChatSnapshot` + live `useChat` |
| Use it for | Lists, boards, tables, dashboards | Conversational, streaming, tool-calling chat |

A chat needs the **session plane** because a tool call is a multi-chunk, mid-stream event: it moves through `pending → streaming → complete` and cannot be expressed as a single reconciled row without losing those intermediate states. Reach for [durable streams](https://rickylabs.github.io/netscript/durable-workflows/streams/) when you want live list/board/table data; reach for [durable chat](https://rickylabs.github.io/netscript/ai/durable-chat/) when you want a replayable conversation. Conflating them is the documented root of the plane confusion — keep them distinct.

## The engine is the design center

`@netscript/ai` is a **ports-and-adapters** (hexagonal) core with zero `@netscript/*` dependencies. Every capability — telemetry, tool registry, embeddings, vision, MCP transport, the agent loop, memory — is a **port**: an interface the composition root wires at startup, defaulting to a no-op or throwing implementation until you inject a real one. Providers register themselves through **side-effect imports** (`import "@netscript/ai/anthropic"`, mirroring `@netscript/kv/redis`), so the base engine pulls no vendor SDK you did not ask for. Models are addressed by a `"provider:model"` reference string, e.g. `"anthropic:claude-sonnet-4-5"`.

Because the engine owns the vocabulary — the `Message`/`ContentPart` content model, the `AgentChunk` streaming union, the tool and MCP contracts — every layer above it speaks the same types. And because telemetry is a port, an agent run is observable the moment you inject a real `TelemetryPort`: the loop opens a `gen_ai.chat` span per run and a `gen_ai.chat.turn` span per model turn, and records tool calls as `gen_ai.tool.call` events. The [engine reference](https://rickylabs.github.io/netscript/ai/engine/) is the full map.

## Thin plugins, centralized convention

The AI capability follows the framework's plugin doctrine (Architecture Doctrine ch. 11): **R-PLUGIN-THIN** — every convention-bearing primitive lives in a core `@netscript/*` package, and a plugin carries only its own specifics — and **R-PLUGIN-SEAM** — a plugin's contract lives in its `-core` sibling and conforms to the base contract in `@netscript/plugin`. In practice the engine (`@netscript/ai`) owns the vocabulary, `@netscript/plugin-ai-core` owns the `/v1/ai` oRPC contract, and `@netscript/plugin-ai` stays a thin delivery shell — all three published at `0.0.1-beta.11`. This split is what keeps the published surface coherent: the runtime layers (`@netscript/fresh/ai`, the fresh-ui copy registry) are self-contained, and adopting the engine later changes nothing about them.

> Not in this release: netscript generate ai
>
> A
>
> netscript generate ai
>
> codegen (app-owned tool and agent files compiled into engine-ready registries) is planned but
>
> not in the CLI today
>
> — the shipped
>
> generate
>
> targets are
>
> plugins
>
> ,
>
> runtime-schemas
>
> , and
>
> aspire
>
> . Wire tools and agent loops through the engine's registries directly.

## One comparison

Medusa's hero names "Agents and Developers" as co-audiences and its agent story is a progressive narrative — agents build a store feature, then optimize it, then operate the running store. Convex ships "backend building blocks for your agents" as components on its reactive backend. NetScript's AI stack occupies the same layered-investment shape with a different center of gravity: the layers here are the **published framework surface itself** — a JSR engine package, subpath exports, and a copy-registry you own — wired to the same contracts-first backend the rest of your app is built on, rather than a product layer alongside it. The trade is explicit: NetScript does not ship an agents-operate-your-app product tier today; it ships the seams those products are made of.

## Where to go next

[Guide   MCP  The MCP client stack: transports, injected auth, multi-server pooling, and safe rendering of ui:// resources from tool results.](https://rickylabs.github.io/netscript/netscript/ai/mcp/) [Guide   Durable chat  Turn a Fresh route into a durable AI chat: history and in-flight tool calls survive reload, reconnect, and multi-tab.](https://rickylabs.github.io/netscript/netscript/ai/durable-chat/) [Guide   Chat UI  The fresh-ui `ai` copy-registry: composer, message thread, tool-call cards, and the generative-UI block renderer — copied into your app and owned by you.](https://rickylabs.github.io/netscript/netscript/ai/chat-ui/) [Reference   AI engine  @netscript/ai: the provider-agnostic runtime, contracts vocabulary, ports, tools, agent loop, MCP transports, and provider adapters.](https://rickylabs.github.io/netscript/netscript/ai/engine/) [Related   Durable streams  The other real-time plane — live list/board/table data over the durable-stream server.](https://rickylabs.github.io/netscript/netscript/durable-workflows/streams/) [Related   Web Layer  The Fresh page and island model the durable-chat runtime plugs into.](https://rickylabs.github.io/netscript/netscript/web-layer/) [API Reference   @netscript/ai  Generated symbols for the AI engine package.](https://rickylabs.github.io/netscript/netscript/reference/ai/) [API Reference   @netscript/plugin-ai  Generated symbols for the thin AI plugin delivery shell.](https://rickylabs.github.io/netscript/netscript/reference/plugin-ai/) [API Reference   @netscript/plugin-ai-core  Generated symbols for the AI plugin's reusable contract and composition core.](https://rickylabs.github.io/netscript/netscript/reference/plugin-ai-core/)

## Learn, do, look up

[Learn  AI chat tutorial  A durable, tool-calling chat with MCP and live streaming.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/ai/how-to/) [Look up  `@netscript/ai` reference  Generated API reference. Related units: `plugin-ai`, `mcp`.](https://rickylabs.github.io/netscript/netscript/reference/ai/) [Understand  The plugin system  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/)

_Canonical: https://rickylabs.github.io/netscript/ai/_

---

# Agent tooling

The rest of this pillar is about the AI you build *into* your app — the [engine](https://rickylabs.github.io/netscript/ai/engine/), the [MCP client stack](https://rickylabs.github.io/netscript/ai/mcp/), [durable chat](https://rickylabs.github.io/netscript/ai/durable-chat/). This page is the mirror image: what NetScript gives the coding agents (and the humans pairing with them) that build your app. One vocabulary across three surfaces:

- the `netscript` CLI performs direct, scriptable operations;
- installed skills explain which NetScript workflow to use and when to hand off to the CLI;
- the MCP server returns compact framework-aware diagnostics, telemetry summaries, and public docs.

There is a fourth surface that is easy to miss: this documentation site is itself built to be read by agents — every page has a Markdown twin, and the whole corpus is published behind `llms.txt`. We cover that [below](#reading-these-docs-as-an-agent).

Prefer the CLI when a command already expresses the operation — it is easier to reproduce in a terminal or CI job, and the [CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) is the task-oriented map of what exists. Use MCP for interactive investigation, especially when one framework-aware tool replaces several telemetry queries or when an agent needs to discover a document before reading it.

> Two different MCP surfaces — don't conflate them
>
> This page documents the NetScript MCP
>
> server
>
> : a standalone stdio server that gives a coding agent diagnostics, telemetry summaries, and doc search
>
> about
>
> the project it is editing. That is a separate surface from the
>
> `@netscript/ai/mcp` client stack
>
> , which wires
>
> external
>
> MCP servers
>
> into
>
> your product's own agent loop. Server in, client out. The server's full per-tool contracts live in the
>
> `@netscript/mcp` reference
>
> .

## Install into a project

```bash
netscript agent init
```

Host detection installs the matching files. If neither host directory exists, NetScript prepares both hosts. Use `--host claude`, `--host vscode`, or `--host all` to select explicitly.

| Host | Files written |
| --- | --- |
| Claude Code | `.mcp.json`, NetScript skills under `.claude/skills/`, and a marked NetScript section in `AGENTS.md` |
| VS Code | `.vscode/mcp.json` |

The generated MCP configuration runs `netscript agent mcp` for the current project. Re-running `agent init` is idempotent: unchanged files are left alone, and existing host configuration is preserved alongside the `netscript` server entry.

The host command includes the absolute project `deno.json` path. Deno 2.9 normally holds newly published registry versions behind a 24-hour minimum dependency age; the generated JSR workspace keeps that policy while excluding only exact-version packages in the matching NetScript release train. Loading the project configuration explicitly lets a newly released `@netscript/cli` MCP server start immediately without changing the age policy for third-party dependencies.

## Run the server

The generated host configuration runs `netscript agent mcp`, which starts the MCP server over standard input/output. Its flags:

| Flag | Purpose |
| --- | --- |
| `--project-root <path>` | NetScript project root used for execution and doctor flows. `agent init` writes this for you. |
| `--endpoint <url>` | Telemetry endpoint URL; overrides discovery (below). Only `http:` and `https:` are accepted. |
| `--docs-root <path>` | Public documentation root for the docs tools; overrides the default corpus (below). |

## What the server exposes

Thirteen tools, every one returning a bounded structured result. Grouped by what an agent is trying to do:

- **Read the running app** — seven telemetry read models: `get_app_status`, `list_runs`, `get_run`, `get_recent_errors`, `get_last_job_result`, `analyze_service_performance`, and `analyze_db_bottlenecks`. Each replaces a handful of raw telemetry queries with one aggregate answer.
- **Diagnose the project** — `doctor` aggregates telemetry reachability, Aspire markers, project wiring, and plugin diagnostics into one verdict; the plugin slice has a direct twin in `netscript plugin doctor`.
- **Search the docs** — `search_docs`, `list_docs`, and `get_doc` form a search-to-get funnel over the documentation corpus (next section).
- **Bridge to the CLI** — `list_commands` discovers the current command tree (the machine-readable twin of `netscript --help`), and `execute_command` runs an allowlisted `netscript …` command with policy checking, timeout handling, and a bounded output tail.

We keep the per-tool schemas, output bounds, and the full `execute_command` policy in the [`@netscript/mcp` reference](https://rickylabs.github.io/netscript/netscript/reference/mcp/) rather than restating them here; for the commands themselves, the [CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) is the cheat-sheet.

## Documentation corpus

Without an override, `list_docs`, `search_docs`, and `get_doc` index the documentation shipped with the installed `@netscript/mcp` package (one document under the `mcp` slug). Point the server at a richer corpus — a project docs folder or a checkout of this site — with `--docs-root <path>` or the `NETSCRIPT_DOCS_ROOT` environment variable. A configured path that does not exist returns a structured `docs_corpus_not_found` error naming the missing path; the server never silently reports an empty corpus.

## Token-efficient use

Tool inputs cap result counts, and the server truncates oversized results and command output. Start with the narrowest filter that answers the question. For documentation, use the search-to-get funnel: call `search_docs`, choose a slug, then call `get_doc` for that document or section.

## Data boundary

The MCP server reads NetScript telemetry, project metadata and generated registries used for diagnostics, and public documentation. It does not return project source code, environment-variable values, credentials, or secrets.

Telemetry requests go only to the resolved dashboard endpoint. Discovery uses, in order, the `--endpoint` option, `NETSCRIPT_TELEMETRY_ENDPOINT`, `ASPIRE_DASHBOARD_PORT`, and the local default `http://localhost:18888`.

`execute_command` is default-deny. Explicit rules allow selected database, generation, contract, service-read, plugin, and UI commands. Deny rules take priority; deployment, project initialization, marketplace operations, database reset, plugin removal, and every unmatched command are rejected with a structured denial before a process is started. The rule-by-rule policy lives in the [`@netscript/mcp` reference](https://rickylabs.github.io/netscript/netscript/reference/mcp/).

## Troubleshooting

Start with the `doctor` tool: it aggregates four check families — `telemetry`, `aspire`, `project`, and `plugins` — into one verdict. Each check carries a `pass`, `warn`, or `fail` status, and warnings and failures may include a suggested fix. Reading the result:

- **`telemetry` warns or fails** — no reachable telemetry endpoint. Verify the app is running, then check the discovery chain: `--endpoint`, `NETSCRIPT_TELEMETRY_ENDPOINT`, `ASPIRE_DASHBOARD_PORT`, and the local default `http://localhost:18888`. Telemetry tools still respond while the endpoint is down — nothing crashes: `get_app_status` reports `status: "warn"` with zero counts, the list and analytics tools (`list_runs`, `get_recent_errors`, `analyze_service_performance`, `analyze_db_bottlenecks`, …) return their ordinary empty or zero-valued results, and `get_run` returns a structured `run_not_found` error.
- **`aspire` or `project` warns** — the project root is wrong or the workspace is missing expected markers. Confirm the `--project-root` written into your host configuration points at the project (re-run `netscript agent init` after moving a project).
- **`plugins` warns or fails** — plugin diagnostics found an issue; the equivalent direct command is `netscript plugin doctor`.
- **Docs tools return `docs_corpus_not_found`** — the configured `--docs-root` / `NETSCRIPT_DOCS_ROOT` path does not exist; fix the path or remove the override to fall back to the packaged corpus.
- **`execute_command` returns a denial** — the command did not match the allowlist (see the data boundary above); run it directly in a terminal instead.

## Reading these docs as an agent

The site you are reading ships its own agent affordances, no MCP server required:

- **Every page has a Markdown twin.** The "View as Markdown" link near the top of each page points at clean Markdown distilled from the rendered page — component markup already resolved, links absolute — so an agent reads source-quality text instead of parsing HTML chrome. The twin lives at the page URL plus `index.md`: this page's twin is [`/ai/agent-tooling/index.md`](https://rickylabs.github.io/netscript/ai/agent-tooling/index.md), and the same suffix works on any page.
- **A tiered `llms.txt`.** [`/llms.txt`](https://rickylabs.github.io/netscript/llms.txt) is the index tier: every real page as an absolute canonical link with a one-line summary, grouped by section, plus a short note telling agents how to reach the twins. [`/llms-full.txt`](https://rickylabs.github.io/netscript/llms-full.txt) is the full tier: every page's Markdown twin concatenated into one corpus for bulk ingestion.

The ladder, cheapest first: start at `llms.txt`, fetch the twin of the one page you need, and reach for `llms-full.txt` only when you genuinely want everything. And the two halves meet: point the MCP server's `--docs-root` at a checkout of this site and `search_docs` runs over the same corpus.

## Run the protocol smoke

```bash
deno test --allow-all packages/cli/e2e/tests/agent/agent-mcp-stdio_test.ts
```

The smoke starts the public CLI binary, initializes MCP over stdio, verifies the 13-tool catalog, and checks docs, diagnostics, unreachable telemetry, and command denial behavior.

## Where to go next

[Reference   @netscript/mcp  Per-tool contracts, output bounds, and the execute_command policy of the agent-facing MCP server.](https://rickylabs.github.io/netscript/netscript/reference/mcp/) [Reference   CLI reference  The task-oriented cheat-sheet for every netscript command, including agent init and agent mcp.](https://rickylabs.github.io/netscript/netscript/cli-reference/) [Guide   MCP client stack  The other MCP surface: consume external MCP servers as tools inside your own product's agents.](https://rickylabs.github.io/netscript/netscript/ai/mcp/)

_Canonical: https://rickylabs.github.io/netscript/ai/agent-tooling/_

---

# Chat UI

The AI chat interface ships as a **copy-registry collection** in `@netscript/fresh-ui`: a composer, a message thread, tool-call cards, a model picker, and a generative-UI block renderer. alpha

These are **not** package subpath imports. The published `@netscript/fresh-ui` subpath exports (`.`, `./primitives`, `./interactive`, `./registry`) carry no chat symbols. The chat surface is a set of files the NetScript CLI **copies into your app**, where you own and edit them like any other source file. This is the same copy-source model as the rest of the Fresh UI — see [Fresh UI & design](https://rickylabs.github.io/netscript/capabilities/fresh-ui/) and [Customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/).

> Copy-registry, not a dependency
>
> The chat components are delivered through the
>
> ai
>
> collection in the fresh-ui copy registry. You do
>
> not
>
> import
>
> them from a
>
> @netscript/fresh-ui/chat
>
> subpath — that subpath does not exist. The CLI copies each item into your workspace, and from that point the code is
>
> yours
>
> : edit it, restyle it, delete what you do not need. Updates are a re-copy, not a version bump.

## The `ai` collection

The collection is described as the "AI / chat surface seams: grounded-agent citations, message thread, composer, model picker, and tool-call disclosure." Its items:

**The ai copy-registry collection**

| Item | Role |
| --- | --- |
| `prompt-input` | Chat composer: auto-grow textarea plus a toolbar (research / grounding pills, model picker, attach / screenshot / voice, send). |
| `message` | A chat message: author + time, inline-markup body (bold / code / `[n]` citations), tool-call and chart / code blocks, follow-up chips, typing indicator. Exports `renderInline` and `TypingIndicator`. |
| `markdown` | Sanitized streaming-markdown component plus its rendering pipeline. |
| `chat-render` | The generative-UI block parser (a `lib` item): copies `parse-blocks.ts` into your app. |
| `tool-call-card` | Tool-call disclosure card for an agent tool invocation. |
| `model-selector` | Model picker used by the composer. |
| `citation-chip` | Grounded-agent citation chip. |
| `code-block` | Rendered code block. |
| `chart-block` | Rendered chart block (a target of the generative-UI renderer). |
| `avatar` | Author avatar. |
| `command-palette` | Command palette surface. |
| `search` | Search surface. |
| `theme-seed` | Theme token seed for the chat surface. |

## The generative-UI renderer — `chat-render` / `parse-blocks`

The `chat-render` item copies `parse-blocks.ts` into your app (`@lib/chat/parse-blocks.ts`). It is the parser that turns streamed markdown into typed, renderable blocks — the seam that lets an agent emit a chart or a table inside its answer.

- **`parseBlocks(input: string): RenderPart[]`** — markdown → typed parts. It **never throws**; an unrecognized fenced block falls through to a verbatim `text` part.
- **`blockToText(part: RenderPart): string`** — the exact inverse projection (canonical markdown / plain-text fallback). `parseBlocks` is a boundary-stable fixed point, which is what gives the transcript reload fidelity.

### The presentation RenderPart

The renderer's `RenderPart` is a **rich presentation** union — distinct from the **transport** `RenderPart` in [`@netscript/fresh/ai`](https://rickylabs.github.io/netscript/ai/durable-chat/) (which is only `text | tool`). Keep the two separate: one describes how a chunk streams, the other describes how a block is drawn.

**Presentation RenderPart (chat-render) — one variant per rendered block**

| Name | Type | Description |
| --- | --- | --- |
| `chart` | `ChartRenderPart` | A chart block (payload `ChartDatum[]`). |
| `donut` | `DonutRenderPart` | A donut block (payload `DonutDatum[]`). |
| `table` | `TableRenderPart` | A table block (`TableColumn` / `TableRow`, with `TableAlign`). |
| `stats` | `StatsRenderPart` | A stats grid (payload `StatsEntry[]`). |
| `line` | `LineRenderPart` | A line chart (payload `LinePoint[]`). |
| `text` | `TextRenderPart` | Verbatim text — the fallback for any unrecognized fence. |

### The fenced-block grammar

`parseBlocks` reads a curated set of fenced-code info-strings — `chart`, `donut`, `table`, `stats`, `line` — and accepts either canonical JSON or a minimal DSL (`label: value @tone`, plus markdown pipe tables). A `RenderTone` colors a value; a fence whose info-string is not in the set is left as a verbatim `text` part, so ordinary code blocks pass through untouched.

```text
```chart
[{ "label": "Q1", "value": 42 }, { "label": "Q2", "value": 58 }]
```

```stats
Revenue: 1.2M @positive
Churn: 3% @negative
```
```

`parse-blocks.ts` is self-contained — it does not import `@netscript/fresh/ai`. The two `RenderPart` types are intentionally separate (presentation vs transport); reconciling them is a downstream concern, not something you wire by hand.

## Streaming markdown and the composer

Two components carry most of the interactive weight:

- **`markdown`** renders **sanitized streaming markdown** — safe to feed partial, mid-stream assistant text as chunks arrive, without waiting for a complete message.
- **`prompt-input`** is the composer: an **auto-grow** textarea that expands with the input, plus a toolbar for research/grounding pills, the model picker, attachment / screenshot / voice affordances, and send.

Because every item is copied into your workspace, restyling the composer, swapping the chart renderer, or removing the citation chip is a normal source edit — there is no package boundary to work around.

## Reference

[Look up — @netscript/fresh-ui  The generated reference for the fresh-ui package, including the copy-registry manifest surface.](https://rickylabs.github.io/netscript/netscript/reference/fresh-ui/)

[Do — customize Fresh UI  How the CLI copies components into your app and how you own them afterward.](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/customize-fresh-ui/)

[Back — durable chat  The runtime that produces the transcript these components render, and the transport RenderPart they widen.](https://rickylabs.github.io/netscript/netscript/ai/durable-chat/)

_Canonical: https://rickylabs.github.io/netscript/ai/chat-ui/_

---

# Durable chat

`@netscript/fresh/ai` is the server + island seam that turns a Fresh route into a **durable AI chat**: a chat whose message history and in-flight tool calls survive reload, reconnect, and multi-tab replay because they are backed by a durable session stream rather than component state. alpha

It composes three upstream libraries — `@durable-streams/tanstack-ai-transport`, `@tanstack/ai-preact`, and `@tanstack/ai` — and adds only NetScript glue: durable-stream URL resolution, server-side auth headers, and the projection law below. It does **not** import `@netscript/ai`, so it composes with the [AI engine](https://rickylabs.github.io/netscript/ai/engine/) but installs independently — you can adopt durable chat without pulling in the engine.

This subpath is published on JSR as part of `@netscript/fresh@0.0.1-beta.11` and is usable now.

## The primitives at a glance

**@netscript/fresh/ai — the durable-chat surface**

| Name | Type | Description |
| --- | --- | --- |
| `createNetScriptChatStreamProxy` | `(options) => handler` | Build the single durable chat-stream proxy handler — resolves the session target (static or per-request), proxies to the durable-stream URL with server auth, passes the body through unbuffered, and tears down on client abort. |
| `toNetScriptChatResponse` | `(options) => Promise` | Produce a durable-session `Response` from a server chat stream; enforces `authorize` (a denial becomes `403`) before the session stream is touched. |
| `resolveChatSnapshot` | `(options) => Promise` | Resolve the seed snapshot for SSR / first paint by materializing the session and reducing it through `projectChatSnapshot`. |
| `projectChatSnapshot` | `(messages) => {messages, renderParts}` | THE single projection reducer — deterministic and side-effect-free. Both seed and live paths MUST route through it (the one-projection law). |
| `createNetScriptChatConnection` | `(options) => NetScriptChatConnection` | Open a live durable session handle: SR2-tolerant `subscribe`, a `send` that persists client messages, and one idempotent teardown (`close`/`stop`/`dispose`). |

## The one-projection law

`resolveChatSnapshot` (the SSR/first-paint seed) and the live island projection MUST run **the same reducer** — `projectChatSnapshot`. They are two entry points into one function applied to one chunk log:

```text
chunks --> [ projectChatSnapshot ] --> { messages, renderParts }
```

If the seed path and the live path diverge — for example the server hand-rolls a snapshot while the island reduces chunks differently — **tool cards drift**: a card materialized at seed time renders differently, or vanishes, once the first live chunk arrives, because the two projections disagree about intermediate tool state. This is a hard invariant, not a nicety. Any downstream slice that adds a projection must route both seed and live through it.

> Route seed and live through one reducer
>
> Never build a bespoke snapshot for SSR and a separate live reducer for the island. Seed the first paint with
>
> resolveChatSnapshot
>
> (which calls
>
> projectChatSnapshot
>
> internally) and hand its
>
> offset
>
> to the live subscription so seed and live read one continuous chunk log. The returned
>
> renderParts
>
> are the transport render parts described below.

## The canonical chat-stream proxy

Every durable chat needs one route that proxies the browser's chat-stream request to the session's durable-stream URL. `createNetScriptChatStreamProxy` is that route — it resolves the session target (static or per-request), attaches server-side streams auth (via `getStreamsAuth` by default), passes the upstream body through **unbuffered**, strips headers that would misdescribe the re-framed bytes, and propagates the client `AbortSignal` so a disconnect tears the upstream fetch down. Use it directly as a Fresh `Handlers` entry.

```ts
// routes/api/chat/[sessionId].ts — the one canonical chat-stream proxy
import { createNetScriptChatStreamProxy } from "@netscript/fresh/ai";

const proxy = createNetScriptChatStreamProxy({
  // Resolve the session per request from the route param.
  target: (req) => ({
    sessionId: new URL(req.url).pathname.split("/").pop()!,
  }),
});

export const handler = { POST: proxy, GET: proxy };
```

> Why a raw Request here, not a route contract
>
> This resolver is the one documented exception to NetScript's typed-route rule:
>
> createNetScriptChatStreamProxy
>
> 's
>
> target
>
> only ever receives the raw
>
> Request
>
> , so the session id is parsed from
>
> req.url
>
> by hand. Everywhere else you build a URL or read a path param, prefer a bound
>
> `createRouteReference`
>
> contract so the pattern and its typed params come from one source of truth.

`NetScriptChatStreamProxyOptions` is small: a `target` (a `NetScriptChatSessionTarget` or a `(request) => NetScriptChatSessionTarget` resolver), an optional `auth` header provider (defaults to `getStreamsAuth` from `@netscript/plugin-streams-core`), and an optional `fetch` override for tests. The returned handler accepts a bare `Request` or a Fresh route context (anything with `.req`), so `{ POST: handler }` and a direct call in a test both work.

## Authorizing the session response

The proxy moves bytes; **authorization happens where you produce the session response**. `toNetScriptChatResponse` sanitizes a server-side chat stream into durable chunks and returns the session `Response`. Supply an `authorize` hook and the matching `request`: a denial yields `403 Forbidden` and the session stream is never touched.

```ts
// The server turn: persist the assistant stream into the durable session, gated by authorize.
import { toNetScriptChatResponse } from "@netscript/fresh/ai";

const response = await toNetScriptChatResponse({
  target: { sessionId },
  request,
  // REQUIRED in production — return false to deny (=> 403).
  authorize: (req, id) => sessionBelongsToUser(req, id),
  newMessages, // client messages to persist before the assistant turn
  source: assistantChatStream, // AsyncIterable of server chat chunks
});
```

> authorize is required in production — there is no default allow-all
>
> NetScriptChatAuthorize = (request, sessionId) => boolean | Promise<boolean>
>
> is optional at the type level (the framework cannot prove a caller is production), but the factory
>
> never
>
> bakes in a default allow-all. Ship a real
>
> authorize
>
> before exposing a chat route publicly — without one,
>
> toNetScriptChatResponse
>
> cannot gate access to the session stream. Supplying
>
> authorize
>
> without a
>
> request
>
> is a programming error and throws.

## Seeding first paint (SSR)

For SSR and first paint, materialize the session and reduce it through the one projection reducer with `resolveChatSnapshot`, then hand the returned `offset` to the live subscription so seed and live share one continuous log.

```ts
import { resolveChatSnapshot } from "@netscript/fresh/ai";

const snapshot = await resolveChatSnapshot({ target: { sessionId } });
// snapshot.messages   -> ordered NetScriptChatMessage[]
// snapshot.renderParts -> transport RenderPart[] (text + tool cards)
// snapshot.offset      -> replay cursor for the live subscription (or null if empty)
```

## The live connection

`createNetScriptChatConnection` opens the live session handle the island subscribes to. Its `subscribe` is SR2-tolerant (a first-subscribe that races a not-yet-created stream re-polls with backoff instead of throwing), `send` persists client messages, and `close`/`stop`/`dispose` are one idempotent teardown so no connection leaks.

```ts
import { createNetScriptChatConnection } from "@netscript/fresh/ai";

const chat = createNetScriptChatConnection({
  target: { sessionId },
  authorize: (req, id) => sessionBelongsToUser(req, id), // REQUIRED in prod
  initialOffset: snapshot.offset ?? undefined, // continue from the seed cursor
});

try {
  for await (const chunk of chat.subscribe(signal)) {
    render(chunk);
  }
} finally {
  chat.dispose();
}
```

## The transport RenderPart

The reducer emits a **minimal, transport-level** `RenderPart` — either reduced message `text` or a `tool` card reduced from the same chunk log. This is distinct from the **rich presentation** `RenderPart` owned by the [chat UI](https://rickylabs.github.io/netscript/ai/chat-ui/); the two are intentionally separate and must not be conflated. The transport part is the stable contract the UI widens.

**RenderPart (transport) — @netscript/fresh/ai**

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `"text" \| "tool"` | Whether this part renders message text or a tool card. |
| `id` | `string` | Stable id of this part within the transcript. |
| `role` | `"system" \| "user" \| "assistant" \| "tool"` | Author role the part belongs to. |
| `text` | `string?` | Reduced text (present when `kind === 'text'`). |
| `toolName` | `string?` | Invoked tool name (present when `kind === 'tool'`). |
| `toolState` | `"pending" \| "streaming" \| "complete" \| "error"` | Lifecycle state of the tool card reduced from the chunk log. |
| `input` | `unknown?` | Reduced tool input (may be partial while `streaming`). |
| `output` | `unknown?` | Reduced tool output, present once `complete`. |

The message and session shapes are equally small: `NetScriptChatMessage` (`{ id, role, content }`), `NetScriptChatSessionTarget` (`{ sessionId, baseUrl?, headers? }` — one durable stream per `sessionId`), and `NetScriptChatSnapshot` (`{ messages, renderParts, offset }`).

## The `ui://` sandbox — `@netscript/fresh/ai/sandbox`

The sandbox subpath serves themed `ui://` resources for MCP-driven UI. Its shipped piece is `createMcpSandboxHandler`: a Fresh route handler that serves a registered `ui://` resource selected by `?uri=`, injects the active theme's `--ns-*` custom properties, stamps `data-theme`, and applies a per-response CSP derived from the resource URI. `?theme=` selects a token set; an absent or unknown theme falls back to `defaultThemeName` (default `"default"`).

```ts
// routes/mcp/sandbox.ts
import { createMcpSandboxHandler } from "@netscript/fresh/ai/sandbox";

export const handler = {
  GET: createMcpSandboxHandler({
    resolveResource: (uri, { signal }) => registry.lookup(uri, { signal }),
    themes: {
      default: { "--ns-color-surface": "#ffffff" },
      dark: { "--ns-color-surface": "#111111" },
    },
  }),
};
```

> The broader MCP tool sandbox is not yet wired
>
> createNetScriptMcpSandbox
>
> (the chat-activity MCP tool sandbox that would merge agent tools and bridge the island
>
> useChat
>
> surface) is an FA3
>
> skeleton stub
>
> — it is not yet wired to a working chat activity. Only the
>
> ui://
>
> resource route handler (
>
> createMcpSandboxHandler
>
> ) is real today. Do not build on
>
> createNetScriptMcpSandbox
>
> yet.

## Reference

This page orients; the generated reference enumerates every exported symbol.

[Look up — @netscript/fresh  The generated API for the Fresh package, including the /ai and /ai/sandbox subpaths.](https://rickylabs.github.io/netscript/netscript/reference/fresh/)

[Next — the chat UI  The fresh-ui copy-registry components that render this transcript: composer, message thread, tool cards, and the generative-UI block renderer.](https://rickylabs.github.io/netscript/netscript/ai/chat-ui/)

[Understand — the two planes  Why chat lives on the durable-session plane and list/board data lives on the StreamDB plane.](https://rickylabs.github.io/netscript/netscript/ai/)

_Canonical: https://rickylabs.github.io/netscript/ai/durable-chat/_

---

# AI engine

This is the **engine guide** — how the pieces of `@netscript/ai` fit together and when to reach for each one. `@netscript/ai` is the provider-agnostic AI engine at the design center of the stack: a zero-`@netscript/*`-dependency, ports-and-adapters core that owns the domain vocabulary, the capability seams, the model registries, the tool system, the agent loop, MCP transports, and opt-in provider adapters. It wraps `@tanstack/ai*` and `@standard-schema/spec` and adds no schema DSL of its own. We keep this page at the "which piece, and why" altitude; the exact symbol tables live in the generated reference, linked at the end.

> Published in 0.0.1-beta.11
>
> @netscript/ai
>
> is
>
> published on JSR
>
> and installs today:
>
> deno add jsr:@netscript/ai
>
> . Every subpath on this page resolves against the published
>
> 0.0.1-beta.11
>
> surface. The engine carries zero
>
> @netscript/*
>
> dependencies, so you can adopt it on its own — the
>
> durable-chat runtime
>
> and
>
> chat UI
>
> each stand alone and neither requires it.

## The map: which subpath answers which question

**@netscript/ai — subpath exports**

| Subpath | Purpose |
| --- | --- |
| `.` | Runtime wiring + the model / embedding / vision registries. |
| `./contracts` | Domain vocabulary — pure types and the error hierarchy. |
| `./ports` | Capability seams (hexagonal) plus default port / registry factories. |
| `./tools` | Tool definition / validation / registry, plus the built-in `render_ui` contract. |
| `./agent` | The agent loop. |
| `./mcp` | MCP transport adapters (stdio + Streamable-HTTP). |
| `./anthropic` | Anthropic provider (side-effect self-register). |
| `./openai-compatible` | OpenAI-compatible chat provider. |
| `./openrouter` | OpenRouter chat provider (OpenAI-compatible base + reasoning option). |
| `./ollama` | Ollama local chat provider (OpenAI-compatible base + reachability preflight). |
| `./openai-embeddings` | OpenAI embeddings + vision provider. |
| `./testing` | Deterministic port fakes. |

A useful way to read that table: the top half is the engine (vocabulary, seams, tools, loop), the bottom half is what you opt into (providers) and how you test without them (fakes).

## The runtime and registries

`createAiRuntime(config)` is a **pure wiring** function: it resolves every capability port, defaulting each to a no-op or throwing implementation, with no IO and no global mutation. `getAiRuntime(config?)` is the process singleton (shaped like `getKv()`), with `resetAiRuntime()` and `isAiRuntimeInitialized()` alongside. Use `createAiRuntime` when you want an isolated instance (tests, one runtime per tenant); use `getAiRuntime` when the process should share one. `AiRuntimeConfig` mirrors the resolved runtime field-for-field, all optional, so you inject only the ports you have real implementations for — everything else stays a safe default until you need it.

Three registries sit at the root — models, embeddings, and vision — each with the same register / get / list / reset shape. Models are addressed by reference: a `ModelRef` is `string | ModelSelector`, and the string form is `"<provider>:<model>"`, e.g. `"anthropic:claude-sonnet-4-5"`. Errors are a small hierarchy rooted at `AiError`; the two you will actually catch are `AiNotConfiguredError` (you called a capability whose port was never injected) and `ModelProviderNotFoundError` (the reference names a provider that never registered).

## Contracts — the shared vocabulary

`@netscript/ai/contracts` is pure types with no IO — the vocabulary every layer above the engine speaks. It carries the `Message` / `MessageRole` conversation model, the multimodal `ContentPart` union (text, image, audio, video, document, each backed by a base64 or URL `ContentSource`), the model descriptors and capability flags, and the tool-call shapes.

The one contract worth internalizing before anything else is the **`AgentChunk` union** — the wire vocabulary the whole stack streams. A run yields text spans, tool calls, tool results, message boundaries, usage, and errors as discriminated chunks, always terminating in a final `done` chunk. The durable-chat runtime persists these chunks and the chat UI renders them, which is why the layers compose without adapters: they all speak `AgentChunk`.

The vocabulary also carries the generative-UI contract: `RENDER_UI_TOOL_NAME = "render_ui"`, `RenderUiResult`, and a `UiResource` whose `uri` is a `ui://` string (mirroring the MCP resource shape).

## Ports — the seams you wire

`@netscript/ai/ports` exposes the capability interfaces — telemetry, tool registry, embeddings, vision, MCP transport, skill loading, the agent loop, memory, and the chat/model provider seams — plus their registry and default factories. Two are worth calling out because they shape how you wire things:

- **`ModelProviderPort`** covers discovery (`listModels()`, `getModel()`, `supports()`), and `createChatClient?()` is optional on it — so a discovery-only provider can omit chat entirely. The agent loop injects the narrower `ChatModelProviderPort`, which requires `createChatClient(modelId)`.
- **`AgentMemoryPort`** — `append(threadId, message)` and `load(threadId)` are the base; **`recall?(threadId, query)` is optional and `undefined` by default**. There is no built-in semantic recall — guard `recall` and fall back to `load`.

## Tools — Standard Schema, no DSL

The tool system validates with **Standard Schema**, so you bring any conforming validator (zod, valibot, arktype, or hand-rolled) — the core adds no schema language.

- **`defineAiTool(name)`** returns a builder: `.describe()`, `.parameters(jsonSchema)`, `.input(schema)`, terminating in either `.server(handler)` or `.client()` (a deferred tool, e.g. `render_ui`).
- **`createToolRegistry(defs?)`** implements `ToolRegistryPort`; its `.dispatch(name, input, ctx?)` validates input before your handler runs and throws `ToolNotFoundError` / `ToolInputValidationError` when it should.
- **`renderUiTool`** is the built-in `render_ui` wire contract: schema-only and **client-deferred** (`result.deferred === true`). The engine runs **no renderer** — rendering is the [chat UI's](https://rickylabs.github.io/netscript/ai/chat-ui/) job.

## The agent loop

`createAgentLoop(deps)` builds the loop from injected collaborators: a required `modelProvider: ChatModelProviderPort`, plus optional `tools`, `history`, and `defaultMaxSteps`. `loop.run(input, options?)` returns an `AsyncIterable<AgentChunk>`; the loop exposes `loop.state` and `loop.stop()`.

The defaults are deliberately conservative: the built-in `slidingWindowHistory` strategy keeps `DEFAULT_HISTORY_WINDOW = 20` messages, and `DEFAULT_MAX_STEPS = 8` bounds how many tool-calling steps a run may take before it must settle. Hitting that bound throws `AgentMaxStepsExceededError` inside the run — the loop settles `errored`, yields an `error` chunk, then the final `done`, so a consumer never hangs on an unterminated stream.

## MCP transports

`@netscript/ai/mcp` adapts remote Model Context Protocol servers into the same tool registry the loop dispatches. `createMcpTransport(config)` takes a discriminated config (`kind: "stdio"` or `kind: "streamable-http"`) and returns an `McpTransportPort`; `registerMcpTools(registry, transport)` surfaces the remote tools and returns a registration whose `.stop()` detaches. The Streamable-HTTP transport reconnects with backoff, and auth (`none` / `api-token` / `oauth`) is injected by your app's startup wiring rather than hardcoded. The full client story — pooling multiple servers, auth modes, rendering `ui://` resources — is the [MCP guide](https://rickylabs.github.io/netscript/ai/mcp/).

## Provider adapters — opt-in side-effect imports

Providers self-register on import, mirroring `@netscript/kv/redis`. The base engine pulls **no** provider SDK; you opt in per provider, and an import is all it takes:

```ts
import "@netscript/ai/anthropic"; // self-registers the "anthropic" provider

const model = await getModel("anthropic:claude-sonnet-4-5");
```

Choosing between them is mostly a question of where your models live:

- **`./anthropic`** talks to Anthropic directly, catalog taken verbatim from `@tanstack/ai-anthropic`, `apiKey` defaulting to `ANTHROPIC_API_KEY`.
- **`./openai-compatible`** is the workhorse for any endpoint that speaks the OpenAI API: no fixed catalog (the remote endpoint owns its model list), and it throws `AiNotConfiguredError` rather than guessing when `baseURL` / `apiKey` are missing.
- **`./openrouter`** builds on the OpenAI-compatible base for OpenRouter (key from `OPENROUTER_API_KEY`) and adds a `reasoningEffort` option (`"low" | "medium" | "high"`) normalized to OpenRouter's wire format.
- **`./ollama`** builds on the same base for a local endpoint and runs a reachability preflight against the host first — so a missing local daemon fails fast instead of at the first token.
- **`./openai-embeddings`** registers for the embedding and vision seams, not chat: `.embed()` and `.analyze()`.

Per-provider config fields and defaults are enumerated in the [generated reference](https://rickylabs.github.io/netscript/netscript/reference/ai/).

## Testing — deterministic fakes

`@netscript/ai/testing` supplies port fakes so an agent or tool can be exercised without a network: fake chat model providers and agent loops that replay scripted turns and chunks, fake memory, embedding, and vision ports, an in-memory tool registry, and `createFakeTelemetryPort()` (whose `.records` capture emitted telemetry). The full factory list lives in the generated reference.

## Wiring tool and agent registries

Today you wire the engine's registries **directly** at app startup: `createToolRegistry(defs?)` from `@netscript/ai/tools` for tools and `createAgentLoop(deps)` from `@netscript/ai/agent` for agent loops. No codegen step sits between your files and the runtime — you register against the engine factories yourself.

> Not in this release: netscript generate ai
>
> A
>
> netscript generate ai
>
> codegen — compiling app-owned tool and agent files into name-keyed and stem-keyed registries — is a planned target but is
>
> not in the CLI today
>
> . The shipped
>
> netscript generate
>
> targets are
>
> plugins
>
> ,
>
> runtime-schemas
>
> , and
>
> aspire
>
> . Until an AI target lands, register tools and agent loops against the engine factories directly.

## Where the exact tables live

This guide stops at the altitude of "which piece, and why". For the complete, generated symbol tables — every export, signature, and config field — use:

- [`@netscript/ai`](https://rickylabs.github.io/netscript/netscript/reference/ai/) — the engine itself: runtime, contracts, ports, tools, agent loop, MCP transports, provider adapters.
- [`@netscript/plugin-ai`](https://rickylabs.github.io/netscript/netscript/reference/plugin-ai/) — the thin AI plugin delivery shell.
- [`@netscript/plugin-ai-core`](https://rickylabs.github.io/netscript/netscript/reference/plugin-ai-core/) — the plugin's reusable `/v1/ai` contract core.

And for the rest of the stack: the [AI overview](https://rickylabs.github.io/netscript/ai/) tells the layering story, [durable chat](https://rickylabs.github.io/netscript/ai/durable-chat/) covers the Fresh runtime, and the [chat UI](https://rickylabs.github.io/netscript/ai/chat-ui/) covers the components that render what this engine streams.

_Canonical: https://rickylabs.github.io/netscript/ai/engine/_

---

# AI & Agents — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/ai/how-to/_

---

# Build a durable chat

**Goal:** wire an AI chat onto a Fresh route whose message history and in-flight tool calls survive reload, reconnect, and a second tab — because the transcript is backed by a **durable session stream**, not component state. This recipe uses the [`@netscript/fresh/ai`](https://rickylabs.github.io/netscript/reference/fresh/) durable-chat plane (published on JSR in `@netscript/fresh`, usable now): one session route, one stream proxy, one SSR seed, and one client island.

The chat surface is built from four seams, each a single function:

**@netscript/fresh/ai — the four durable-chat seams**

| Name | Type | Description |
| --- | --- | --- |
| `toNetScriptChatResponse` | `session route` | Turn a server chat stream into a durable session Response; authorize-gated (→ 403 on deny). |
| `createNetScriptChatStreamProxy` | `the one proxy` | The single durable chat-stream proxy handler the browser reads through — strips misdescribing headers, attaches streams auth server-side. |
| `resolveChatSnapshot` | `SSR seed` | Materialize the transcript so far for first paint, reduced through projectChatSnapshot. |
| `createNetScriptChatConnection` | `client island` | Live handle over one session: subscribe / send, with idempotent close / stop / dispose. |

## Prerequisites

- A NetScript workspace with a scaffolded `apps/dashboard/` Fresh app (`netscript init`).
- The **streams runtime** reachable — durable sessions are addressed through the `@netscript/plugin-streams-core` seam. Add it with `netscript plugin install stream --name streams` and bring it up under Aspire.
- A model provider key. This recipe calls Anthropic directly through [`@tanstack/ai`](https://tanstack.com/ai); export `ANTHROPIC_API_KEY` before you start the app (Aspire injects it into the app process).
- A stable `sessionId` per conversation — one durable stream lives per `sessionId`.

## The one-projection law (read this first)

`resolveChatSnapshot` (the SSR seed) and the live island projection MUST run the **same** reducer — `projectChatSnapshot`. Seed and live are two entry points into one function:

```text
messages --> [ projectChatSnapshot ] --> { messages, renderParts }
```

If the seed path and the live path diverge, **tool cards drift**: a card materialized at first paint renders differently — or vanishes — once the first live chunk arrives, because the two projections disagree about intermediate tool state. Route both through `projectChatSnapshot` (the seed already does) and the transcript is reload-stable by construction.

## 1. The durable chat session route

This route runs one model turn and persists it to the durable session. Two things are non-negotiable: an `authorize` hook (there is **no** default allow-all), and that the model stream is handed to `toNetScriptChatResponse` as its `source`.

```ts
// apps/dashboard/routes/api/chat/[sessionId].ts
import { chat } from '@tanstack/ai';
import { anthropicText } from '@tanstack/ai-anthropic';
import { resolveChatSnapshot, toNetScriptChatResponse } from '@netscript/fresh/ai';

// Only the owner of a session may drive its turns. REQUIRED in production —
// the factory bakes in no default allow-all.
const authorize = (request: Request, sessionId: string): boolean =>
  sessionBelongsToUser(request, sessionId);

export const handler = {
  async POST(ctx: { req: Request; params: { sessionId: string } }): Promise<Response> {
    const { sessionId } = ctx.params;
    const target = { sessionId } as const;

    // History so far, reduced through the SAME projection the island uses.
    const snapshot = await resolveChatSnapshot({ target });
    const messages = snapshot.messages.map((m) => ({ role: m.role, content: m.content }));

    // Direct model wiring: a TanStack adapter + chat(). anthropicText() reads
    // ANTHROPIC_API_KEY from the environment when no key is passed.
    const adapter = anthropicText('claude-sonnet-4-5');
    const source = chat({
      adapter,
      messages,
      systemPrompts: ['You are a helpful assistant.'],
    });

    // Persist + stream the assistant turn into the durable session, gated by authorize.
    return toNetScriptChatResponse({
      target,
      request: ctx.req,
      authorize,
      source,
    });
  },
};
```

> authorize is required — do not skip it
>
> toNetScriptChatResponse
>
> only enforces access when you pass an
>
> authorize
>
> hook, and it applies
>
> no
>
> default. Without one, the session stream is unauthenticated. Supplying
>
> authorize
>
> without a
>
> request
>
> is a programming error and throws. Return
>
> false
>
> to deny — the response becomes
>
> 403 Forbidden
>
> and the session stream is never touched.

> The @netscript/ai engine is published — this recipe still shows the direct wiring
>
> This recipe calls the model through
>
> @tanstack/ai
>
> +
>
> @tanstack/ai-anthropic
>
> directly, the same way the reference chat app wires it on shipped seams. The
>
> @netscript/ai
>
> engine (model registry, provider ports, agent loop) is published on JSR as of
>
> 0.0.1-beta.11
>
> (
>
> deno add jsr:@netscript/ai@0.0.1-beta.11
>
> ) and can own this model-call layer behind
>
> import '@netscript/ai/anthropic'
>
> — see the
>
> AI engine
>
> page. The direct wiring below remains a valid, dependency-light path.

## 2. The one stream proxy

The browser never talks to the durable-streams service directly — it reads through a single proxy that attaches streams auth server-side and keeps every response header accurate. Mount `createNetScriptChatStreamProxy` once, as a catch-all under your API namespace.

```ts
// apps/dashboard/routes/api/chat-stream/[...path].ts
import { createNetScriptChatStreamProxy } from '@netscript/fresh/ai';

const proxy = createNetScriptChatStreamProxy({
  // Derive the session from the request path: /api/chat-stream/ai/chat/{sessionId}
  target: (req) => ({ sessionId: new URL(req.url).pathname.split('/').pop()! }),
});

export const handler = { GET: proxy, POST: proxy };
```

> Why a raw Request here, not a route contract
>
> This resolver is the one documented exception to NetScript's typed-route rule:
>
> createNetScriptChatStreamProxy
>
> 's
>
> target
>
> only ever receives the raw
>
> Request
>
> , so the session id is parsed from
>
> req.url
>
> by hand. Everywhere else you build a URL or read a path param, prefer a bound
>
> `createRouteReference`
>
> contract so the pattern and its typed params come from one source of truth.

The proxy passes the durable-stream body through **unbuffered**, strips `content-encoding` / `content-length` (they no longer describe the re-framed bytes) plus the hop-by-hop headers, and propagates the client `AbortSignal` so a disconnect tears the upstream fetch down. The `Authorization` header it overlays lives only on the server → streams hop; it is never echoed to the browser.

## 3. Seed the first paint (SSR)

In the page loader, materialize the transcript so the chat renders complete on first paint — no loading flash, and the same content a reload would show.

```ts
// apps/dashboard/routes/chat/[sessionId].tsx (loader)
import { resolveChatSnapshot } from '@netscript/fresh/ai';

const snapshot = await resolveChatSnapshot({ target: { sessionId } });
// snapshot -> { messages, renderParts, offset }
// `offset` seeds the live subscription so seed and live read one continuous log.
```

Pass `snapshot` into the island as its initial state. `renderParts` here is the **transport** shape (`text` | `tool`) — the minimal reducer output. The rich presentation parts (charts, tables) come from `parseBlocks` in the UI layer; see [Customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/) and the chat tutorial.

## 4. The client island

The island opens a durable connection, seeds from the SSR snapshot, `send`s the user message into the session, fires the model turn, and re-materializes when the turn settles. `close` / `stop` / `dispose` are one idempotent teardown — call it on cleanup.

```tsx
// apps/dashboard/islands/Chat.tsx
import { useSignal } from '@preact/signals';
import { createNetScriptChatConnection, resolveChatSnapshot } from '@netscript/fresh/ai';
import type { NetScriptChatSnapshot } from '@netscript/fresh/ai';

const Chat = ({ sessionId, seed }: { sessionId: string; seed: NetScriptChatSnapshot }) => {
  const snapshot = useSignal(seed);

  const connection = createNetScriptChatConnection({
    target: { sessionId, baseUrl: `${location.origin}/api/chat-stream` },
    initialOffset: seed.offset ?? undefined,
    authorize: (req, id) => sessionOwnedInBrowser(id), // REQUIRED in prod
  });

  const refresh = async () => {
    snapshot.value = await resolveChatSnapshot({
      target: { sessionId, baseUrl: `${location.origin}/api/chat-stream` },
    });
  };

  const onSubmit = async (text: string) => {
    // 1. Append the user message to the durable session.
    await connection.send([{ id: crypto.randomUUID(), role: 'user', content: text }]);
    // 2. Fire the model turn (the session route streams + persists the reply).
    await fetch(`/api/chat/${sessionId}`, { method: 'POST' });
    // 3. Re-materialize the settled transcript through the same projection.
    await refresh();
  };

  // Live durable updates (reload/second-tab replay); dispose on unmount.
  // for await (const chunk of connection.subscribe(signal)) { ... }
  // globalThis.addEventListener('beforeunload', () => connection.dispose());

  return renderTranscript(snapshot.value, onSubmit);
};

export default Chat;
```

> Transport RenderPart vs presentation RenderPart
>
> Two
>
> RenderPart
>
> types exist and must not be conflated.
>
> @netscript/fresh/ai
>
> emits the
>
> transport
>
> part (
>
> text
>
> |
>
> tool
>
> ) — the durable-session wire shape.
>
> @netscript/fresh-ui
>
> 's
>
> chat-render
>
> (
>
> parseBlocks
>
> ) owns the
>
> presentation
>
> part (
>
> chart
>
> |
>
> donut
>
> |
>
> table
>
> |
>
> stats
>
> |
>
> line
>
> |
>
> text
>
> ) — the rich blocks you render. The transcript reduces through the first; the UI renders through the second.

## Failure modes

- **`403 Forbidden` on the turn route:** `authorize` returned `false`, or the caller is not the session owner. This is the hook doing its job — not a bug.
- **`authorize` throws:** you passed `authorize` without a `request`. Thread `ctx.req` in.
- **Empty transcript on first subscribe:** a first-subscribe can race a not-yet-created session stream; `createNetScriptChatConnection` re-polls with backoff and returns an empty stream rather than a terminal error. A hard `401` / `403` propagates immediately.
- **Streams runtime unreachable:** the durable stream URL does not resolve. Confirm `netscript plugin install stream --name streams` ran and the streams service is up under Aspire.
- **Model call fails:** `ANTHROPIC_API_KEY` is unset or invalid — `chat()` surfaces the provider error into the assistant stream.

## Next steps

- Walk it end to end in the [AI Chat tutorial](https://rickylabs.github.io/netscript/tutorials/chat/).
- Render rich blocks and citation chips: [Customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/).
- The list/board/table live-data plane is different — see [Publish a durable stream](https://rickylabs.github.io/netscript/durable-workflows/how-to/publish-a-durable-stream/) and [Live Dashboard, chapter 05](https://rickylabs.github.io/netscript/tutorials/live-dashboard/05-live-stream/).
- Look up exact signatures in the [fresh reference](https://rickylabs.github.io/netscript/reference/fresh/).

[Customize Fresh UI](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/customize-fresh-ui/) [Deploy](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy/)

_Canonical: https://rickylabs.github.io/netscript/ai/how-to/build-a-durable-chat/_

---

# MCP

`@netscript/ai/mcp` is the **MCP client stack**: it turns external Model Context Protocol servers into typed tools your agent loop can call — transports, injected auth, multi-server pooling, and a safe rendering path for the `ui://` resources a tool result can carry. It is published as part of `@netscript/ai@0.0.1-beta.11` and installs with the engine: `deno add jsr:@netscript/ai@0.0.1-beta.11`.

> Two different MCP surfaces — don't conflate them
>
> This page documents the
>
> @netscript/ai/mcp
>
> client library
>
> : your app
>
> consumes
>
> external MCP servers as agent tools. That is a separate surface from the NetScript MCP
>
> server
>
> — a standalone stdio server for coding agents that you run with
>
> netscript agent mcp
>
> and install with
>
> netscript agent init
>
> . The server exposes framework-aware diagnostics, telemetry summaries, and doc search
>
> about
>
> your project; the client library on this page wires
>
> remote
>
> MCP servers
>
> into
>
> your product's agent loop. See
>
> Agent tooling
>
> and the
>
> `@netscript/mcp` reference
>
> for the server.

## The story: one config instead of a protocol integration

Your agent needs a capability that lives behind an MCP server — a docs-search server, an internal ops server, a vendor's tool endpoint. Wiring that by hand is a protocol integration, not a feature: JSON-RPC framing over stdio or HTTP, session lifecycle, reconnect-with-backoff when the connection drops mid-run, auth headers that must not be hardcoded, translating the server's tool schemas into whatever your agent's tool registry expects, and deciding what to do when a result embeds UI content you did not author. Every one of those steps is a place for an agent — human or AI — to burn a turn on glue that has nothing to do with the feature.

The `./mcp` subpath collapses that to configuration. You declare servers as data, register the pool into the same tool registry the [agent loop](https://rickylabs.github.io/netscript/ai/engine/) already dispatches through, and the remote tools become ordinary registry entries:

```ts
import { createMcpTransportPool, registerMcpTools } from "@netscript/ai/mcp";
import { createToolRegistry } from "@netscript/ai/tools";

const pool = createMcpTransportPool({
  servers: [{
    kind: "streamable-http",
    serverId: "search",
    url: "https://mcp.example.com",
    auth: { mode: "api-token", token: Deno.env.get("MCP_TOKEN")!, scheme: "Bearer" },
  }],
});

const registry = createToolRegistry();
const registration = await registerMcpTools(registry, pool);
// registration.toolNames — the remote tools, now dispatchable like any local tool
// registration.stop()   — detach them again
```

From here the agent loop treats a remote MCP tool exactly like a local `defineAiTool` definition — same registry, same dispatch, same [`AgentChunk` stream](https://rickylabs.github.io/netscript/ai/engine/) on the wire.

## Transports — stdio and reconnectable Streamable-HTTP

`createMcpTransport(config)` takes a discriminated config — `{ kind: "stdio" }` or `{ kind: "streamable-http" }` — and returns an `McpTransportPort`. The Streamable-HTTP transport is built for long-lived agent sessions: it reconnects with configurable backoff (`McpBackoffConfig`) and exposes its lifecycle as an observable state machine.

**Transport lifecycle — @netscript/ai/mcp**

| Name | Type | Description |
| --- | --- | --- |
| `McpConnectionState` | `"disconnected" \| "connecting" \| "connected" \| "reconnecting" \| "closed"` | The transport lifecycle union; `reconnecting` is a first-class state, not an error. |
| `onStateChange(handler)` | `(state, previous) => void` | Subscribe to lifecycle transitions (`McpStateChangeHandler`); returns an unsubscribe function. |
| `StreamableHttpMcpTransport` | `class` | The reconnectable Streamable-HTTP transport; configured via `StreamableHttpMcpTransportConfig` (serverId, url, auth, backoff). |
| `StdioMcpTransport` | `class` | The stdio transport for local process-based MCP servers. |

Auth is **injected at the composition root**, never baked into a transport class. `McpAuthConfig` is a three-mode union — `{ mode: "none" }`, `{ mode: "api-token", token, headerName?, scheme? }`, or `{ mode: "oauth", accessToken, tokenType? }` — so the same server declaration works across environments with only the secret changing.

## The pool — many servers, one tool namespace

Real agents talk to more than one server. `createMcpTransportPool(config)` builds a multi-server pool from **serializable** transport configs (so server declarations can live in configuration, not code); `createMcpTransportPoolFromTransports` wraps transports you already own. The pool is itself an `McpTransportPort`, so everything that accepts one transport accepts a pool of them.

**McpTransportPool — the multi-server surface**

| Name | Type | Description |
| --- | --- | --- |
| `connect(options)` | `Promise` | Open every pooled transport and return the discovered tools, name-prefixed by server id so two servers' tools never collide. |
| `listTools(options)` | `Promise` | Re-list tools from all pooled transports without tearing down warm connections. |
| `callTool(name, args, options)` | `Promise` | Route a prefixed tool name to its server and extract any `ui://` resources from the result. |
| `state / onStateChange` | `McpConnectionState` | The aggregate lifecycle across all pooled transports. |
| `server(serverId) / serverIds` | `McpTransportPort \| undefined` | Reach a single pooled transport when you need it. |
| `stop()` | `Promise` | Stop every pooled transport and clear discovered tool routes. |

`registerMcpTools(registry, transport)` is the bridge into the agent: it surfaces the remote tools into a `ToolRegistryPort` and returns an `McpToolRegistration` whose `.stop()` detaches them — registration is reversible, not a global mutation.

## `ui://` resources — tool results that carry UI, rendered safely

An MCP tool result can embed **`ui://` resources** — UI content authored by the server, not by you. The pool surfaces these on every `McpPooledToolResult` as `uiResources`, and `extractMcpUiResources(result)` pulls the **data-only** `McpUiResource` records from any raw tool result. The engine stops there by design: it extracts, it never renders.

Rendering belongs to the web layer, behind two guardrails you install with `netscript ui:add ai`:

- the **`McpUiWidget` island** (from the `@netscript/fresh-ui` copy registry) renders a `ui://` resource in a sandboxed frame — sanitized, themed through the sandbox route, `no-referrer`;
- the **`createMcpSandboxHandler`** route (on `@netscript/fresh/ai/sandbox`) serves the resource with the active theme's tokens and a per-response CSP — see [the durable-chat sandbox section](https://rickylabs.github.io/netscript/ai/durable-chat/) for the handler itself.

This is the same trust boundary as the [`render_ui` tool](https://rickylabs.github.io/netscript/ai/chat-ui/): model- or server-authored UI reaches the page only through a curated renderer or a sandbox, never as raw HTML in your island tree. The whole path is exercised by the framework's own merge gate — the CLI E2E suite drives a real Streamable-HTTP MCP round trip through this client stack into a rendered `McpUiWidget` before a branch can land.

## One comparison

Encore's MCP story points **inward**: it ships an MCP server that exposes a running Encore backend's introspection surface to coding agents, so an agent can inspect and verify the backend it is editing. NetScript ships **both halves**. The inward half is the `netscript agent mcp` server (documented under [Agent tooling](https://rickylabs.github.io/netscript/ai/agent-tooling/) and the [`@netscript/mcp` reference](https://rickylabs.github.io/netscript/reference/mcp/)): a stdio server that gives a coding agent framework-aware diagnostics, telemetry summaries, and doc search over the project it is editing. The outward half — this page — is the `@netscript/ai/mcp` client stack for consuming external MCP servers as tools inside your own product's agents, with a sandboxed path for the UI those tools return. Both paths are published and gate-tested.

## Where to go next

[The engine — ports, tools, agent loop  The @netscript/ai surface this stack plugs into: the tool registry, the agent loop, and the McpTransportPort seam.](https://rickylabs.github.io/netscript/netscript/ai/engine/)

[Durable chat — the sandbox route  createMcpSandboxHandler on @netscript/fresh/ai/sandbox: themed, CSP-guarded serving of ui:// resources.](https://rickylabs.github.io/netscript/netscript/ai/durable-chat/)

[Chat UI — rendering the transcript  The fresh-ui copy registry: tool cards, the render_ui block renderer, and the McpUiWidget island.](https://rickylabs.github.io/netscript/netscript/ai/chat-ui/)

[Look up — @netscript/ai  The generated reference for the engine package, including every ./mcp export.](https://rickylabs.github.io/netscript/netscript/reference/ai/)

_Canonical: https://rickylabs.github.io/netscript/ai/mcp/_

---

# CLI reference

This is the cheat-sheet: which `netscript` command we reach for, grouped by task. Each section lists the everyday spelling and stops there — every flag, subcommand, and extended verb lives in the [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/), and the embeddable TypeScript surface is on the [`@netscript/cli` package page](https://rickylabs.github.io/netscript/reference/cli/). Every command here uses the public `netscript <cmd>` form backed by the published JSR package; the vendored `packages/cli/...` path you may see in a local-source checkout is a contributor-only shape.

> Database commands need Aspire running first
>
> The
>
> netscript db ...
>
> commands provision and talk to your database
>
> through Aspire
>
> .
>
> cd aspire && aspire start
>
> brings up Postgres and Redis via Docker and opens the dashboard at
>
> :18888
>
> — do this
>
> before
>
> any
>
> db
>
> command (
>
> sqlite
>
> is the file-backed exception with no container). Run a
>
> db
>
> command with Aspire down and it fails to find the database — the “aspire start failed: project file does not exist” error almost always means exactly this. See the
>
> database & migration how-to
>
> .

## Install

The CLI is published to JSR as `@netscript/cli`. Install it globally for a tidy `netscript` command on your PATH, or run it ad-hoc with no install at all.

```bash
# Installs a `netscript` command on your PATH
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11

netscript --help
```

```bash
# Run the same CLI without installing anything
deno x jsr:@netscript/cli@0.0.1-beta.11 --help
```

```bash
# Re-run the install with --force to pull the latest published version
deno install --global --allow-all --force --name netscript jsr:@netscript/cli@0.0.1-beta.11
```

`netscript --version` prints the installed CLI version; `netscript --help` and `netscript <group> --help` (for example `netscript db --help`) show the exact flag spelling your installed version ships.

## The everyday flow

Most sessions follow the same shape, and the order matters: **Aspire (step 2) must be up before any `db` command (step 3).**

1 · Scaffold

netscript init lays down the whole workspace — contracts, an example service, plugins, and the Aspire layer.

2 · Orchestrate

cd aspire && aspire start brings up your database and Redis, and opens the dashboard at :18888. Do this before any db command.

3 · Database

netscript db init / generate / migrate / seed — only after Aspire is up.

4 · Extend & generate

netscript plugin install, then netscript generate plugins to wire the registry.

## Scaffold a workspace

**netscript init**

| Name | Type | Description |
| --- | --- | --- |
| `Create a workspace` | `netscript init my-app` | Scaffold everything — contracts, plugin registry, Fresh app, a default Redis cache, and the Aspire layer. On a terminal it prompts for whatever you omit (name, database, service, cache). |
| `Preview first` | `netscript init my-app --dry-run` | Print every file and directory the scaffold would create, and write nothing. |
| `Fully specified, no prompts` | `netscript init my-app --db postgres --service --service-name users --service-port 3001 --yes` | Postgres database support, an example oRPC `users` service on port 3001, defaults for the rest. `--yes` accepts defaults, `--ci` is non-interactive; both engage automatically when stdin is not a terminal. |
| `Pick a database engine` | `netscript init my-app --db postgres` | `postgres` (recommended), `mysql`, `mssql`, `sqlite`, or `none` — the default is no database unless you pass `--db`. |
| `Skip Aspire` | `netscript init my-app --no-aspire` | Scaffold without the .NET Aspire footprint; start the Fresh app directly with `deno task --cwd apps/dashboard dev`. |
| `Tune the rest` | `--cache-backend garnet · --model-name Product · --path ./apps · --editor zed` | Cache backend (`redis` default, `garnet`, or app-level `deno-kv`; `--cache=false` for none), the Prisma model name for the scaffolded CRUD surface, the target directory, and editor settings. |

Every `init` flag — including `--app-name`, `--no-git`, `--force`, `--json`, and `--from <preset>` — is spelled out in the [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Run & iterate

These are workspace `deno task`s, not `netscript` subcommands — the day-to-day loop once the scaffold exists.

**Run and gate the workspace**

| Name | Type | Description |
| --- | --- | --- |
| `Orchestrate everything` | `cd aspire && aspire start` | Bring up the database, Redis, services, and plugin processors, with the dashboard at :18888. |
| `Run the dashboard alone` | `deno task --cwd apps/dashboard dev` | Start the Fresh frontend directly (or let `aspire start` orchestrate it). |
| `Run a service alone` | `deno task --cwd services/users dev` | Start the example `users` oRPC service on port 3001. |
| `Check, lint, test` | `deno task check · deno task lint · deno task fmt · deno task test` | Type-check, lint, format, and test the whole workspace. |

## Services & contracts

A NetScript workspace is contract-first: you define an oRPC contract, then a service implements it.

**Services and contracts**

| Name | Type | Description |
| --- | --- | --- |
| `Add a service` | `netscript service add --name orders --port 3002` | Add a service workspace member, its v1 contract, and the Aspire registration. |
| `Add a contract` | `netscript contract add catalog-items` | Create `contracts/versions/v1/catalog-items.contract.ts` from the oRPC contract template and regenerate the v1 aggregate exports. |
| `Add a route + handler` | `netscript contract add-route · netscript service add-handler` | Append a typed procedure to a contract, then bind it with a compiling service handler stub. |
| `See what exists` | `netscript service list · netscript contract list · netscript contract inspect ` | List services, list v1 contract modules (and whether each has a matching service), and inspect a contract's procedures and schemas. |
| `Regenerate Aspire helpers` | `netscript service generate` | Regenerate the Aspire helper files from your service configuration. |

The full groups — `service set` / `remove` / `ref add`, `contract remove` / `version add`, and every flag — are in the [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Plugins

Plugins add capabilities — background workers, durable sagas, webhook triggers, durable streams, authentication. Public install adds the plugin package dependency, emits workspace-owned glue that imports it, and registers its contributions; the plugin's internals stay in the installed dependency.

**Plugin lifecycle**

| Name | Type | Description |
| --- | --- | --- |
| `Install an official plugin` | `netscript plugin install workers --name workers` | Bare aliases (`workers`, `auth`, …), scoped specs (`@netscript/plugin-workers`), and `jsr:` specs all work. After auth, pick the runtime backend with `NETSCRIPT_AUTH_BACKEND` — see [add authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/). |
| `Wire the registry` | `netscript generate plugins` | Regenerate the plugin registries from project source. Run this after every `plugin install`. |
| `Check health` | `netscript plugin list · netscript plugin doctor · netscript plugin info workers` | List registered plugins, run the wiring sanity check, and show a single plugin's details. |
| `Author your own` | `netscript plugin new billing` | Scaffold a new two-tier plugin: a JSR-publishable core package plus a thin connector. See [author a plugin](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/author-a-plugin/). |
| `Discover & maintain` | `netscript marketplace search  · netscript plugin update  · netscript plugin remove ` | Search the plugin marketplace, re-pin and regenerate an installed plugin, or remove one and update workspace registration. |

The extended verbs — `plugin sync`, `enable` / `disable` / `setup`, `item-add`, and the `plugin auth` backend/provider/session subcommands — are in the [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Database

The database workflow uses Prisma with a Deno runtime, and every command below requires Aspire to be running first (`cd aspire && aspire start`) — `sqlite` being the file-backed exception. Plugin schemas (`workers`, `sagas`, `triggers`, `auth`) are picked up by the same `generate` / `migrate` pass. The walkthrough is the [database & migration how-to](https://rickylabs.github.io/netscript/data-persistence/how-to/database-migration/).

**Database workflow (Aspire must be running)**

| Name | Type | Description |
| --- | --- | --- |
| `Initialize + first migration` | `netscript db init --name init` | Initialize database tooling and create the named migration. |
| `Generate the client` | `netscript db generate` | Generate the Deno-runtime Prisma client (and zod) — including plugin schemas such as `auth.prisma`. |
| `Migrate & seed` | `netscript db migrate · netscript db seed` | Apply migrations (including each plugin's contributed schema), then run the workspace seed scripts. |
| `Inspect` | `netscript db status · netscript db studio` | Show migration/tooling status, or open the database studio for browsing data. |
| `Recover` | `netscript db introspect · netscript db reset` | Introspect the configured database, or reset it back to a clean state. |
| `Multiple databases` | `netscript db add  · netscript db list` | Add a second database workspace to an existing project and list registered targets. |

The scaffolded workspace also defines Aspire-less `deno task db:*` tasks (`db:generate`, `db:migrate`, `db:seed`, `db:studio`, …) inside `database/<engine>/` that run Prisma directly — the form to use in deno-only or CI jobs. The target-management and migration-history verbs (`db deploy`, `validate`, `resolve`, `remove`) are in the [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Generate

After adding or changing plugins or configuration, regenerate the artifacts the project consumes.

**Code generation**

| Name | Type | Description |
| --- | --- | --- |
| `Plugin registries` | `netscript generate plugins` | Regenerate the plugin registries from project source — the post-install step. |
| `Runtime config schemas` | `netscript generate runtime-schemas` | Generate JSON Schema files for runtime configuration topics. |
| `Aspire helpers` | `netscript generate aspire` | Regenerate the Aspire AppHost helpers from `appsettings.json` without re-scaffolding. |

Related: `netscript config inspect` / `get` / `set` read and write the resolved project configuration, and `netscript config override` manages versioned runtime overrides — the full subcommand table is in the [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Fresh UI

The frontend is copy-source: components are copied into your repo under `apps/dashboard`, and the code is yours to own and edit. See [customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/).

**UI registry commands**

| Name | Type | Description |
| --- | --- | --- |
| `Initialize the design system` | `netscript ui:init --project-root apps/dashboard` | Copy the fresh-ui components and tokens into the dashboard app. |
| `Add a component` | `netscript ui:add  --project-root apps/dashboard` | Copy an additional registry item — you own the copied source from that point. |
| `List & maintain` | `netscript ui:list · netscript ui:update · netscript ui:remove ` | List registry items, update only files you have not modified, or remove a copied item. |

## Deploy

Two deploy paths are wired today: the **Deno Deploy** cloud target and the **Windows Service** (Servy) path. `netscript deploy docker` and `deploy compose` exist as command groups but are not wired — they only print help. See [deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/) for the portability story.

**Deploy commands**

| Name | Type | Description |
| --- | --- | --- |
| `Deno Deploy: preflight` | `netscript deploy deno-deploy plan` | Run the unstable-API guard (scans for `Deno.openKv`, `Deno.cron`, `BroadcastChannel`, `Temporal`) without pushing. The same guard **blocks** `up --prod` on a violation; a preview push warns but proceeds. |
| `Deno Deploy: lifecycle` | `netscript deploy deno-deploy up [--prod] · down · status · logs` | Push, delete, and inspect the deployment. A thin router over the native `deno deploy` CLI — it must be on your PATH and handles authentication. |
| `Windows Service: build` | `netscript deploy build` | Build the Windows Service deployment artifacts from a deployment manifest via Servy. |
| `Windows Service: lifecycle` | `netscript deploy install · start · stop · status · logs · upgrade · uninstall` | Install, run, inspect, upgrade, and remove Windows Services from the manifest. |

The shared flags (`--org`, `--app`, `--entrypoint`, `--env-file`, `--project-root`), the planning-only cloud targets, and the artifact-copy verbs are in the [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/).

## Agent tooling

**AI agent commands**

| Name | Type | Description |
| --- | --- | --- |
| `Install agent tooling` | `netscript agent init` | Install NetScript MCP and skills for detected agent hosts (`--host claude`, `vscode`, or `all`). |
| `Run the MCP server` | `netscript agent mcp` | Start the NetScript MCP server over standard input/output. |

See [Agent tooling](https://rickylabs.github.io/netscript/ai/agent-tooling/) for the mental model.

## The full surface

This page is the curated common path. For every command, every subcommand, and every flag — spelled exactly as the installed CLI prints it — go to the [command reference](https://rickylabs.github.io/netscript/reference/cli/commands/); for the embeddable package API, the [`@netscript/cli` package page](https://rickylabs.github.io/netscript/reference/cli/).

[Command reference  The exhaustive command surface — every command, subcommand, and flag verbatim.](https://rickylabs.github.io/netscript/netscript/reference/cli/commands/)

[Quickstart  Install → init → aspire start → db → hit an endpoint, in about five minutes.](https://rickylabs.github.io/netscript/netscript/quickstart/)

[Database & migration  The full db workflow, with the Aspire-up dependency spelled out step by step.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/)

[@netscript/cli package  The generated package reference — the embeddable TypeScript surface, not the command tree.](https://rickylabs.github.io/netscript/netscript/reference/cli/)

[Glossary](https://rickylabs.github.io/netscript/netscript/glossary/)

_Canonical: https://rickylabs.github.io/netscript/cli-reference/_

---

# Three ideas explain almost everything in NetScript.

The contract is the source of truth, the host is empty until plugins fill it, and one runtime brings up many resources together. Hold these three and the rest of the docs read as detail.

[Quickstart — 5 min](https://rickylabs.github.io/netscript/netscript/quickstart/) [Why NetScript](https://rickylabs.github.io/netscript/netscript/why/)

> Read this once
>
> This is the five-minute mental model — what talks to what, and nothing deeper; the *why* behind this shape lives in the
>
> architecture essay
>
> . Every capability hub, tutorial, and reference page assumes the three ideas below — so the time you spend here is paid back on every other page. Nothing here is aspirational: each claim links to the published surface that proves it.

NetScript is a Deno-native backend framework that generates a workspace you own and run yourself. It is not a hosted service and not a single library — it is a coordinated package family plus a CLI that wires the boring seams together. To reason about *any* part of it, you only need three ideas.

![A NetScript workspace: contracts define services; services, workers, sagas, triggers, streams, and auth plugins register against a host; the AppHost materializes each as an Aspire resource alongside Postgres, Redis, and the dashboard.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/architecture-overview.svg)

*The whole system in one picture: contracts at the center, plugins contributing to a host, and the AppHost bringing every resource up together.*

## Idea 1 — The contract is the source of truth

Most type drift in a TypeScript backend comes from having *two* sources of truth: the shape a service returns, and the shape the client believes it returns. NetScript removes the second one. You define an oRPC **contract** once; the typed client is *derived* from it, not generated alongside it. There is no codegen step to fall out of sync, and the type checker becomes your integration test — change the contract and every caller that no longer matches fails to compile.

```ts
// One source of truth — imported, not duplicated.
import { baseContract, OffsetPaginationQuerySchema } from '@netscript/contracts';
import { z } from 'zod';

export const usersContract = {
  list: baseContract
    .route({ method: 'GET', path: '/users' })
    .input(OffsetPaginationQuerySchema)
    .output(z.object({ items: z.array(z.object({ id: z.string(), email: z.string() })) })),
};
```

```ts
// `clients.users.list` is typed FROM the contract above — no second definition.
import { defineServices } from '@netscript/sdk';
import { usersContract } from './contracts/users.ts';

const { clients } = defineServices({ users: { contract: usersContract } });

const result = await clients.users.list({ limit: 20, offset: 0 });
console.log(result.items); // fully typed end to end
```

The same contract that types the client also drives the service router, the OpenAPI document, the Scalar docs, and — because every handler is span-wrapped — the traces. One definition, many consumers, zero hand-maintained duplicates. That is what "the contract is the product" means in practice. Go deeper in [contracts & type flow](https://rickylabs.github.io/netscript/netscript/explanation/contracts/) or the [services capability hub](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) .

## Idea 2 — The host is empty; plugins fill it

A NetScript application is a **host** that, on its own, does almost nothing. Capabilities — workers, sagas, triggers, streams, auth — arrive as **plugins**, and each plugin *registers* what it contributes rather than asking you to edit a central wiring file. Three nouns carry the whole model: a plugin declares a **manifest**, the manifest names a set of **contributions** against a fixed set of axes, and a generated **registry** turns those declarations into static modules the runtime imports.

```ts
// definePlugin(name, version) returns a builder. No behavior runs here —
// each .with*() call only NAMES a contribution against a fixed axis.
import { definePlugin } from '@netscript/plugin';

export const workersManifest = definePlugin('@netscript/plugin-workers', '0.0.1-beta.11')
  .withService({ name: 'workers-api', entrypoint: './services/src/main.ts', port: 8091 })
  .withBackgroundProcessor({ name: 'workers-worker', entrypoint: './bin/worker.ts', concurrency: 2 })
  .withDbSchemas([{ path: './database/workers.prisma', engine: 'postgres' }])
  .build();
```

Because the host only understands a *fixed* set of contribution shapes — a service, a background processor, a schema fragment, a stream topic, a config topic — but *any number* of plugins may contribute against them, capabilities compose without the host ever growing new code. Adding one is a regeneration step (`netscript plugin install …` then regenerate the registry), never an edit to someone else's boundary. And because a plugin's HTTP API and its background work are materialized as *separate* resources, a crash in a worker never takes down the API.

![A single plugin splits into an HTTP API service resource and one or more isolated background-processor resources, each started by the AppHost as a separate Aspire resource with its own permissions.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/plugin-thread-isolation.svg)

*"One plugin" is a packaging unit, not a runtime unit: at runtime it fans out into one API service and N isolated background resources.*

The full walkthrough — core/plugin split, the contribution axes, and why the registry is generated rather than scanned — is in [the plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) . The auth plugin is the model at its richest: see [the auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) .

## Idea 3 — One runtime, many resources

The third idea is what turns a pile of packages into a system you can *run*. NetScript is Deno-native and distributed on JSR — you import from `jsr:@netscript/*` and use Web Platform APIs you already know. But a real backend is never one process, so the generated workspace ships an **AppHost** that brings every resource up together through .NET Aspire: your database, your cache (`redis` by default, or `garnet` / `deno-kv` via `--cache-backend`), each plugin's service and background processors, and a real dashboard — locally and on the way to deploy.

![The AppHost graph: Postgres and Redis at the base; service, workers-api, sagas, triggers, auth-api, and streams resources above them; the Aspire dashboard observing all of them.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/aspire-resource-graph.svg)

*One command brings up the whole graph: data stores first, then every service and background resource, with the dashboard wired in for traces and logs.*

The flow is two commands — `cd aspire && aspire start` brings up your database and Redis *before* any `netscript db` command touches the database — and you watch the result in the Aspire dashboard at `:18888`. Postgres is the recommended default; pass `--db mysql`, `--db mssql`, or `--db sqlite` at scaffold time to pick another engine (Postgres, MySQL, and SQL Server run as Aspire container resources, while SQLite is file-backed).

**What comes up when you run the workspace (ports are range-allocated conventions; the dashboard is the authority)**

| Name | Type | Description |
| --- | --- | --- |
| `Aspire dashboard` | `:18888` | Every resource, trace, and log in one place — you don't stand up your own observability stack. |
| `Your service` | `:3000` | The oRPC API the contract drives, served at /api/rpc/* with OpenAPI and health wired in. |
| `Plugin services` | `:8091–:8094` | Each plugin's API runs as its own resource — workers :8091, sagas :8092, triggers :8093, auth :8094. |
| `Data stores` | `Postgres · Redis` | Brought up first, before migrations run; provisioned by the AppHost, not a hand-written compose file. Postgres is the recommended engine — pass --db postgres; mysql / mssql / sqlite / none are the other choices. |

The whole runtime is opt-out, not lock-in: [scaffold with](https://rickylabs.github.io/netscript/netscript/quickstart/) `netscript init my-app --no-aspire` and the .NET footprint is gone, leaving the Deno workspace you own. How the AppHost reads manifests and materializes resources is covered in [orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) and the [runtime configuration hub](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/runtime-config/) .

## How the three ideas connect

They are one idea seen from three angles. The **contract** defines what a capability exposes; a **plugin** packages that capability and declares how it contributes; the **runtime** materializes every contribution as an isolated resource and traces it end to end. Drift can't open up between layers because each layer derives from the one before it — the client from the contract, the registry from the manifests, the resource graph from the registry.

[Learn it by building  Pick a track and ship one complete app end to end — the fastest way to feel all three ideas at once.](https://rickylabs.github.io/netscript/netscript/tutorials/)

[Map the capabilities  Every feature, hub by hub, each with a Learn / Do / Reference triplet.](https://rickylabs.github.io/netscript/netscript/capabilities/)

[Read the architecture  The deep why behind the three ideas — the full essay this page is the five-minute version of.](https://rickylabs.github.io/netscript/netscript/explanation/architecture/)

> Still beta
>
> NetScript is in
>
> beta
>
> (targeting a stable release in late 2026). The published package surface is the contract: what you import from
>
> jsr:@netscript/*
>
> is what's documented and type-checked. Every
>
> @netscript/*
>
> package shares one aligned version (
>
> 0.0.1-beta.11
>
> ) and releases move in lockstep. Scaffolded JSR imports use exact
>
> @0.0.1-beta.11
>
> pins for the beta train. Build with us — but pin your versions.

[Quickstart — 5 minutes](https://rickylabs.github.io/netscript/netscript/quickstart/)

_Canonical: https://rickylabs.github.io/netscript/concepts/_

---

# Glossary

NetScript is a small framework with a handful of load-bearing words. Most of the friction in learning it is vocabulary, not syntax — once you can map a term to the file it lives in and the API that produces it, the rest of the docs read quickly.

This page is the dictionary. Every entry is one to three sentences, grounded in the real scaffold and reconciled to the current framework, and links to the canonical page where the term is *taught* (the Explanation that gives you the mental model, the Capability hub that shows the headline API, or the generated [Reference](https://rickylabs.github.io/netscript/reference/) that lists every export). Use it as a lookup, not a tutorial: when a page drops a word like **contribution**, **single-active-backend**, or **durability tier** and you want the precise meaning, come here, then follow the link back into the learning thread.

> How to read an entry
>
> The middle column is the
>
> headline API or file
>
> a term maps to — the concrete thing you type or open. The description links to where it is taught. Terms are alphabetized within each table; related terms cross-reference each other so you can chase a concept across the
>
> Explanation
>
> ,
>
> Capabilities
>
> , and
>
> Reference
>
> zones without a dead end.

## Core vocabulary

These are the words you will meet first — in the [Quickstart](https://rickylabs.github.io/netscript/quickstart/), the [tutorials ladder](https://rickylabs.github.io/netscript/tutorials/), and the [architecture overview](https://rickylabs.github.io/netscript/explanation/architecture/).

**A–C**

| Name | Type | Description |
| --- | --- | --- |
| `AppHost` | `aspire/apphost.mts` | The Aspire orchestration entry point that boots your whole workspace — Postgres, Redis, services, and plugin processors — as one resource graph with a dashboard at https://localhost:18888. In NetScript the AppHost is a **generated Node/TypeScript** file (`aspire/apphost.mts`) driven by `aspire.config.json` and `appsettings.json`, not a dotnet project. You start it with `cd aspire && aspire start`, and it must be up *before* any `netscript db` command. See [Explanation → Aspire](https://rickylabs.github.io/netscript/explanation/aspire/) and [reference/aspire/](https://rickylabs.github.io/netscript/reference/aspire/). |
| `archetype` | `doctrine classification` | The architectural category a package or plugin belongs to (for example a contract unit, an adapter, a runtime, or a plugin), which determines its public surface, quality gates, and allowed dependencies. Archetype is a *framework-internal* doctrine term; as an app author you mostly meet it indirectly through the shape of a scaffolded plugin. See [Explanation → Plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/). |
| `Aspire` | `aspire start` | The .NET Aspire orchestration layer NetScript uses for local development. It provisions your database (Postgres is the recommended engine; or `mysql` / `mssql` via `--db`, each an Aspire container resource — `sqlite` is file-backed and adds no container) and Redis as Docker containers and wires every service and plugin processor together with health, logs, and OTLP traces — no manual `docker compose`. The escape hatch is `netscript init --no-aspire` for a leaner single-process loop. See [Explanation → Aspire](https://rickylabs.github.io/netscript/explanation/aspire/) and [How-to → Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/). |
| `AuthBackendPort` | `@netscript/plugin-auth-core/ports` | The single seam every authentication backend implements — defined by `@netscript/plugin-auth-core`, it composes provider, session-store, crypto, and principal-mapper sub-ports plus an `authenticate(request)` method and an *optional* `interactive` flow. Backends are pure adapters behind this port; the host never special-cases a vendor. See [Capabilities → Authentication](https://rickylabs.github.io/netscript/capabilities/auth/) and [Explanation → Auth model](https://rickylabs.github.io/netscript/explanation/auth-model/). |
| `AuthBackendOperationUnsupportedError` | `typed capability boundary` | The typed error a backend throws when you call an operation it does not implement — for example a session mutation on a stateless backend, or an interactive sign-in on a non-interactive one. It makes the **single-active-backend** capability matrix fail loud rather than silently no-op, so missing surface is a visible error, not a mystery. See [Explanation → Auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) and the [Capabilities → Auth](https://rickylabs.github.io/netscript/capabilities/auth/) export list. |
| `AuthSession` | `@netscript/plugin-auth-core/domain` | The domain record for an authenticated session — id, user, account, and state (`active` \| `expired` \| `revoked`) — defined as a Zod-validated type in `@netscript/plugin-auth-core`. It is the durable shape the session store reads and writes and the entity the auth stream projects. See [Explanation → Auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) and [Capabilities → Authentication](https://rickylabs.github.io/netscript/capabilities/auth/). |
| `capability` | `/capabilities//` | A first-class thing NetScript does — services, background jobs, durable sagas, triggers, streams, authentication, database, KV/queues/cron, telemetry, and the Fresh UI. Each capability has a hub page pairing a one-screen concept with its headline API and a Learn / Do / Reference triplet. See the [Capabilities](https://rickylabs.github.io/netscript/capabilities/) index. |
| `composition root` | `netscript.config.ts` | The single place where a NetScript app is assembled — `defineConfig({...})` declares the project name, path layout, logging, databases, and plugin entrypoints such as generated `./auth/mod.ts` glue or author-owned `./plugins/<name>/mod.ts`. It is the wiring manifest the runtime reads to know what your app is made of. See [Explanation → Architecture](https://rickylabs.github.io/netscript/explanation/architecture/) and [reference/config/](https://rickylabs.github.io/netscript/reference/config/). |
| `contract` | `oc.route().input().output()` | The versioned, schema-first definition of an API — built with [@orpc/contract](https://orpc.unnoq.com) plus [zod](https://zod.dev) in `contracts/versions/v1/` — that locks the request and response shape *before* any handler exists. Passing a contract to `implement(Contract)` produces the object whose `.handler(...)` methods the service router binds, so the client and server share one source of truth. This is the heart of NetScript's contracts-first model. See [Explanation → Contracts](https://rickylabs.github.io/netscript/explanation/contracts/) and [reference/contracts/](https://rickylabs.github.io/netscript/reference/contracts/). |
| `contribution` | `plugin manifest export` | A typed unit of functionality a plugin contributes to the host — a job, a saga, a webhook trigger, a route, an Aspire resource, or a database schema — surfaced through the plugin's `mod.ts` **manifest** so the runtime can discover and wire it. The auth plugin, for instance, contributes a service, a Prisma schema, and durable stream events through its manifest. See [Explanation → Plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/). |

**C–J**

| Name | Type | Description |
| --- | --- | --- |
| `compensation-as-effect` | `handler return value` | How the scaffolded saga sample models rollback: instead of an explicit `.step()` / `.compensate()` chain, a message handler *returns an array of effects* (such as `sagaComplete({...})`) that the runtime applies. Compensation is just another effect a handler can emit. See [Explanation → Durability model](https://rickylabs.github.io/netscript/explanation/durability-model/). |
| `durability tier` | `.durability('t1')` | The persistence guarantee a saga declares in its builder chain — for example `'t1'` in `defineSaga(id).durability('t1')` — telling the runtime how durably to checkpoint the saga's state across messages. This is distinct from the **saga store backend** (kv \| prisma), which is *where* that state is written. See [Explanation → Durability model](https://rickylabs.github.io/netscript/explanation/durability-model/) and [Capabilities → Durable sagas](https://rickylabs.github.io/netscript/capabilities/durable-sagas/). |
| `durable` | `saga state checkpointing` | Describes work that survives process restarts because its progress is persisted, not held only in memory. NetScript's sagas are durable: their state is checkpointed per the chosen durability tier — to the **saga store backend** (kv or prisma) — so a long-running, message-driven workflow can resume after a crash. See [Explanation → Durability model](https://rickylabs.github.io/netscript/explanation/durability-model/). |
| `InteractiveFlowPort` | `optional AuthBackendPort member` | The optional sub-port a backend implements when it drives a redirect-based sign-in (the `signIn` / `handleCallback` / `getSessionId` / `signOut` flow). Only the `kv-oauth` backend exposes it; on `workos` and `better-auth` the `signin` / `callback` endpoints return a typed provider error because they have no interactive flow. See [Explanation → Auth model](https://rickylabs.github.io/netscript/explanation/auth-model/). |
| `job` | `defineJobHandler(async (ctx) => …)` | A unit of background work authored with `@netscript/plugin-workers-core`, returning `createSuccessResult({...})` or `createFailureResult(...)` and tagged with an id via `Object.assign(handler, { id })`. Jobs run on the workers processor and are triggered over HTTP at `POST /api/v1/workers/jobs/{id}/trigger` on port 8091. Job dispatch and execution are instrumented with real OpenTelemetry spans (see **OTel / observability**). See [Tutorial → Background jobs](https://rickylabs.github.io/netscript/tutorials/erp-sync/) and [Capabilities → Background jobs](https://rickylabs.github.io/netscript/capabilities/background-jobs/). |

**M–P**

| Name | Type | Description |
| --- | --- | --- |
| `manifest` | `plugins//mod.ts` | A plugin's public face — its `mod.ts` — which exports the plugin object (for example `workersPlugin` or `authPlugin`), an inspector (`inspectWorkers`, `inspectAuth`), and the contribution types the host discovers. The composition root references each plugin by its manifest path, and a generated **registry** aggregates them. See [Explanation → Plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/). |
| `oRPC` | `@orpc/contract · @orpc/server` | The contract-and-RPC toolkit ([@orpc/*](https://orpc.unnoq.com), pinned at ^1.14.6) that underpins NetScript's typed APIs: contracts are declared with `oc.route().input().output()`, implemented with `implement(...)`, served by `defineService` / `createService`, and consumed by a fully typed client. Workers, sagas, the auth service, and triggers all expose oRPC (mounted under `/api/rpc/*`); triggers' only exception is the raw, HMAC-verifying **webhook ingress endpoint**. See [Explanation → Contracts](https://rickylabs.github.io/netscript/explanation/contracts/). |
| `opaque session token (HMAC)` | `createHmacSessionTokenCrypto(secret)` | The default session-token scheme in the auth core — a WebCrypto HMAC-SHA256 token that carries no readable claims (opaque to the client) and is verified server-side against a secret. It is what the `AuthSessionCryptoPort` produces by default, so a stolen token reveals nothing and cannot be forged without the secret. See [Explanation → Auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) and [Capabilities → Auth](https://rickylabs.github.io/netscript/capabilities/auth/). |
| `plugin` | `package + generated glue` | An installable, thread-isolated capability. Public workspaces install plugin packages with commands such as `netscript plugin install @netscript/plugin-workers`, which add the dependency and emit user-owned glue/sample files that import the package; local-source contributor samples use `deno run -A packages/cli/bin/netscript-dev.ts plugin install worker --name workers --samples`. The plugin's contracts, services, runtime entrypoints, and Prisma schema stay in the installed package unless you are authoring or syncing full source. See [Explanation → Plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/) and [How-to → Add a plugin](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/add-a-plugin/). |
| `Principal` | `@netscript/service/auth` | The authenticated identity an authenticator resolves from a request — id, scopes, and a `scheme` (`'api-key'` \| `'bearer'` \| `'trusted-header'` \| `'custom'`). The auth-plugin backends map their sessions to a Principal with `scheme: 'custom'`, so service-layer authz treats vendor-backed identities uniformly. See [Explanation → Auth model](https://rickylabs.github.io/netscript/explanation/auth-model/). |

**R–S**

| Name | Type | Description |
| --- | --- | --- |
| `registry` | `generated registry file` | A generated index the runtime reads to discover what your app contains without runtime reflection. `netscript plugin list` emits the plugin registry, and the workers profile generates a jobs registry (for example to `.netscript/generated/plugin-workers/job-registry.ts`, keyed by job id). Registries are derived artifacts — regenerate them, do not hand-edit. See [Explanation → Plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/). |
| `saga` | `defineSaga(id)…build()` | A durable, message-driven workflow authored with the fluent builder from `@netscript/plugin-sagas-core`: `defineSaga(id).durability('t1').state<S>({...}).on<Type,Payload>(type, handler).build()`. Each `.on(...)` handler reacts to a message and returns effects such as `sagaComplete({...})`. Runtime state persists to a chosen **saga store backend** (kv \| prisma). The sagas service lists registered sagas at `/api/v1/sagas/sagas` on port 8092. See [Tutorial → Durable workflow](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/) and [Capabilities → Durable sagas](https://rickylabs.github.io/netscript/capabilities/durable-sagas/). |
| `saga store backend` | `NETSCRIPT_SAGA_STORE=kv\|prisma` | Where a durable saga runtime persists its checkpointed state — selectable as `'kv'` or `'prisma'` via `NETSCRIPT_SAGA_STORE` (or appsettings `sagas.store.backend`) and constructed with `createDurableSagaRuntime({ backend, prisma })`. The selection is *mandatory* — the runtime throws if it is unset, and Prisma mode requires a client. This is distinct from a saga's **durability tier**. See [Capabilities → Durable sagas](https://rickylabs.github.io/netscript/capabilities/durable-sagas/) and [Explanation → Durability model](https://rickylabs.github.io/netscript/explanation/durability-model/). |
| `service` | `defineService(router, {...})` | An oRPC HTTP application. Local app services use a one-shot `defineService(router, { name, version, port, openapi })` call (the `users` service on port 3001), while plugin API services use the fluent `createService(router, {...}).withCors()…serve()` builder — two construction APIs in the same project. oRPC is served at `/api/rpc/*`; the service layer also offers an authn/authz middleware seam (`.withAuthn()` / `.withAuthz()`). See [Capabilities → Services](https://rickylabs.github.io/netscript/capabilities/services/) and [reference/service/](https://rickylabs.github.io/netscript/reference/service/). |
| `single-active-backend` | `NETSCRIPT_AUTH_BACKEND` | The hard v1 boundary of the auth plugin: exactly one authentication backend is active at a time — `kv-oauth` (default), `workos`, or `better-auth` — chosen by `NETSCRIPT_AUTH_BACKEND` (or appsettings `auth.backend`); the unified auth oRPC service answers on port `:8094`. There is no multi-active routing, cross-backend account linking, global logout, or historical session replay yet. See [Capabilities → Authentication](https://rickylabs.github.io/netscript/capabilities/auth/) and [Explanation → Auth model](https://rickylabs.github.io/netscript/explanation/auth-model/). |
| `stream` | `createDurableStream({...})` | A typed, durable event-stream abstraction. The **producer runtime is real**: `createDurableStream({ streamPath, schema, producerId })` from `@netscript/plugin-streams-core` writes durable entity state, served as an Aspire service on port 4437 and wired into workers, auth, and sagas. The `@netscript/plugin-streams` manifest helpers `defineStreamProducer` / `defineStreamConsumer` are intentional stubs that *throw* `StreamUnsupportedOperationError` and redirect you to the core; there is no in-process consumer `subscribe()` (consumption is HTTP/SSE). See [Capabilities → Streams](https://rickylabs.github.io/netscript/capabilities/streams/) and [reference/streams/](https://rickylabs.github.io/netscript/reference/streams/). |

**T–Z**

| Name | Type | Description |
| --- | --- | --- |
| `trigger` | `defineWebhook(handler, {...})` | An inbound event source — most commonly a webhook — authored with `defineWebhook(handler, { id, path, verifier, tags })` from `@netscript/plugin-triggers-core/builders`. The handler returns an array of effects binding an HTTP request to background work. The **supported action is** `enqueueJob(jobRef, { payload, priority })` (live); `defer` is defined-but-unsupported — it *throws* and routes the message to the DLQ, with no deferred replay. Like workers and sagas, the triggers service serves a **typed v1 oRPC contract** for trigger and event introspection plus management on port 8093; the one exception is the raw, HMAC-verifying **webhook ingress endpoint** (`POST /api/v1/webhooks/:triggerId`). See [Tutorial → Ingest a webhook](https://rickylabs.github.io/netscript/tutorials/storefront/05-shipping-webhook/) and [Capabilities → Triggers](https://rickylabs.github.io/netscript/capabilities/triggers/). |

## Less common, still load-bearing

A second tier of words you will meet once you go past the happy path — the toolchain, the data layer, the auth seams, and the moving parts under a running plugin.

**Infrastructure, data & auth internals**

| Name | Type | Description |
| --- | --- | --- |
| `appsettings.json` | `infra config` | The root infrastructure manifest the Aspire **AppHost** actually reads — declaring `NetScript.Databases` (the database engine — Postgres is the recommended engine, or `mysql` / `mssql` / `sqlite` selected at scaffold with `--db` — container mode, primary database), `NetScript.Cache` (the `redis` cache by default; `garnet` or `deno-kv` via `--cache-backend`), the services, and the per-plugin `Workdir`s. It is also where backend selections like `sagas.store.backend` and `auth.backend` can live. Note that `netscript.config.ts`'s `databases` block is intentionally near-empty; the live DB/cache config lives here. See [Explanation → Aspire](https://rickylabs.github.io/netscript/explanation/aspire/). |
| `auth backend` | `@netscript/auth-*` | A pure adapter that implements **AuthBackendPort**: `kv-oauth` (interactive OAuth/OIDC redirect flow, KV sessions — the only one exposing **InteractiveFlowPort**), `workos` (AuthKit sealed cookie, non-interactive), and `better-auth` (Prisma-backed, non-interactive). The plugin composes exactly one — see **single-active-backend** — and serves the unified auth oRPC surface on port `:8094`. See [Explanation → Auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) and [How-to → Add authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/). |
| `background processor` | `bin/combined.ts` | The separate, long-running process that executes a plugin's work, distinct from its HTTP API service. Workers run from `bin/combined.ts`; sagas run from `src/runtime/saga-runner.ts`; triggers run from `src/runtime/trigger-processor.ts`. The AppHost starts these as their own Aspire resources. See [Explanation → Plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/). |
| `Garnet` | `Cache.garnet (KV)` | One of the Redis-compatible cache/KV backends Aspire can provision as a container alongside Postgres (the default is `redis`; select Garnet with `--cache-backend garnet`), used for executions, saga registry metadata, kv-oauth sessions, and Deno KV-backed state. See [Capabilities → KV / queues / cron](https://rickylabs.github.io/netscript/capabilities/kv-queues-cron/) and [reference/kv/](https://rickylabs.github.io/netscript/reference/kv/). |
| `OTel / observability` | `@netscript/telemetry` | OpenTelemetry tracing and structured logging wired into the framework. Job dispatch, execution, step events, progress, scheduler runs, and subprocess trace continuation emit *real* spans — traces show up in Aspire automatically (OTLP endpoint at http://localhost:4318). The one remaining gap is the scaffold `createJobTools(ctx)` handler helpers (`trace.addEvent` / `withChildSpan` / `progress`), which are still no-op stubs (tracked debt, fix planned) — for custom handler spans call `@netscript/telemetry` helpers directly. See [Explanation → Observability](https://rickylabs.github.io/netscript/explanation/observability/) and [Capabilities → Telemetry](https://rickylabs.github.io/netscript/capabilities/telemetry/). |
| `Prisma (Deno runtime)` | `database/postgres/schema/` | The ORM layer, backed by a polyglot database. The engine is chosen at scaffold time with `--db` — `postgres` (the recommended default; Prisma provider `postgresql`), `mysql`, `mssql` (provider `sqlserver`), or `sqlite` (file-backed, with no Aspire container resource) — while the Prisma authoring model stays identical across engines. The root schema sets `generator client { runtime = "deno" }` plus a zod generator, and each plugin contributes its own `.prisma` models, aggregated under `schema/plugins/<plugin>/` (the auth plugin installs `auth_users` / `auth_sessions` / `auth_accounts` / `auth_verifications`). The typed client is generated with `netscript db generate` after Aspire is up. See [Capabilities → Database](https://rickylabs.github.io/netscript/capabilities/database/) and [reference/database/](https://rickylabs.github.io/netscript/reference/database/). |
| `queue provider` | `QueueProvider.Postgres` | The transport a `createQueue('name', { provider })` binds to — one of **four** backends: Deno KV, Redis, RabbitMQ, and PostgreSQL (`provider: 'postgres'`, `connection.postgres.{url,tableName}`). Postgres is selectable by *explicit provider only*; auto-discovery probes RabbitMQ → Redis → Deno KV and never picks Postgres. See [Capabilities → KV / queues / cron](https://rickylabs.github.io/netscript/capabilities/kv-queues-cron/) and [reference/queue/](https://rickylabs.github.io/netscript/reference/queue/). |

## Where each term is taught

The glossary lowers lookup cost; these zones build the understanding. Follow a word into the zone that matches what you need next.

[Explanation  Mental models for contracts, the plugin model, durable workflows, the auth model, observability, and Aspire — the why behind the vocabulary.](https://rickylabs.github.io/netscript/netscript/explanation/)

[Capabilities  One hub per capability: concept, headline API, and a Learn / Do / Reference triplet for services, jobs, sagas, triggers, streams, authentication, and more.](https://rickylabs.github.io/netscript/netscript/capabilities/)

[Reference  The generated @netscript/* API — the authoritative export list for every symbol named above, including the plugin-auth-core port surface.](https://rickylabs.github.io/netscript/netscript/reference/)

[Tutorials  One continuous app that introduces these terms in order: contract, service, job, saga, then trigger.](https://rickylabs.github.io/netscript/netscript/tutorials/)

> Still stuck on a word?
>
> If a term here is unfamiliar, start with
>
> Explanation → Architecture
>
> for the big picture, then jump to the matching
>
> capability hub
>
> to see the headline API in context. The
>
> CLI reference
>
> covers every command name a glossary entry mentions.

[CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/)

_Canonical: https://rickylabs.github.io/netscript/glossary/_

---

# Quickstart

From nothing to a running NetScript workspace you can watch boot — in about five minutes. Three commands: **install** the CLI, **scaffold** a project, then bring it up under **Aspire**, which starts Postgres and a shared cache (`redis` by default, or `garnet` / `deno-kv` via `--cache-backend`) for you *before* anything else and hands you a real dashboard, distributed traces, and a handful of example routes on the very first run.

> Prerequisites
>
> You need
>
> [Deno](https://docs.deno.com) 2.x
>
> on your PATH (check with
>
> deno --version
>
> ). The default path also uses
>
> [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/)
>
> to orchestrate Postgres, Redis, and your services — install the
>
> aspire
>
> CLI if you don't have it, or skip orchestration entirely with
>
> --no-aspire
>
> (see the aside in step 3).

> Beta
>
> NetScript is in beta. Public package versions are
>
> 0.0.1-beta.11
>
> and the API is subject to change as it ships incrementally. Pin versions in real projects.

1. [Install the CLI](https://rickylabs.github.io/netscript/netscript/)
2. [Scaffold a workspace](https://rickylabs.github.io/netscript/netscript/)
3. [Start it under Aspire](https://rickylabs.github.io/netscript/netscript/)

## 1. Install the CLI

The CLI is published to JSR as `@netscript/cli`. Install it globally for a tidy `netscript` command, or run it ad-hoc with no install at all.

```bash
# Installs a `netscript` command on your PATH
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11

netscript --help
```

```bash
# Run the same CLI without installing anything
deno x jsr:@netscript/cli@0.0.1-beta.11 --help
```

> The rest of this page assumes the global `netscript` command. If you went ad-hoc, swap `netscript` for `deno x jsr:@netscript/cli@0.0.1-beta.11` in each step.

## 2. Scaffold a workspace

One command lays down the whole opinionated workspace — a Fresh 2 app, shared oRPC contracts, a plugin registry, and the Aspire orchestration layer:

```bash
netscript init my-app --db postgres
```

> Pick your database engine
>
> Postgres is the recommended default shown throughout these docs. The database is polyglot — swap
>
> --db postgres
>
> for
>
> mysql
>
> ,
>
> mssql
>
> , or
>
> sqlite
>
> to scaffold a Prisma-backed schema for that engine instead. (
>
> postgres
>
> /
>
> mysql
>
> /
>
> mssql
>
> run as an Aspire container resource;
>
> sqlite
>
> is file-backed with no container.)

> Want to see the plan before anything touches disk? Add `--dry-run` — `netscript init my-app --db postgres --dry-run` previews every file it would create and writes nothing.

You'll see a banner, a creating step, and a success summary with numbered next steps. It looks like this:

```text
╔═════════════════════════════════════════════════════════════╗
║              NetScript — Scaffold New Project                 ║
╚═════════════════════════════════════════════════════════════╝

📁 Creating project "my-app"...

✅ Project scaffolded successfully in 1.4s

  Created: 47 files, 12 directories

Next steps:
  1. cd my-app
  2. cd aspire  # TS AppHost lives here, isolated from the Deno workspace
  3. aspire restore  # download TypeScript AppHost SDK modules (run once)
  4. aspire start  # start TypeScript AppHost
```

If you see that success line and the numbered steps, the scaffold worked. The exact file count and the next steps adapt to the options you chose (a database, an example service, and so on) — on the strict happy path above, the four steps are sufficient.

> Aspire comes before any database command
>
> On the default path,
>
> Aspire is step 2 of running your app
>
> :
>
> cd aspire && aspire start
>
> provisions Postgres and Redis first. Any
>
> netscript db
>
> command (init, generate, seed) runs
>
> after
>
> Aspire is up, because it needs that database to exist. See
>
> Database migrations
>
> for the full flow.

## 3. Start it

Follow the next steps the CLI just printed. The Aspire TypeScript AppHost lives in its own `aspire/` folder, isolated from the Deno workspace; restore its modules once, then run it. **This is the step that actually starts your stack** — Postgres, Redis, and every wired service come up together:

```bash
cd my-app/aspire
aspire restore   # one-time: downloads the AppHost SDK modules
aspire start       # boots Postgres + Redis + services, opens the dashboard
```

> Prefer no orchestration?
>
> Scaffold with
>
> netscript init my-app --no-aspire
>
> and start the Fresh app directly instead:
>
> deno task --cwd apps/dashboard dev
>
> . You trade the dashboard, Postgres/Redis provisioning, and multi-resource wiring for a leaner single-process dev loop.

### See the framework code

The scaffold is more than bash and URLs — it generates real, typed framework code for you. Here's the kind of code the scaffold writes: a single `defineService` call wires the cross-cutting concerns so you don't have to. Your RPC procedures are then served under `/api/rpc/*`.

```ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';

// One call wires CORS, request logging, OpenAPI, RPC (/api/rpc/*), and health.
const service = await defineService(router, { name: 'users', port: 3001 });
```

```bash
# oRPC procedures are served under /api/rpc/*
curl http://localhost:3001/api/rpc/users/list

# Health and OpenAPI come for free
curl http://localhost:3001/health
```

> Fluent alternative
>
> Prefer a builder? The fluent equivalent of
>
> defineService(...)
>
> is the explicit chain
>
> createService(router, config).withCors().withLogger().withOpenAPI().withDocs().withRPC().withServiceInfo().withHealth().serve()
>
> — each
>
> .withXxx()
>
> adds one layer of the wiring that
>
> defineService
>
> bundles, including the
>
> /api/rpc/*
>
> mount (added by
>
> .withRPC()
>
> ). Calling
>
> createService(...).serve()
>
> with no chaining produces a bare app: no RPC handler, no CORS, no health. See
>
> the Storefront catalog-service chapter
>
> .

## What you see

Once `aspire start` settles, you have a live workspace to poke at:

- **The Aspire dashboard** at [https://localhost:18888](https://localhost:18888) — every resource (Postgres, Redis, your services), its health, logs, and distributed traces in one place.
- **The Fresh app** at [http://localhost:8000](http://localhost:8000) — your frontend, served by the `dashboard` app.
- **The `/design` route** — a living token-and-component showcase: the `--ns-*` design tokens, the fresh-ui components copied into *your* repo, and composition examples. Click a token to copy it.
- **The `/examples` routes** — runnable end-to-end paths: `/examples/crud`, `/examples/service`, and `/examples/telemetry`, plus a `/health` check.

> If something doesn't come up
>
> - A port is already in use — `18888` (dashboard) or `8000` (Fresh app). Stop the other process or change the port.
> - The first `aspire restore` downloads the AppHost SDK and can take a minute.
> - If a `netscript db` command can't connect, confirm `aspire start` is still up — Postgres lives inside Aspire.
> - `deno: command not found` means Deno isn't on your PATH.

> Start at /design
>
> The scaffolded
>
> /design
>
> showcase is the fastest way to feel what you have: the tokens are real CSS custom properties, and the components are source you own and can edit on the spot. Open
>
> http://localhost:8000/design
>
> .

## You now have

A complete, type-checked workspace — not a starter you have to assemble:

A running app + dashboard

A Fresh 2 frontend and the Aspire dashboard, wired together with health, logs, and traces from line one.

A database + Redis, provisioned

Aspire stands up the database (Postgres is the recommended engine; or mysql / mssql / sqlite via --db) and cache for you — no docker-compose to babysit, no connection strings to copy.

Contracts and a plugin registry

Shared, versioned oRPC contracts and a plugin registry ready for workers, sagas, triggers, auth, and streams.

UI you own

fresh-ui components copied into your repo under apps/dashboard — the code is yours to change.

### Next steps

> Start here
>
> New to NetScript? Work through
>
> the Storefront tutorial
>
> — a guided track that takes this scaffold to a real feature.

[Build the Storefront  A guided, end-to-end track that takes this scaffold to a real storefront — services, a durable checkout, and a webhook.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/)

[Build a service  Define an oRPC contract, implement it, and serve it under /api/rpc/* with one call.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[Capabilities  Durability model, background jobs, observability, auth, plugins, and Aspire integration — what NetScript does and why.](https://rickylabs.github.io/netscript/netscript/capabilities/)

[Reference  The full CLI surface and the @netscript/* package APIs.](https://rickylabs.github.io/netscript/netscript/reference/)

[Tutorial — Build the Storefront](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/)

_Canonical: https://rickylabs.github.io/netscript/quickstart/_

---

# Aspire quickstart

A NetScript workspace is never one process — it is a Fresh app, oRPC services, plugin APIs, background processors, a database, and a cache. Aspire is how we make that whole fleet start with **one command**, wired together, with a real dashboard from the first run. This page is the shortest path to seeing it; the [main Quickstart](https://rickylabs.github.io/netscript/quickstart/) covers installing the CLI and the scaffold in more detail.

> Alpha
>
> NetScript is alpha software and the API is subject to change. Pin versions in real projects.

## What you get

- **One workspace, one command up.** `aspire start` boots the database, the cache, every service, every plugin API, and every background processor — in dependency order, no docker-compose to babysit.
- **Multi-resource wiring, resolved for you.** Connection strings and neighbour endpoints are computed and injected as environment variables before each process starts, so nothing has to discover anything at runtime.
- **The Aspire dashboard.** Live resource list, per-process console logs, and distributed traces in one place — `aspire start` prints its URL and a one-time login token.
- **A TypeScript AppHost — not .NET authoring.** The orchestrator entry point is a generated TypeScript program at `aspire/apphost.mts`, running on an isolated Node runtime inside `aspire/` so it never leaks into your Deno workspace. You write no C#.

> Prerequisites
>
> [Deno](https://docs.deno.com) 2.x
>
> and the
>
> netscript
>
> CLI (install steps in the
>
> Quickstart
>
> ), the external
>
> [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/) CLI
>
> , and a running
>
> Docker
>
> daemon — Aspire provisions Postgres and Redis as local containers.

## The commands

Scaffold a workspace, then bring it up. The Aspire layer lives in its own `aspire/` folder; restore its SDK modules once, then start:

```bash
netscript init my-app --db postgres

cd my-app/aspire
aspire restore   # one-time: downloads the AppHost SDK modules
aspire start     # boots Postgres + Redis + services, prints the dashboard URL
```

When boot settles, open the dashboard URL `aspire start` printed (conventionally `https://localhost:18888`) and paste the login token. Every resource, its logs, and its traces are one click away.

> Database commands come after
>
> netscript db init
>
> ,
>
> db generate
>
> , and
>
> db seed
>
> run from the
>
> workspace root
>
> only once
>
> aspire start
>
> is up — they provision the database
>
> through
>
> the running AppHost. With no Aspire up there is no Postgres for them to reach.

## Prefer no orchestration?

Aspire is the default, not a requirement. Scaffold with `--no-aspire` to skip the orchestration layer entirely — no `aspire/` folder, no dashboard — and start the Fresh app directly:

```bash
netscript init my-app --db postgres --no-aspire
deno task --cwd apps/dashboard dev
```

You take over infrastructure and wiring yourself: bring your own Postgres and cache, hand each process its connection strings. When that trade is the right call — and what exactly you give up — is covered in [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/).

## Where next

- **Step-by-step recipe:** [Deploy locally with Aspire](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-local-aspire/) — the full local flow, including the database sequence and first-run footguns.
- **Why it works this way:** [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) — the AppHost, plugin contributions, and the resource graph.
- **Exact symbols and the port map:** [the Aspire reference](https://rickylabs.github.io/netscript/netscript/reference/aspire/) and the [CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/).

_Canonical: https://rickylabs.github.io/netscript/quickstart/aspire/_

---

# You shouldn't have to assemble a backend from a dozen libraries that have never met.

NetScript is one coordinated workspace where the contract you define is the client you call, workflows survive crashes by design, and tracing is wired in from line one.

[Quickstart — 5 min](https://rickylabs.github.io/netscript/netscript/quickstart/) [Browse the API reference](https://rickylabs.github.io/netscript/netscript/reference/)

> Where we are
>
> NetScript is in
>
> beta
>
> (
>
> 0.0.1
>
> ), shipping incrementally. The API is subject to change — so build with us, but pin your versions. The published package surface is the contract: what you import from
>
> jsr:@netscript/*
>
> is what's documented and type-checked.

## The problem

The short version: we ship the boring integration seams pre-fitted and type-checked, so you spend your time on product instead of plumbing. That's the answer the rest of this page earns.

A real TypeScript backend is rarely one decision. It's a dozen, made on different days, by different libraries that were never designed to sit in the same repo:

1. **A queue here, a tracer there.** You pick a job runner, then a separate OpenTelemetry setup, then glue them together so a job actually shows up in a trace. The glue is yours to maintain forever.
2. **A scaffold script that rots.** Someone wrote a `create-app` once. Two refactors later it generates code nobody recognizes, and updating it is a project of its own.
3. **A `docker-compose.yml` and a prayer.** Your database, your app, your worker, your dashboard — all hand-wired, all drifting from how you actually deploy.
4. **A DI container you didn't want.** To make any of the above testable, you reach for a dependency-injection framework, and now wiring is a layer of indirection instead of a function call.
5. **Drift between the API and the client.** The service returns one shape; the client believes another. You find out at runtime, in production, from a user. Codegen helps until the generated types and the hand-written ones disagree.
6. **Durability model faked with retries.** "It'll just retry" is not a state machine. There's no correlation, no compensation, no record of where a multi-step flow actually stopped when the process died.
7. **Auth bolted on at the end.** You wire OAuth, sessions, and a provider SDK by hand, then discover the provider you chose is the one you now can't swap without a rewrite.

None of these are hard problems individually. The cost is the **integration tax** — the standing maintenance of seven unrelated tools pretending to be one system.

## The NetScript answer

We didn't invent new primitives. We made a set of opinions about how the boring parts fit together, and shipped them as one coordinated package family plus a CLI that scaffolds the whole workspace. Each value below is a direct answer to a pain above.

**What you'd hand-assemble → what NetScript gives you**

| Name | Type | Description |
| --- | --- | --- |
| `Type-safe to the edges` | `API ↔ client drift` | The contract you import is designed, documented, and enforced. oRPC contracts flow from service to client to UI with no codegen step to drift. |
| `Predictable builder surface` | `DI containers & glue` | The common path is one chained call. Advanced options live on named builder methods, without hidden container wiring. |
| `Standards-first` | `bespoke abstractions` | Built on fetch, URL, streams, and @std/* — skills you already have, not a private runtime to relearn. |
| `Durable by design` | `retries pretending to be workflows` | Sagas, triggers, and jobs are explicit state machines with correlation, persistence, and compensation. They survive crashes; failure handling is named, not bolted on. |
| `Observable by default` | `a tracer you wire yourself` | OpenTelemetry tracing, structured logs, and health probes are wired into jobs, queues, RPC, and SSE from the first line. Job dispatch, execution, scheduling, and subprocess spans appear in the dashboard automatically. |
| `Orchestrated out of the box` | `docker-compose & a prayer` | One workspace, many resources, a real dashboard — local and deployed — via .NET Aspire integration. Opt out with --no-aspire. |
| `Composable` | `a scaffold script that rots` | Add workers, sagas, triggers, streams, and auth in any combination. The host never changes; plugins register contributions. |
| `Auth as a swappable seam` | `a provider you can't change later` | A pure-backend auth plugin defines the port; pick one backend — KV-OAuth, WorkOS, or better-auth — behind a single switch, without rewriting your service. |

## What makes it different

Each differentiator below is paired with a runnable TypeScript path from the public package surface.

### 1. Contract-first, type-safe end to end

Define a contract once. The client is *derived* from it — no codegen, no second source of truth. Change the contract and the type checker becomes your integration test: every caller that no longer matches fails to compile.

```ts
// This replaces a hand-maintained OpenAPI spec + generated client.
import {
  baseContract,
  OffsetPaginationMetaSchema,
  OffsetPaginationQuerySchema,
} from '@netscript/contracts';
import { z } from 'zod';

export const usersContract = {
  list: baseContract
    .route({ method: 'GET', path: '/users' })
    .input(OffsetPaginationQuerySchema)
    .output(z.object({
      items: z.array(z.object({ id: z.string(), email: z.string() })),
      pagination: OffsetPaginationMetaSchema,
    })),
};
```

```ts
// The client is derived from the contract above — not generated, not duplicated.
import { defineServices } from '@netscript/sdk';
import { usersContract } from './contracts/users.ts';

const { clients } = defineServices({
  users: { contract: usersContract },
});

// `result` is fully typed from the contract's output schema.
const result = await clients.users.list({ limit: 20, offset: 0 });
console.log(result.items, result.pagination);
```

### 2. Durability model by design

A saga is an explicit state machine, not a retry loop. You declare its state, the messages it reacts to, and what each handler emits — including completion and failure as first-class outcomes. It's authored in plain TypeScript builders, but the model is closer to Temporal than to a job queue. Runtime state persists to a durable store you choose — `kv` or `prisma` — so a saga in flight survives a process restart.

```ts
// This replaces an ad-hoc 'mark paid, then hope the retry fires' flow.
import { defineSaga, sagaComplete } from '@netscript/plugin-sagas-core';

const orderSaga = defineSaga('order')
  .state({ paid: false })
  .on('order.paid', (saga, _event, context) => {
    saga.state.paid = true;
    // Completion is an explicit, recorded outcome — not a fall-through.
    return [sagaComplete({ orderId: context.sagaId })];
  })
  .build();
```

```ts
// Handlers return named effects: send, schedule, complete, or fail.
import { defineSaga, send, sagaFail } from '@netscript/plugin-sagas-core';

const checkout = defineSaga('checkout')
  .state({ attempts: 0 })
  .on('payment.attempted', (saga, event, context) => {
    saga.state.attempts += 1;
    if (saga.state.attempts > 3) {
      return [sagaFail('payment retries exhausted')];
    }
    // Fan out the next step as a correlated message.
    return [send('payment.charge', { orderId: context.sagaId })];
  })
  .build();
```

### 3. Observable by default

Tracing isn't a follow-up ticket. Spans wrap the work itself: `withSpan` runs your handler inside a span, marks it OK or records the exception on throw, and closes it for you — so a service handler is traced the moment it exists. Background jobs go further: dispatch, execution, scheduling, and the subprocess that runs a job are span-wrapped automatically, and the trace context propagates into the subprocess — so a job shows up in the Aspire dashboard end to end without you wiring a thing.

```ts
// This replaces manual span start/end + try/catch/recordException boilerplate.
import { getTracer, withSpan } from '@netscript/telemetry/tracer';

const tracer = getTracer('users');

export const chargeOrder = async (orderId: string) => {
  // The span is opened, status-tracked, and closed around your work.
  return await withSpan(tracer, 'order.charge', async (span) => {
    span.setAttribute('order.id', orderId);
    const receipt = await processPayment(orderId);
    return receipt; // span auto-marked OK; a throw is recorded + re-raised.
  });
};
```

```ts
// defineService wires CORS, logging, OpenAPI, RPC, and health in one call —
// and your traced handlers run inside it with no extra plumbing.
import { defineService } from '@netscript/service';
import { router } from './router.ts';

const service = await defineService(router, {
  name: 'users',
  port: 3000,
});

// ... handlers like chargeOrder() above are already instrumented.
await service.stop();
```

### 4. Orchestrated with Aspire

Your database, services, workers, and a real dashboard come up together — locally and on the way to deploy — through NetScript's .NET Aspire integration. The flow is two commands: `cd aspire && aspire start` brings up your database container (Postgres is the recommended engine — or `mysql` / `mssql` via `--db`; `sqlite` is file-backed and needs no container) and Redis and the dashboard *before* any `netscript db` command touches the database. One workspace wires the resources; you get the Aspire dashboard (`:18888`) for traces and logs without standing up your own. Don't want the .NET footprint? `netscript init --no-aspire` and it's gone.

### 5. Composable plugins

Workers, sagas, triggers, streams, and auth are plugins. You add them in any combination and the host application never changes — each one registers its contributions rather than asking you to edit a central wiring file. The saga in proof #2 *is* a plugin contribution; so is the auth service in proof #7. Each official plugin runs as its own Aspire service on its own port — workers `:8091`, sagas `:8092`, triggers `:8093`, auth `:8094`, streams `:4437` — so adding one is additive, never a rewire.

### 6. You own your UI

fresh-ui is copy-source. The CLI copies the components into your repo, and from that moment the code is yours to read, fork, and evolve. There's no black-box component dependency to fight when you need a different border-radius. (`@netscript/fresh` — the meta-framework with server, islands, and query subpaths — is a separate, real package; the scaffolded Fresh UI app is the copy-source layer you own outright.)

### 7. Auth as a swappable backend

Authentication is a plugin like any other, and its defining opinion is that the *backend is pure*. `@netscript/plugin-auth-core` defines an `AuthBackendPort`; the three backends — `@netscript/auth-kv-oauth` (the full interactive OAuth/OIDC flow), `@netscript/auth-workos`, and `@netscript/auth-better-auth` — are pure adapters behind it. `@netscript/plugin-auth` composes exactly **one** active backend, chosen by `NETSCRIPT_AUTH_BACKEND` (default `kv-oauth`), and exposes an `auth-api` oRPC service on `:8094` with five endpoints: `signin`, `callback`, `signout`, `session`, and `me`. Swap providers by changing a switch, not your service.

```ts
// The interactive backend: a full OAuth/OIDC redirect flow with KV sessions.
import { createKvOAuthBackend, providers } from '@netscript/auth-kv-oauth';

const backend = await createKvOAuthBackend({
  provider: providers.google({ clientId, clientSecret, redirectUri }),
});

// One active backend at a time; selected by NETSCRIPT_AUTH_BACKEND.
// Swap to 'workos' or 'better-auth' without touching your service.
```

> Framework beta
>
> NetScript packages share the aligned
>
> 0.0.1-beta.11
>
> version, and scaffolded JSR imports pin that exact beta train. Only
>
> kv-oauth
>
> is fully interactive — on WorkOS and better-auth the
>
> signin
>
> /
>
> callback
>
> endpoints return a typed unsupported-operation error by design. It's one active backend at a time: no multi-active routing, cross-backend linking, or global logout yet. See
>
> the auth capability hub
>
> for the full surface.

## Compared to assembling it yourself

You can build all of this by hand — most teams have. The comparison that matters isn't NetScript versus any one library; it's NetScript versus the standing cost of integrating several. We're deliberate about what we wrap and what we are *not*:

**How NetScript compares**

| Name | Type | Description |
| --- | --- | --- |
| `vs. wiring it yourself` | `the baseline` | You keep full control but own every integration seam — queue↔tracer, scaffold, compose file, client drift, auth provider — indefinitely. NetScript trades a slice of that control for those seams being pre-fitted and type-checked. |
| `NestJS` | `opinionated backend framework` | An opinionated, DI-first Node backend framework. NetScript is Deno-native and JSR-distributed, leads with oRPC contract-first typing end to end, and treats durable workflows as first-class — not a backend framework you bolt a workflow engine onto. |
| `Encore` | `infra-from-code backend framework` | An infra-from-code Go/TS backend framework. NetScript is Deno-native and JSR-distributed, leads with oRPC contract-first typing end to end, and treats durable workflows as first-class — not a backend framework you bolt a workflow engine onto. |
| `tRPC-style stacks` | `end-to-end typing` | NetScript shares the typed-edge goal via oRPC, then adds the rest of the system around it: services, jobs, sagas, streams, auth, orchestration, and observability in one workspace. |
| `Temporal` | `durable workflow engine` | Our sagas borrow the state-machine, correlation, and compensation ideas — authored in plain TS builders inside your app, not a separate cluster you operate. |
| `Hono` | `HTTP foundation` | We wrap it, not replace it. defineService stands up a Hono/oRPC runtime; you're never cut off from the underlying framework. |

NetScript is the opinion that these pieces should arrive already fitted — and the published surface is the product, so what you import is what's documented and type-checked.

> When NetScript is NOT the right tool
>
> - **You need a stable, frozen API today.** We're in beta; surfaces still move. If churn is unacceptable, wait for a later beta or pin hard.
> - **You can't take a .NET dependency.** The default scaffold integrates .NET Aspire for orchestration. You can [`--no-aspire`](https://rickylabs.github.io/netscript/explanation/aspire/), but if even the option offends your platform constraints, weigh that first.
> - **You want a frontend framework or a hosted PaaS.** NetScript is backend-scoped: services, workflows, jobs, streams, auth, and a generated workspace you run yourself. It ships a Fresh UI, but it is not a React-style frontend framework, and it does not host anything for you.

## Convinced enough to try it?

The fastest way to feel the difference is to generate a workspace and watch it come up. From there, the [capabilities](https://rickylabs.github.io/netscript/capabilities/) map the system feature by feature, and the [API reference](https://rickylabs.github.io/netscript/reference/) is generated from the published surface — never duplicated by hand.

[Quickstart — 5 minutes](https://rickylabs.github.io/netscript/netscript/quickstart/)

_Canonical: https://rickylabs.github.io/netscript/why/_

---

# Tutorials

Tutorials are for **learning by building**. Each one walks a fixed path from an empty directory to a running application — no step skipped, every rung proven by a real command or endpoint. You don't need to understand the whole framework before you start; each track introduces its capabilities in the order you'd actually reach for them.

Unlike the [how-to guides](https://rickylabs.github.io/netscript/how-to/), which assume you already know the shape of the task, a tutorial follows one continuous example and never leaves you guessing what to do next.

> How the four lanes fit together
>
> Tutorials teach you a path end to end. When you already know the path and just need the recipe, use the
>
> how-to guides
>
> . For exact symbols and signatures, go to the
>
> reference
>
> . For the design reasoning behind durability, contracts, and plugins, read the
>
> explanation
>
> pages.

## Five tracks, five applications

There are five independent tracks. **Each builds one complete application** from a fresh `netscript init`, and each ends by running that application **locally under .NET Aspire** — so whichever you pick, you finish with something that boots, serves, and survives a restart. The tracks don't depend on each other; start with the one closest to what you're building.

[Storefront  Build an e-commerce backend: a typed catalog service, contract-first cart, a durable `checkout` saga with compensation, and an HMAC-verified shipping webhook. The track for **services + durable workflows**. 6 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/)

[Team Workspace  Build an authenticated SaaS backend: add a pluggable auth backend and session, model per-plugin data across a second database, run a provisioning job, and protect routes with the `.withAuthz()` seam. The track for **auth + access control**. 6 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/)

[ERP Sync  Build a legacy-ERP migration sync: watch for incoming data files, ingest them with durable jobs, run a sandboxed transform task, and add a queue provider and a cron schedule. The track for **jobs, queues & polyglot**. 5 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/)

[Live Dashboard  Build a real-time UI that stays current with no polling and no hand-rolled WebSocket: go from a typed contract to an SDK client, a cache-first query, a Fresh `definePage` with a hydrated `QueryIsland`, and finally a durable StreamDB feed that pushes updates into the table live. The track for **the typed-end-to-end Fresh + SDK stack**. 6 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/)

[AI Chat  Build a durable AI chat app whose transcript, streaming markdown, tool-call cards, and MCP widgets survive reload and reconnect: wire a durable chat route on `@netscript/fresh/ai`, hydrate the `fresh-ui` chat components, add a server-side tool, connect a remote MCP server, and turn the island live. The track for **durable AI chat**. 6 chapters.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/)

## Not sure which to pick?

**Choose by what you're building**

| Name | Type | Description |
| --- | --- | --- |
| `An API with multi-step business logic` | `Storefront` | You need typed services and a workflow that can't half-complete — orders, payments, fulfillment. Teaches contracts, defineService, sagas, and webhooks. |
| `An app behind a login` | `Team Workspace` | You need authentication, sessions, and route-level access control before anything else. Teaches the auth backend, session crypto, and the .withAuthz() seam. |
| `Data pipelines and scheduled work` | `ERP Sync` | Your work happens off the request path — file ingestion, batch jobs, scheduled syncs, and tasks in other languages. Teaches triggers, jobs, queues, cron, and the task runtime. |
| `A live, reactive frontend` | `Live Dashboard` | You're rendering server data in a Fresh UI that stays current without a refresh. Teaches the SDK client, cache-first queries, the page builder, islands, and durable streams. |
| `A durable AI chat app` | `AI Chat` | You're building a chat UI whose transcript, streaming markdown, tool-call cards, and MCP widgets survive reload and reconnect, with replies that stream in live. Teaches the durable chat route on @netscript/fresh/ai, the fresh-ui chat components, a server-side tool, the MCP client stack, and the live subscription. |

New to NetScript entirely? Any track starts from zero, but **Storefront** is the broadest tour of the core ideas — to inspect the whole shape of a NetScript backend, start there.

## Before you start

Every track assumes a working local toolchain. If you have never run NetScript on this machine, the [quickstart](https://rickylabs.github.io/netscript/quickstart/) installs the CLI and gets a project up in a few commands; each track's first chapter then re-grounds you from the scaffold, so you can start in either place.

> What you'll need
>
> A recent
>
> Deno
>
> and the
>
> .NET Aspire
>
> CLI on your PATH. Install the NetScript CLI with
>
> deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11
>
> . Each chapter lists its own prerequisite state, so you always know which earlier chapters it builds on.

## When you finish

Once you've completed a track, branch out into the rest of the docs:

[How-to guides  Task-focused recipes for things the tutorials don't cover — discovering services, exposing OpenAPI, choosing a queue provider, second databases, and production pitfalls.](https://rickylabs.github.io/netscript/netscript/how-to/)

[Capabilities  One hub per capability (services, workers, sagas, triggers, streams, auth) with the headline API, ports, and endpoints on one screen.](https://rickylabs.github.io/netscript/netscript/capabilities/)

[Reference  Generated, always-current API surface for every `@netscript/*` unit — exact symbols, signatures, and types.](https://rickylabs.github.io/netscript/netscript/reference/)

[Explanation  The design reasoning behind contracts-first services, durable execution, the plugin model, and the local Aspire topology.](https://rickylabs.github.io/netscript/netscript/explanation/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/_

---

# AI Chat

This track builds one thing end to end: a **durable AI chat app** — think a production support-chat surface, the kind of assistant a real product ships next to its docs. By the last chapter you will have a chat whose transcript — messages, streaming markdown, tool-call cards, and MCP widgets — survives reload, reconnect, and a second tab, and whose replies stream in live as the model produces them, because it is backed by a durable session stream rather than component state. That is the differentiator this track proves: most chat UIs keep the conversation in component state, so a refresh, a dropped socket, or a second tab loses it — here the transcript lives in the durable session and the UI is only a view of it, so the same log replays identically on reload, reconnect, and every other tab watching. It runs on shipped NetScript seams: the [`@netscript/fresh/ai`](https://rickylabs.github.io/netscript/reference/fresh/) durable-chat plane (published on JSR in `@netscript/fresh` and usable now, including the `ai/sandbox` MCP-UI subpath), the [`@netscript/fresh-ui`](https://rickylabs.github.io/netscript/reference/fresh-ui/) copy-registry chat components, and the [`@netscript/ai`](https://rickylabs.github.io/netscript/reference/ai/) MCP client stack.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)
2. [2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)
3. [3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)
4. [4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)
5. [5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)
6. [6 · Live streaming](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

## What you will build

A `chat-app/` Fresh workspace whose home screen is a working chat. The reader scaffolds a fresh NetScript project with the streams runtime, wires a durable chat session route that calls a model directly on `@tanstack/ai`, copies the fresh-ui `ai` component collection and hydrates a chat island, adds one server-side tool whose result surfaces as a tool-call card with citation chips, connects the chat to a remote MCP server and renders the `ui://` widgets its tools return, and finally turns the island live so replies stream in as they arrive. This is a learning track: the same project grows chapter by chapter, so do them in order.

## Before you begin

You need the standard NetScript toolchain — Deno, the Aspire CLI, and Docker — plus a model provider key. Confirm the toolchain:

```sh
deno --version && aspire --version && docker info
```

You should see a Deno 2.x version, an Aspire CLI version, and Docker engine details. If any are missing, the [quickstart](https://rickylabs.github.io/netscript/quickstart/) walks through installing them. Install the NetScript CLI once:

```sh
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11
```

> You need a model provider key
>
> This track calls Anthropic directly through
>
> @tanstack/ai
>
> . Have an
>
> ANTHROPIC_API_KEY
>
> ready before chapter 1 — chapter 1 shows where to set it so Aspire injects it into the app process. Any provider
>
> @tanstack/ai
>
> supports works; this track uses Anthropic for concreteness.

## The arc: route → UI → tools → MCP → live streaming

Each chapter adds exactly one link in the durable-chat spine:

[1 · Scaffold the workspace  Create `chat-app/` with `netscript init`, add the `streams` plugin so durable sessions have a runtime, set `ANTHROPIC_API_KEY`, and boot under Aspire.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)

[2 · The durable chat route  Wire the session route with `toNetScriptChatResponse` + a required `authorize` hook, the one `createNetScriptChatStreamProxy`, and a direct model call on `@tanstack/ai`.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)

[3 · The chat UI  Copy the fresh-ui `ai` collection (message, prompt-input, markdown, chat-render) and hydrate an island that seeds from `resolveChatSnapshot` and drives `createNetScriptChatConnection`.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)

[4 · A server-side tool call  Add one `@tanstack/ai` tool the model can call; surface the invocation as a `tool-call-card` and render its citations as chips.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)

[5 · MCP tools & widgets  Connect a remote MCP server with `createMcpTransportPool` from `@netscript/ai/mcp`, bridge its tools into the chat turn, and render `ui://` widgets sandboxed through `createMcpSandboxHandler` and the copied `McpUiWidget`.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)

[6 · Live streaming  Upgrade the island from settle-then-render to a live `connection.subscribe(signal)` read, folding each chunk through the one projection so replies stream in as they arrive, across tabs.](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

> What this track deliberately leaves out
>
> The tutorial stays on the durable-chat spine: durable chat, streaming markdown, tools (local and over MCP), sandboxed
>
> ui://
>
> widgets, and a live subscription. It does
>
> not
>
> cover the generative-UI renderer, agent memory / semantic recall, or RAG. The
>
> @netscript/ai engine
>
> — model registry, agent loop, tool registry, and MCP transports — is published on JSR as of
>
> 0.0.1-beta.11
>
> ; this track wires the model call directly on
>
> @tanstack/ai
>
> , because the durable session plane persists and replays TanStack chunk streams. Chapter 2 shows where the engine fits, and chapter 5 uses its MCP client stack.

## What you built

By the end of this track you own a working durable chat app and understand the seams that make it durable — the session route, the stream proxy, the SSR seed, and the client connection's send and live-subscribe sides — plus how the fresh-ui chat components render its transcript, how a tool call (yours or a remote MCP server's) lands as a durable card, and how MCP `ui://` widgets render themed and sandboxed inside the chat.

[Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)

After this track, keep building in **Build › [AI & Agents](https://rickylabs.github.io/netscript/ai/)** — the guides and recipes there pick up where these chapters stop.

_Canonical: https://rickylabs.github.io/netscript/tutorials/chat/_

---

# Scaffold the chat workspace

Every track starts with a real project on disk. In this chapter you create `chat-app/` — a NetScript workspace with a Fresh frontend — add the **streams runtime** so durable chat sessions have somewhere to live, set your model key, and boot the whole thing under Aspire.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)
2. [2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)
3. [3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)
4. [4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)
5. [5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)
6. [6 · Live streaming](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

## What you will build

A `chat-app/` workspace on disk: a [Fresh](https://rickylabs.github.io/netscript/web-layer/) app, the `streams` plugin wired for durable sessions, and Aspire orchestration. By the end the Aspire dashboard at `:18888` shows every resource running, `ANTHROPIC_API_KEY` reaches the app process, and the workspace type-checks. You reuse this same workspace for every later chapter.

## Before you begin

The only prerequisite is the toolchain from the [track index](https://rickylabs.github.io/netscript/tutorials/chat/) plus an `ANTHROPIC_API_KEY`. Confirm the CLI is installed and reachable:

```sh
netscript --help
```

You should see the public command groups: `init`, `contract`, `db`, `deploy`, `generate`, `marketplace`, `plugin`, `service`, `ui:add`, and `ui:init`. If `netscript` is not found, make sure Deno's install directory is on your `PATH` and open a fresh terminal.

## Step 1 — Preview the scaffold with a dry run

Before writing files, ask the CLI what it *would* create. `--dry-run` plans the scaffold and prints totals without touching disk:

```sh
netscript init chat-app --dry-run
```

A clean dry run confirms your flags are valid and is your green light to scaffold for real.

## Step 2 — Create the workspace

Scaffold for real. This track does not need an example service — the chat route you write in chapter 2 is the only backend — so a plain Fresh workspace is enough:

```sh
netscript init chat-app
cd chat-app
```

This writes `chat-app/`, formats the output with `deno fmt`, and initializes a git repository. On completion the CLI prints a **next steps** summary tailored to your options.

## Step 3 — Add the streams runtime

A durable chat session is one append-only stream, addressed through the streams runtime. Add the `streams` plugin so `@netscript/fresh/ai` has a runtime to resolve session URLs against:

```sh
netscript plugin install stream --name streams --samples
```

> Why streams, for a chat app?
>
> @netscript/fresh/ai
>
> does not reimplement transport — it addresses each chat session as one durable stream under the
>
> @netscript/plugin-streams-core
>
> seam (the same seam
>
> @netscript/fresh/streams
>
> uses for live tables). No
>
> streams
>
> runtime means no place for the session log to live, so
>
> resolveChatSnapshot
>
> and the connection have nothing to read.

## Step 4 — Set your model key

The chat route calls Anthropic directly; the adapter reads `ANTHROPIC_API_KEY` from the app process environment. Put it where Aspire will inject it — your workspace's local environment file (never commit a real key):

```sh
# chat-app/.env  (add .env to .gitignore if it is not already)
ANTHROPIC_API_KEY=sk-ant-...
```

> The key stays server-side
>
> ANTHROPIC_API_KEY
>
> is read only inside the chat
>
> route
>
> (server code). It is never bundled into the island or sent to the browser — the model call happens on the server, and the browser only ever sees the durable session stream through the proxy you build in chapter 2.

## Step 5 — Bring up orchestration

Boot the whole thing under Aspire. Run it from the `aspire/` subfolder so the CLI finds `apphost.mts`:

```sh
cd aspire
aspire restore   # once: restores the Aspire SDK modules into .aspire/
aspire start     # starts the AppHost, the streams runtime, and the Fresh app
```

`aspire start` prints a URL and login token for the **Aspire dashboard**:

```
https://localhost:18888
```

Leave `aspire start` running in this terminal; it is your control plane for the rest of the track.

## Verify your progress

In a second terminal, type-check the whole workspace from the project root:

```sh
deno task check
```

A clean check confirms the scaffold and plugin wiring line up.

- [ ] `netscript --help` lists the public command groups.
- [ ] `chat-app/` exists with `apps/dashboard/` and a `plugins/` entry for `streams`.
- [ ] `ANTHROPIC_API_KEY` is set in the app environment.
- [ ] `aspire start` is up; the dashboard at `:18888` lists the streams runtime and the Fresh app.
- [ ] `deno task check` is clean.

> If something is not green
>
> Three checks cover most first-run snags: (1) is
>
> aspire start
>
> still up, with the streams runtime healthy in the
>
> dashboard
>
> ? (2) is Docker running (
>
> docker info
>
> )? (3) did you
>
> cd aspire
>
> before
>
> aspire start
>
> so it found
>
> apphost.mts
>
> ?

## What you built

A real NetScript workspace — `chat-app/` — with a Fresh app, the streams runtime for durable sessions, and your model key wired to the app process, all orchestrated by Aspire. Next you will wire the durable chat route that turns a prompt into a persisted, streamed reply.

[AI Chat](https://rickylabs.github.io/netscript/netscript/tutorials/chat/) [2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/chat/01-scaffold/_

---

# The durable chat route

The backend of a durable chat is two routes and one model call. In this chapter you wire the **session route** (runs a model turn, persists it durably, gated by `authorize`), the **one stream proxy** the browser reads through, and the direct model call on `@tanstack/ai`. When you finish, a `curl` can drive a full turn and a second `curl` replays it — the transcript is durable.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)
2. [2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)
3. [3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)
4. [4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)
5. [5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)
6. [6 · Live streaming](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

## The four seams

`@netscript/fresh/ai` gives you one function per job. This chapter uses three of the four; chapter 3 uses the fourth (`createNetScriptChatConnection`) in the island.

**@netscript/fresh/ai — the durable-chat seams used here**

| Name | Type | Description |
| --- | --- | --- |
| `toNetScriptChatResponse` | `session route` | Turn a server chat stream into a durable session Response; authorize-gated (→ 403 on deny). |
| `resolveChatSnapshot` | `history seed` | Materialize the transcript so far, reduced through projectChatSnapshot — the model's context. |
| `createNetScriptChatStreamProxy` | `the one proxy` | The single durable chat-stream proxy the browser reads through; attaches streams auth server-side. |

## Step 1 — The model call

The model layer is wired directly on `@tanstack/ai` and a provider adapter. `chat()` returns an async iterable of stream chunks — exactly the `source` shape `toNetScriptChatResponse` persists. `anthropicText()` reads `ANTHROPIC_API_KEY` from the environment, so no key appears in code:

```ts
import { chat } from '@tanstack/ai';
import { anthropicText } from '@tanstack/ai-anthropic';

const adapter = anthropicText('claude-sonnet-4-5');
const source = chat({
  adapter,
  messages: [{ role: 'user', content: 'Hello!' }],
  systemPrompts: ['You are a helpful assistant.'],
});
// `source` is an AsyncIterable of TanStack stream chunks.
```

> Where the @netscript/ai engine fits
>
> NetScript also ships a provider-neutral engine — the
>
> @netscript/ai
>
> package, published on JSR as of
>
> 0.0.1-beta.11
>
> . Its entry seam is a model registry with self-registering providers:
>
> import '@netscript/ai/anthropic'
>
> registers the Anthropic provider, and
>
> getModel('anthropic:claude-sonnet-4-5')
>
> resolves a model handle; an agent loop, a tool registry, and MCP transports live behind its other subpaths (
>
> reference
>
> ). This route keeps the direct
>
> @tanstack/ai
>
> wiring because the durable session plane persists and reduces TanStack chunk streams, while the engine's chat clients stream the engine's own event vocabulary — two different wire shapes.

## Step 2 — The session route

This route runs one turn and persists it. It pulls the transcript so far through `resolveChatSnapshot` (so the model has context), calls the model, and hands the stream to `toNetScriptChatResponse` — gated by an `authorize` hook.

First give that dynamic route a **typed identity**. `createRouteReference` from `@netscript/fresh/route` infers the `{ sessionId }` path param straight from the `[sessionId]` pattern, so the id the server reads and the URL the browser posts to in chapter 3 both come from one declaration — never a string assembled two different ways. Put it in the shared `contracts/` tree so the route and the island import the *same* object:

```ts
// contracts/routes/chat-turn.ts
import { createRouteReference } from '@netscript/fresh/route';

/** The one place the chat turn route pattern is written. */
export const chatTurnRoute = createRouteReference('/api/chat/[sessionId]');
// chatTurnRoute.parsePath({ sessionId })      -> typed { sessionId: string }
// chatTurnRoute.href({ path: { sessionId } }) -> "/api/chat/<id>"  (the island posts here in ch. 3)
```

Now the route reads its param **through the contract** instead of touching `ctx.params` by hand:

```ts
// apps/dashboard/routes/api/chat/[sessionId].ts
import { chat } from '@tanstack/ai';
import { anthropicText } from '@tanstack/ai-anthropic';
import { resolveChatSnapshot, toNetScriptChatResponse } from '@netscript/fresh/ai';
import { chatTurnRoute } from '../../../../contracts/routes/chat-turn.ts';

// REQUIRED in production — no default allow-all. Replace with your real check
// (session cookie → owner lookup). Returning false denies the turn with a 403.
const authorize = (request: Request, sessionId: string): boolean =>
  Boolean(request) && sessionId.length > 0;

export const handler = {
  async POST(ctx: { req: Request; params: { sessionId: string } }): Promise<Response> {
    // Typed off the one route contract — the same object the island builds its URL from.
    const { sessionId } = chatTurnRoute.parsePath(ctx.params);
    const target = { sessionId } as const;

    // History so far, reduced through the SAME projection the island seeds from.
    const snapshot = await resolveChatSnapshot({ target });
    const messages = snapshot.messages.map((m) => ({ role: m.role, content: m.content }));

    const source = chat({
      adapter: anthropicText('claude-sonnet-4-5'),
      messages,
      systemPrompts: ['You are a helpful assistant.'],
    });

    return toNetScriptChatResponse({ target, request: ctx.req, authorize, source });
  },
};
```

> authorize is not optional
>
> toNetScriptChatResponse
>
> enforces access only when you pass an
>
> authorize
>
> hook, and the factory applies
>
> no
>
> default. Omit it and the session stream is unauthenticated. Pass
>
> authorize
>
> without a
>
> request
>
> and it throws — always thread
>
> ctx.req
>
> through. A denial returns
>
> 403 Forbidden
>
> and the session stream is never touched.

The user message is appended to the durable session by the island in chapter 3 (via `connection.send`), so this route reads it back through `resolveChatSnapshot` and only needs to stream the assistant reply. You could instead pass `newMessages: [userMessage]` to `toNetScriptChatResponse` to persist the prompt here — one place, either way, never both.

## Step 3 — The one stream proxy

The browser must not hold streams credentials, so it never talks to the durable-streams service directly. It reads through a single proxy that attaches auth server-side and keeps every response header accurate. Mount `createNetScriptChatStreamProxy` once as a catch-all:

```ts
// apps/dashboard/routes/api/chat-stream/[...path].ts
import { createNetScriptChatStreamProxy } from '@netscript/fresh/ai';

const proxy = createNetScriptChatStreamProxy({
  // The session id is the last path segment: /api/chat-stream/ai/chat/{sessionId}
  target: (req) => ({ sessionId: new URL(req.url).pathname.split('/').pop()! }),
});

export const handler = { GET: proxy, POST: proxy };
```

> Why a raw Request here, not a route contract
>
> This resolver is the one documented exception to NetScript's typed-route rule:
>
> createNetScriptChatStreamProxy
>
> 's
>
> target
>
> only ever receives the raw
>
> Request
>
> , so the session id is parsed from
>
> req.url
>
> by hand. Everywhere else you build a URL or read a path param, prefer a bound
>
> `createRouteReference`
>
> contract so the pattern and its typed params come from one source of truth.

> Why a proxy at all?
>
> The proxy exists so the browser gets a durable stream
>
> without
>
> streams credentials. It attaches the
>
> Authorization
>
> header only on the server → streams hop (never echoed back), passes the body through unbuffered, and strips
>
> content-encoding
>
> /
>
> content-length
>
> — which stop describing the bytes once the stream is re-framed across the proxy. A client disconnect aborts the upstream fetch, so no stream is left dangling.

## Verify your progress

With `aspire start` running, drive one turn against a fresh session id, then replay it:

```sh
# Run a turn (the assistant reply streams back and is persisted durably).
curl -N -X POST http://localhost:8010/api/chat/demo-1

# Replay: read the same session again — the transcript is still there.
curl -N http://localhost:8010/api/chat-stream/ai/chat/demo-1
```

The first call streams a reply; the second shows the durable session already holds it — that is durability, not a re-run. Then type-check:

```sh
deno task check
```

- [ ] `POST /api/chat/{sessionId}` streams an assistant reply.
- [ ] A denied `authorize` returns `403`.
- [ ] Re-reading the session through the proxy replays the transcript.
- [ ] `deno task check` is clean.

> If the turn errors
>
> A provider error (bad or missing
>
> ANTHROPIC_API_KEY
>
> ) surfaces
>
> into
>
> the assistant stream rather than as an HTTP error — check the reply body. A
>
> 403
>
> means
>
> authorize
>
> returned
>
> false
>
> . An empty replay means the streams runtime is not up: confirm it in the Aspire dashboard.

## What you built

The durable backend: a session route that runs a model turn and persists it behind a required `authorize` gate, and the one proxy the browser reads through. Notice the discipline underneath — one agreed message shape (`NetScriptChatMessage`) flows through the route, and the turn is written to the durable session *before* anyone renders it, so an accepted reply survives the request that produced it. That "durable delivery" spine is what every later chapter builds on. Next you give it a face — copy the fresh-ui chat components and hydrate an island.

[1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/) [3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/chat/02-durable-chat-route/_

---

# The chat UI

The backend streams and persists turns; now it needs a face. In this chapter you copy the fresh-ui `ai` component collection into your app, seed the first paint from `resolveChatSnapshot`, and hydrate a chat island that drives `createNetScriptChatConnection` — subscribe, send, dispose. The transcript renders complete on load and updates as turns settle.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)
2. [2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)
3. [3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)
4. [4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)
5. [5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)
6. [6 · Live streaming](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

## Step 1 — Copy the AI component collection

The chat primitives are **copy-source**: the CLI copies them into your app, where you own them. The `ai` collection installs the whole chat surface in one command — message, prompt-input, markdown, the `chat-render` block parser, and the tool-call and citation components you use in chapter 4:

```bash
netscript ui:add ai
```

This copies component files into `apps/dashboard/components/ui/`, the `chat-render` parser into `apps/dashboard/lib/chat/parse-blocks.ts`, and their CSS into `apps/dashboard/assets/ui/`, then wires the styles and merges any required imports. After the copy, that code is yours to edit — see [Customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/) for the ownership model.

**The ai collection — the pieces this track uses**

| Name | Type | Description |
| --- | --- | --- |
| `message` | `chat message` | Author + time, inline markup (bold / code / [n] citation chips), tool-call + chart/code blocks, follow-up chips, typing indicator. Exports Message, renderInline, TypingIndicator. |
| `prompt-input` | `composer` | Auto-grow textarea + toolbar. Presentational ; onSubmit(text, meta) reads the field. |
| `markdown` | `renderer` | Sanitized streaming-markdown component + pipeline for assistant prose. |
| `chat-render` | `block parser (lib)` | parseBlocks(input): RenderPart[] — turns assistant markdown into typed rich blocks. Never throws. |
| `tool-call-card` | `tool disclosure` | Tool invocation + result as a  with a status badge (used in chapter 4). |
| `citation-chip` | `citation` | Inline [n] source marker that pairs with a sources list (used in chapter 4). |

## Step 2 — Seed the first paint

In the page that hosts the chat, materialize the transcript so far and pass it into the island. `resolveChatSnapshot` returns `{ messages, renderParts, offset }`; the `offset` seeds the live subscription so seed and live read one continuous log:

```ts
// In your chat page route (server side)
import { resolveChatSnapshot } from '@netscript/fresh/ai';

const sessionId = 'demo-1'; // from the route params / the signed-in user's session
const seed = await resolveChatSnapshot({ target: { sessionId } });
// Render <Chat sessionId={sessionId} seed={seed} /> as an island.
```

Wire `seed` into your page with the scaffold's page builder the same way the dashboard passes data to a view — see [Customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/) for the `definePage` pattern. The important part is that the island receives `seed` as a prop.

> The one-projection law, in one sentence
>
> resolveChatSnapshot
>
> reduces the session through
>
> projectChatSnapshot
>
> — the
>
> same
>
> reducer the live path uses. That is why a tool card rendered at first paint does not jump or vanish when the first live chunk arrives: seed and live never disagree about intermediate state.

## Step 3 — The chat island

The island is where the browser hydrates. It holds the snapshot in a signal, opens a durable connection pointed at the proxy from chapter 2, and on submit: appends the user message with `connection.send`, fires the model turn, then re-materializes the settled transcript.

```tsx
// apps/dashboard/islands/Chat.tsx
import { useSignal } from '@preact/signals';
import { createNetScriptChatConnection, resolveChatSnapshot } from '@netscript/fresh/ai';
import type { NetScriptChatMessage, NetScriptChatSnapshot } from '@netscript/fresh/ai';
import { chatTurnRoute } from '@app/contracts/routes/chat-turn.ts';
import { Message, type MessageData } from '@app/components/ui/message.tsx';
import { PromptInput } from '@app/components/ui/prompt-input.tsx';

const toMessageData = (m: NetScriptChatMessage): MessageData => ({
  role: m.role === 'assistant' ? 'assistant' : 'user',
  author: { name: m.role === 'assistant' ? 'Assistant' : 'You', agent: m.role === 'assistant' },
  body: m.content,
});

interface ChatProps {
  sessionId: string;
  seed: NetScriptChatSnapshot;
}

const Chat = ({ sessionId, seed }: ChatProps) => {
  const snapshot = useSignal(seed);
  const pending = useSignal(false);
  const base = `${location.origin}/api/chat-stream`;

  const connection = createNetScriptChatConnection({
    target: { sessionId, baseUrl: base },
    initialOffset: seed.offset ?? undefined,
    authorize: () => true, // browser half; the server route re-checks ownership
  });

  const onSubmit = async (text: string) => {
    pending.value = true;
    // 1. Append the user message to the durable session.
    await connection.send([{ id: crypto.randomUUID(), role: 'user', content: text }]);
    // 2. Fire the model turn (chapter 2's route streams + persists the reply).
    //    The URL comes from the same route contract the server reads its param through.
    await fetch(chatTurnRoute.href({ path: { sessionId } }), { method: 'POST' });
    // 3. Re-materialize the settled transcript through the same projection.
    snapshot.value = await resolveChatSnapshot({ target: { sessionId, baseUrl: base } });
    pending.value = false;
  };

  return (
    <div class='ns-stack'>
      <div class='ns-stack'>
        {snapshot.value.messages.map((m) => (
          <Message key={m.id} message={toMessageData(m)} />
        ))}
        {pending.value
          ? <Message message={ { role: 'assistant', author: { name: 'Assistant', agent: true }, pending: true } } />
          : null}
      </div>
      <PromptInput onSubmit={onSubmit} placeholder='Ask anything…' />
    </div>
  );
};

export default Chat;
```

A few rules keep the island cheap and correct: keep it leaf-shaped, pass plain serializable props in (the seed snapshot is serializable), and declare handlers as arrow functions. The connection's `close` / `stop` / `dispose` are one idempotent teardown — call `connection.dispose()` when the island unmounts so no subscription leaks.

> Live streaming vs settle-then-render
>
> This island re-materializes each turn once it
>
> settles
>
> , which keeps the code mechanical and correct — and reload durability, the headline feature, is fully in hand this way. The connection also exposes
>
> subscribe(signal)
>
> for token-by-token live chunks;
>
> chapter 6
>
> upgrades this island to that live subscription so replies stream in as they arrive.

> Why not useIslandQuery for the transcript?
>
> NetScript's typed island-query hooks (
>
> useIslandQuery
>
> /
>
> useLiveQuery
>
> ) are the right tool when a page reads a
>
> typed service contract
>
> — a cache-first read whose data lives behind an oRPC service, as the
>
> live-dashboard track
>
> shows end to end. The chat transcript is different: it is not a service query but a
>
> durable session stream
>
> , so it is read through
>
> createNetScriptChatConnection
>
> and reduced by the one projection, not fetched through a query key. If
>
> this
>
> page also showed, say, a typed list of past conversations from a service, that sidebar is exactly where a
>
> useIslandQuery
>
> island would belong — the transcript itself stays on the durable connection.

## Step 4 — Rich blocks with chat-render

Assistant replies are markdown, and they can embed fenced data blocks (`chart`, `donut`, `table`, `stats`, `line`). `parseBlocks` from the copied `chat-render` parser turns that markdown into typed **presentation** parts you render with the copied primitives:

```tsx
import { parseBlocks, type RenderPart } from '@app/lib/chat/parse-blocks.ts';
import { Markdown } from '@app/components/ui/markdown.tsx';
import { ChartBlock } from '@app/components/ui/chart-block.tsx';

const renderPart = (part: RenderPart) => {
  switch (part.kind) {
    case 'text':
      return <Markdown>{part.text}</Markdown>;
    case 'chart':
      return <ChartBlock title={part.title} data={part.data} unit={part.unit} />;
    // donut / table / stats / line follow the same shape → their primitive.
    default:
      return null;
  }
};

// Render an assistant message body as rich blocks:
// {parseBlocks(message.content).map(renderPart)}
```

`parseBlocks` never throws — an unrecognized fence falls back to a verbatim `text` part — and its inverse `blockToText` guarantees a parsed message survives a reload without drift.

> Two RenderParts — transport vs presentation
>
> Do not conflate the two
>
> RenderPart
>
> types.
>
> @netscript/fresh/ai
>
> emits the
>
> transport
>
> part (
>
> text
>
> |
>
> tool
>
> ) — the durable-session wire shape in
>
> snapshot.renderParts
>
> .
>
> chat-render
>
> 's
>
> parseBlocks
>
> owns the
>
> presentation
>
> part (
>
> chart
>
> |
>
> donut
>
> |
>
> table
>
> |
>
> stats
>
> |
>
> line
>
> |
>
> text
>
> ) — the rich blocks you mount. The transcript reduces through the first; the UI renders through the second.

## Verify your progress

With `aspire start` running, open the app in the browser:

1. The chat renders your existing transcript on load — no loading flash.
2. Type a message and send it; the assistant reply appears once the turn settles.
3. **Reload the page.** The full transcript is still there — that is the durable session, not browser state.
4. Type-check the app:

```bash
deno task --cwd apps/dashboard check
```

- [ ] `netscript ui:add ai` copied the chat components into `components/ui/` and the parser into `lib/chat/`.
- [ ] The chat renders the seeded transcript on first paint.
- [ ] Sending a message produces a persisted assistant reply.
- [ ] A reload replays the full transcript.
- [ ] `deno task --cwd apps/dashboard check` is clean.

## What you built

A working chat UI: copied, app-owned components; an SSR-seeded island that sends through the durable connection and re-renders on settle; and `chat-render` turning assistant markdown into rich blocks. Next you give the model a tool to call — and render its result as a tool-call card with citation chips.

[2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/) [4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/chat/03-chat-ui/_

---

# A server-side tool call

A chat gets useful when the model can *do* something. In this chapter you give the model one server-side tool, pass it into the same `chat()` call from chapter 2, and surface the invocation in the UI as a **tool-call card** whose results render as **citation chips**. The tool runs on the server — its result is captured in the durable transcript, so the card survives a reload exactly like the messages around it.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)
2. [2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)
3. [3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)
4. [4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)
5. [5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)
6. [6 · Live streaming](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

## What you will build

One tool — `searchDocs` — that the model can call to look something up, returning a short answer plus a list of sources. When the model calls it, the transcript records the invocation as a transport `tool` part, and the UI renders it as a `tool-call-card` with the sources shown as inline `[1]`, `[2]` citation chips.

## Step 1 — Define the tool

A tool is a name, a description the model reads to decide when to call it, an input schema, and a server handler. Build it with `toolDefinition(...).server(handler)` from `@tanstack/ai`: `.server()` marks the handler server-side, and `chat()` runs it automatically — on the server, inside the turn — whenever the model calls the tool. Keep the handler pure and fast; return a plain object, including a `citations` array, which is just structured output your UI knows how to render:

```ts
// apps/dashboard/lib/tools/search-docs.ts
import { toolDefinition } from '@tanstack/ai';

export const searchDocs = toolDefinition({
  name: 'searchDocs',
  description: 'Look up a short factual answer from the docs. Use for product questions.',
  // Plain JSON Schema is accepted; bring a Standard Schema library (Zod, Valibot, …)
  // as `inputSchema` instead if you want the handler args typed for you.
  inputSchema: {
    type: 'object',
    properties: { query: { type: 'string', description: 'The question to look up.' } },
    required: ['query'],
  },
}).server(async ({ query }: { query: string }) => {
  const hits = await lookup(query); // your retrieval — DB query, search index, etc.
  return {
    answer: hits.map((h) => h.snippet).join(' '),
    citations: hits.map((h, i) => ({ index: i + 1, source: h.title, href: h.url })),
  };
});
```

> Citations are plain tool output — not RAG magic
>
> The
>
> citations
>
> array is ordinary structured data your tool returns. There is no retrieval framework or vector store behind it — you decide what
>
> lookup
>
> does, and the UI renders whatever citations the tool hands back. If you want embeddings-backed retrieval under
>
> lookup
>
> , the
>
> @netscript/ai engine
>
> ships embedding provider ports (
>
> @netscript/ai/openai-embeddings
>
> ); full RAG and agent memory stay out of scope for this track.

## Step 2 — Pass the tool to the model

Wire the tool into the same `chat()` call from chapter 2 by adding a `tools` array. The model now decides, per turn, whether to call `searchDocs`; when it does, the runtime executes it and feeds the result back into the turn — and the whole exchange lands in the durable session.

```ts
// apps/dashboard/routes/api/chat/[sessionId].ts  (add tools to the existing chat() call)
import { chat } from '@tanstack/ai';
import { anthropicText } from '@tanstack/ai-anthropic';
import { resolveChatSnapshot, toNetScriptChatResponse } from '@netscript/fresh/ai';
import { searchDocs } from '../../../lib/tools/search-docs.ts';

// ...inside POST, after building `messages` and the authorize check:
const source = chat({
  adapter: anthropicText('claude-sonnet-4-5'),
  messages,
  systemPrompts: ['You are a helpful assistant. Use searchDocs for product questions.'],
  tools: [searchDocs],
});

return toNetScriptChatResponse({ target, request: ctx.req, authorize, source });
```

> The tool runs server-side — behind authorize
>
> The tool's server handler runs in the route, on the server, inside the same
>
> authorize
>
> -gated turn. Its result is persisted into the durable session as a transport
>
> tool
>
> part, so a reload replays the tool call and its result. Never move tool execution into the island — the browser has neither the credentials nor the trust boundary for it.

## Step 3 — Render the tool call as a card

The tool invocation arrives in the transcript as a transport `tool` part (`kind: 'tool'`) carrying `toolName`, `toolState`, `input`, and `output`. Map it onto the copied `tool-call-card`, and turn the `output.citations` into the `sources` list that `message`'s inline `[n]` markup renders as chips:

```tsx
// In the chat island's assistant renderer
import { ToolCallCard } from '@app/components/ui/tool-call-card.tsx';
import { CitationChip } from '@app/components/ui/citation-chip.tsx';
import type { RenderPart } from '@netscript/fresh/ai';

const toStatus = (state?: string) =>
  state === 'error' ? 'error' : state === 'complete' ? 'done' : 'running';

const renderToolPart = (part: RenderPart) => {
  if (part.kind !== 'tool') return null;
  const citations = (part.output as { citations?: { index: number; source?: string; href?: string }[] })
    ?.citations ?? [];
  return (
    <div class='ns-stack'>
      <ToolCallCard
        name={part.toolName ?? 'tool'}
        args={part.input}
        result={part.output}
        status={toStatus(part.toolState)}
      />
      {citations.length
        ? (
          <div class='ns-citations'>
            {citations.map((c) => <CitationChip index={c.index} source={c.source} />)}
          </div>
        )
        : null}
    </div>
  );
};

// Drive it from the transport render parts the snapshot already gives you:
// {snapshot.value.renderParts.filter((p) => p.kind === 'tool').map(renderToolPart)}
```

> One projection feeds the card
>
> The card reads from
>
> snapshot.renderParts
>
> — the transport parts produced by
>
> projectChatSnapshot
>
> , the same reducer the SSR seed used. That is the one-projection law paying off: because the tool part is materialized once, the card renders identically on first paint and after a reload, and its
>
> toolState
>
> is never ambiguous between the seed and live paths.

## Verify your progress

With `aspire start` running, open the app and ask a question that triggers the tool — for example, "what database does a scaffold use by default?":

1. The assistant reply includes a **tool-call card** naming `searchDocs`, expandable to show its arguments and result.
2. The answer carries inline `[1]` / `[2]` **citation chips** matching the tool's sources.
3. **Reload.** The card and its chips are still there — the tool call is in the durable transcript, not transient UI state.
4. Type-check the app:

```bash
deno task --cwd apps/dashboard check
```

- [ ] Asking a product question triggers a `searchDocs` tool-call card.
- [ ] The card shows the tool arguments and result on expand.
- [ ] Sources render as inline citation chips.
- [ ] A reload replays the card and chips.
- [ ] `deno task --cwd apps/dashboard check` is clean.

> If the model never calls the tool
>
> Models call a tool only when the description makes it obviously relevant. Sharpen the tool
>
> description
>
> and add a nudge to
>
> systemPrompts
>
> ("use searchDocs for product questions"). If the card renders but stays
>
> running
>
> , your tool handler threw — check the route logs; a thrown tool surfaces as an
>
> error
>
> card, not a crash.

## What you built

A server-side tool the model can call, wired into the same `authorize`-gated turn: its invocation and citations render as a durable `tool-call-card`, and because the tool runs on the server its result is captured in the durable transcript — so the card survives a reload exactly like the messages around it. Next you reach past your own code: chapter 5 connects the chat to a remote MCP server and renders the `ui://` widgets its tools return.

[3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/) [5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/chat/04-tool-call/_

---

# MCP tools & widgets

Chapter 4's tool was code you wrote. Real products also need capabilities that live behind **Model Context Protocol** servers — a docs-search server, an ops server, a vendor's tool endpoint. In this chapter you connect the chat to a remote MCP server with the `@netscript/ai/mcp` client stack, call one of its tools from the same `authorize`-gated turn, and render the `ui://` **widget** an MCP tool result can carry — sandboxed and themed, never as raw HTML in your island tree.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)
2. [2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)
3. [3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)
4. [4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)
5. [5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)
6. [6 · Live streaming](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

## The pieces — all shipped, one boundary

Three seams do the work, and every one of them is published and installable today:

**The MCP surface this chapter uses**

| Name | Type | Description |
| --- | --- | --- |
| `@netscript/ai/mcp` | `client stack — jsr:@netscript/ai` | createMcpTransportPool declares remote servers as data (stdio or reconnectable Streamable-HTTP, auth injected); callTool routes a call to its server; extractMcpUiResources pulls the data-only ui:// records out of a result. |
| `createMcpSandboxHandler` | `route — @netscript/fresh/ai/sandbox` | Serves a registered ui:// resource themed with the active token set and behind a per-response CSP. The serving half of the render path. |
| `McpUiWidget` | `island — fresh-ui copy registry` | The copied island (installed by netscript ui:add ai in chapter 3) that renders a ui:// resource in a sanitized, no-referrer sandboxed frame through the sandbox route. |

> Client, not server
>
> NetScript's shipped MCP surface is
>
> client-side
>
> : your app
>
> consumes
>
> external MCP servers as tools. There is no scaffolded NetScript MCP server in this release — this chapter points your chat
>
> at
>
> a server, it does not make your app one. See
>
> the MCP guide
>
> for the full client stack.

## What you will build

A `searchRemote` tool whose handler routes through an MCP transport pool instead of your own code: the model calls it like any chapter-4 tool, the pool executes it on the remote server, and the result — including any `ui://` widget the server returns — lands in the durable transcript and renders in the chat, themed and walled off behind a per-response CSP.

## Before you begin

You need the working chat from chapters [1](https://rickylabs.github.io/netscript/tutorials/chat/01-scaffold/)–[4](https://rickylabs.github.io/netscript/tutorials/chat/04-tool-call/), plus the engine package, which owns the MCP client stack:

```sh
deno add jsr:@netscript/ai
```

You also need an MCP server to talk to — any Streamable-HTTP MCP endpoint you have access to works (a docs-search server is the running example below). Put its URL and token in the app environment next to your model key, never in code.

## Step 1 — Declare the server pool

`createMcpTransportPool` turns server declarations into a connected tool surface. The configs are **serializable data** — kind, id, URL, auth — so they can live in configuration. Auth is injected here at the composition root, never baked into a transport:

```ts
// apps/dashboard/lib/mcp/pool.ts
import { createMcpTransportPool } from '@netscript/ai/mcp';

export const mcpPool = createMcpTransportPool({
  servers: [{
    kind: 'streamable-http',
    serverId: 'search',
    url: Deno.env.get('MCP_SEARCH_URL')!,
    auth: { mode: 'api-token', token: Deno.env.get('MCP_TOKEN')!, scheme: 'Bearer' },
  }],
});

// connect() opens every pooled transport and returns the discovered tools,
// name-prefixed by server id ("search:…") so two servers' tools never collide.
export const mcpTools = await mcpPool.connect({});
```

The Streamable-HTTP transport is built for long-lived sessions: it reconnects with backoff, and `reconnecting` is a first-class `McpConnectionState`, not an error. Add a second server to the `servers` array and the pool keeps their tools namespaced — many servers, one surface.

## Step 2 — Bridge a pooled tool into the chat turn

Your route's model call runs on `@tanstack/ai` (chapter 2), so give the model a chapter-4-style tool whose **handler routes through the pool**. `callTool` sends the prefixed tool name to its server and hands back the result with any `ui://` resources already extracted:

```ts
// apps/dashboard/lib/tools/search-remote.ts
import { toolDefinition } from '@tanstack/ai';
import { mcpPool } from '../mcp/pool.ts';

export const searchRemote = toolDefinition({
  name: 'searchRemote',
  description: 'Search the product docs. Use for any product or how-to question.',
  inputSchema: {
    type: 'object',
    properties: { query: { type: 'string', description: 'The question to look up.' } },
    required: ['query'],
  },
}).server(async ({ query }: { query: string }) => {
  // Route the call to the remote server through the pool.
  const result = await mcpPool.callTool('search:search_docs', { query }, {});
  // Plain structured output, like chapter 4 — plus the extracted ui:// records.
  return { result, uiResources: result.uiResources ?? [] };
});
```

Add `searchRemote` to the same `tools` array as chapter 4's `searchDocs`. Nothing else in the route changes: the tool runs server-side, inside the `authorize`-gated turn, and the whole exchange — arguments, result, and the `ui://` references — is persisted as a transport `tool` part in the durable session.

> Two ways in — this track takes the bridge
>
> The engine-native path is
>
> registerMcpTools(registry, pool)
>
> , which surfaces remote tools into the engine's tool registry for its
>
> agent loop
>
> to dispatch — registration is reversible via
>
> .stop()
>
> . This track bridges through a
>
> @tanstack/ai
>
> tool instead, because the durable session plane persists and replays TanStack chunk streams (the wire-shape note from chapter 2). Same pool, same servers — choose the entry point that matches your model-call layer.

## Step 3 — Render the `ui://` widget, sandboxed

An MCP tool result can embed `ui://` resources — **UI authored by the server, not by you**. They reach the page only through two guardrails, both already in your app:

1. **The sandbox route.** Mount `createMcpSandboxHandler` once; it serves a registered resource selected by `?uri=`, injects the active theme's `--ns-*` custom properties, stamps `data-theme`, and applies a per-response CSP derived from the resource URI. `?theme=` picks a token set; an unknown theme falls back to `defaultThemeName` (`"default"`).

```ts
// apps/dashboard/routes/mcp/sandbox.ts
import { createMcpSandboxHandler } from '@netscript/fresh/ai/sandbox';
import { resourceRegistry } from '../../lib/mcp/registry.ts';

export const handler = {
  GET: createMcpSandboxHandler({
    resolveResource: (uri, { signal }) => resourceRegistry.lookup(uri, { signal }),
    themes: {
      default: { '--ns-color-surface': '#ffffff' },
      dark: { '--ns-color-surface': '#111111' },
    },
  }),
};
```

1. **The widget island.** The `ai` collection you copied in chapter 3 includes the `McpUiWidget` island: hand it a `ui://` resource from the tool part's output and it renders the widget in a sanitized, `no-referrer` sandboxed frame served through the route above. In the chapter-4 render switch, a tool part whose output carries `uiResources` renders those through `McpUiWidget` alongside (or instead of) the plain tool-call card.

> Server-authored UI never enters your island tree raw
>
> This is the same trust boundary as the generative-UI renderer: model- or server-authored UI reaches the page only through a curated renderer or the sandbox — sanitized, themed, CSP-guarded, frame-isolated. Never interpolate a
>
> ui://
>
> resource's content into your own markup. And do not build on
>
> createNetScriptMcpSandbox
>
> (the chat-activity tool sandbox): it is a skeleton stub in this release — the route + widget path above is the shipped one.

## Verify your progress

With `aspire start` running and your MCP server reachable:

1. Ask a question that triggers the remote tool. The reply carries a tool-call card naming `searchRemote` — its result came over MCP, not from your code.
2. If the server returned a `ui://` resource, the **widget renders** inside the chat, themed like the page around it.
3. Probe the sandbox route directly and check the isolation headers:

```sh
curl -i 'http://localhost:8010/mcp/sandbox?uri=ui%3A%2F%2Fwidget%2Fdemo&theme=dark'
```

You should see the resolved resource with `data-theme="dark"` and the dark `--ns-*` tokens, under a `content-security-policy` response header derived from the resource URI.

1. **Reload.** The tool card — and the widget reference in its output — replays from the durable session, exactly like every other part of the transcript.
2. Type-check the app:

```bash
deno task --cwd apps/dashboard check
```

- [ ] `deno add jsr:@netscript/ai` resolved and the pool `connect()`s to your server.
- [ ] Asking a relevant question triggers the `searchRemote` tool over MCP.
- [ ] A `ui://` result renders through `McpUiWidget`, themed and framed.
- [ ] The sandbox route answers with theme tokens and a per-response CSP.
- [ ] A reload replays the tool card and its widget reference.
- [ ] `deno task --cwd apps/dashboard check` is clean.

> If the remote tool never fires
>
> Check the pool first:
>
> connect()
>
> returns the discovered tool descriptors — if your tool is missing, the server URL, auth mode, or token is wrong. A tool that fires but errors surfaces as an
>
> error
>
> tool card (chapter 4's rule), and a dropped connection shows as the transport's
>
> reconnecting
>
> state, not a crash — subscribe with
>
> onStateChange
>
> to watch the lifecycle while debugging.

## What you built

A chat whose tools no longer stop at your own code: a declared MCP server pool, a bridged tool the model calls like any other, and server-authored `ui://` widgets rendered through the sandbox route and the copied `McpUiWidget` island — durable in the transcript, isolated on the page. Next you make the whole transcript feel live — folding the model's chunks into the UI as they arrive instead of after each turn settles.

[4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/) [6 · Live streaming](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/chat/05-mcp/_

---

# Live streaming

Your chat works, but it still feels turn-based: chapter 3's island fires a turn, waits for it to **settle**, then re-materializes the transcript in one jump. Real chat streams — the reply appears token by token, the tool card moves through `pending → streaming → complete` in front of you. In this final chapter you switch the island from settle-then-render to a **live subscription**, folding each chunk into the transcript as it arrives on the same durable connection you already opened.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/chat/01-scaffold/)
2. [2 · Durable chat route](https://rickylabs.github.io/netscript/netscript/tutorials/chat/02-durable-chat-route/)
3. [3 · Chat UI](https://rickylabs.github.io/netscript/netscript/tutorials/chat/03-chat-ui/)
4. [4 · Server-side tool call](https://rickylabs.github.io/netscript/netscript/tutorials/chat/04-tool-call/)
5. [5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/)
6. [6 · Live streaming](https://rickylabs.github.io/netscript/netscript/tutorials/chat/06-live-streaming/)

## The live half of a durable stream

A durable chat session is one append-only log, and it has two readers. The **seed** reader (`resolveChatSnapshot`) materializes everything written so far for first paint. The **live** reader is `createNetScriptChatConnection(...).subscribe(signal)` — an async iterable that yields each new chunk as the server appends it. You already opened the connection in chapter 3 to `send` messages; here you finally read from it.

**@netscript/fresh/ai — the live-read seam**

| Name | Type | Description |
| --- | --- | --- |
| `connection.subscribe(signal)` | `AsyncIterable` | Yields each durable chunk as it lands. SR2-tolerant: a first subscribe that races a not-yet-created stream re-polls with backoff instead of throwing. |
| `initialOffset` | `connection option` | The seed snapshot's offset — hand it in so the live read continues from where SSR stopped, one continuous log. |
| `connection.dispose()` | `() => void` | One idempotent teardown (close / stop / dispose) — call it on unmount so no subscription leaks. |

> This is the same producer→consumer split as any durable stream
>
> The durable chat plane is the
>
> durable-streams
>
> plane specialized for conversations: the server
>
> produces
>
> chunks into the session log, and the browser
>
> consumes
>
> them live over the connection — the log outlives both the turn that wrote it and the tab that was watching. Chapter 2's route is the producer; the subscription below is the consumer.

## Step 1 — Subscribe from the island

Replace chapter 3's "fire the turn, then re-materialize on settle" flow with a live loop. On mount, open a subscription seeded at the snapshot's `offset`; for each chunk, re-derive the rendered transcript through the **same projection the seed used**, so live and seed never disagree about an in-flight tool card. The connection is the one from chapter 3 — you are adding the read side.

```tsx
// apps/dashboard/islands/Chat.tsx — the live subscription (replaces the settle-then-render onSubmit)
import { useSignal } from '@preact/signals';
import { useEffect } from 'preact/hooks';
import { createNetScriptChatConnection, resolveChatSnapshot } from '@netscript/fresh/ai';
import type { NetScriptChatSnapshot } from '@netscript/fresh/ai';
import { chatTurnRoute } from '@app/contracts/routes/chat-turn.ts';

const Chat = ({ sessionId, seed }: { sessionId: string; seed: NetScriptChatSnapshot }) => {
  const snapshot = useSignal(seed);
  const base = `${location.origin}/api/chat-stream`;

  const connection = createNetScriptChatConnection({
    target: { sessionId, baseUrl: base },
    initialOffset: seed.offset ?? undefined, // continue from the SSR seed cursor
    authorize: () => true, // browser half; the server route re-checks ownership
  });

  // Live read: fold each chunk into the transcript as it lands.
  useEffect(() => {
    const controller = new AbortController();
    (async () => {
      for await (const _chunk of connection.subscribe(controller.signal)) {
        // Re-materialize through the SAME projection the seed used, so the in-flight
        // tool card moves pending → streaming → complete without drift.
        snapshot.value = await resolveChatSnapshot({ target: { sessionId, baseUrl: base } });
      }
    })();
    return () => {
      controller.abort();
      connection.dispose(); // idempotent teardown — no leaked subscription
    };
  }, []);

  const onSubmit = async (text: string) => {
    // 1. Append the user message to the durable session.
    await connection.send([{ id: crypto.randomUUID(), role: 'user', content: text }]);
    // 2. Fire the model turn. Its chunks now arrive through the subscription above —
    //    no manual re-materialize here; the live loop owns rendering.
    await fetch(chatTurnRoute.href({ path: { sessionId } }), { method: 'POST' });
  };

  return (
    <div class='ns-stack'>
      <div class='ns-stack'>
        {snapshot.value.messages.map((m) => <Message key={m.id} message={toMessageData(m)} />)}
      </div>
      <PromptInput onSubmit={onSubmit} placeholder='Ask anything…' />
    </div>
  );
};

export default Chat;
```

The shape of the change is the point: `onSubmit` no longer re-reads the transcript itself. It just appends the prompt and fires the turn; the **subscription** is what advances the UI, one chunk at a time, for this tab and any other tab watching the same session.

> One projection, seed and live
>
> The live loop re-derives through
>
> resolveChatSnapshot
>
> — which reduces the session through
>
> projectChatSnapshot
>
> , the
>
> same
>
> reducer that seeded first paint. That is the one-projection law from chapter 3 doing its job under streaming: because both paths route through one reducer, a tool card rendered mid-stream never jumps or vanishes when the next chunk arrives. Never hand-roll a separate live reducer — seed and live must share the projection.

## Step 2 — Tear down cleanly

A live subscription is a long-lived resource. The `useEffect` above aborts its `AbortController` and calls `connection.dispose()` on unmount — `close` / `stop` / `dispose` are one idempotent teardown, so calling it twice is harmless and calling it once is mandatory. Skip it and every navigation away from the chat leaks a subscription against the streams runtime.

> Backpressure and reconnect are already handled
>
> subscribe
>
> is SR2-tolerant: if the island mounts and subscribes before the session stream exists (a fresh chat), it re-polls with backoff instead of throwing. And because reads are seeded from
>
> initialOffset
>
> , a reconnect resumes from the last chunk you saw rather than replaying the whole log — the durable offset is the reconnect cursor.

## Verify your progress

With `aspire start` running, open the app in two browser tabs pointed at the same session:

1. In tab A, send a message. The assistant reply **streams in** — text grows as chunks land, and a tool call surfaces as a card that fills from `pending` to `complete` — rather than appearing all at once when the turn settles.
2. Watch **tab B**: the same message and reply appear live there too, with no refresh. Two consumers, one durable log.
3. **Reload either tab.** The full transcript is still there and the live read resumes from the seed offset — durability and live streaming on the one connection.
4. Type-check the app:

```bash
deno task --cwd apps/dashboard check
```

- [ ] The island opens `connection.subscribe(signal)` seeded at the snapshot `offset`.
- [ ] An assistant reply renders incrementally as chunks arrive, not only on settle.
- [ ] A second tab on the same session updates live.
- [ ] `connection.dispose()` runs on unmount (no leaked subscription).
- [ ] A reload replays the transcript and resumes the live read.
- [ ] `deno task --cwd apps/dashboard check` is clean.

> If the reply does not stream
>
> If replies still appear only on settle, confirm the subscription loop is actually running — a thrown
>
> authorize
>
> on the server route (chapter 2) closes the stream, and an empty subscription usually means the streams runtime is not up (check the
>
> Aspire dashboard
>
> ). If a second tab never updates, both tabs must target the
>
> same
>
> sessionId
>
> — the session id is the stream identity.

## What you built

A complete, production-shaped durable AI chat: a scaffolded workspace, an `authorize`-gated route that streams and persists each turn, an app-owned chat UI, a server-side tool with citation chips, remote MCP tools whose `ui://` widgets render themed and sandboxed, and now a live subscription that folds the model's chunks into the transcript the moment they land — across tabs and across reloads, because every part lives in the durable session rather than the browser.

That progression — **one agreed message shape → durable delivery → live stream** — is the spine every NetScript real-time surface is built from; you just built it in its AI-chat form. Where to go next:

- Reach for the durable-chat seams directly with the [Build a durable chat](https://rickylabs.github.io/netscript/ai/how-to/build-a-durable-chat/) recipe.
- Restyle any chat or widget component — you own the copied source: [Customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/).
- Model live list/board/table data (the other real-time plane) with [Publish a durable stream](https://rickylabs.github.io/netscript/durable-workflows/how-to/publish-a-durable-stream/).
- Compose the provider-neutral engine — model registry, agent loop, tool registry, MCP transports: [AI engine](https://rickylabs.github.io/netscript/ai/engine/).
- Look up exact signatures in the [fresh reference](https://rickylabs.github.io/netscript/reference/fresh/).

[5 · MCP tools & widgets](https://rickylabs.github.io/netscript/netscript/tutorials/chat/05-mcp/) [Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/chat/06-live-streaming/_

---

# ERP Sync

Your team is mid-migration between two ERPs. **SAP**, the legacy system, is still the system of record — production plans against it every day. **Microsoft Dynamics**, its replacement, goes live in stages, which means that for months the two run in parallel and Dynamics is only as correct as the sync that feeds it. The integration you are handed is a **file export**, not an API: SAP drops a nightly file, and your job is to ingest it. This track builds that sync: a back-office service that watches for the SAP export drops, turns each one into a durable background job, transforms legacy rows into Dynamics' shape, absorbs backfill bursts behind a queue, and re-syncs nightly on a cron. It is the durable-processing companion to the [main tutorials ladder](https://rickylabs.github.io/netscript/tutorials/): where that ladder ends at a request/response service plus a webhook, this one is about everything that happens **off** the request path.

The differentiator this track proves is **durable background processing you did not hand-roll**: the file-watch trigger, the job, the queue, and the cron are first-class NetScript primitives wired into one orchestrated runtime — in place of the pile of cron entries, ad-hoc `nohup` workers, and bespoke glue scripts most teams reach for, the kind that silently drop a file or a row when a process dies mid-run.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/)
2. [2 · Import job](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)
3. [3 · Polyglot transform](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/)
4. [4 · Queue & cron](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/)
5. [5 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/05-deploy/)

## What you will build

By the end of this five-chapter track you will have `my-erp/` on disk: a NetScript workspace with the **workers** and **triggers** plugins installed, a file-watch trigger that fires the moment the SAP export job drops a `products_*.csv` into the hand-off folder, a background **job** that parses it, a runnable **transform task** — executed as a sandboxed subprocess — that rewrites the legacy columns and integer-cent prices into Dynamics' shape, a **queue** sized for backfill bursts, and a **cron** schedule that re-syncs nightly — all orchestrated locally by Aspire and visible in one dashboard. Along the way you will see how the same task builder targets **polyglot** (non-TypeScript) runtimes, so a Python or shell step can join the pipeline when TypeScript is not the right tool.

The spine is one idea repeated at every layer: **durable background processing**. The stakes are concrete: a file the watcher misses is a day of catalog changes Dynamics never sees; a row loaded untransformed puts prices off by a factor of one hundred; a burst that overwhelms a single worker delays the re-sync everyone plans against. An inbound file becomes a queued job; the job runs in an isolated worker; the transform runs in a sandboxed subprocess; recurring work runs on a schedule; and nothing is lost across a restart.

## The arc

```
SAP export job drops products_2024.csv     (a file lands in .data/incoming/products)
        │  defineFileWatch trigger fires on 'create'
        ▼
enqueueJob('import-products')              (a durable worker job, :8091)
        │  the job parses + records the raw SAP rows
        ▼
normalize-sap transform task               (sandboxed deno subprocess: SAP shape → Dynamics shape)
        │
        ▼
queue provider (Deno KV → Redis/RabbitMQ)  (sized for backfill bursts in config)
        │
        ▼
cron / scheduled trigger                   (nightly re-sync until cutover)
```

Every chapter on this spine is hands-on and closes on something you can observe — a JSON body, a log line, a file on disk. Chapter 3 also carries the track's one deliberately forward-looking section: the Python variant of the transform, marked plainly as a step for your own host because non-Deno runtimes are not sandboxed and need their interpreter installed.

## The chapters

[1 · Scaffold the workspace  Create `my-erp/` with `netscript init`, add the **workers** and **triggers** plugins, and boot the whole thing under Aspire. Ends at the dashboard on `:18888`.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/)

[2 · Import job  Watch `.data/incoming/products` with `defineFileWatch` and turn every `products_*.csv` the SAP export drops into a durable `defineJobHandler` background job that parses the rows.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)

[3 · Polyglot transform  Build and **run** the SAP→Dynamics transform as a sandboxed `deno` task: `defineTask`, explicit `.permissions()` compiled to `--allow-*` flags, and the executor. The Python variant is the caveated next step.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/)

[4 · Queue & cron  Pick a `QueueProvider`, size worker concurrency in config, and add a `defineScheduledTrigger` cron for the nightly re-sync. Includes the concurrency env-var gotcha.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/)

[5 · Deploy locally  Run the whole sync — workers, triggers, queue, and cron processors — on one machine under `aspire start`, and read it from the dashboard. Shows local-vs-production topology clearly.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/05-deploy/)

## Before you start

This track assumes the same local toolchain as the main ladder: a recent [Deno](https://deno.com/) and the [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/) CLI on your `PATH`, plus Docker running so Aspire can provision Postgres and Redis. This track uses Postgres (the default; swap `--db postgres` for `mysql`, `mssql`, or `sqlite` when you scaffold). If NetScript is brand new to you, walk the [Storefront tutorial](https://rickylabs.github.io/netscript/tutorials/storefront/) first — it explains every generated directory in more depth than we re-cover here. This track then re-grounds you from a fresh scaffold, so you can start either place.

> One workspace, five chapters
>
> Every chapter grows the same
>
> my-erp/
>
> project. Each one opens with a
>
> Before you begin
>
> state check and closes with
>
> What you built
>
> , so the work compounds instead of resetting between chapters. Follow them in order.

[Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/)

After this track, keep building in **Build › [Background jobs](https://rickylabs.github.io/netscript/background-processing/)** — the guides and recipes there pick up where these chapters stop.

_Canonical: https://rickylabs.github.io/netscript/tutorials/erp-sync/_

---

# Scaffold the workspace

This is the first chapter of the ERP Sync track — the service that keeps **Microsoft Dynamics**, the ERP your team is migrating to, fed from the file exports of **SAP**, the legacy system that is still the system of record. Before you can watch the SAP file drops or run background jobs, you need a workspace with the right plugins installed and an orchestrator to run them. In this chapter you create `my-erp/`, add the **workers** and **triggers** plugins, and boot the whole stack under Aspire so the rest of the track has something real to build on.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/)
2. [2 · Import job](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)
3. [3 · Polyglot transform](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/)
4. [4 · Queue & cron](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/)
5. [5 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/05-deploy/)

## What you will build

By the end of this chapter you will have `my-erp/` on disk — a NetScript workspace with a Postgres database, the **workers** plugin at `plugins/workers/` (the background-job engine on `:8091`), and the **triggers** plugin at `plugins/triggers/` (the ingress engine on `:8093`) — all running together under one `aspire start`, with the Aspire dashboard live on `:18888`.

## Before you begin

You need the same local toolchain the [main tutorials](https://rickylabs.github.io/netscript/tutorials/) use:

- **[Deno](https://deno.com/) 2.x** on your `PATH` — check with `deno --version`.
- The **[Aspire CLI](https://aspire.dev)** — check with `aspire --version`. Aspire provisions your database and cache locally so you do not wire up Docker by hand.
- **Docker** running, so Aspire can start the Postgres and Redis containers — confirm with `docker info`.

Install the NetScript CLI from JSR once, then confirm it:

```sh
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11
netscript --help
```

You should see the public command groups, including `init`, `plugin`, `generate`, `db`, and `deploy`. If `netscript` is not found, make sure Deno's install directory is on your `PATH` and open a fresh terminal.

> Prefer not to install globally?
>
> Run any command ad-hoc with
>
> deno x jsr:@netscript/cli@0.0.1-beta.11 <command>
>
> . The rest of this track assumes the installed
>
> netscript
>
> form.

## Step 1 — Preview the scaffold with a dry run

Before writing files, ask the CLI what it *would* create. `--dry-run` plans the scaffold and prints the file and directory totals per phase without touching disk:

```sh
netscript init my-erp --dry-run
```

A clean dry run means your flag combination is valid — the CLI rejects bad option mixes (an unknown `--db` engine, for instance) here, before any files exist. Treat it as a green light to scaffold for real.

## Step 2 — Create the workspace

This track needs a database to anchor durable execution, so scaffold with Postgres — the recommended default. `--db` is polyglot: swap `postgres` for `mysql`, `mssql`, or `sqlite` and the rest of the track works the same (this track uses `postgres` throughout):

```sh
netscript init my-erp --db postgres
cd my-erp
```

This scaffolds `my-erp/`, formats the output with `deno fmt`, and initializes a git repository. On completion the CLI prints a **next steps** summary tailored to your options.

**netscript init options used here (run netscript init --help for the full list)**

| Option | What it does |
| --- | --- |
| --db postgres | Scaffold a Postgres database workspace. Durable execution and queue persistence anchor on it. |
| --dry-run | Plan the scaffold and print totals without writing any files. |
| --no-aspire | Skip the Aspire orchestration files. Do NOT pass this — the rest of the track runs under Aspire. |

> Where is packages/?
>
> If you scaffolded from a checkout of the NetScript repo you may see a vendored
>
> packages/
>
> directory. A normal JSR install does not have one — your project pulls
>
> @netscript/*
>
> from the registry. Ignore
>
> packages/
>
> in this track.

## Step 3 — Add the workers plugin

NetScript's background capabilities arrive as plugins. Add the **workers** plugin with its sample jobs so you have a working reference to read and adapt:

```sh
netscript plugin install worker --name workers --samples
```

This lands the plugin at **`plugins/workers/`** — the canonical, config-referenced install location — and registers it in `netscript.config.ts` (`./plugins/workers/mod.ts`) and `appsettings.json`. The workers plugin ships an API service on `:8091` and a separate background processor that drains the job queue.

## Step 4 — Add the triggers plugin

Now add the **triggers** plugin, which is how NetScript receives events — including the file-watch trigger you build in [Chapter 2](https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/):

```sh
netscript plugin install trigger --name triggers --samples
```

This lands a workspace at `plugins/triggers/` and registers it in `netscript.config.ts` (`./plugins/triggers/mod.ts`) and `appsettings.json`. The triggers API runs on `:8093`. Confirm both plugins registered:

```sh
netscript plugin list
```

You should see `workers` and `triggers` in the registry.

> Two trees, one canonical home
>
> A scaffold may also create slimmer top-level
>
> workers/
>
> and
>
> triggers/
>
> directories — workspace members that stage a subset of files for the background processors. The real, config-referenced plugins live at
>
> `plugins/workers/`
>
> and
>
> `plugins/triggers/`
>
> : that is what
>
> netscript.config.ts
>
> points at and where you author code. Edit under
>
> plugins/
>
> .

## Step 5 — Bring up orchestration

This is the step that turns a folder of files into a running system. **Aspire provisions your database and cache and starts every process; you do not start containers by hand, and you run it before any `netscript db` command.** Run it from the `aspire/` subfolder so the CLI sees `apphost.mts`:

```sh
cd aspire
aspire restore   # once per machine: restores the Aspire SDK modules into .aspire/
aspire start       # starts the AppHost and every declared resource
```

`aspire start` brings up Postgres, the Redis cache, the workers API + processor, and the triggers API

- processor together, then prints a URL and a one-time login token for the **Aspire dashboard**:

```
https://localhost:18888
```

The dashboard's **Resources** tab is the authority for which port each resource bound — the conventional assignments (workers `:8091`, triggers `:8093`) are what this two-plugin workspace lands on, allocated from the `:8091–8099` plugin range. Leave `aspire start` going in this terminal; it is your control plane for the rest of the track.

> Aspire is step 2 — database commands need it running
>
> The Postgres container only exists while
>
> aspire start
>
> is up. So
>
> netscript db init
>
> ,
>
> db generate
>
> , and
>
> db seed
>
> must run
>
> after
>
> Aspire has started — never before. There is more on the database sequence in
>
> Deploy locally with Aspire
>
> .

## Verify your progress

In a second terminal (leave `aspire start` going in the first), confirm both plugin APIs are alive:

```sh
curl http://localhost:8091/health   # workers API
curl http://localhost:8093/health   # triggers API
```

Both should return a healthy JSON response. Then type-check the whole workspace from the project root:

```sh
deno task check
```

Expected: a clean check with no errors — the scaffold, both plugins, and the database wiring all line up.

- [ ] `my-erp/` exists with `plugins/workers/` and `plugins/triggers/` on disk.
- [ ] `netscript plugin list` shows both `workers` and `triggers`.
- [ ] `aspire start` is up; the dashboard on `:18888` lists `postgres`, `redis`, and both plugin APIs.
- [ ] `curl :8091/health` and `curl :8093/health` both return healthy.
- [ ] `deno task check` is clean.

> If something is not green
>
> Three checks cover most first-run snags: (1) is
>
> aspire start
>
> still up, with
>
> postgres
>
> and
>
> redis
>
> healthy in the
>
> dashboard
>
> ? (2) is Docker running (
>
> docker info
>
> )? (3) did you
>
> cd aspire
>
> before
>
> aspire start
>
> , so it found
>
> apphost.mts
>
> ? A failed
>
> curl
>
> usually means a service is still starting — give it a few seconds and retry.

## What you built

A real NetScript workspace, `my-erp/`, with the **workers** and **triggers** plugins installed and the whole stack — Postgres, Redis, both plugin APIs and their background processors — running under one `aspire start` and visible in the dashboard. Next, you give it the SAP export to ingest.

[ERP Sync](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/) [2 · Import job](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/erp-sync/01-scaffold/_

---

# A CSV file-watch import job

In [Chapter 1](https://rickylabs.github.io/netscript/tutorials/erp-sync/01-scaffold/) you stood up `my-erp/` with the workers and triggers plugins running. Now you wire the first real piece of the pipeline: a **file-watch trigger** that fires the moment the SAP export job drops a CSV into the hand-off folder, and a durable **background job** that parses it. This is the ingest core of the migration — the SAP export reaches you as a file, not an API call, and every file it writes must become durable background work. A file the watcher misses is a day of catalog changes Dynamics never sees; a file parsed twice is a day counted twice. Both failure modes start here, so this chapter is where the pipeline earns the word *durable*.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/)
2. [2 · Import job](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)
3. [3 · Polyglot transform](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/)
4. [4 · Queue & cron](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/)
5. [5 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/05-deploy/)

## What you will build

By the end of this chapter, dropping a file named `products_*.csv` into `my-erp/.data/incoming/products` will automatically enqueue and run a worker job that reads the file, parses its rows, logs a summary, and returns a structured success result — all without any HTTP call. You author two files: a **trigger** (`defineFileWatch`) and a **job** (`defineJobHandler`), then register the job so the trigger can address it by `id`.

## Before you begin

You need the workspace from [Chapter 1](https://rickylabs.github.io/netscript/tutorials/erp-sync/01-scaffold/) with **both** the workers and triggers plugins installed, and `aspire start` healthy. Confirm the prior state from the project root:

```sh
netscript plugin list
```

Expected: `workers` and `triggers` both appear. Also confirm Aspire is up — the file-watch processor and the workers runtime both depend on it:

```sh
curl http://localhost:8091/health   # workers API, healthy JSON
curl http://localhost:8093/health   # triggers API, healthy JSON
```

If either is missing, return to Chapter 1 — do not start over.

## Step 1 — Create the watched folder

The trigger watches a directory; create it (and the staging path suppliers will write to) so the watcher has something to attach to:

```sh
mkdir -p .data/incoming/products
```

This is just a local folder in your workspace. In production it would be the mounted share the SAP nightly export job writes into; the trigger does not care where the bytes come from, only that a matching file appears.

## Step 2 — Scaffold the import job

A NetScript job is a function wrapped by `defineJobHandler`, given a stable `id`, and exported as the module default. Inside the handler you receive a `ctx` carrying the payload, do the work, and return a result built with `createSuccessResult` / `createFailureResult`. Create the job under the workers plugin. Let the CLI create the payload schema, handler wrapper, stable export, and registry entry:

> ns-workers / ns-triggers are shorthands you install once
>
> ns-workers
>
> and
>
> ns-triggers
>
> are names
>
> you
>
> give the workers and triggers plugin CLIs — the scaffold does not create them. Install them once, globally, and every shorthand command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> deno install -gArf -n ns-triggers jsr:@netscript/plugin-triggers@0.0.1-beta.11/cli
> ```
>
> Rather not install them? Each
>
> ns-<plugin> <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-<plugin>@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```sh
ns-workers add job import-products
```

In `workers/jobs/import-products.ts`, extend the generated `PayloadSchema` with `filePath` and `fileName`, import `createFailureResult`, and replace only the starter handler body with the CSV logic below:

```ts
const handler = defineJobHandler(async (ctx) => {
  const { filePath, fileName } = PayloadSchema.parse(ctx.payload ?? {});

  // 1. Read the staged file.
  let rawContent: string;
  try {
    rawContent = await Deno.readTextFile(filePath);
  } catch (error: unknown) {
    const message = error instanceof Error ? error.message : String(error);
    return createFailureResult(`Failed to read ${fileName}: ${message}`);
  }

  // 2. Parse a simple CSV (header row + data rows). No external lib needed.
  const lines = rawContent.trim().split('\n').filter((line) => line.trim().length > 0);
  if (lines.length < 2) {
    return createFailureResult('CSV is empty or has no data rows');
  }
  const headers = lines[0].split(',').map((h) => h.trim().toLowerCase());
  const rows = lines.slice(1).map((line) => {
    const values = line.split(',').map((v) => v.trim());
    const row: Record<string, string> = {};
    headers.forEach((h, i) => row[h] = values[i] ?? '');
    return row;
  });

  // 3. Return a structured result. The runtime records it on the execution.
  return createSuccessResult({ fileName, rowCount: rows.length, headers });
});
```

The two things to read off this: the handler is an `async`/arrow function (never a bare `function`), and the stable `id` is attached with `Object.assign` so the runtime registry can address the job by a predictable string rather than its filename.

> Jobs do one thing
>
> This handler reads, parses, and reports — and stops. In a fuller ERP sync the next step (validate, upsert into a service, publish a saga message) would be its own job or a saga, keeping each unit small and independently retryable. The scaffold's
>
> --samples
>
> jobs show that fuller chain under
>
> plugins/workers/jobs/
>
> ; for this track one job is enough to prove the pipeline.

## Step 3 — Scaffold the file-watch trigger

Create the watcher from the current trigger CLI surface:

The `add-file-watch` verb uses the spaced `add file-watch` shell syntax:

```sh
ns-triggers add file-watch product-import-trigger \
  --path=.data/incoming/products \
  --pattern=products_*.csv
```

The command writes `triggers/product-import-trigger.ts` and refreshes the trigger registry. The file-watch command deliberately scaffolds a neutral handler, so replace that generated handler with the enqueue effect shown below. `defineFileWatch(handler, spec)` comes from `@netscript/plugin-triggers-core/builders`. The handler returns an **array of effects**; the one you want is `enqueueJob(jobRef, { payload })`, which hands a worker job the inbound event. The job is referenced by a small typed object — its `id`, `name`, `topic`, and `entrypoint`.

```ts
import { defineFileWatch, enqueueJob } from '@netscript/plugin-triggers-core/builders';
import type { JobDefinition } from '@netscript/plugin-workers-core';

// A reference to the worker job authored in Step 2.
const importProductsJob = {
  id: 'import-products' as JobDefinition<'import-products'>['id'],
  name: 'Import Products',
  topic: 'default',
  entrypoint: './workers/jobs/import-products.ts',
} satisfies JobDefinition<'import-products'>;

export default defineFileWatch(
  // event.payload carries filePath / fileName for the matched file.
  (event) => Promise.resolve([enqueueJob(importProductsJob, { payload: event.payload })]),
  {
    id: 'product-import-trigger',
    paths: ['.data/incoming/products'],
    patterns: ['products_*.csv'],
    on: ['create'],
    stabilityThreshold: { checkIntervalMs: 1000, stableChecks: 2 },
    description: 'Watches for product CSV files and starts the import job.',
    tags: ['file-watch', 'product', 'import'],
  },
);
```

Read the `spec` carefully — it is the whole behavior of the watcher:

**FileWatchSpec — the static fields you set on defineFileWatch**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable identifier for this trigger, used in logs and the events feed. |
| `paths` | `string[]` | Directories to watch. Here, the .data/incoming/products folder you created in Step 1. |
| `patterns` | `string[]` | Glob patterns a file must match to fire the handler. products_*.csv ignores everything else. |
| `on` | `('create' \| 'modify' \| 'remove')[]` | Which filesystem events fire the trigger. 'create' = a new file landing. |
| `stabilityThreshold` | `{ checkIntervalMs, stableChecks }` | Debounce: wait until the file size is unchanged across stableChecks polls before firing, so a half-written upload is never parsed. |

> stabilityThreshold is not optional polish
>
> A supplier copying a large file appears on disk before it is fully written. Without a stability check the watcher would fire on the first byte and your job would read a truncated CSV. The
>
> checkIntervalMs: 1000, stableChecks: 2
>
> here waits for the size to hold steady for two one-second polls before enqueuing — set it generously for large files on slow shares.

## Step 4 — Register the job

The trigger addresses the job by `id`, which means the workers runtime needs a generated registry that maps each `id` to its handler. Generate the plugin registries:

```sh
netscript generate plugins
```

This scans `plugins/workers/jobs` (and the triggers plugin) and writes a registry the running services load. After this, `import-products` is addressable, and `product-import-trigger` is loaded by the file-watch processor.

> Restart the processors after generating
>
> If
>
> aspire start
>
> was up before you generated the registry, restart it (or let it hot-reload) so the workers runtime and the file-watch processor pick up the new job and trigger.

## Verify your progress

With Aspire up, drop a matching CSV into the watched folder and watch the pipeline run end to end. First create a sample file in the SAP export shape — legacy column names, prices in integer cents (Chapter 3 transforms exactly this file into Dynamics' shape):

```sh
cat > .data/incoming/products_2024.csv <<'CSV'
material_no,description,price_cents
WID-1,Widget,999
GAD-2,Gadget,1999
CSV
mv .data/incoming/products_2024.csv .data/incoming/products/products_2024.csv
```

Moving the finished file into the watched folder fires a single `create` event (and avoids the watcher seeing a half-written file). Now confirm both sides of the hand-off:

```sh
# 1. The trigger recorded the inbound file event (:8093).
curl 'http://localhost:8093/api/v1/events?limit=10'

# 2. The job it enqueued executed (:8091).
ns-workers executions --limit=10 --json
```

Expected: the events feed lists a `product-import-trigger` event, and the executions feed shows a completed `import-products` run whose result is `{ "fileName": "products_2024.csv", "rowCount": 2, "headers": ["material_no","description","price_cents"] }`. Open the `workers` resource logs in the [Aspire dashboard](https://localhost:18888) to read the job's structured log lines.

- [ ] `.data/incoming/products/` exists and you dropped a `products_*.csv` into it.
- [ ] The triggers events feed shows a `product-import-trigger` event.
- [ ] The workers executions feed shows a completed `import-products` run with `rowCount: 2`.
- [ ] `deno task check` is clean.

> If the job never runs
>
> - **Aspire isn't up** — the file-watch processor and the workers runtime are Aspire resources. Start `aspire start` from `aspire/` and retry.
> - **The job isn't registered** — re-run `netscript generate plugins` so `import-products` is in the generated registry, then restart Aspire.
> - **Filename didn't match** — the pattern is `products_*.csv`. A file named `catalog.csv` in the same folder is ignored by design.
> - **Wrong folder** — the file must land inside `.data/incoming/products`, the directory in `paths`, not its parent.

## What you built

A file-watch trigger (`defineFileWatch`) that fires on every `products_*.csv` the SAP export drops into the hand-off folder, and a durable background job (`defineJobHandler`) that parses it — wired together by `enqueueJob` and made addressable with `netscript generate plugins`. An inbound SAP export now becomes durable background work with no HTTP in the loop. But the rows you just imported are still in the legacy shape — column names Dynamics does not use and prices in cents. Next, you build the transform stage that fixes that, and run it.

[1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/) [3 · Polyglot transform](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/_

---

# A polyglot transform task

In [Chapter 2](https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/) you imported a SAP export as-is. But the SAP export is not a Dynamics import: the legacy system writes `material_no` where Dynamics wants `sku`, `description` where Dynamics wants `name`, and — the one that really hurts — prices as **integer cents** where Dynamics wants decimals. Load a legacy row into Dynamics untransformed and every price in the new system is wrong by a factor of one hundred. The pipeline needs a **transform stage**, and in NetScript that stage is a **task**: a standalone script defined with a builder, spawned as a subprocess, its result captured. In this chapter you build one and **run it**, using the `deno` runtime — the one task runtime NetScript sandboxes.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/)
2. [2 · Import job](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)
3. [3 · Polyglot transform](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/)
4. [4 · Queue & cron](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/)
5. [5 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/05-deploy/)

## What you will build

By the end of this chapter you will have a runnable **`normalize-sap`** task: a transform script that reads the SAP export you dropped in Chapter 2, rewrites its legacy columns into Dynamics' shape, and writes the normalized file to a staging folder — executed through the workers task executor as a **sandboxed subprocess** whose filesystem access you granted explicitly. You will watch its output stream into your terminal, read its structured JSON result, and `cat` the normalized file it produced. You will also see how the **same builder chain** targets Python or shell when a transform belongs in another language — as a clearly-marked forward step for your own host, since those runtimes are not sandboxed and need their interpreter installed.

## Before you begin

You need the `my-erp/` workspace from [Chapter 2](https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/) with the workers plugin installed and the SAP export still on disk from that chapter's file drop:

```sh
netscript plugin list
cat .data/incoming/products/products_2024.csv
```

Expected: `workers` appears in the plugin list, and the CSV prints the SAP legacy shape — `material_no,description,price_cents` and two rows. If the file is missing, re-create it exactly as in Chapter 2's [verify step](https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/). Aspire does not need to be running for this chapter — the task executor runs the transform directly.

## Step 1 — Write the transform script

A subprocess task is a contract about two streams. Input goes **in** as argv and environment variables — never stdin. The result comes **back** as exactly one JSON object printed as the **last line of `stdout`**; everything else on `stdout`/`stderr` is captured as logs. Write the transform as a plain Deno script honoring that contract:

```ts
// plugins/workers/scripts/normalize-sap.ts
// Legacy SAP export rows in -> Microsoft Dynamics-shaped rows out. Runs as a sandboxed subprocess.

// Input arrives as argv + env (NOT stdin).
const input = Deno.args[Deno.args.indexOf('--input') + 1];
const outDir = Deno.env.get('STAGING_DIR') ?? '.data/staging';

const raw = await Deno.readTextFile(input);
const lines = raw.trim().split('\n').filter((line) => line.trim().length > 0);
const headers = lines[0].split(',').map((h) => h.trim().toLowerCase());
const col = (name: string) => headers.indexOf(name);

// legacy -> target: material_no -> sku, description -> name, price_cents -> price (decimal).
const out: string[] = ['sku,name,price'];
let skipped = 0;
for (const line of lines.slice(1)) {
  const values = line.split(',').map((v) => v.trim());
  const sku = values[col('material_no')] ?? '';
  const name = values[col('description')] ?? '';
  const cents = Number.parseInt(values[col('price_cents')] ?? '', 10);
  if (sku === '' || Number.isNaN(cents)) {
    skipped++;
    continue;
  }
  out.push(`${sku},${name},${(cents / 100).toFixed(2)}`);
}

await Deno.mkdir(outDir, { recursive: true });
const fileName = input.split('/').pop() ?? 'export.csv';
const output = `${outDir}/${fileName.replace(/\.csv$/, '')}.normalized.csv`;
await Deno.writeTextFile(output, out.join('\n') + '\n');

// Diagnostics go to stderr; the RESULT is the last stdout line and must be a
// single JSON OBJECT (not an array) to populate result.result.
console.error(`normalize-sap: ${lines.length - 1} rows in, ${out.length - 1} written`);
console.log(JSON.stringify({ input, output, read: lines.length - 1, written: out.length - 1, skipped }));
```

Nothing here imports NetScript — that is the point. The script is an ordinary program with a narrow I/O contract, which is what lets the same execution model run TypeScript today and Python tomorrow.

> The result is the LAST stdout line — and only if it is a JSON object
>
> A trailing log line, a pretty-print, a JSON
>
> array
>
> , or a stray newline after the payload all make the parsed result
>
> null
>
> even when the task otherwise succeeds. Emit the JSON object last and send everything else to
>
> stderr
>
> , as the script above does.

## Step 2 — Define the task, permissions included

Now wrap the script in a task definition. `defineTask(id)` from `@netscript/plugin-workers-core/builders` returns a typestate builder: `.runtime(type)` selects the runtime (default `'deno'`), `.entrypoint(path)` points at the script and unlocks `.build()`, and input crosses as `.args(...)` plus `.env({...})`. For a `deno` task, `.permissions({...})` is the sandbox — each key compiles directly into an `--allow-*` flag on the spawned `deno run` command line:

```ts
// plugins/workers/tasks/normalize-sap.ts
import { defineTask } from '@netscript/plugin-workers-core/builders';

export const normalizeSap = defineTask('normalize-sap')
  .runtime('deno') // the default — and the only sandboxed runtime
  .entrypoint('./plugins/workers/scripts/normalize-sap.ts')
  .args('--input', '.data/incoming/products/products_2024.csv')
  .env({ STAGING_DIR: '.data/staging' })
  .permissions({
    read: ['.data'],           // -> --allow-read=.data
    write: ['.data/staging'],  // -> --allow-write=.data/staging
    env: ['STAGING_DIR'],      // -> --allow-env=STAGING_DIR
  })
  .timeout(30_000) // ms; defaults to 300_000
  .build();

export default normalizeSap;
```

Read the permission set as a statement about the transform: it may read the incoming drop folder, write only to staging, and see one environment variable — nothing else. If the script ever tries to phone home or touch a file outside those grants, the Deno sandbox refuses at the subprocess boundary, not in your code review.

> Omitting .permissions() on a deno task means --allow-all
>
> Calling
>
> .build()
>
> on a
>
> deno
>
> task
>
> without
>
> .permissions(...)
>
> produces an
>
> --allow-all
>
> command line — full access. Always pass an explicit, least-privilege set. The framework also ships named
>
> permissions
>
> presets (
>
> minimal
>
> ,
>
> readOnly
>
> ,
>
> network
>
> , …) so you do not hand-roll the object for common cases — see
>
> Tune the worker runtime
>
> .

## Step 3 — Run it through the executor

`createDefaultTaskExecutor()` from `@netscript/plugin-workers-core/executor` builds the multi-runtime executor wired with every built-in runtime adapter. `executor.execute(task)` resolves the adapter for the task's runtime, spawns the subprocess, streams its output, and returns one `TaskResult`. Write a small runner:

```ts
// plugins/workers/run-normalize.ts
import { createDefaultTaskExecutor } from '@netscript/plugin-workers-core/executor';
import { normalizeSap } from './tasks/normalize-sap.ts';

const executor = createDefaultTaskExecutor();

const result = await executor.execute(normalizeSap, {
  onStdout: (line) => console.log('[normalize]', line),
  onStderr: (line) => console.warn('[normalize:err]', line),
});

if (result.success) {
  // result.result is the parsed JSON object from the LAST stdout line, or null.
  console.log('normalized', result.result, `in ${result.duration}ms`);
} else {
  // status is 'failed' | 'timeout' | 'cancelled'; exitCode is -1 when the process never ran.
  console.error('task failed', result.status, result.exitCode, result.error);
  Deno.exit(1);
}
```

Run it from the **workspace root** (the task's relative paths — entrypoint, input, staging — resolve from where you launch the runner):

```sh
deno run -A plugins/workers/run-normalize.ts
```

The runner itself is trusted host code, so `-A` is fine here — the sandbox that matters is the **subprocess**: the executor spawns `deno run --allow-read=.data --allow-write=.data/staging --allow-env=STAGING_DIR …` with exactly the flags your permission set compiled to. You should see:

```
[normalize:err] normalize-sap: 2 rows in, 2 written
[normalize] {"input":".data/incoming/products/products_2024.csv","output":".data/staging/products_2024.normalized.csv","read":2,"written":2,"skipped":0}
normalized {
  input: ".data/incoming/products/products_2024.csv",
  output: ".data/staging/products_2024.normalized.csv",
  read: 2,
  written: 2,
  skipped: 0
} in 187ms
```

(Your duration will differ.) Now read the file the task produced:

```sh
cat .data/staging/products_2024.normalized.csv
```

```
sku,name,price
WID-1,Widget,9.99
GAD-2,Gadget,19.99
```

The cents are decimals, the legacy columns are Dynamics' names, and the off-by-100 price bug never gets a chance to exist. This is the transform stage of the pipeline: the [import job](https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/) stages the raw SAP rows, `normalize-sap` rewrites them for Dynamics, and a follow-up job would upsert the staged file. Tasks run through the same workers runtime as jobs and propagate W3C trace context (`TRACEPARENT`/`TRACESTATE`) into the subprocess, so a cross-runtime span still stitches together in the Aspire dashboard.

## Step 4 — The same chain in another language

`normalize-sap` is TypeScript because a column rename needs nothing more. But some transforms live more naturally elsewhere — a pandas dedupe across historical SAP exports, a shell pipeline through `jq`, a .NET routine you already own. The builder chain is identical; only the `.runtime(...)` argument and the entrypoint change:

```ts
// The Python variant of the same stage — a forward step for your own host.
export const dedupeSap = defineTask('dedupe-sap')
  .runtime('python')
  .entrypoint('./plugins/workers/scripts/dedupe_sap.py')
  .args('--input', '.data/staging')
  .timeout(120_000)
  .build();

// Spawns: python3 -u ./plugins/workers/scripts/dedupe_sap.py --input .data/staging
```

The process contract is unchanged — argv + env in, one JSON object on the last `stdout` line out (the Python runtime runs `python3 -u`, unbuffered, for exactly that reason). Two things do change, and they are why this step is a **read-now, run-on-your-own-host** capability rather than part of this chapter's checkpoint:

> Only the deno runtime is sandboxed
>
> For
>
> python
>
> ,
>
> shell
>
> ,
>
> powershell
>
> ,
>
> cmd
>
> ,
>
> dotnet
>
> , and
>
> executable
>
> tasks, the
>
> .permissions({...})
>
> keys are
>
> ignored
>
> — the subprocess inherits the worker process's full OS-level access. A non-Deno task is a trust boundary: pin the entrypoint to a known script, prefer a pinned interpreter or venv (
>
> pythonConfig.venvPath
>
> ) over
>
> $PATH
>
> discovery, never interpolate untrusted input into
>
> args
>
> , and gate access at the OS layer.

> The runtime must exist on the worker host
>
> A missing interpreter surfaces as a
>
> failed task
>
> , not a thrown error: exit code
>
> 127
>
> is reported as
>
> command not found
>
> and
>
> 126
>
> as
>
> command not executable
>
> . Confirm
>
> python3 --version
>
> /
>
> pwsh --version
>
> /
>
> dotnet --version
>
> on the actual worker host before you ship a task that depends on it. When yours is ready,
>
> Run a polyglot task
>
> walks the Python and shell variants end to end, including interpreter pinning.

Seven runtime types ship today — the literal members of the `TASK_TYPES` constant in `@netscript/plugin-workers-core`:

**Task runtimes (TASK_TYPES) and their adapters**

| Runtime | Spawns | Sandboxed? | Reach for it when |
| --- | --- | --- | --- |
| `deno` | `deno run` with compiled `--allow-*` flags | **Yes** — per-task permissions enforced | TypeScript/JS that should run with least privilege. The default, and what you just ran. |
| `python` | `python3 -u <script>` (or a pinned venv/py) | No — inherits worker OS access | Data science, pandas/ML transforms, anything with a mature Python library. |
| `shell` | `bash <script>` | No | POSIX pipelines, `jq` aggregation, glue between CLIs. |
| `powershell` | `pwsh` / `powershell <script>` | No | Windows-centric automation and reporting; cross-platform via `pwsh`. |
| `dotnet` | `dotnet run <file.cs>` (single-file C#) | No | Existing .NET logic — statistics, formatting, a library you already own. |
| `cmd` | Windows `cmd.exe` batch | No — Windows-only | Legacy Windows batch steps. Platform-specific. |
| `executable` | Any prebuilt binary directly | No | A compiled tool (Go, Rust, a vendor binary) you invoke by path. |

## Verify your progress

Confirm the transform ran and the workspace still type-checks:

```sh
cat .data/staging/products_2024.normalized.csv   # sku,name,price + 2 decimal-priced rows
deno task check                                  # clean
```

- [ ] `deno run -A plugins/workers/run-normalize.ts` exits 0 and prints `normalized { … written: 2 … }`.
- [ ] `.data/staging/products_2024.normalized.csv` exists with headers `sku,name,price` and prices `9.99` / `19.99`.
- [ ] The `[normalize:err]` diagnostic line and the JSON result line both appeared — logs and result travel on separate streams.
- [ ] `deno task check` is clean.

> If the task fails instead
>
> Read
>
> result.status
>
> and
>
> result.exitCode
>
> from the runner's error line. A Deno permission error on
>
> stderr
>
> means the script touched a path outside the grants in Step 2 — that is the sandbox working; widen the specific permission, not to
>
> --allow-all
>
> . A
>
> NotFound
>
> read error means the Chapter 2 CSV is missing — re-create it and rerun. A
>
> timeout
>
> status means the 30s budget elapsed; raise
>
> .timeout(...)
>
> .

## What you built

A runnable transform stage for the SAP→Dynamics pipeline: a plain-Deno script honoring the argv/env-in

- JSON-out process contract, a `defineTask` definition whose `.permissions(...)` compile into real `--allow-*` flags on the spawned subprocess, and an executor run you observed end to end — plus the shape of the same stage in Python, clearly marked with the two rules that govern non-Deno runtimes (no sandbox, interpreter must exist). Next, the pipeline learns to absorb bursts and run on a schedule.

## Where to go deeper

- **Run the Python/shell variants for real** → [Run a polyglot task](https://rickylabs.github.io/netscript/background-processing/how-to/run-a-polyglot-task/) — the hands-on recipe: define, write the script, pin the interpreter, read the result.
- **The capability** → [Polyglot tasks](https://rickylabs.github.io/netscript/background-processing/polyglot-tasks/) — the WHY: what a task is, the subprocess seam, the full `TaskResult` shape.
- **Tune the runtime** → [Tune the worker runtime](https://rickylabs.github.io/netscript/background-processing/how-to/tune-worker-runtime/) — concurrency, the permission presets, and the per-task timeout/retry knobs.

[2 · Import job](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/) [4 · Queue & cron](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/erp-sync/03-polyglot-transform/_

---

# Add a queue and a cron schedule

Your [import job](https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/) runs one file at a time. A migration does not: the day you backfill Dynamics with SAP's historical exports, twenty files land in the hand-off folder at once, and until cutover the two systems only stay aligned if a full re-sync runs every night whether or not a file arrived. This chapter adds the two pieces that make both durable: a **queue provider** and a worker **concurrency** so bursts drain in parallel, and a **cron schedule** that fires on a cadence rather than an event.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/)
2. [2 · Import job](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)
3. [3 · Polyglot transform](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/)
4. [4 · Queue & cron](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/)
5. [5 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/05-deploy/)

## What you will build

By the end of this chapter your workers config will name a **queue provider** and a worker **concurrency** so bursts of imports drain in parallel instead of one-by-one, and a new **scheduled trigger** (`defineScheduledTrigger`) will enqueue a re-sync job on a cron cadence. You will also know the one concurrency naming gotcha to set explicitly so it does not bite you under Aspire.

## Before you begin

You need the `my-erp/` workspace from [Chapter 2](https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/) with the `import-products` job and `product-import-trigger` working, and `aspire start` healthy. Confirm the job is registered:

```sh
curl 'http://localhost:8091/api/v1/workers/jobs'
```

Expected: `import-products` appears in the list. If not, return to Chapter 2 and re-run `netscript generate plugins`.

## Step 1 — Choose a queue provider

A NetScript queue is provider-agnostic: the same job-enqueue path runs on the zero-config Deno KV default on your laptop and on a real broker under Aspire, without touching your job code. The `QueueProvider` enum has four selectable production backends, and auto-discovery picks one for you when you do not pin one:

**Queue providers (QueueProvider) in @netscript/queue**

| Provider | How you select it | Reach for it when |
| --- | --- | --- |
| `deno-kv` | Auto-discovery **fallback**, or pin `QueueProvider.DenoKv` | Local dev and single-instance apps with no broker. Durable to the Deno KV store; needs `--unstable-kv`. |
| `redis` | Auto-discovered when a Redis/Garnet connection is present; or pin `QueueProvider.Redis` | High-throughput production with a Redis/Garnet resource already provisioned by Aspire. |
| `rabbitmq` | Auto-discovered **first** when an AMQP broker is present; or pin `QueueProvider.RabbitMQ` | Broker-grade routing and reliability; the top of the auto-discovery probe. |
| `postgres` | **Explicit only** — pass `QueueProvider.Postgres`; never auto-discovered | You already run Postgres and want the queue in the same transactional store. Row-claim via FOR UPDATE SKIP LOCKED. |

For the ERP sync, the right default is to let the environment decide: write provider-neutral config and you get Deno KV locally, and the Aspire cache once it is up — `redis` by default, or `garnet` via `--cache-backend`. The auto-discovery probe order is **RabbitMQ → Redis → Deno KV**.

> PostgreSQL is the deliberate exception
>
> Auto-discovery probes
>
> RabbitMQ → Redis → Deno KV only
>
> . It will
>
> never
>
> fall through to PostgreSQL, even when a Postgres connection is present. The SQL-durable queue is opt-in — you must pass
>
> provider: QueueProvider.Postgres
>
> or you will quietly land on the Deno KV adapter. The full decision guide is in
>
> Choose a queue provider
>
> .

## Step 2 — Size worker concurrency in config

`concurrency` on the workers config is the size of the worker pool the runner spins up — each slot is its own V8 isolate (~20–40 MB), so raising it buys parallelism at a memory cost. This is where a burst of imports gets drained in parallel. Set it in the generated worker config:

```ts
// config/official-plugins/mod.ts
import { defineWorkers } from '@netscript/plugin-workers-core/config';

export const workers = defineWorkers({
  jobsDir: './workers/jobs',
  tasksDir: './workers/tasks',
  queueProvider: 'auto', // Deno KV locally; the Aspire cache once up (redis default, garnet alt).
  queueName: 'jobs',
  concurrency: 4, // pool size: 4 isolates → ~80–160 MB. Raise for throughput, lower to bound memory.
  enabled: true,
  groups: [],
});
```

**WorkersConfigData — the fields you set here (@netscript/plugin-workers-core/config)**

| Name | Type | Description |
| --- | --- | --- |
| `concurrency` | `number` | Default worker pool size (V8 isolates running jobs in parallel). Schema default 2. |
| `queueProvider` | `'auto' \| 'deno-kv' \| 'redis' \| 'postgres' \| 'amqp'` | Queue backend. 'auto' resolves one for you. Default 'auto'. |
| `queueName` | `string` | Queue the runner consumes from. Default 'jobs'. |
| `jobsDir / tasksDir` | `string` | Directories scanned for default-exported job and task modules. |
| `groups` | `WorkerGroupData[]` | Per-topic worker groups, each with its own scaling.concurrency and retention. |
| `enabled` | `boolean` | Whether workers run at all. Default true. |

For per-topic control — a hot `imports` topic at concurrency 10 while a heavy `reports` topic stays at 1 — use a `WorkerGroup` with its own `scaling: { mode, concurrency }`. The full per-topic and runner-mode knobs are in [Tune the worker runtime](https://rickylabs.github.io/netscript/background-processing/how-to/tune-worker-runtime/).

> Set scaling.concurrency in config — the Aspire env var is silently ignored
>
> There are
>
> two
>
> concurrency env names in play and they are
>
> not
>
> the same variable. The worker entrypoint reads
>
> WORKERS_CONCURRENCY
>
> (note the
>
> S
>
> ) and defaults it to
>
> 1
>
> . The Aspire contribution, however, declares and injects
>
> WORKER_CONCURRENCY
>
> (no S). Under
>
> aspire start
>
> today the injected
>
> WORKER_CONCURRENCY
>
> does
>
> not
>
> feed the entrypoint's
>
> WORKERS_CONCURRENCY
>
> read, so the Aspire value is silently ignored and the process pool falls back to its default. Treat the config-driven
>
> concurrency
>
> (and per-topic
>
> scaling.concurrency
>
> ) above as the durable control, and if you must override the pool by env, set
>
> WORKERS_CONCURRENCY
>
> explicitly on the background resource. This naming seam is a known rough edge, tracked for a framework-side fix.

## Step 3 — Add a cron schedule

Some migration work is time-driven, not file-driven: the nightly full re-sync that keeps Dynamics aligned with SAP until cutover, an hourly cleanup of stale staging files. That is a **scheduled trigger** — `defineScheduledTrigger(handler, spec)` from `@netscript/plugin-triggers-core/builders`. The `add-scheduled` verb uses the spaced `add scheduled` shell syntax and can scaffold the job action already wired:

> ns-triggers / ns-workers are shorthands you install once
>
> ns-triggers
>
> and
>
> ns-workers
>
> are names
>
> you
>
> give the triggers and workers plugin CLIs — the scaffold does not create them. Install them once, globally, and every shorthand command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-triggers jsr:@netscript/plugin-triggers@0.0.1-beta.11/cli
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> ```
>
> Rather not install them? Each
>
> ns-<plugin> <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-<plugin>@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```sh
ns-triggers add scheduled daily-resync-schedule \
  --cron="0 6 * * *" \
  --timezone=UTC \
  --job=import-products \
  --description="Runs a full product re-sync every morning." \
  --tags=resync,products,scheduled
```

The command writes `triggers/daily-resync-schedule-trigger.ts` and refreshes the trigger registry. Like the file-watch trigger, its generated handler returns an array of effects; here the `--job` flag supplies the enqueue action without hand-authoring the definition.

```ts
// triggers/daily-resync-schedule-trigger.ts (generated excerpt)
import { defineScheduledTrigger, enqueueJob } from '@netscript/plugin-triggers-core/builders';
import type { JobDefinition } from '@netscript/plugin-workers-core';

const importProductsJob = {
  id: 'import-products' as JobDefinition<'import-products'>['id'],
  name: 'Import Products',
  topic: 'default',
  entrypoint: './workers/jobs/import-products.ts',
} satisfies JobDefinition<'import-products'>;

export const dailyResyncSchedule = defineScheduledTrigger(
  (event) => Promise.resolve([enqueueJob(importProductsJob, { payload: event.payload })]),
  {
    id: 'daily-resync-schedule',
    cron: '0 6 * * *', // every day at 06:00
    timezone: 'UTC',
    description: 'Runs a full product re-sync every morning.',
    tags: ['resync', 'products', 'scheduled'],
  },
);

export default dailyResyncSchedule;
```

**ScheduledTrigger spec — the fields that define the cadence**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable identifier for the schedule, used in logs and the events feed. |
| `cron` | `string` | Standard 5-field cron expression. '0 6 * * *' = daily at 06:00; '*/5 * * * *' = every five minutes. |
| `timezone` | `string` | IANA timezone the cron is evaluated in. Set it explicitly — 'UTC' here — so the cadence is unambiguous. |
| `description / tags` | `string / string[]` | Metadata for discovery and the dashboard. |

> Cron lives on the triggers axis
>
> Scheduling is a triggers concern, not a workers concern — a scheduled trigger is just another way to
>
> enqueueJob
>
> , alongside file-watch and webhooks. That keeps one durable path: every job enters the workers runtime the same way, however it was kicked off. The scaffold's
>
> --samples
>
> ship several
>
> defineScheduledTrigger
>
> examples under the triggers plugin to crib from.

## Step 4 — Load the new trigger

The scaffold command already refreshed the registry. Restart `aspire start` (or let it hot-reload) so the triggers processor loads `daily-resync-schedule`.

## Verify your progress

First confirm the config type-checks with the new concurrency and provider settings:

```sh
deno task check
```

Expected: a clean check. Then confirm the cron schedule registered — for a fast feedback loop you can temporarily set its `cron` to `*/2 * * * *` (every two minutes), regenerate, restart Aspire, wait, and read the executions feed:

```sh
ns-workers executions --limit=10 --json
```

Expected: an `import-products` execution appears on the cron cadence with no file dropped — the schedule, not a file event, enqueued it. Set the cron back to `0 6 * * *` when you are done testing.

- [ ] `config/official-plugins/mod.ts` sets `concurrency` and `queueProvider`.
- [ ] `deno task check` is clean.
- [ ] `daily-resync-schedule` is registered (after `netscript generate plugins` + Aspire restart).
- [ ] A scheduled `import-products` execution appears on the cron cadence with no file dropped.
- [ ] You set `WORKERS_CONCURRENCY` explicitly (or rely on config `concurrency`) rather than the ignored Aspire `WORKER_CONCURRENCY`.

> Make handlers idempotent before you scale concurrency
>
> Raising
>
> concurrency
>
> means more jobs run at once, and every queue backend can redeliver a message on retry. An idempotent import — keyed on the file's content hash or name — can re-run without double-importing. Pair retries with an
>
> idempotencyKey
>
> on enqueue so a redelivery after a restart does not duplicate rows. See
>
> Choose a queue provider
>
> for each backend's delivery semantics.

## What you built

A workers config that names a queue provider and a worker concurrency so a SAP backfill burst drains in parallel, and a `defineScheduledTrigger` cron that enqueues the nightly re-sync — plus the knowledge to set concurrency where it actually takes effect. The sync now absorbs bursts and runs its recurring work unattended. The last chapter runs the whole thing under Aspire.

[3 · Polyglot transform](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/) [5 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/05-deploy/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/erp-sync/04-queue-and-cron/_

---

# Run it locally under Aspire

You have built the whole SAP→Dynamics sync: a file-watch import job, a sandboxed transform task, a queue, and a cron schedule. This final chapter runs all of it together — workers, triggers, queue, and cron processors — on one machine under `aspire start`, and shows you how to read the running system from the dashboard. It is the **local** orchestration story: one command, one observable stack, throwaway infrastructure.

And you wrote none of the wiring that makes that possible. `netscript init` scaffolded the AppHost back in Chapter 1; every plugin you added since contributed its own API and background processor to the graph on its own; a single `aspire start` then boots the lot with cross-references resolved for you. That is the scaffold-to-Aspire story this chapter surfaces end to end — from an empty folder to a live, correctly-wired, observable stack with no hand-written orchestration config in between.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/01-scaffold/)
2. [2 · Import job](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)
3. [3 · Polyglot transform](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/)
4. [4 · Queue & cron](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/)
5. [5 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/05-deploy/)

## What you will build

By the end of this chapter you will bring the full `my-erp/` resource graph up with a single `aspire start` — Postgres, Redis, the workers API + processor, and the triggers API + processor (which runs your file-watch and cron triggers) — initialize the database through the running AppHost, and read the live import pipeline in the Aspire dashboard: resources, console logs, and the traces that stitch a file drop to its job execution.

> Aspire is the LOCAL story — not a production deployer
>
> aspire start
>
> exists to make
>
> git clone
>
> → one command produce a complete, observable, correctly-wired stack on
>
> one machine
>
> . The Postgres and Redis it starts are throwaway Docker containers for dev convenience —
>
> not
>
> your production database or cache. Shipping to a remote target (managed infrastructure, your own process lifecycle) is the
>
> Deploy
>
> recipe; this chapter is the local companion. The full local walkthrough lives in
>
> Deploy locally with Aspire
>
> .

## Before you begin

You need the complete `my-erp/` workspace from [Chapter 4](https://rickylabs.github.io/netscript/tutorials/erp-sync/04-queue-and-cron/): the workers and triggers plugins, the `import-products` job, the `normalize-sap` transform task, the `product-import-trigger` file watch, and the `daily-resync-schedule` cron. Docker must be running so Aspire can provision Postgres and Redis. Confirm the AppHost was scaffolded (it is a TypeScript/Node program, not C#):

```sh
ls aspire/apphost.mts aspire/aspire.config.json
```

Expected: both files exist. `netscript init` generated them in Chapter 1; you never hand-write them.

## Step 1 — Understand the graph you are about to run

The resource graph is **derived from your installed plugins** at boot via `composeAppHost` — add a plugin and its API plus background processor appear; remove it and they vanish, no edit to `apphost.mts`. With workers and triggers installed, a single `aspire start` stands up this graph:

**What aspire start brings up for the ERP sync**

| Name | Type | Description |
| --- | --- | --- |
| `aspire (dashboard)` | `https://localhost:18888 / http://localhost:18889` | Live resource list, console logs, structured logs and traces. A login token is printed on start. |
| `OTLP collector` | `http://localhost:4318` | OpenTelemetry endpoint the dashboard runs; framework spans and structured logs land here automatically. |
| `postgres` | `Container` | Throwaway Docker Postgres. The database netscript db commands target — reachable only while Aspire is up. |
| `redis` | `Container (cache)` | Redis cache — the default `--cache-backend`; Redis-compatible. Backs the KV/queue workloads — this is what auto-discovery resolves the queue to once it is up. |
| `workers API + processor` | `:8091 (PLUGIN_API range) + executable` | The :8091 API enqueues; a separate background processor drains the queue and runs your import job. |
| `triggers API + processor` | `:8093 (PLUGIN_API range) + executable` | The :8093 API plus the processor that runs your file-watch and cron triggers. |

> Plugin API ports are range-allocated, not fixed
>
> The runtime plugins publish their APIs from the
>
> :8091–8099
>
> PLUGIN_API range. The conventional assignments (workers
>
> :8091
>
> , triggers
>
> :8093
>
> ) are what this two-plugin workspace lands on — but the dashboard's
>
> Resources
>
> tab is the authority for the exact port each resource bound, not a memorized number. Read it from there.

## Step 2 — Restore and run

The AppHost runs on its own isolated Node runtime inside `aspire/` so its dependencies never leak into your Deno workspace. Restore once per machine, then run — both from inside `aspire/`:

```sh
cd aspire
aspire restore   # one-time SDK restore (and after an SDK bump)
aspire start       # boots the whole graph; prints the dashboard URL + a login token
```

`aspire start` brings up infrastructure first, then the plugin APIs and background processors, with cross-references resolved into injected environment variables. Leave it running.

## Step 3 — Initialize the database through the running AppHost

With Aspire up, Postgres is live and the `netscript db` commands can reach it. Run them from the **workspace root** in a second terminal (leave `aspire start` going in the first):

```sh
netscript db init --name init   # create + apply the first migration
netscript db generate           # generate the Prisma client
netscript db seed               # optional: seed development data
```

These talk to the Postgres container Aspire provisioned. Run them with no Aspire up and they fail — there is no Postgres for them to reach.

> Order matters: scaffold → orchestrate → database
>
> The single most common first-run error is running a
>
> netscript db
>
> command before
>
> aspire start
>
> .
>
> aspire restore
>
> and
>
> aspire start
>
> run from inside
>
> aspire/
>
> ;
>
> netscript db
>
> commands run from the
>
> workspace root
>
> ,
>
> after
>
> the graph is up. Mixing the directories or the order is what breaks. There is no
>
> netscript generate aspire
>
> — the AppHost is produced by
>
> netscript init
>
> .

## Step 4 — Watch the pipeline run end to end

With the full stack up, exercise the pipeline you built and read it from the dashboard. Drop a file in the SAP export shape:

```sh
cat > .data/incoming/products_live.csv <<'CSV'
material_no,description,price_cents
ANV-9,Anvil,4999
CSV
mv .data/incoming/products_live.csv .data/incoming/products/products_live.csv
```

Then open `https://localhost:18888`, paste the login token `aspire start` printed, and use the three dashboard surfaces:

**Reading the running ERP sync in the Aspire dashboard**

| Name | Type | Description |
| --- | --- | --- |
| `Resources` | `tab` | Every container and executable with status and the port it bound. Confirm workers, triggers, postgres, and redis are all green. |
| `Console logs` | `tab` | stdout/stderr per resource. Open the workers processor to read your import job's log lines; the triggers processor shows the file-watch event. |
| `Structured logs + Traces` | `tab` | Spans correlated by traceparent. The framework instruments job dispatch and execution automatically, so a file drop → job run trace appears with no extra wiring. |

Because Aspire starts each resource with an OTLP endpoint pointed at `http://localhost:4318`, framework-level spans (job dispatch, job execution, scheduler runs) surface in the **Traces** view on their own.

> Which spans you see vs. don't
>
> The
>
> dispatch/execution trace appears automatically
>
> — that is the framework instrumenting the run end to end, and
>
> log.*
>
> emits real structured logs. What is
>
> not
>
> yet wired are the custom-span helpers some scaffold samples call inside a handler (
>
> trace.withChildSpan
>
> via
>
> createJobTools
>
> ) — those are no-op stubs today (tracked debt). For custom spans now, import from
>
> @netscript/telemetry
>
> directly. See
>
> Observability
>
> for the framework-vs-scaffold span boundary.

## Verify your progress

Confirm the whole graph is healthy and the pipeline ran:

```sh
# Both plugin APIs answer.
curl http://localhost:8091/health
curl http://localhost:8093/health

# The dropped file produced an import execution.
ns-workers executions --limit=10 --json
```

> ns-workers is a shorthand you install once
>
> ns-workers
>
> is a name
>
> you
>
> give the workers plugin's CLI — the scaffold does not create it. Install it once, globally, and the
>
> ns-workers
>
> command above works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> ```
>
> Rather not install it?
>
> ns-workers <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-workers@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

Expected: both health checks return healthy JSON, and the executions feed shows a completed `import-products` run for `products_live.csv`.

- [ ] `aspire start` is up; the dashboard lists `postgres`, `redis`, workers, and triggers all green.
- [ ] `netscript db init/generate` succeeded against the Aspire Postgres.
- [ ] `curl :8091/health` and `curl :8093/health` both return healthy.
- [ ] A file drop produced an `import-products` execution and a dispatch/execution trace in the dashboard.

> Footguns when aspire start will not boot
>
> - **Docker not running** — Aspire provisions Postgres + Redis through Docker; no daemon means the happy path does not start.
> - **Wrong directory** — `aspire restore`/`aspire start` run from `aspire/`; `netscript db` runs from the workspace root.
> - **Ports in use** — the dashboard wants `:18888`/`:18889` and OTLP `:4318`; a stale prior run holding a port blocks boot. Free it and retry.

## What you built

You ran the complete SAP→Dynamics sync — workers, triggers, queue, and cron — on one machine under a single `aspire start`, initialized the database through the running AppHost, and watched a SAP export flow into a durable job execution with its trace in the dashboard. You now have an end-to-end durable background-processing backend that could carry a real migration's parallel-run, and you know exactly where the local story ends and a production deployment begins.

## Where to go next

You have finished the ERP Sync track. From here, branch into task-oriented and reference docs:

- **Ship it remotely** → [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/) — the production companion to this local run: deployable units, managed backing services, and the `--no-aspire` path.
- **Take the transform polyglot** → [Run a polyglot task](https://rickylabs.github.io/netscript/background-processing/how-to/run-a-polyglot-task/) — swap Chapter 3's Deno transform for a Python or shell step on your own host.
- **Tune throughput** → [Choose a queue provider](https://rickylabs.github.io/netscript/data-persistence/how-to/choose-a-queue-provider/) and [Tune the worker runtime](https://rickylabs.github.io/netscript/background-processing/how-to/tune-worker-runtime/).
- **Understand the orchestrator** → [Orchestration with Aspire](https://rickylabs.github.io/netscript/explanation/aspire/) and the full [How-to guides](https://rickylabs.github.io/netscript/how-to/).

[4 · Queue & cron](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/04-queue-and-cron/) [How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/erp-sync/05-deploy/_

---

# Live Dashboard

An order queue goes wrong quietly. The screen your fulfillment team watches shows five-minute-old rows, so the packing station ships an order the customer cancelled three minutes ago, and a payment that failed at 14:02 sits looking like `processing` until someone thinks to hit refresh. The usual fix — poll harder — just trades staleness for load and still leaves a gap for the next missed cancellation.

This track builds the alternative end to end: a real-time operations dashboard for an order queue. By the last chapter you will have a table that updates **live** in the browser — no manual refresh, no polling loop, no hand-rolled WebSocket — fed by the full NetScript data spine, from a typed contract on the backend to a durable change-stream on the frontend. It is the same durable-stream seam the streams plugin scaffolds into a workspace for notification fan-out — here, pointed at your orders.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)
2. [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)
3. [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)
4. [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)
5. [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

## What you will build

A `my-dashboard/` Fresh workspace whose home screen is the live order queue described above. You scaffold a fresh NetScript project, expose an `orders` read-model through a typed oRPC service, wire a cache-first SDK query layer, render the queue with NetScript's `definePage` page builder and a hydrated TanStack Query island, then upgrade it to push real-time updates over a durable change-stream — the point where the refresh button stops mattering. The final chapter runs the whole graph locally under Aspire. This is a learning track: the same project grows chapter by chapter, so do them in order.

## Before you begin

You need a working local toolchain — the same one every NetScript tutorial assumes. Confirm Deno, the Aspire CLI, and Docker are on your `PATH`:

```sh
deno --version && aspire --version && docker info
```

You should see a Deno 2.x version, an Aspire CLI version, and Docker engine details (not a connection error). If any are missing, the [quickstart](https://rickylabs.github.io/netscript/quickstart/) walks through installing them. Install the NetScript CLI once:

```sh
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11
```

> New to NetScript? Walk the main ladder first
>
> This track assumes you are comfortable with the contract-first service loop. If
>
> defineService
>
> and oRPC contracts are new, do the
>
> Quickstart
>
> and the
>
> Storefront catalog-service chapter
>
> first — they move slower. This track moves faster and goes deeper on the Fresh consumer surface.

## The arc: contract → client → query → island → stream

NetScript's signature spine carries one shape of data from the database all the way to a live cell in the browser, type-checked at every hop. Each chapter adds exactly one link:

[1 · Scaffold the workspace  Create `my-dashboard/` with `netscript init`, tour the Fresh app, and boot it under Aspire. You end with a running frontend on the app port and the Aspire dashboard on :18888.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)

[2 · A typed read-model service  Define an `orders` oRPC contract with `.route().input().output()` and serve it with `defineService`. This is the data your dashboard reads.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)

[3 · SDK client + cache-first query  Build a typed `createServiceClient` and a `createQueryFactories` query layer with KV-backed stale-while-revalidate. Service discovery resolves the URL for you.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)

[4 · definePage + QueryIsland  Render the table with NetScript's `definePage` builder — the layer / partial / island triad — and hydrate a TanStack Query island for client-side reads and optimistic mutations.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)

[5 · Go live with StreamDB  Replace polling with a durable change-stream: `createSagasStreamDB` feeds `useLiveQuery` so rows update the instant state changes on the server.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)

[6 · Run it all under Aspire  Bring the whole graph up locally — service, Fresh app, streams runtime, Postgres (the default; swap `--db` for `mysql` / `mssql` / `sqlite` at scaffold time), Redis — with one `aspire start`. Clear about what local orchestration is and is not.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

> Where to look things up
>
> This track teaches the path. For exact symbols and signatures, the
>
> reference
>
> is generated from source and always current — the
>
> fresh
>
> ,
>
> sdk
>
> ,
>
> service
>
> , and
>
> streams
>
> units back the chapters here. For the reasoning behind contracts and durability, read the
>
> explanation
>
> pages.

## What you built

By the end of this track you will own an order queue your operations team can act on without second-guessing it — and, more importantly, the full NetScript read spine that powers it, from contract to durable stream. Every hop is typed off the same contract, so the row a packer sees is the row the service wrote.

[Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)

After this track, keep building in **Build › [Web Layer](https://rickylabs.github.io/netscript/web-layer/)** — the guides and recipes there pick up where these chapters stop.

_Canonical: https://rickylabs.github.io/netscript/tutorials/live-dashboard/_

---

# Scaffold the dashboard workspace

Every track starts with a real project on disk. In this chapter you create `my-dashboard/` — the workspace that will grow into the live order queue from the [track index](https://rickylabs.github.io/netscript/tutorials/live-dashboard/): a Fresh frontend, an `orders` service, and a Postgres database — then boot the whole thing under Aspire so the rest of the track has a running system to build on.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)
2. [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)
3. [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)
4. [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)
5. [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

## What you will build

A `my-dashboard/` workspace on disk: shared contracts, an example `orders` service on port **3002**, a [Fresh](https://rickylabs.github.io/netscript/web-layer/) app, and a Postgres database — all orchestrated by Aspire. By the end the Aspire dashboard at `:18888` shows every resource running, and you understand which generated directory does what. You will reuse this same workspace for every later chapter.

## Before you begin

This is the first chapter; the only prerequisite is the toolchain from the [track index](https://rickylabs.github.io/netscript/tutorials/live-dashboard/). Confirm the CLI is installed and reachable:

```sh
netscript --help
```

You should see the public command groups: `init`, `contract`, `db`, `deploy`, `generate`, `marketplace`, `plugin`, `service`, `ui:add`, and `ui:init`. If `netscript` is not found, make sure Deno's install directory is on your `PATH` and open a fresh terminal.

## Step 1 — Preview the scaffold with a dry run

Before writing files, ask the CLI what it *would* create. `--dry-run` plans the scaffold and prints totals without touching disk:

```sh
netscript init my-dashboard --dry-run
```

`netscript init` validates your options, then runs an ordered pipeline that lays down the project root, Aspire orchestration, contracts, the Fresh app workspace, an empty plugin registry, and (optionally) a database workspace and an example service. The dry run reports file and directory totals per phase, so you see the project's shape before committing to it.

> Why dry-run first?
>
> A dry run is the cheapest way to confirm your flag combination is valid — the CLI rejects bad option mixes (an unknown
>
> --db
>
> engine, say) here, before any files exist. A clean dry run is your green light to scaffold for real.

## Step 2 — Create the workspace

Scaffold for real, with an example service and a Postgres database so the dashboard has live data to read later. This track names the example service `orders` and runs it on port **3002**:

```sh
netscript init my-dashboard --service --service-name orders --service-port 3002 --db postgres
cd my-dashboard
```

This writes `my-dashboard/`, formats the output with `deno fmt`, and initializes a git repository. On completion the CLI prints a **next steps** summary tailored to your options — keep it handy.

**init options this track uses (run netscript init --help for the full list)**

| Name | Type | Description |
| --- | --- | --- |
| `--service --service-name orders --service-port 3002` | `flags` | Include an example oRPC service named orders on port 3002 — the read-model the dashboard consumes. |
| `--db postgres` | `flag` | Scaffold a Postgres database workspace. The orders read-model is persisted here. Postgres is this track's stack; swap --db postgres for mysql, mssql, or sqlite for a different engine. |
| `--dry-run` | `flag` | Plan the scaffold and print totals without writing any files (Step 1). |

## Step 3 — Tour what you got

Open `my-dashboard/`. The shape that matters for this track:

- apps/

  - dashboard/ # The Fresh frontend — defineFreshApp, your dashboard UI lives here
- contracts/ # Shared oRPC + Zod contracts, versioned under versions/v1/
- services/

  - orders/ # The example oRPC service (src/main.ts, router.ts, routers/)
- plugins/ # Plugin registry + manifests — empty until you add one
- aspire/

  - apphost.mts # Entry point for aspire start (TypeScript/Node, not C#)
- appsettings.json # Infrastructure manifest Aspire reads
- deno.json # Workspace root: members, tasks, dependency catalog
- netscript.config.ts # Framework config (defineConfig)

The two directories this track lives in:

- **`apps/dashboard/`** — your Fresh app. Its entry point is `main.ts`, which calls [`defineFreshApp`](https://rickylabs.github.io/netscript/web-layer/); its build is configured by `vite.config.ts`. Chapters 4 and 5 add routes and islands here. This is the heart of the track.
- **`services/orders/`** and **`contracts/`** — the typed read-model your dashboard reads. You shape these in chapter 2, then consume them from the Fresh app in chapters 3–5.

For a guided walk through *every* generated directory, see the [Storefront scaffold chapter](https://rickylabs.github.io/netscript/tutorials/storefront/01-scaffold/) — this track keeps the tour short on purpose.

## Step 4 — Look at the Fresh app entry point

Before booting, read the two files that define how the Fresh app starts. You do not edit them yet — this is orientation for chapters 4 and 5.

The app entry point registers the KV adapter and creates the app. **The order matters:** the Redis/Garnet KV adapter import must run *before* any code that reaches for KV, so it sits at the very top of the file:

```ts
// apps/dashboard/main.ts
// Register Redis/Garnet KV adapter — must run before any getKv() call.
import '@netscript/kv/redis';
import { defineFreshApp } from '@netscript/fresh/server';
import type { State } from '@app/utils.ts';

export const app = defineFreshApp<State>({ name: 'dashboard' });
```

The Vite config wires NetScript's Fresh build plugin alongside the Fresh and Tailwind plugins. `createNetScriptVitePlugin` from `@netscript/fresh/vite` is what teaches Vite about NetScript's route manifest, workspace aliases, and watch paths:

```ts
// apps/dashboard/vite.config.ts (trimmed to the NetScript-specific wiring)
import { fresh } from '@fresh/plugin-vite';
import tailwindCSS from '@tailwindcss/vite';
import { createNetScriptVitePlugin } from '@netscript/fresh/vite';
import { defineConfig } from 'vite';

export default defineConfig(() => ({
  plugins: [
    fresh(),
    tailwindCSS(),
    createNetScriptVitePlugin({
      appRoot,
      workspaceRoot,
      aliasEntries,
      watchPaths: [/* packages, contracts, plugins */],
      routeManifest: {},
    }),
  ],
}));
```

> @app/* aliases point inside your Fresh app
>
> The Vite config registers
>
> @app
>
> ,
>
> @app/lib
>
> ,
>
> @app/components
>
> ,
>
> @app/islands
>
> , and
>
> @app/routes
>
> aliases that resolve to folders inside
>
> apps/dashboard/
>
> . Throughout this track, an import like
>
> @app/lib/api-clients.ts
>
> means the file at
>
> apps/dashboard/lib/api-clients.ts
>
> .

## Step 5 — Bring up orchestration

This is the step that turns a folder of files into a running system. **Aspire provisions your database and cache; you run it before any `netscript db` command.** Run it from the `aspire/` subfolder so the CLI finds `apphost.mts`:

```sh
cd aspire
aspire restore   # once: restores the Aspire SDK modules into .aspire/
aspire start       # starts the AppHost and every declared resource
```

`aspire start` brings up the Postgres database, the Redis cache, your `orders` service, and the Fresh app together, then prints a URL and login token for the **Aspire dashboard**:

```
https://localhost:18888
```

Leave `aspire start` running in this terminal; it is your control plane for the rest of the track.

> Aspire is step 2 — before any database command
>
> The Postgres container only exists while
>
> aspire start
>
> is up. So
>
> netscript db init
>
> ,
>
> db generate
>
> , and
>
> db seed
>
> must run
>
> after
>
> Aspire has started — never before. You will run them in chapter 2.

## Verify your progress

In a second terminal (leave `aspire start` going in the first), confirm the `orders` service answers its health endpoint:

```sh
curl http://localhost:3002/health
```

You should get a healthy JSON response. Then type-check the whole workspace from the project root:

```sh
deno task check
```

A clean check confirms the scaffold, contracts, and service line up.

- [ ] `netscript --help` lists the public command groups.
- [ ] `my-dashboard/` exists with `apps/dashboard/`, `contracts/`, and `services/orders/`.
- [ ] `aspire start` is up; the dashboard at `:18888` lists `postgres`, `redis`, and `orders`.
- [ ] `curl http://localhost:3002/health` returns a healthy response.
- [ ] `deno task check` is clean.

> If something is not green
>
> Three checks cover most first-run snags: (1) is
>
> aspire start
>
> still up, with
>
> postgres
>
> and
>
> redis
>
> healthy in the
>
> dashboard
>
> ? (2) is Docker running (
>
> docker info
>
> )? (3) did you
>
> cd aspire
>
> before
>
> aspire start
>
> so it found
>
> apphost.mts
>
> ? A failed
>
> curl
>
> usually means the service is still starting — wait a few seconds and retry.

## What you built

A real NetScript workspace — `my-dashboard/` — with a Fresh app, an `orders` service on `:3002`, and a Postgres database, all orchestrated by Aspire and visible at `:18888`. Next you will shape the `orders` read-model — the rows your operations team will eventually watch live.

[Live Dashboard](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/) [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/live-dashboard/01-scaffold/_

---

# A typed read-model service

In chapter 1 you scaffolded `my-dashboard/` and booted it under Aspire. Now you will shape the data the dashboard reads: an `orders` oRPC contract with a typed `list` procedure, served by `defineService`. The contract is the single source of truth — the same schema locks the types for the server handler and, later, for the Fresh client.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)
2. [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)
3. [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)
4. [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)
5. [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

## What you will build

An `orders.list` procedure: a `GET` route that takes pagination plus a `status` filter and returns a typed page of orders. The `status` filter is not decoration — it is the lens an operations queue lives in: `pending` and `processing` are the work to do, `failed` is the money at risk, `cancelled` is the ship-it-and-regret-it pile. You will read the scaffolded contract, understand the `.route().input().output()` shape, and serve it on port **3002** with `defineService`. This is the read-model every later chapter consumes — the rows that will eventually update live in the browser.

## Before you begin

You should have completed [chapter 1](https://rickylabs.github.io/netscript/tutorials/live-dashboard/01-scaffold/): `my-dashboard/` on disk and `aspire start` up. Confirm the `orders` service is reachable before you change anything — in a second terminal:

```sh
curl http://localhost:3002/health
```

A healthy JSON response means the scaffolded `orders` service is live on **3002** and ready to read.

## Step 1 — Read the orders contract

Contracts are the typed seam between your service and every client. They live in `contracts/`, versioned under `versions/v1/`, and are built from [`@orpc/contract`](https://rickylabs.github.io/netscript/explanation/contracts/) routes plus [Zod](https://zod.dev) schemas. Open `contracts/versions/v1/orders.contract.ts`. The dashboard only needs the read path, so focus on the `list` procedure:

```ts
// contracts/versions/v1/orders.contract.ts (the read path the dashboard uses)
import { z } from 'zod';
import { baseContract } from '../../shared.ts';

// The order status the dashboard table colours its badges by.
export const OrderStatusSchema = z.enum([
  'pending', 'processing', 'shipped', 'delivered', 'cancelled', 'returned', 'failed',
]);

// One order row, as the API returns it.
export const OrdersSchemaV1 = z.object({
  id: z.number().int().positive(),
  userId: z.number().int().positive(),
  status: OrderStatusSchema,
  total: z.number().nonnegative(),
  shippingCity: z.string(),
  shippingCountry: z.string(),
  createdAt: z.string().datetime(),
});

export const ordersContract = {
  list: baseContract
    .route({ method: 'GET' })
    .input(z.object({
      limit: z.number().int().positive(),
      offset: z.number().int().nonnegative(),
      status: OrderStatusSchema.optional(),
    }))
    .output(z.object({
      items: z.array(OrdersSchemaV1),
      total: z.number().int().nonnegative(),
      limit: z.number().int().positive(),
      offset: z.number().int().nonnegative(),
      hasMore: z.boolean(),
    })),
};
```

The pattern is the whole point:

1. **Schemas first.** Zod objects describe the input and the output. They double as runtime validation and as the TypeScript types that flow everywhere else.
2. **`baseContract.route({ method }).input(...).output(...)`** declares *what* the procedure accepts and returns — there is no handler body in the contract. `baseContract` is the scaffold's shared base that pre-declares common errors (`NOT_FOUND`, `VALIDATION_ERROR`, and friends).

> The real scaffold derives schemas from Prisma
>
> The contract you generated wires its order schemas from
>
> @database/zod
>
> — Zod schemas generated from your Prisma models — so the contract and the database never drift. The hand-written
>
> OrdersSchemaV1
>
> above is the
>
> same shape
>
> , spelled out so you can read it. When you wire real persistence, prefer the generated schemas. See
>
> Database & Prisma
>
> .

## Step 2 — Read the handler

A contract describes the shape; a handler supplies the behavior. Handlers live under `services/orders/src/routers/`. Open `services/orders/src/routers/v1.ts`. The `list` handler binds to the contract's `list` route and queries the database through the injected context:

```ts
// services/orders/src/routers/v1.ts (the list handler, trimmed)
import { v1 } from '@contracts';

const router = v1.orders.$context<{ db: OrdersDb }>();

export const ordersV1 = {
  list: router.list.handler(async ({ input, context }) => {
    const { db } = context;
    const { limit, offset, status } = input;

    const where = status ? { status } : {};
    const total = await db.netscript.order.count({ where });
    const orders = await db.netscript.order.findMany({
      where,
      include: { items: true },
      skip: offset,
      take: limit,
    });

    return {
      items: orders.map(toOrderResponse),
      total,
      limit,
      offset,
      hasMore: offset + limit < total,
    };
  }),
  // getById, create, update, delete, getStats … also bound here.
};
```

What is type-locked here, for free:

- `input` is already parsed and typed as `{ limit: number; offset: number; status?: ... }`. You never re-validate it — the contract did that.
- The returned object must satisfy the contract's `output` schema. Drop `hasMore`, mistype `total`, or forget `items`, and `deno task check` rejects it.

The `$context<{ db: OrdersDb }>()` call is how the handler declares it needs a database client; the service injects it (next step). The router then aggregates the handlers and namespaces them by version so the service can host `v1`, `v2`, and so on side by side.

## Step 3 — Serve it with defineService

The service entry point is `services/orders/src/main.ts`. One `defineService` call wires CORS, request logging, OpenAPI, the typed RPC surface, and health endpoints, and injects the database client the handler asked for:

```ts
// services/orders/src/main.ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';
import { db } from '@database';

// Each call returns the correctly typed client instance.
const netscript = await db.getClient();

await defineService(router, {
  name: 'orders',
  version: '1.0.0',
  port: parseInt(Deno.env.get('PORT') || '3002'),
  db: { netscript },
  openapi: { title: 'Orders API', description: 'Order management service' },
  debug: true,
});
```

Aspire injects `PORT` at runtime, so the entrypoint reads it from the environment; the typed source of truth is your `netscript.config.ts` `services.<name>.port` field, which the scaffold wires as the fallback default — set the port there rather than editing this line.

The service binds the router and exposes the same surface on port **3002**:

**orders service endpoints (port 3002)**

| Name | Type | Description |
| --- | --- | --- |
| `/api/rpc/*` | `POST` | The typed oRPC surface. Your typed client calls procedures (v1.orders.list) under this prefix with end-to-end type safety. This is what the dashboard talks to. |
| `/api/v1/orders/list` | `GET` | The OpenAPI/REST projection of the same procedure — handy for curl and tools. |
| `/health` | `GET` | Liveness probe — the plain JSON check you hit above. |

> Two ways to stand a service up
>
> The scaffold uses
>
> defineService(router, { … })
>
> — one call, sensible defaults. NetScript also offers a fluent
>
> createService(router, { … }).withCors().withLogger().withRPC().serve()
>
> builder when you need to control middleware order or add custom wiring. Stick with
>
> defineService
>
> for this track. See
>
> Services & contracts
>
> .

## Step 4 — Initialize the database

The `list` handler reads from Postgres, so the database needs its schema and some rows. With `aspire start` still up (Postgres is only live while Aspire is), run these from the **workspace root** in a second terminal:

```sh
netscript db init --name init   # create + apply the first migration
netscript db generate           # generate the Prisma client
netscript db seed               # seed development data (orders, users, products)
```

These talk to the Postgres container Aspire provisioned. Run them with no Aspire up and they fail — there is no database to reach. The full sequence is in [Database & migration](https://rickylabs.github.io/netscript/data-persistence/how-to/database-migration/).

## Verify your progress

Call the `list` procedure over the OpenAPI projection with `curl`. From a second terminal:

```sh
curl 'http://localhost:3002/api/v1/orders/list?limit=2&offset=0'
```

You should see up to two seeded orders and a total, shaped exactly like the contract's `output`:

```json
{
  "items": [
    { "id": 1, "userId": 1, "status": "delivered", "total": 129.5, "shippingCity": "Berlin", "shippingCountry": "DE", "createdAt": "2026-01-01T00:00:00.000Z" }
  ],
  "total": 42,
  "limit": 2,
  "offset": 0,
  "hasMore": true
}
```

Then confirm the whole workspace still type-checks — contract, handler, and router together — from the project root:

```sh
deno task check
```

- [ ] `curl …/api/v1/orders/list?limit=2&offset=0` returns a typed page of orders.
- [ ] The shape matches the contract's `output` (items / total / limit / offset / hasMore).
- [ ] `deno task check` is clean.

> Empty items array?
>
> If
>
> items
>
> comes back empty, the seed step did not run or the database is fresh. Re-run
>
> netscript db seed
>
> from the workspace root (with
>
> aspire start
>
> still up), then retry the curl.

## What you built

A typed `orders.list` read-model: an oRPC contract (`@orpc/contract` + Zod), a database-backed handler bound with `.handler(...)`, and a running service via `defineService` on port **3002**, with a verified `/api/rpc/*` surface and its `/api/v1/orders/*` OpenAPI projection. Next you will read this service from the Fresh app through a typed SDK client and a cache-first query layer.

[1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/) [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/live-dashboard/02-contract-to-service/_

---

# SDK client and cache-first query

In chapter 2 you served an `orders.list` read-model on port **3002**. Now you will read it from the Fresh app. The SDK gives you a typed client built from the same contract, and a query factory that wraps every procedure in a KV-backed stale-while-revalidate cache. For an operations screen that posture matters: the queue paints instantly from the last-known rows — even while the `orders` service is mid-redeploy — and refreshes in the background instead of blocking the person watching it.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)
2. [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)
3. [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)
4. [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)
5. [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

## What you will build

A single module, `apps/dashboard/lib/api-clients.ts`, that exports a typed `ordersClient` and a `baseQueries.orders` query utility. The client is derived from `typeof ordersContract`, so calling `ordersClient.list({ … })` is type-checked against the contract you wrote in chapter 2. The query factory adds per-procedure helpers — `queryOptions()`, `clientKey()`, and the cache-first `getCachedEntry()` — that chapters 4 and 5 build the page on.

## Before you begin

You should have completed [chapter 2](https://rickylabs.github.io/netscript/tutorials/live-dashboard/02-contract-to-service/): the `orders` service answering on **3002**, the database seeded, and `aspire start` up. Confirm the typed read-model still returns data:

```sh
curl 'http://localhost:3002/api/v1/orders/list?limit=1&offset=0'
```

You should get one seeded order back. If `items` is empty, re-run `netscript db seed` from the workspace root.

## Step 1 — Create the typed service client

`createServiceClient` from `@netscript/sdk/client` builds a client from a contract. The key fields: the `contract` itself, and a `serviceName` that is the **discovery key** — how the client finds the service's URL at call time. Create the clients module in your Fresh app:

```ts
// apps/dashboard/lib/api-clients.ts
import { ordersContract } from '@contracts';
import { createServiceClient } from '@netscript/sdk/client';
import { createQueryFactories } from '@netscript/sdk/query';

export const ordersClient = createServiceClient<typeof ordersContract>({
  contract: ordersContract,
  serviceName: 'orders',
});
```

`ordersClient.list(input)` now has the exact signature the contract declared — wrong input shape, or reading a field the output does not have, is a compile error.

> How serviceName resolves to a URL
>
> You never hardcode
>
> http://localhost:3002
>
> .
>
> serviceName: 'orders'
>
> is resolved at call time from an Aspire-injected env var — server-side
>
> services__orders__http__0
>
> , and the browser mirror
>
> VITE_services__orders__http__0
>
> — via
>
> getServiceUrl
>
> in
>
> @netscript/sdk/discovery
>
> . Aspire sets those when you list
>
> orders
>
> as a reference; the client just reads them. Full mechanics in
>
> Discover services
>
> .

## Step 2 — Add the cache-first query factory

A bare client calls the service every time. For a dashboard you want **cache-first**: serve the last-known answer instantly, then revalidate in the background. `createQueryFactories` wraps each procedure in exactly that — a KV-backed stale-while-revalidate layer. Add it to the same module:

```ts
// apps/dashboard/lib/api-clients.ts (add below the client)
// Server-side query factories — KV-backed stale-while-revalidate.
export const baseQueries = createQueryFactories({
  orders: { contract: ordersContract, client: ordersClient },
});

// App code reads the per-procedure utilities off the factory.
export const ordersQueryUtils = baseQueries.orders;
```

`baseQueries.orders` carries one entry per contract procedure (`list`, `getById`, `getStats`, …), each a small object of typed helpers. The four you will use across the next chapters:

**Per-procedure query helpers (e.g. ordersQueryUtils.list)**

| Name | Type | Description |
| --- | --- | --- |
| `.queryOptions(input)` | `(input) => options` | A TanStack Query options object (queryKey + queryFn) for the client island — chapter 4 passes it straight to useQuery. |
| `.clientKey(input?)` | `(input?) => key` | The stable query key the client uses to read, write, and invalidate this procedure's cache. |
| `.getCachedEntry(input)` | `(input) => entry \| undefined` | Server-side cache-first read: returns { data, cachedAt } from the KV cache, or undefined on a cold cache. This is the page loader's fast path. |
| `.key(input?)` | `(input?) => key` | The server-side KV cache key for the entry. |

> Why KV, and why cache-first
>
> The cache is backed by KV (Redis in your Aspire stack — the default
>
> --cache-backend
>
> , registered at the top of
>
> main.ts
>
> in chapter 1;
>
> garnet
>
> and
>
> deno-kv
>
> are alternatives). Cache-first means a page render does not block on the service:
>
> getCachedEntry
>
> returns immediately from KV when warm, and the stale entry refreshes in the background. A cold cache returns
>
> undefined
>
> , which the page handles with a skeleton — you wire that in chapter 4.

## Step 3 — Understand the calling shapes

You now have two ways to read orders, for two different places in the stack:

- **Server, cache-first** — `await ordersQueryUtils.list.getCachedEntry(input)` inside a page loader. Returns `{ data, cachedAt }` from KV, or `undefined`. Used in chapter 4's `definePage` loaders.
- **Client, in an island** — `useQuery(ordersQueryUtils.list.queryOptions(input))` inside a Fresh island. Used in chapter 4's `QueryIsland` for client-side reads and refetch.

Both derive their types and their cache key from the *same* contract, so a server-rendered row and a client-refetched row are guaranteed to be the same shape.

## Verify your progress

Type-check the workspace to prove the client and query factory line up with the contract:

```sh
deno task check
```

A clean check confirms `createServiceClient<typeof ordersContract>` and the query factory typed themselves off your chapter-2 contract. To prove the discovery key resolves end to end, leave `aspire start` up — the next chapter renders the page that calls through this client, and a missing `services__orders__http__0` shows up there as a clear "Service URL not found" error.

- [ ] `apps/dashboard/lib/api-clients.ts` exports `ordersClient`, `baseQueries`, and `ordersQueryUtils`.
- [ ] `deno task check` is clean.
- [ ] `deno check apps/dashboard/lib/api-clients.ts --unstable-kv` passes on its own — the module compiles against the chapter-2 contract with no other file in play.

## What you built

A typed `ordersClient` and a cache-first `ordersQueryUtils` query layer, both derived from the chapter-2 contract, with service discovery resolving the URL for you. Next you will render the live table: NetScript's `definePage` builder for the server shell, and a `QueryIsland` that hydrates these query helpers in the browser.

[2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/) [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/_

---

# The page builder and the query island

This is the heaviest chapter in the track, and the most rewarding. You will render the orders table with NetScript's `definePage` builder — its **layer / partial / island** triad — and hydrate a TanStack Query island so the table reads and mutates on the client. By the end the dashboard renders instantly from cache and refetches in the background. We flag where the surface is conceptually dense.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)
2. [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)
3. [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)
4. [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)
5. [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

## What you will build

An `/dashboard/orders/` route that renders a filterable orders table — the screen the fulfillment team keeps open. The server shell is a `definePage` page with a cache-first `list` layer; the interactive part is a `QueryIsland` that reads through the chapter-3 query helpers with `useQuery` and advances order status with an optimistic `useMutation`. Optimistic matters here: when a packer marks an order `shipped`, the row must move instantly — a badge that lags invites clicking it twice, and a double-advanced order is exactly the kind of quiet mistake this dashboard exists to prevent. You end with a page that paints from KV cache on first byte and stays live on the client.

## Before you begin

You should have completed [chapter 3](https://rickylabs.github.io/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/): `apps/dashboard/lib/api-clients.ts` exports `ordersClient`, `baseQueries`, and `ordersQueryUtils`, and `deno task check` is clean. Confirm the query module is in place:

```sh
deno check apps/dashboard/lib/api-clients.ts --unstable-kv
```

A clean check means the typed client and query factory are ready to wire into a page.

## The mental model: layer / partial / island

Before any code, hold these three words apart — most of the chapter is just them working together:

**The definePage triad**

| Name | Type | Description |
| --- | --- | --- |
| `Layer` | `withLayer(name, Component, config)` | A named region of the page. Each layer has its own server loader, its own fallback skeleton, and its own staleness window. The page is a composition of layers. |
| `Partial` | `partial + partialName on a layer` | The Fresh partial route a layer re-renders through. It lets one layer refresh on the server without a full page navigation — the cache-first refresh path. |
| `Island` | `a layer whose Component is a Fresh island` | An interactive layer that hydrates in the browser. Here it is the QueryIsland: client-side reads, refetch, and optimistic mutations. |

A `definePage` page wires several layers into a layout, each fed by its own loader. The server renders every layer from cache; the island layer then takes over interactivity in the browser.

## Step 1 — Declare the route contract

A NetScript route declares its own typed search params. `defineRouteContract` from `@netscript/fresh/route` builds that schema; `paginationSearchSchema` and `fallback` give you safe defaults for missing or malformed query strings. Create the route file:

```ts
// apps/dashboard/routes/(dashboard)/dashboard/orders/index.route.ts
import { defineRouteContract, fallback, paginationSearchSchema } from '@netscript/fresh/route';
import { z } from 'zod';

const ORDERS_SEARCH_SCHEMA = paginationSearchSchema({
  defaultSort: 'createdAt',
  defaultOrder: 'desc',
}).extend({
  search: fallback(z.string(), ''),
  status: fallback(z.enum([
    'pending', 'processing', 'shipped', 'delivered', 'cancelled', 'returned', 'failed',
  ]).optional(), undefined),
});

export default defineRouteContract({ searchSchema: ORDERS_SEARCH_SCHEMA });

// The parsed shape every loader and island receives — page, limit, offset, sortBy,
// sortOrder, plus the search/status fields the schema extends with.
export type OrdersSearch = ReturnType<typeof ORDERS_SEARCH_SCHEMA.parse>;
```

`fallback(schema, default)` is the safety belt: a junk `?status=banana` resolves to the default instead of throwing, so a hand-edited URL never 500s the page. This is the same `paginationSearchSchema()` the framework uses site-wide — every route that paginates parses `limit` and `offset` through it rather than reading `searchParams` by hand.

## Step 2 — Write the cache-first page loader

The page reads the cache, not the service. Add a small loader that pulls the orders island's initial data from KV through the chapter-3 helpers. Because the page binds the Step 1 contract, the loader is handed a typed `search` object — `limit`, `offset`, and `status` are already parsed and defaulted, so there is no `searchParams.get(...)` to write. A cold cache returns `undefined`, which the page renders as a skeleton:

```ts
// apps/dashboard/routes/(dashboard)/dashboard/orders/(_shared)/query-loaders.ts
import { baseQueries } from '@app/lib/api-clients.ts';
import type { OrdersSearch } from '../index.route.ts';

export async function ordersQueryLoader({ search }: { search: OrdersSearch }) {
  const input = { limit: search.limit, offset: search.offset, status: search.status };
  const entry = await baseQueries.orders.list.getCachedEntry(input);

  return {
    initialOrders: entry?.data,
    cachedAt: entry?.cachedAt,
    input,
  };
}
```

The loader returns three things the island needs: the cached `data`, the `cachedAt` timestamp (so the client knows how stale the seed is), and the `input` (so the client can refetch the same slice). The `search` object is the contract's payoff — the same typed slice the Step 3 layer loader reads, so both loaders agree on what `limit`/`offset` mean without either one touching the raw query string.

## Step 3 — Compose the page with definePage

`definePage` from `@netscript/fresh/builders` is a fluent builder. You bind the route, set a caching policy, add layers, lay them out, and `build()`. Here is the orders page reduced to the live-table spine:

```tsx
// apps/dashboard/routes/(dashboard)/dashboard/orders/index.tsx
import { definePage } from '@netscript/fresh/builders';
import { routes } from '@app/router.ts';
import OrdersQueryIsland from './(_islands)/OrdersQueryIsland.tsx';
import { ordersQueryLoader } from './(_shared)/query-loaders.ts';
import { PlaygroundOrdersList, PlaygroundOrdersListSkeleton } from './(_components)/list.tsx';
import { baseQueries } from '@app/lib/api-clients.ts';

export const ordersListPage = definePage()
  .withRoute(routes.dashboard.orders.$route)
  .withPolicy('balanced')
  .withTelemetry({ enabled: true, spanName: 'dashboard.orders.list' })
  .withLayer('list', PlaygroundOrdersList, {
    loader: async ({ url, search }) => {
      const input = { limit: search.limit, offset: search.offset, status: search.status };
      const cachedEntry = await baseQueries.orders.list.getCachedEntry(input);
      if (!cachedEntry) return undefined; // cold cache → fallback skeleton
      return { data: cachedEntry.data, cachedAt: cachedEntry.cachedAt };
    },
    partial: routes.partials.dashboard.orders.list.$route.href(),
    partialName: 'orders-list',
    fallback: <PlaygroundOrdersListSkeleton />,
    staleTime: 15_000,
    staleReloadMode: 'background',
  })
  .withLayer('ordersQuery', OrdersQueryIsland, {
    loader: ordersQueryLoader,
    staleTime: 15_000,
    staleReloadMode: 'background',
  })
  .withLayout((slots) => (
    <main class='ns-page-end'>
      <div class='ns-stack ns-stack--lg'>
        {slots.list()}
        {slots.ordersQuery()}
      </div>
    </main>
  ))
  .withMeta(() => ({
    title: 'Order Queue',
    description: 'Browse and manage orders in the live dashboard.',
  }))
  .build();

export const { handler, default: page } = ordersListPage;
export { page as default };
```

Read the builder one call at a time:

**definePage builder steps**

| Name | Type | Description |
| --- | --- | --- |
| `.withRoute(route)` | `route contract` | Binds the typed search schema from Step 1. The loaders receive a typed search object. |
| `.withPolicy('balanced')` | `caching policy` | The page's caching posture. 'balanced' serves cache-first and revalidates in the background. |
| `.withTelemetry({ enabled, spanName })` | `tracing` | Wraps the page render in a named span that surfaces in the Aspire dashboard traces. |
| `.withLayer(name, Component, config)` | `a named region` | Adds a layer with its own loader, partial, fallback, and staleTime. Call it once per region. |
| `.withLayout(slots => …)` | `layout callback` | Places each layer by calling slots.(). The layout is plain JSX. |
| `.withMeta(() => …)` | `head metadata` | Page title and description. |
| `.build()` | `finalize` | Produces the page object: { handler, default } that Fresh serves. |

> This is the dense part — and it earns its weight
>
> The layer config carries a lot: a
>
> loader
>
> (cache-first server read), a
>
> partial
>
> +
>
> partialName
>
> (the refresh route), a
>
> fallback
>
> (cold-cache skeleton), and
>
> staleTime
>
> +
>
> staleReloadMode
>
> (the staleness window and how it refreshes). It is more upfront ceremony than a plain Fresh route — the payoff is that each region renders from cache independently and refreshes without a full navigation. If you only need a static page, a plain Fresh route is lighter; reach for
>
> definePage
>
> when a region must be cache-first and self-refreshing, which a live table is. See
>
> the Fresh meta-framework
>
> .

## Step 4 — Hydrate the QueryIsland

The server shell paints from cache; the island makes it interactive. `QueryIsland` from `@netscript/fresh/query` provides the TanStack Query context; inside it, `useQuery` reads through the chapter-3 `queryOptions`, seeded with the loader's `initialData` so there is no client refetch flash. `useMutation` advances an order's status optimistically:

```tsx
// apps/dashboard/routes/(dashboard)/dashboard/orders/(_islands)/OrdersQueryIsland.tsx
import { QueryIsland, useMutation, useQuery, useQueryClient } from '@netscript/fresh/query';
import { ordersQueryUtils } from '@app/lib/api-clients.ts';

function OrdersQueryInner(props) {
  const queryClient = useQueryClient();
  const currentKey = ordersQueryUtils.list.clientKey(props.input);

  // Server-seeded read: no client refetch flash on first paint.
  const { data: orders, isRefetching } = useQuery({
    ...ordersQueryUtils.list.queryOptions(props.input),
    initialData: props.initialOrders,
    initialDataUpdatedAt: props.cachedAt,
    staleTime: 15_000,
  });

  // Optimistic status advance — update the cache, roll back on error.
  const statusMutation = useMutation({
    ...ordersQueryUtils.update.mutationOptions(),
    onMutate: async (variables) => {
      await queryClient.cancelQueries({ queryKey: currentKey });
      const previous = queryClient.getQueryData(currentKey);
      queryClient.setQueryData(currentKey, (prev) => applyStatus(prev, variables));
      return { previous };
    },
    onError: (_e, _v, ctx) => {
      if (ctx?.previous) queryClient.setQueryData(currentKey, ctx.previous);
    },
    onSettled: () =>
      queryClient.invalidateQueries({ queryKey: ordersQueryUtils.list.clientKey() }),
  });

  const items = orders?.items ?? [];
  return <OrdersTable items={items} isRefetching={isRefetching} onAdvance={statusMutation.mutate} />;
}

export default function OrdersQueryIsland(props) {
  return (
    <QueryIsland>
      <OrdersQueryInner {...props} />
    </QueryIsland>
  );
}
```

The key moves:

- **`initialData` + `initialDataUpdatedAt`** seed `useQuery` from the server loader, so the table is populated on first paint and TanStack treats it as fresh until `staleTime` elapses.
- **`clientKey(input)`** is the same stable key from chapter 3 — `useMutation` reads, writes, and invalidates the cache through it, so the optimistic update lands on exactly the rows `useQuery` is showing.
- **`onMutate` / `onError`** are the optimistic pattern: apply the change immediately, snapshot the previous data, and roll back if the server rejects it.

## Verify your progress

Make sure `aspire start` is up, then open the route in a browser:

```
http://localhost:8010/dashboard/orders/
```

(The Fresh app's port is `:8010` in the Aspire stack; confirm the exact port in the [dashboard](https://rickylabs.github.io/netscript/explanation/aspire/) resource list.) You should see the orders table render immediately — populated from KV cache, not a spinner — and a "Refreshing" indicator flicker as it revalidates. Advancing an order's status should update its badge instantly. Type-check too:

```sh
deno task check
```

- [ ] `index.route.ts`, `(_shared)/query-loaders.ts`, `index.tsx`, and `(_islands)/OrdersQueryIsland.tsx` all exist under `apps/dashboard/routes/(dashboard)/dashboard/orders/`.
- [ ] The page renders the orders table from cache on first paint (no spinner flash).
- [ ] Advancing a status updates the row optimistically.
- [ ] `deno task check` is clean.

> Table is empty or spinning forever?
>
> A perpetually empty table usually means the KV cache is cold and the loader returned
>
> undefined
>
> with nothing to refetch — confirm
>
> aspire start
>
> is up so
>
> services__orders__http__0
>
> resolves, and that
>
> netscript db seed
>
> ran. The first request warms the cache; reload once.

## What you built

A `definePage` orders page that renders cache-first through the layer/partial/island triad, plus a hydrated `QueryIsland` that reads with `useQuery` and mutates optimistically with `useMutation` — all keyed off the same contract-derived helpers. The table is live on the client. Next you make it live from the *server*: real-time row updates over a durable StreamDB.

[3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/) [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/_

---

# Real-time updates with durable streams

In chapter 4 the table was live on the *client* — it refetched and mutated without a navigation. But it still only knows what it fetched: between revalidations, a cancelled order sits on the screen looking shippable. This chapter closes that gap from the *server* side: a durable change-stream pushes state changes to the browser, and a `useLiveQuery` hook re-renders rows the instant they change — no polling loop, no refresh button, no window where the screen and the database disagree. This is the payoff of the whole track: a table that updates by itself.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)
2. [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)
3. [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)
4. [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)
5. [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

## What you will build

A live monitor island that subscribes to a durable StreamDB and renders rows that update in real time. You will open a `StreamDB` handle pointed at the streams runtime on port **4437**, drive a table with `useLiveQuery`, and seed the island from the server so the first paint is instant. The worked example is the **sagas** stream — the durable change-stream the showcase ships and the same mechanism your order dashboard uses to go live.

> Why the example uses the sagas stream
>
> NetScript's durable-streams runtime mirrors execution state — saga instances, worker executions — into change-streams that the frontend can subscribe to. The sagas plugin ships the ready-made
>
> typed
>
> collection for this:
>
> createSagasStreamDB
>
> gives
>
> useLiveQuery
>
> a StreamDB it can query with full types, which is why this chapter's worked live table grounds there. The pattern is identical for any StreamDB collection; once you have it, pointing a live table at your own stream is the same three moves — and the producer half of that story is already in reach, because the streams plugin scaffolds a user-owned durable stream into your workspace (see the closing section). To follow this chapter against running data, the workspace needs the
>
> sagas
>
> plugin and its streams runtime — add the published package with
>
> netscript plugin install @netscript/plugin-sagas
>
> if it is not already installed.

## Before you begin

You should have completed [chapter 4](https://rickylabs.github.io/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/): the orders page rendering through `definePage` with a hydrated `QueryIsland`. The live layer needs the streams runtime reachable. With `aspire start` up, confirm it answers on **4437**:

```sh
curl http://localhost:4437/health
```

A healthy response means the durable-streams producer runtime is live. If the port is dead, the sagas plugin (which brings the stream) is not installed or Aspire has not finished booting it — check the [dashboard](https://rickylabs.github.io/netscript/explanation/aspire/) resource list at `:18888`.

> HTTP/2 is opt-in for live subscriptions
>
> The live subscription runs over plaintext
>
> HTTP/1.1
>
> by default, which caps how many concurrent SSE connections a browser opens per origin. HTTP/2 lifts that cap but is opt-in and requires TLS — via
>
> ServiceTlsOptions
>
> or the
>
> NETSCRIPT_TLS_CERT_FILE
>
> /
>
> NETSCRIPT_TLS_KEY_FILE
>
> environment variables. See
>
> Durable streams
>
> for the connection-limit detail.

## Step 1 — Open a StreamDB handle

`createSagasStreamDB` from `@plugins/sagas/streams` opens a typed StreamDB client against the streams runtime. You give it the runtime's `baseUrl`; it gives you typed `collections` you can query. Build it inside the island, memoized on the URL, and manage its lifecycle:

```tsx
// apps/dashboard/islands/SagasLiveIsland.tsx (the StreamDB handle)
import { useEffect, useMemo } from 'preact/hooks';
import { createSagasStreamDB, type SagaInstance } from '@plugins/sagas/streams';

function SagasLiveInner(props: { streamsBaseUrl: string }) {
  const sagasDb = useMemo(
    () => createSagasStreamDB({ baseUrl: props.streamsBaseUrl }),
    [props.streamsBaseUrl],
  );

  // Preload the stream on mount; close it on unmount.
  useEffect(() => {
    void sagasDb.preload();
    return () => sagasDb.close();
  }, [sagasDb]);

  // … useLiveQuery below
}
```

`preload()` warms the stream so the first frame has data; `close()` tears the subscription down when the island unmounts. Always pair them — a leaked subscription keeps a connection open.

## Step 2 — Drive a table with useLiveQuery

`useLiveQuery` from `@netscript/fresh/query` runs a query against a StreamDB collection and **re-renders whenever the underlying data changes** — no polling, no manual refetch. Query the `sagaInstance` collection:

```tsx
// apps/dashboard/islands/SagasLiveIsland.tsx (the live query)
import { useLiveQuery } from '@netscript/fresh/query';

const { data: instanceRows = [] } = useLiveQuery(
  (query) => query.from({ instance: sagasDb.collections.sagaInstance }),
  [sagasDb],
);

const instances = instanceRows as SagaInstance[];
// Render `instances` as a table — each row updates the moment its saga advances.
```

The callback shape is a tiny query builder: `query.from({ instance: <collection> })` selects rows from the `sagaInstance` collection. When the server pushes a change for any of those rows, `useLiveQuery` returns the new array and the table re-renders. That is the entire real-time path on the client.

> Live vs. fetched, side by side
>
> A live island typically runs
>
> both
>
> kinds of read: a
>
> useQuery
>
> for the slow-changing inventory (the list of sagas), and a
>
> useLiveQuery
>
> for the fast-changing instance rows. The first is cache-first and revalidated; the second is pushed in real time. The showcase island does exactly this — the inventory comes from
>
> useQuery
>
> , the live rows from
>
> useLiveQuery
>
> .

## Step 3 — Seed the island from the server

Real time should not mean a blank first paint. Seed the island on the server: resolve the streams URL, pre-warm the SDK cache, and dehydrate a TanStack Query client so the island hydrates with data already in hand. `getStreamsUrl` from `@netscript/plugin-streams-core` resolves the runtime address:

```ts
// apps/dashboard/routes/(dashboard)/dashboard/plugin/(_shared)/stream-loaders.ts
import { dehydrateQueryClient } from '@netscript/fresh/query';
import { createNetScriptQueryClient } from '@netscript/sdk/query-client';
import { getStreamsUrl } from '@netscript/plugin-streams-core';
import { sagasQueryUtils } from '@app/lib/api-clients.ts';

const INVENTORY_INPUT = { limit: '12', offset: '0' } as const;

export async function sagasStreamSeedLoader() {
  // 1. Fetch through the SDK (also warms the KV cache for getCachedEntry hits).
  const sagasData = await sagasQueryUtils.listSagas(INVENTORY_INPUT);

  // 2. Populate a temporary QueryClient and dehydrate it for the island.
  const queryClient = createNetScriptQueryClient();
  queryClient.setQueryData(sagasQueryUtils.listSagas.clientKey(INVENTORY_INPUT), sagasData);
  const dehydratedState = dehydrateQueryClient(queryClient);

  return {
    inventoryInput: INVENTORY_INPUT,
    streamsBaseUrl: getStreamsUrl(),
    dehydratedState,
  };
}
```

The island receives `streamsBaseUrl` (for Step 1's StreamDB handle), `inventoryInput` (for the `useQuery` inventory read), and `dehydratedState` (the pre-warmed TanStack cache). On mount the island rehydrates from `dehydratedState`, so the inventory is present immediately and the live rows stream in on top.

> Streams is its own runtime — and it must be up
>
> The durable-streams producer is a
>
> separate Aspire service on :4437
>
> , not part of your orders service.
>
> getStreamsUrl()
>
> resolves its address from the environment the same way
>
> getServiceUrl
>
> does for services — so it only works when
>
> aspire start
>
> has brought the streams runtime up. With no streams runtime,
>
> useLiveQuery
>
> has nothing to subscribe to and the live table stays empty (the
>
> useQuery
>
> inventory still renders from cache). See
>
> Durable streams
>
> .

## Step 4 — Wrap the island in QueryIsland

`useLiveQuery` and `useQuery` both need the TanStack Query context, so the live monitor lives inside a `QueryIsland` exactly like chapter 4's orders island. Hydrate the dehydrated state on first render:

```tsx
// apps/dashboard/islands/SagasLiveIsland.tsx (the island boundary)
import { getIslandQueryClient, hydrateFromDehydrated, QueryIsland } from '@netscript/fresh/query';

export default function SagasLiveIsland(props) {
  return (
    <QueryIsland>
      <SagasLiveInner {...props} />
    </QueryIsland>
  );
}

// Inside SagasLiveInner, once, before the queries:
//   const islandQueryClient = getIslandQueryClient();
//   if (props.dehydratedState) hydrateFromDehydrated(islandQueryClient, props.dehydratedState);
```

`getIslandQueryClient()` returns the island's QueryClient; `hydrateFromDehydrated` seeds it from the server's `dehydratedState`. After that, `useQuery` reads the seeded inventory and `useLiveQuery` takes over the live rows. The island is now complete — prove it compiles as a unit:

```sh
deno check apps/dashboard/islands/SagasLiveIsland.tsx --unstable-kv
```

A clean check confirms the StreamDB handle, both query hooks, and the hydration wiring line up.

## Point it at your own stream

Everything above consumes a stream the framework produces for you. The producer half of the seam is just as close: if your workspace has the **streams** plugin installed (`netscript plugin install streams`), its scaffolder wrote `streams/notifications-stream.ts` — a user-owned durable stream you edit like any other source file. It is the same two primitives this whole chapter rides on:

```ts
// streams/notifications-stream.ts (scaffolded — yours to edit)
// defineStreamSchema declares the typed collections; createDurableStream
// returns the producer. Swap the sample event shape for your own domain
// events — an order.cancelled event is one zod object away.
import { createDurableStream, defineStreamSchema } from '@netscript/plugin-streams-core';
```

The producer publishes with `upsert(collection, row)` and `await flush()`; a browser consumes a user-defined stream over HTTP/SSE at its `streamPath`. The full producer surface, URL resolution, and current limitations are on [the Durable streams page](https://rickylabs.github.io/netscript/netscript/durable-workflows/streams/) — when you outgrow the sagas monitor, that is where your own `order-events` stream starts.

## Verify your progress

With `aspire start` up, open the live monitor in the browser and watch it update. The showcase serves it at the plugin route; in your workspace the live saga monitor renders wherever you mount `SagasLiveIsland`. To *see* it move, trigger a saga — creating an order publishes an `OrderCreated` saga message (chapter 2's service does this), which advances a saga instance and pushes a change down the stream:

```sh
curl -X POST http://localhost:3002/api/v1/orders/create \
  -H 'content-type: application/json' \
  -d '{ "userId": 1, "total": 49.9, "status": "pending", "shippingStreet": "1 Main", "shippingCity": "Berlin", "shippingCountry": "DE", "shippingZipCode": "10115", "items": [{ "productId": 1, "quantity": 1 }] }'
```

Within a moment a new saga instance row should appear and advance through its steps **without a page reload**. Type-check the new files:

```sh
deno task check
```

- [ ] `curl http://localhost:4437/health` returns healthy (streams runtime up).
- [ ] The live island opens a `createSagasStreamDB` handle and queries it with `useLiveQuery`.
- [ ] The island is seeded server-side (`getStreamsUrl` + `dehydrateQueryClient`) and hydrates on mount.
- [ ] Creating an order makes a row appear/advance live, with no reload.
- [ ] `deno task check` is clean.

> Nothing moves when you create an order?
>
> Two usual causes: the sagas plugin (and its streams runtime on :4437) is not installed/booted — check the
>
> dashboard
>
> resource list; or
>
> getStreamsUrl()
>
> resolved nothing because
>
> aspire start
>
> is down. The
>
> useQuery
>
> inventory still renders from cache, which is why the panel looks alive but never moves.

## What you built

A real-time table: a durable StreamDB handle (`createSagasStreamDB`) driving `useLiveQuery`, seeded from the server with `getStreamsUrl` + dehydration, wrapped in a `QueryIsland`. The refresh button is now irrelevant: the moment an order's state changes on the server, the row your operations team is looking at changes with it — the full contract → client → query → island → stream spine, end to end. Next you run the whole graph locally under Aspire.

[4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/) [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/live-dashboard/05-live-stream/_

---

# Run the whole dashboard under Aspire

You have built the full spine — contract, service, query layer, page, and live stream. This final chapter steps back and runs the entire graph as one system: the `orders` service, the Fresh dashboard, the durable-streams runtime, Postgres, and Redis, all under a single `aspire start`. That is the payoff of scaffolding on NetScript — you never wrote a compose file, a container manifest, or a service-discovery config, yet one command boots the whole graph in dependency order, resolves every cross-reference into injected environment variables, and hands you a live view of it. This chapter is also precise about what local Aspire is — a development orchestrator — and what it is not.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/01-scaffold/)
2. [2 · Contract to service](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/02-contract-to-service/)
3. [3 · Cache-first query](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/)
4. [4 · definePage + island](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/)
5. [5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/06-deploy/)

## What you will build

A complete, observable run of `my-dashboard/` on one machine: every resource your dashboard touches, booted in dependency order from a single command, with the wiring resolved into injected environment variables and the whole graph visible in the Aspire dashboard at `:18888`. You finish the track with a running live dashboard you can open, watch, and trust you understand.

## Before you begin

You should have completed [chapter 5](https://rickylabs.github.io/netscript/tutorials/live-dashboard/05-live-stream/): the live monitor updating in real time. The AppHost was scaffolded back in chapter 1 (you did not pass `--no-aspire`), so confirm the orchestration entry points are on disk — from the workspace root:

```sh
ls aspire/apphost.mts aspire/aspire.config.json
```

Both files should exist. `apphost.mts` is the **TypeScript/Node** program `aspire start` executes; `aspire.config.json` pins the SDK. `netscript init` generated them — you never hand-write the AppHost.

> The graph is derived from your plugins
>
> The resource graph inside the AppHost is assembled at boot from your installed plugins via
>
> composeAppHost
>
> — add the sagas plugin (chapter 5) and its API plus its streams runtime appear; remove it and they vanish, no edit to
>
> apphost.mts
>
> . The mechanics are in
>
> Orchestration with Aspire
>
> .

## Step 1 — Restore the AppHost SDK (once)

The AppHost runs on its own isolated Node runtime inside `aspire/` so its dependencies never leak into your Deno workspace. Restore that runtime once per machine (and after an SDK bump):

```sh
cd aspire
aspire restore
```

## Step 2 — Start the whole graph

A single `aspire start` translates `appsettings.json` plus the plugin contributions into a resource graph and boots all of it — infrastructure first, then the service, the Fresh app, and the streams runtime, with cross-references resolved into injected environment variables:

```sh
# Still inside aspire/. Prints the dashboard URL + a one-time login token.
aspire start
```

When boot finishes, `aspire start` prints the dashboard address and a login token. The graph it stands up for this track:

**What aspire start brings up for my-dashboard**

| Name | Type | Description |
| --- | --- | --- |
| `aspire (dashboard)` | `https://localhost:18888` | The Aspire dashboard: live resource list, console logs, structured logs and traces. A login token prints on start. |
| `postgres` | `Container` | Provisioned via Docker. The database your orders service reads — reachable only once Aspire is up. |
| `redis` | `Container (cache)` | Redis cache — the default `--cache-backend`; Redis-compatible. Backs the KV-backed query layer from chapter 3. |
| `orders` | `:3002` | Your oRPC service (defineService). RPC at /api/rpc/*, OpenAPI at /api/v1/orders/*. |
| `dashboard (Fresh app)` | `:8010` | Your Fresh frontend — the live dashboard you built in chapters 4–5. |
| `streams` | `:4437` | Durable-streams producer runtime, present once the sagas plugin is installed. Feeds useLiveQuery. |

> Ports are range-allocated — read the dashboard for the truth
>
> The conventional ports above (orders
>
> :3002
>
> , Fresh app
>
> :8010
>
> , streams
>
> :4437
>
> ) are what a default workspace lands on, but services come from the
>
> :3000–3099
>
> range and plugin runtimes from
>
> :8091–8099
>
> /
>
> :4437
>
> . The Aspire dashboard's resource list is the authority for the exact port each resource bound — read it from there, not from memory.

## Step 3 — Open the live dashboard

With the graph up, open your Fresh app and the orders route you built:

```
http://localhost:8010/dashboard/orders/
```

The table renders cache-first (chapter 4), refetches on the client, and — if the streams runtime is up — the live monitor updates in real time (chapter 5). Then open the Aspire dashboard to watch the system behind it:

```
https://localhost:18888
```

Paste the login token `aspire start` printed. You get one pane over the running graph:

**Aspire dashboard surfaces**

| Name | Type | Description |
| --- | --- | --- |
| `Resources` | `tab` | Every container and process with status, endpoints, and resolved environment. The authority for which port each resource bound. |
| `Console logs` | `tab` | stdout/stderr per resource — a failing service or streams runtime is one click away, not buried in a terminal. |
| `Structured logs + Traces` | `tab` | Spans your handlers and pages emit (including the withTelemetry span from chapter 4), correlated across resources via the OTLP collector on :4318. |

## Step 4 — Watch a request flow through the graph

Create an order and follow it across the whole stack in one place. From a second terminal:

```sh
curl -X POST http://localhost:3002/api/v1/orders/create \
  -H 'content-type: application/json' \
  -d '{ "userId": 1, "total": 49.9, "status": "pending", "shippingStreet": "1 Main", "shippingCity": "Berlin", "shippingCountry": "DE", "shippingZipCode": "10115", "items": [{ "productId": 1, "quantity": 1 }] }'
```

In the **Resources** tab you can see the `orders` service handle it; in **Traces** the request shows as a span; the live monitor in your Fresh app advances a new saga row; and the orders table picks up the new order on its next revalidation. One command, the full spine, observable end to end.

## Verify your progress

```sh
# From the workspace root, with `aspire start` up in another terminal:
curl http://localhost:3002/health      # orders service
curl http://localhost:4437/health      # streams runtime (if sagas installed)
```

Both should return healthy responses, and the dashboard at `:18888` should list `postgres`, `redis`, `orders`, the Fresh `dashboard`, and `streams` all running.

- [ ] `aspire restore` then `aspire start` boots the graph without errors.
- [ ] `https://localhost:18888` lists every resource healthy.
- [ ] `http://localhost:8010/dashboard/orders/` renders the live table.
- [ ] Creating an order is visible in the dashboard traces and the live monitor.

> Aspire is the LOCAL story — not a production deployer
>
> aspire start
>
> exists to make one command produce a complete, observable, correctly-wired stack on
>
> one machine
>
> . The Postgres and Redis it starts are throwaway Docker containers for dev convenience —
>
> not
>
> your production database or cache. For a remote target you point processes at managed infrastructure and let your platform own lifecycle; that is the
>
> Deploy
>
> recipe, and the
>
> --no-aspire
>
> path in
>
> Orchestration with Aspire
>
> .

> Footguns when aspire start will not boot
>
> - **Docker not running.** Aspire provisions Postgres + Redis through Docker; no daemon means the happy path does not start. Start Docker, or take the `--no-aspire` path with your own infrastructure.
> - **Wrong directory.** `aspire restore` and `aspire start` run from inside `aspire/`; `netscript db` commands run from the workspace root. Mixing them up is the most common first-run error.
> - **db command before `aspire start`.** Every `netscript db` command needs a live Postgres — bring the graph up first.
> - **Ports in use.** The dashboard wants `:18888`/`:18889` and OTLP `:4318`; the service, Fresh app, and streams claim `:3000+`, `:8010`, and `:4437`. A stale prior run holding a port blocks boot — free it.

## What you built

You ran the complete `my-dashboard/` graph under one `aspire start`: service, Fresh app, durable streams, Postgres, and Redis, wired automatically and observable in the dashboard at `:18888`. That closes the track — the order queue from the opening premise is real now: no polling loop, no refresh button, no window where a cancelled order looks shippable. You built and ran it on the full NetScript spine.

## Where to go next

- **Task recipes** → the [how-to guides](https://rickylabs.github.io/netscript/how-to/) cover what the tutorials don't: adding plugins, database migrations, queue backends, and production pitfalls.
- **Ship it remotely** → [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/) is the production companion to local Aspire.
- **Go deeper** → [Orchestration with Aspire](https://rickylabs.github.io/netscript/explanation/aspire/) explains the AppHost, plugin contributions, and two-pass reference resolution; [Durable streams](https://rickylabs.github.io/netscript/netscript/durable-workflows/streams/) and

[the Fresh meta-framework](https://rickylabs.github.io/netscript/netscript/web-layer/) back chapters 4 and 5.

[5 · Live stream](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/) [How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/live-dashboard/06-deploy/_

---

# Build a storefront backend

This track is a project, not a tour. Across seven chapters you build a small e-commerce storefront — a products catalog, a cart, a durable checkout, a shipping webhook, and a storefront page — in one workspace that grows chapter by chapter. It is the same spine the NetScript playground runs, re-themed as a shop, so every pattern you learn here is one the framework's own example app uses in anger.

The differentiator this track proves is **one typed contract, honored from the database to the button**: the oRPC schema you write once is the same object the server handler validates against, the same one a page's query and checkout mutation are typed from, so a wrong field is a compile error, not a 2 a.m. incident. **What this replaces:** the hand-maintained REST-plus-fetch-wrapper-plus-DTO stack where the client's idea of a cart and the server's idea of a cart are two files that drift until production catches them apart.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)
2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)
3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)
4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)
5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)
6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)
7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

## What you will build

A working storefront backend called `my-shop/`: a typed `products` catalog service backed by Postgres, a `cart` domain defined contract-first, a durable `checkout` saga that survives restarts and compensates on failure, and an HMAC-verified shipping webhook that hands inbound provider events to a background job. By the last chapter the whole thing runs on your machine under one orchestrator, visible in a single dashboard.

The arc is deliberate. It teaches NetScript's central opinion — **the oRPC contract is the single source of truth** — and then shows what that buys you once the happy path needs to survive money changing hands: durable workflows and verified webhooks make checkout reliable instead of hopeful.

## The shape of the app

[Catalog → cart → checkout → shipping  Products live in a typed service. A cart contract models a new domain. Checkout is a durable saga with a compensation branch. Shipping arrives as a verified webhook that enqueues a job. Each piece is one chapter.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[Contract-first, everywhere  Every service surface is an `@orpc/contract` route with Zod input/output schemas — many of them generated from Prisma. Write the schema once and the server handler, the typed client, and the OpenAPI projection all agree.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[Durable by design  Checkout is not a one-shot call — it is a state machine with `defineSaga` that checkpoints its state, reacts to payment and inventory messages, and runs a compensation path when a step fails.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)

## Who this is for

You are comfortable with TypeScript and have used Deno at least a little. You do not need prior NetScript experience — chapter 1 starts from an empty folder — but if you have never run the framework locally, skim the [Quickstart](https://rickylabs.github.io/netscript/quickstart/) first; it covers the same scaffold at a gentler pace. This track moves faster and stays on the storefront domain the whole way.

You also do not need to read the whole framework before you start. Each chapter introduces exactly one new capability, grounds it in real running code, and proves it with a command whose output you can check.

## The seven chapters

[1 · Scaffold  Create `my-shop/` with the `netscript` CLI and boot it under Aspire. Postgres (the default; swap `--db postgres` for `mysql`, `mssql`, or `sqlite`), the Redis cache, and your service come up together; the dashboard answers on :18888.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)

[2 · Catalog service  Define a typed `products` contract whose schemas come from Prisma, implement the handlers against a Postgres-backed database client, and serve it with `defineService` on :3001.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[3 · Cart contracts  Model a brand-new `cart` domain contract-first — list, getById, create, update — with shared typed errors, then derive a fully typed client from it. No handler guesswork.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)

[4 · Checkout saga  Turn checkout into a durable workflow with `defineSaga`: a state machine that walks order → payment → inventory → shipment and compensates when a step fails.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)

[5 · Shipping webhook  Accept an HMAC-verified shipping/payment webhook with `defineWebhook` and hand each inbound event to a background job with `enqueueJob`. Triggers API on :8093.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)

[6 · Storefront UI  Put a face on the backend: a typed cart route with `createRouteReference`, a catalog query and a checkout mutation driven through `createServiceClient` → `createServiceQueryUtils` in a Fresh island. The typed contract, honored all the way to the button.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)

[7 · Deploy  Run the whole storefront locally under one `aspire start` — every service, plugin API, and background processor in one resource graph, observable from the dashboard. The local topology, not a cloud deployer.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

> One workspace, carried forward
>
> This is a tutorial track: state compounds. The
>
> my-shop/
>
> workspace you create in chapter 1 is the same one you finish in chapter 7 — each chapter begins by checking the project state the previous one left, and each "What you built" feeds the next chapter's objective. Work the chapters in order.

## Start the build

[Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)

After this track, keep building in **Build › [Services & SDK](https://rickylabs.github.io/netscript/services-sdk/)** — the guides and recipes there pick up where these chapters stop.

_Canonical: https://rickylabs.github.io/netscript/tutorials/storefront/_

---

# Scaffold the storefront

This is chapter 1 of the storefront track. Before you can sell anything you need a workspace on disk and a running system to grow it in. In this chapter you create `my-shop/` with the `netscript` CLI, tour what it generated, and bring the whole thing up under [Aspire](https://rickylabs.github.io/netscript/explanation/aspire/) — Postgres, the Redis cache, and an example service all running together behind one dashboard.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)
2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)
3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)
4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)
5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)
6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)
7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

## What you will build

By the end of this chapter you will have a real NetScript workspace named `my-shop/` on disk — with a shared `contracts/` workspace, a `products` service, a Fresh app, and a Postgres database — and you will have watched it boot under a single `aspire start`, with the Aspire dashboard live on `https://localhost:18888` and Postgres plus Redis reporting healthy.

## Before you begin

This is the first chapter, so the only prerequisites are a working local toolchain. You need:

- **[Deno](https://deno.com/) 2.x** on your `PATH` — check with `deno --version`.
- The **[Aspire CLI](https://aspire.dev)** — check with `aspire --version`. NetScript uses Aspire to provision your database and cache locally, so you never wire up Docker containers by hand.
- **Docker** running, so Aspire can start the Postgres and Redis containers. Confirm with `docker info` — it should print engine details, not a connection error.

Install the NetScript CLI from JSR once:

```sh
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11
```

Confirm it resolves and inspect the command groups:

```sh
netscript --help
```

You should see the public groups: `init`, `contract`, `db`, `deploy`, `generate`, `marketplace`, `plugin`, `service`, `ui:add`, and `ui:init`. If `netscript` is not found, make sure Deno's install directory (printed by `deno install`) is on your `PATH`, then open a fresh terminal.

> Prefer not to install globally?
>
> Run any command ad-hoc with
>
> deno x jsr:@netscript/cli@0.0.1-beta.11 <command>
>
> . The rest of this track assumes the installed
>
> netscript
>
> form.

## Step 1 — Preview the scaffold with a dry run

Before writing any files, ask the CLI what it *would* create. `--dry-run` plans the scaffold and prints the result without touching disk:

```sh
netscript init my-shop --dry-run
```

`netscript init` validates your options, then runs an ordered pipeline that lays down the project root, Aspire orchestration, the shared contracts workspace, a Fresh app, an empty plugin registry, and — when you ask for them — a database workspace and an example service. The dry run reports file and directory totals per phase, so you can see the project's shape before committing to it. A clean dry run is your green light to scaffold for real.

## Step 2 — Create the workspace

Scaffold `my-shop/` with an example service named `products` on port **3001** and a Postgres database, so you have something real to run and a place for the catalog you build next chapter:

```sh
netscript init my-shop --service --service-name products --service-port 3001 --db postgres
cd my-shop
```

This scaffolds `my-shop/`, formats the output with `deno fmt`, and initializes a git repository. On completion the CLI prints a **next steps** summary tailored to your options — keep it handy; the steps below mirror the common path.

This track uses Postgres, but the database is polyglot: swap `--db postgres` for `mysql`, `mssql`, or `sqlite` and the scaffold wires Prisma for that engine instead (sqlite is file-backed, with no Aspire container). Keep `--db postgres` to follow along.

A few `init` options you will reach for (run `netscript init --help` for the full list):

**Common netscript init options**

| Name | Type | Description |
| --- | --- | --- |
| `--service --service-name  --service-port ` | `flag group` | Include an example oRPC service on the given port. We use products on 3001. |
| `--db ` | `flag` | Scaffold a Prisma-backed database workspace. First-class engines: postgres (default for this track), mysql, mssql, sqlite. Omit or use --db none to skip database tooling. |
| `--no-aspire` | `flag` | Skip the Aspire orchestration files — you would then wire infrastructure yourself. Do NOT pass this for the track; we rely on aspire start. |
| `--editor ` | `flag` | Generate editor settings for the chosen editor. |
| `--dry-run` | `flag` | Plan the scaffold and print totals without writing any files. |

## Step 3 — Tour what you got

Open `my-shop/` and you will find this shape:

- my-shop/

  - apps/dashboard/ # Fresh frontend (defineFreshApp)
  - contracts/ # Shared oRPC contracts, versioned under versions/v1/
  - services/products/ # The example oRPC service (src/main.ts, router.ts, routers/)
  - plugins/ # Plugin registry + manifests — empty until chapter 4
  - database/ # Postgres workspace (Prisma schema + migrations) — initialized in chapter 2
  - tests/ # Workspace-level test suite scaffolded alongside the project
  - aspire/

    - apphost.mts # Entry point for aspire start
    - aspire.config.json # AppHost language + SDK pin
  - appsettings.json # Infrastructure config (Services / Databases / Persistent)
  - deno.json # Workspace root (members, tasks, dependency catalog)
  - netscript.config.ts # Framework config (defineConfig)

What each piece is for:

- **`contracts/`** — the typed seam between your services and any client. Contracts are oRPC + Zod, versioned under `versions/v1/`. Everything else derives its types from here. You add the cart contract here in [chapter 3](https://rickylabs.github.io/netscript/tutorials/storefront/03-cart-contracts/). See [Contracts & type flow](https://rickylabs.github.io/netscript/explanation/contracts/).
- **`services/products/`** — a working oRPC service. `src/main.ts` calls `defineService(...)`; handlers live under `src/routers/`. You make it a real catalog in [chapter 2](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/).
- **`apps/dashboard/`** — a Fresh app for your storefront UI, already wired to consume contracts. The [`@netscript/fresh`](https://rickylabs.github.io/netscript/web-layer/fresh-ui/) meta-framework powers it. This track stays on the backend, so you will not edit it.
- **`plugins/`** — where background capabilities (workers, sagas, triggers, streams) register. Empty until you add the sagas plugin in [chapter 4](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/).
- **`database/`** — the Postgres-backed database workspace: the Prisma schema and migrations that back `context.db` in your handlers. You initialize it in [chapter 2](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/) with `netscript db init`.
- **`tests/`** — the workspace-level test suite scaffolded alongside the project. Extend it as you add handlers and contracts.
- **`aspire/`** — the orchestrator. `aspire start` reads `apphost.mts` and starts every resource your app declares — Postgres, the Redis cache, your services — with one command.
- **`appsettings.json`** — the infrastructure manifest Aspire reads: which services, databases, and persistent resources to provision.
- **`netscript.config.ts`** — declares paths, plugins, logging, and database wiring via `defineConfig`. See the [config reference](https://rickylabs.github.io/netscript/reference/config/).

> Where is packages/?
>
> If you scaffolded from a checkout of the NetScript repo you may see a vendored
>
> packages/
>
> directory. A normal JSR install does not have one — your project pulls
>
> @netscript/*
>
> from the registry. Ignore
>
> packages/
>
> in this track.

## Step 4 — Bring up orchestration

This is the step that turns a folder of files into a running system — and the one most people miss. **Aspire provisions your database and cache; you do not start containers by hand, and you run it before any `netscript db` command.** Run it from the `aspire/` subfolder so the CLI finds `apphost.mts`:

```sh
cd aspire
aspire restore   # once per machine: restores the Aspire SDK modules into .aspire/
aspire start       # starts the AppHost and every declared resource
```

`aspire start` brings up the Postgres database, the Redis cache, and your `products` service together, then prints a URL and a one-time login token for the **Aspire dashboard**:

```
https://localhost:18888
```

The dashboard lists every resource (`postgres`, `redis`, your service), live console logs, and distributed traces. Leave `aspire start` running in this terminal — it is your storefront's control plane for the rest of the track.

> Aspire is step 2 — database commands need it running
>
> The Postgres container only exists while
>
> aspire start
>
> is up. So
>
> netscript db init
>
> ,
>
> db generate
>
> , and
>
> db seed
>
> must be run
>
> after
>
> Aspire has started — never before. You use them in
>
> chapter 2
>
> .

## Verify your progress

The example `products` service exposes a plain health endpoint. In a second terminal — leave `aspire start` going in the first — confirm the service answers on port **3001**:

```sh
curl http://localhost:3001/health
```

> Endpoints are HTTP/1.1 — HTTP/2 is opt-in
>
> You reach services over plaintext
>
> HTTP/1.1
>
> at
>
> http://localhost:3001
>
> — that is the default. HTTP/2 is opt-in and requires TLS: configure it with
>
> ServiceTlsOptions
>
> (or the
>
> NETSCRIPT_TLS_CERT_FILE
>
> /
>
> NETSCRIPT_TLS_KEY_FILE
>
> environment variables). See
>
> Aspire & the AppHost
>
> for the local-versus-deployed runtime model.

You should get a healthy JSON response. Then type-check the whole workspace from the project root to confirm the scaffold, contracts, and service all line up:

```sh
deno task check
```

A clean check, plus a healthy `curl`, means the scaffold is sound.

- [ ] `netscript --help` lists the public command groups.
- [ ] `my-shop/` exists with `contracts/`, `services/products/`, `database/`, and `aspire/`.
- [ ] `aspire start` is up; the dashboard at `https://localhost:18888` shows `postgres` and `redis` healthy.
- [ ] `curl http://localhost:3001/health` returns healthy JSON.
- [ ] `deno task check` passes with no errors.

> If something is not green
>
> Three quick checks cover most first-run snags: (1) is
>
> aspire start
>
> still up in its terminal, with
>
> postgres
>
> and
>
> redis
>
> healthy in the
>
> dashboard
>
> ? (2) is Docker running (
>
> docker info
>
> )? (3) did you
>
> cd aspire
>
> before
>
> aspire start
>
> , so it found
>
> apphost.mts
>
> ? A failed
>
> curl
>
> usually means the service has not finished starting — give it a few seconds and retry.

## What you built

A real NetScript workspace, `my-shop/`: a shared `contracts/` workspace, a `products` service, a Fresh app, and a Postgres database plus Redis cache — all orchestrated by Aspire and visible in one dashboard. Next, you turn that placeholder `products` service into a real, typed catalog.

[Storefront](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/) [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/storefront/01-scaffold/_

---

# A typed catalog service

In [chapter 1](https://rickylabs.github.io/netscript/tutorials/storefront/01-scaffold/) you scaffolded `my-shop/` and watched it boot under Aspire, with a `products` service answering on `:3001`. That service is not a placeholder — when you passed `--service --db postgres`, the scaffold generated a **complete, typed CRUD catalog**: a contract whose schemas come from your Prisma model, Prisma-backed handlers, and a `defineService` entry point. In this chapter you read what was generated, prove it does real work over its OpenAPI projection, and make one deliberate upgrade — turning a not-found into a typed `404`. By the end you will have seen NetScript's central idea on your own data: **the contract is the single source of truth**.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)
2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)
3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)
4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)
5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)
6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)
7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

## What you will build

You will initialize the Postgres database behind the generated `products` catalog, read the generated contract (a `createCrudContract` surface whose Zod schemas are **generated from Prisma**) and its Prisma-backed handlers, then `curl` the catalog over its OpenAPI projection: create a product, list it back, and watch the contract reject a malformed write with a typed `400` before any handler runs. Finally you make one authored change — upgrading `getById` from a generic `500` to a typed `404 NOT_FOUND` — and prove it with a curl.

## Before you begin

You should have finished [chapter 1](https://rickylabs.github.io/netscript/tutorials/storefront/01-scaffold/), so:

- `my-shop/` exists with `services/products/`, `contracts/`, and `database/` directories.
- `aspire start` is up from the `aspire/` folder, so the dashboard at [https://localhost:18888](https://localhost:18888) is live and Postgres is online.

With Aspire up, initialize the database so the catalog has real tables to read and write. Run these from the **workspace root** (a second terminal — leave `aspire start` going in the first):

```sh
netscript db init --name init   # create + apply the first migration
netscript db generate           # generate the Prisma client and @database/zod schemas
netscript db seed               # verifies the connection (SELECT 1) — the table starts empty
```

The scaffolded seed script only checks connectivity; it does **not** insert sample rows. Your `products` table starts empty — you will create your first product over the API further down, which is the direct way to prove the write path.

Confirm the service is reachable before you change anything:

```sh
curl http://localhost:3001/health
```

A healthy JSON response means the scaffolded `products` service is up on port **3001**.

> db commands need aspire starting first
>
> netscript db init / generate / seed
>
> reach the Postgres container
>
> through
>
> the running AppHost. If
>
> aspire start
>
> is not up, there is no database to migrate and these commands fail fast. Bring Aspire up first — always.

## Step 1 — Read the generated contract

Contracts are the typed seam between your service and every client. They live in `contracts/`, versioned under `versions/v1/`, and are built from [`@orpc/contract`](https://rickylabs.github.io/netscript/explanation/contracts/) routes plus [Zod](https://zod.dev) schemas. The key move for a database-backed service is that you do not hand-write the entity schema — it is **generated from your Prisma model** and re-exported from a `@database/zod` module, so the contract and the table can never drift. And you do not hand-roll the CRUD routes either: `createCrudContract` generates them from the schemas.

Open the generated `contracts/versions/v1/products.contract.ts` and read it:

```ts
// contracts/versions/v1/products.contract.ts (generated)
import { implement } from '@orpc/server';
import { baseContract } from '@netscript/contracts';
import { createCrudContract } from '@netscript/contracts/crud';
import { z } from 'zod';
import { ProductCreateInput, ProductSchema, ProductUpdateInput } from '@database/zod';

export const ProductsHealthSchemaV1 = z.object({
  status: z.enum(['healthy', 'unhealthy', 'degraded']).describe('Service health status'),
  service: z.string().describe('Service name'),
  version: z.string().describe('Service version'),
  timestamp: z.string().datetime().describe('ISO timestamp'),
  uptime: z.number().int().nonnegative().optional().describe('Uptime in seconds'),
});

// The entity and input schemas are GENERATED from Prisma — no hand-written shape to drift.
export const ProductsProductSchemaV1 = ProductSchema;
export const ProductsProductCreateInputSchemaV1 = ProductCreateInput;
export const ProductsProductUpdateInputSchemaV1 = ProductUpdateInput;

// createCrudContract builds list/getById/create/update/delete routes on baseContract.
export const ProductsCrudContractV1 = createCrudContract({
  resource: 'products',
  entitySchema: ProductsProductSchemaV1,
  createSchema: ProductsProductCreateInputSchemaV1,
  updateSchema: ProductsProductUpdateInputSchemaV1,
});

export const ProductsContractV1 = {
  health: {
    check: baseContract
      .route({ method: 'GET', path: '/products/health' })
      .output(ProductsHealthSchemaV1),
  },
  ...ProductsCrudContractV1,
};

// implement() turns the contract object into a `.handler()`-bindable surface.
export const ProductsV1 = implement(ProductsContractV1);
```

Three ideas carry the whole pattern:

1. **Schemas come from Prisma.** `ProductSchema`, `ProductCreateInput`, and `ProductUpdateInput` are generated into `@database/zod` from your `schema.prisma` (a `Product` with `id`, `name`, `createdAt`, `updatedAt`). They double as runtime validation and as the TypeScript types that flow everywhere else — change a column, `netscript db generate`, and every consumer re-type-checks.
2. **`createCrudContract` generates the standard five.** Given `resource`, `entitySchema`, `createSchema`, and `updateSchema`, it builds `list` (`GET /products`), `getById` (`GET /products/{id}`), `create` (`POST /products`), `update` (`PATCH /products/{id}`), and `delete` (`DELETE /products/{id}`) — every route built on `baseContract`, imported from `@netscript/contracts`, so each one inherits typed `NOT_FOUND`, `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `RATE_LIMITED`, and `SERVICE_UNAVAILABLE` errors for free.
3. **`implement(ProductsContractV1)`** produces `ProductsV1`, whose `.handler(...)` is now bound to the schemas above. Return the wrong shape and `deno task check` fails.

> Why a separate contracts/ workspace?
>
> Because your service
>
> and
>
> your Fresh app both import from the same
>
> @my-shop/contracts
>
> alias, there is exactly one definition of a "product". Change a field here and every consumer re-type-checks against it — see
>
> Contracts & type flow
>
> .

## Step 2 — Read the Prisma-backed handlers

A contract describes the shape; a handler supplies the behavior. Database-backed handlers need a Prisma client, and NetScript injects it through a **typed context**: `v1.products.$context<{ db }>()` declares the context shape, then each `.handler(...)` receives it as `context`. Open the generated `services/products/src/routers/v1.ts`:

```ts
// services/products/src/routers/v1.ts (generated, condensed)
import type { PrismaClient } from '@database';
import { v1 } from '@my-shop/contracts';

type ProductHandlerContext = { readonly db: PrismaClient };
const productsV1 = v1.products.$context<ProductHandlerContext>();

export const ProductsV1 = {
  // list is PAGE-BASED: input { page, limit, sortBy?, sortOrder }.
  list: productsV1.list.handler(async ({ input, context }) => {
    const skip = (input.page - 1) * input.limit;
    const [data, total] = await Promise.all([
      context.db.product.findMany({ skip, take: input.limit }),
      context.db.product.count(),
    ]);
    const totalPages = Math.ceil(total / input.limit);
    return {
      data,
      pagination: {
        page: input.page,
        limit: input.limit,
        total,
        totalPages,
        hasNext: input.page < totalPages,
        hasPrev: input.page > 1,
      },
    };
  }),

  getById: productsV1.getById.handler(async ({ input, context }) => {
    const record = await context.db.product.findUnique({ where: { id: input.id } });
    if (!record) throw new Error(`Product ${input.id} not found`); // ← upgraded in Step 3
    return record;
  }),

  create: productsV1.create.handler(async ({ input, context }) =>
    await context.db.product.create({ data: input })
  ),

  update: productsV1.update.handler(async ({ input, context }) =>
    await context.db.product.update({ where: { id: input.id }, data: input.data })
  ),

  delete: productsV1.delete.handler(async ({ input, context }) =>
    await context.db.product.delete({ where: { id: input.id } })
  ),
};
```

What is type-locked here, for free:

- `input` is already parsed and typed to the contract's input schema — you never re-validate it. `list` input is **page-based** (`{ page, limit, sortBy?, sortOrder }`, `page` 1-indexed), and its output is `{ data, pagination: { page, limit, total, totalPages, hasNext, hasPrev } }`. For `update`, `createCrudContract` shapes the input as `{ id, data }`, so the handler reads `input.id` and passes `input.data` straight through to Prisma.
- `context.db` is the Prisma client the service injects; `db.product.*` is the generated table API.
- Each handler's return value must satisfy the contract's output schema. Drop a field and `deno task check` rejects it.

Notice `getById` throws a **generic `Error`** when a row is missing. That surfaces to the client as a `500 INTERNAL_SERVER_ERROR` — technically wrong: a missing product is a client-addressable `404`, not a server fault. That is the one thing you improve next.

## Step 3 — Upgrade the not-found to a typed 404

Every `createCrudContract` route inherits the typed `NOT_FOUND` error from `baseContract`, and each handler receives an `errors` object with a constructor for it. Edit `getById` in `services/products/src/routers/v1.ts` to throw the typed error instead of a bare `Error`:

```ts
// services/products/src/routers/v1.ts — getById, upgraded
getById: productsV1.getById.handler(async ({ input, context, errors }) => {
  const record = await context.db.product.findUnique({ where: { id: input.id } });
  if (!record) throw errors.NOT_FOUND({ message: `Product ${input.id} not found` });
  return record;
}),
```

`errors.NOT_FOUND(...)` raises the contract's own typed error — the client now receives a `404` with a typed `{ code: 'NOT_FOUND', ... }` body instead of a generic `500` throw. This is the whole point of `baseContract`: the error vocabulary is part of the contract, so both sides agree on it.

The service router (`services/products/src/router.ts`) already aggregates these handlers and nests the generated `health` router under the `products` namespace — you do not need to touch it:

```ts
// services/products/src/router.ts (generated)
import { health } from './routers/health.ts';
import { ProductsV1 } from './routers/v1.ts';

export const v1 = { products: { ...ProductsV1, health } };
export const router = { v1 };
export type Router = typeof router;
```

## Step 4 — How it is served

The service entry point is `services/products/src/main.ts`. Because this service talks to the database, it passes a Prisma client through the `db` option — `defineService` then makes that client available as the handler `context.db` you read above:

```ts
// services/products/src/main.ts (generated)
import { defineService } from '@netscript/service';
import { db } from '@database';
import { router } from './router.ts';

const database = await db.getClient();

// One call wires CORS, request logging, OpenAPI, RPC, and health endpoints.
await defineService(router, {
  name: 'products',
  version: '1.0.0',
  port: parseInt(Deno.env.get('PORT') || '3001'),
  db: database,
  openapi: { title: 'Products API', description: 'products service' },
  debug: true,
});
```

> Where the port really comes from
>
> That
>
> parseInt(Deno.env.get('PORT') || '3001')
>
> is not the source of truth — it is the runtime read. Aspire
>
> injects
>
> PORT
>
> when it starts the service, and the typed
>
> services.products.port
>
> field in
>
> netscript.config.ts
>
> is what the scaffold uses to decide which port to inject. The
>
> '3001'
>
> fallback only applies when you run the entrypoint outside Aspire. So the env read stays (it is how the process receives its assigned port), but the number you would actually change lives in the typed config, not in this line.

`defineService(router, { … })` is the one-shot form the scaffold uses, and what you will reach for 99% of the time. NetScript also exposes a fluent `createService(router, { … })` builder when you need to control middleware order, attach auth, or run startup hooks — the [services capability](https://rickylabs.github.io/netscript/services-sdk/services/) compares them — but `defineService` covers a typical catalog. It exposes the same surface on port **3001**:

**products service endpoints (port 3001)**

| Name | Type | Description |
| --- | --- | --- |
| `/api/rpc/*` | `POST` | The typed oRPC surface. A typed client calls procedures (v1.products.list) under this prefix with end-to-end type safety. |
| `/api/products` | `GET / POST` | The OpenAPI/REST projection: GET lists (paginated), POST creates. getById/update/delete live at /api/products/{id}. |
| `/health` | `GET` | Liveness probe — the plain JSON health check you hit in chapter 1. |

## Verify your progress

If `aspire start` is orchestrating everything, the `products` service is already live on `:3001` with your upgraded handler. The REST projection mounts under the `/api` prefix (no `/v1` segment — that is the RPC namespace, not the URL). From a second terminal, first create a product, since the table started empty:

```sh
curl -X POST http://localhost:3001/api/products \
  -H 'content-type: application/json' \
  -d '{ "name": "Aeron Chair" }'
```

You get the created row back, with a numeric `id`. Now list the catalog — the output is page-shaped:

```sh
curl "http://localhost:3001/api/products?page=1&limit=10"
```

You should see `{ "data": [ … ], "pagination": { "page": 1, "limit": 10, "total": 1, … } }`, exactly the contract's `list` output. Prove the contract is doing real work — send a `create` with the required `name` missing and watch it get rejected before any handler runs:

```sh
curl -X POST http://localhost:3001/api/products \
  -H 'content-type: application/json' \
  -d '{}'
```

You get a `400` with `{ "code": "BAD_REQUEST", "message": "Input validation failed", ... }` — the framework's automatic input-validation gate, distinct from the handler-thrown `VALIDATION_ERROR` (`422`) you would raise for a semantic rule. Finally, prove your Step 3 upgrade: fetch an id that does not exist and confirm it is now a typed `404`, not a `500`:

```sh
curl -i http://localhost:3001/api/products/999999
```

You should see `HTTP/1.1 404` and a `{ "code": "NOT_FOUND", ... }` body. Then confirm the whole workspace still type-checks end to end:

```sh
deno task check
```

- [ ] `netscript db init / generate / seed` completed with Aspire up.
- [ ] `POST /api/products` creates a product; `GET /api/products` returns it under `data` with `pagination`.
- [ ] A `create` missing `name` returns `400 BAD_REQUEST` ("Input validation failed").
- [ ] `GET /api/products/999999` returns a typed `404 NOT_FOUND` — your Step 3 upgrade.
- [ ] `deno task check` passes — the handlers satisfy the generated output schemas.

> The RPC prefix is /api/rpc/*
>
> NetScript mounts the typed oRPC surface under
>
> /api/rpc/*
>
> ; the
>
> /api/products/*
>
> paths you curl'd are its OpenAPI projection under the
>
> /api
>
> prefix. A typed
>
> @orpc/client
>
> reads the base URL from the service, so you rarely type the RPC path by hand. See
>
> Contracts & type flow
>
> .

## What you built

- A read of the versioned **oRPC contract** the scaffold generated with `createCrudContract` from entity and input schemas **generated from Prisma** via `@database/zod` — `list`/`getById`/`create`/`update`/`delete`, with typed errors inherited from `baseContract`.
- Prisma-backed handlers bound with `v1.products.$context<{ db }>()` → `.handler(...)`, page-based `list`, and one authored upgrade: `getById` now raises `errors.NOT_FOUND(...)` for a missing row, turning a `500` into a typed `404`.
- A running catalog served by `defineService(router, { name, version, port, db, openapi })` on port **3001**, its OpenAPI projection at `/api/products` confirmed by `curl` and `deno task check`.

You own the contract-first, database-backed loop every NetScript service follows. Next you apply it to a domain that does **not** exist yet — a shopping cart — by designing its contract first.

[1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/) [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/_

---

# Cart, contract-first

In [chapter 2](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/) you read a typed catalog built around a contract that was largely generated from Prisma. Now you design a domain that does **not** exist yet — a shopping `cart` — the other way round: contract first, then everything else. You write the cart's procedures and schemas as the single source of truth, then derive a fully typed client from them without a codegen step. This is the discipline that makes the checkout saga in the next chapter safe to build.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)
2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)
3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)
4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)
5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)
6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)
7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

## What you will build

You will add a new `cart` contract under `contracts/versions/v1/` with `list` / `getById` / `create` / `update` procedures, Zod schemas for a cart and its line items, and typed errors inherited from `baseContract`. Then you will derive a typed `@orpc/client` from that contract and call it — proving that the contract alone, with no implementation written yet, is enough to give a client end-to-end type safety.

> Cart is a new domain — modeled on orders
>
> Be clear-eyed about what is happening: unlike
>
> products
>
> , there is no cart in the NetScript playground. You are designing a brand-new domain. To stay on proven ground, this chapter models the cart's contract on the playground's
>
> orders
>
> contract — same procedure set (
>
> list
>
> /
>
> getById
>
> /
>
> create
>
> /
>
> update
>
> ), same
>
> baseContract
>
> typed-error pattern. Where orders has a database table behind it, your cart schemas here are hand-authored Zod; you can generate them from Prisma later if you add a cart table.

## Before you begin

You should have finished [chapter 2](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/), so:

- `my-shop/` has a working `products` service on `:3001` and a `contracts/versions/v1/` directory with `products.contract.ts` in it.
- `aspire start` is up (the dashboard answers at [https://localhost:18888](https://localhost:18888)).

Confirm the contracts workspace is where you left it:

```sh
ls contracts/versions/v1/
```

You should see `products.contract.ts` among the files. The CLI will add `cart.contract.ts` next to it.

## Step 1 — Scaffold the cart contract

Let the CLI lay down the contract file and wire it into the version aggregate for you, exactly as the [Add a service](https://rickylabs.github.io/netscript/services-sdk/how-to/add-a-service/) recipe does. From the workspace root:

```sh
netscript contract add cart
```

This writes `contracts/versions/v1/cart.contract.ts` — a starter contract with example schemas and procedures — and regenerates `contracts/versions/v1/mod.ts` so the new contract is already exported and reachable as `v1.cart`. There is no `mod.ts` to hand-edit: the aggregate now imports both the plain `CartContractV1` and the implemented `CartV1`, re-exports the plain object, and adds `cart` to the `v1.*` map — the same `CartContractV1` (routes) → `CartV1` (implemented) convention the generated products contract uses.

Confirm the file landed:

```sh
ls contracts/versions/v1/
```

You now replace the scaffolded example with the cart's real shape.

## Step 2 — Define the cart schemas

A cart holds line items, each referencing a product by id with a quantity, plus a status. Open the scaffolded `contracts/versions/v1/cart.contract.ts` and replace its starter schemas with the ones below. The helpers (`positiveInt`, `nonNegativeInt`, the pagination schemas) and `baseContract` all come from the `@netscript/contracts` package — swap the scaffold's `oc`/`@orpc/contract` import for `baseContract` so every route inherits the shared typed errors, exactly as the playground's `orders` contract does:

```ts
// contracts/versions/v1/cart.contract.ts
import { z } from 'zod';
import { implement } from '@orpc/server';
import {
  baseContract,
  nonNegativeInt,
  OffsetPaginationQuerySchema,
  paginationLimit,
  paginationOffset,
  positiveInt,
} from '@netscript/contracts';

// A single line in a cart.
export const CartItemSchemaV1 = z.object({
  productId: positiveInt({ description: 'Product being added' }),
  quantity: z.number().int().positive().describe('How many'),
});

// The cart status lifecycle.
export const CartStatusSchemaV1 = z.enum(['open', 'checking_out', 'ordered', 'abandoned']);

// A cart, as returned by the API.
export const CartSchemaV1 = z.object({
  id: positiveInt({ description: 'Cart ID' }),
  customerId: z.string().min(1).describe('Owner of the cart'),
  status: CartStatusSchemaV1,
  items: z.array(CartItemSchemaV1).describe('Line items'),
  total: z.number().nonnegative().describe('Computed cart total'),
  createdAt: z.string().datetime(),
});

// Inputs the create/update procedures accept.
export const CreateCartSchemaV1 = z.object({
  customerId: z.string().min(1).describe('Owner of the cart'),
  items: z.array(CartItemSchemaV1).describe('Initial line items'),
});

export const UpdateCartSchemaV1 = z.object({
  id: positiveInt({ description: 'Cart ID to update' }),
  status: CartStatusSchemaV1.optional(),
  items: z.array(CartItemSchemaV1).optional().describe('Replaces existing items'),
});
```

These hand-authored schemas play the same role the generated `@database/zod` schemas played for products: they are both the runtime validators and the TypeScript types every consumer derives.

Now reduce the scaffolded `CartContractV1` to a single `baseContract` route — the paginated `list` — so the CLI has a `baseContract` builder to extend in the next step, and keep the trailing `implement()` call the scaffold generated:

```ts
// contracts/versions/v1/cart.contract.ts (continued)
export const CartContractV1 = {
  // List carts with pagination.
  list: baseContract
    .route({ method: 'GET', path: '/cart' })
    .input(OffsetPaginationQuerySchema.extend({ status: CartStatusSchemaV1.optional() }))
    .output(z.object({
      items: z.array(CartSchemaV1),
      total: nonNegativeInt({ description: 'Total count' }),
      limit: paginationLimit({ description: 'Results per page' }),
      offset: paginationOffset({ description: 'Current offset' }),
      hasMore: z.boolean(),
    })),
};

// implement() makes the contract `.handler()`-bindable — the same ProductsContractV1 → ProductsV1
// convention the generated products contract uses.
export const CartV1 = implement(CartContractV1);
```

## Step 3 — Add the remaining procedures

Add the rest of the cart's surface with the CLI rather than hand-editing the contract object. Each `contract add-route` call appends a typed route to `CartContractV1`, reusing the `baseContract` builder you seeded in Step 2, so every procedure inherits the typed errors (`NOT_FOUND`, `VALIDATION_ERROR`, …) you met in chapter 2:

```sh
netscript contract add-route cart getById \
  --method GET \
  --path /cart/{id} \
  --input "z.object({ id: positiveInt({ description: 'Cart ID' }) })" \
  --output "CartSchemaV1"

netscript contract add-route cart create \
  --method POST \
  --path /cart \
  --input "CreateCartSchemaV1" \
  --output "CartSchemaV1"

netscript contract add-route cart update \
  --method PATCH \
  --path /cart/{id} \
  --input "UpdateCartSchemaV1" \
  --output "CartSchemaV1"
```

Inspect the result — as source, or as machine-readable JSON:

```sh
netscript contract inspect cart
netscript contract inspect cart --json
```

The appended routes leave `CartContractV1` with the full surface; the equivalent source shape is:

```ts
// contracts/versions/v1/cart.contract.ts (CartContractV1, after the CLI additions)
export const CartContractV1 = {
  // List carts with pagination.
  list: baseContract
    .route({ method: 'GET', path: '/cart' })
    .input(OffsetPaginationQuerySchema.extend({ status: CartStatusSchemaV1.optional() }))
    .output(z.object({
      items: z.array(CartSchemaV1),
      total: nonNegativeInt({ description: 'Total count' }),
      limit: paginationLimit({ description: 'Results per page' }),
      offset: paginationOffset({ description: 'Current offset' }),
      hasMore: z.boolean(),
    })),

  // Fetch one cart. @throws NOT_FOUND when the id is unknown.
  getById: baseContract
    .route({ method: 'GET', path: '/cart/{id}' })
    .input(z.object({ id: positiveInt({ description: 'Cart ID' }) }))
    .output(CartSchemaV1),

  // Create a cart. @throws VALIDATION_ERROR when input is invalid.
  create: baseContract
    .route({ method: 'POST', path: '/cart' })
    .input(CreateCartSchemaV1)
    .output(CartSchemaV1),

  // Update status or items. @throws NOT_FOUND, VALIDATION_ERROR.
  update: baseContract
    .route({ method: 'PATCH', path: '/cart/{id}' })
    .input(UpdateCartSchemaV1)
    .output(CartSchemaV1),
};
```

The shape is intentionally the same as `products` and `orders`: a paginated `list`, a `getById` that can throw `NOT_FOUND`, a `create` that can throw `VALIDATION_ERROR`, and an `update`. Reusing the shape means anyone who has read one NetScript contract can read this one. The `v1.cart` entry the scaffold wired into `mod.ts` still points at the implemented `CartV1`, so these new procedures are reachable from both the `@my-shop/contracts` barrel and `@my-shop/contracts/versions/v1` with no extra wiring.

**The cart contract surface**

| Name | Type | Description |
| --- | --- | --- |
| `list` | `GET /cart` | List carts, optionally filtered by status. Returns items + total + pagination metadata. |
| `getById` | `GET /cart/{id}` | Fetch one cart by id. Throws the typed NOT_FOUND error when the id is unknown. |
| `create` | `POST /cart` | Open a new cart for a customer with initial items. Throws VALIDATION_ERROR on bad input. |
| `update` | `PATCH /cart/{id}` | Change cart status or replace items. The checkout saga (chapter 4) flips status to checking_out. |

## Step 4 — Derive a typed client

Here is the payoff of contract-first: a client needs **only the contract** to be fully typed — no running server, no generated SDK, no hand-written request types. The typed-client packages are not in the scaffold's import map, so add them once:

```sh
deno add npm:@orpc/client npm:@orpc/openapi-client
```

Then create a small script to prove it:

```ts
// scripts/cart-client.ts
import { createORPCClient } from '@orpc/client';
import { OpenAPILink } from '@orpc/openapi-client/fetch';
import { CartContractV1 } from '@my-shop/contracts/versions/v1';

// The client's type comes entirely from the contract. The REST projection is under /api.
const link = new OpenAPILink(CartContractV1, { url: 'http://localhost:3001/api' });
const client = createORPCClient<typeof CartContractV1>(link);

// `created` is typed as CartSchemaV1 — the editor knows its fields before you run anything.
const created = await client.create({
  customerId: 'cust_1001',
  items: [{ productId: 1, quantity: 2 }],
});

console.log(created.status, created.total);
```

Even with no cart service implemented yet, your editor types `created.status` as the `CartStatusSchemaV1` union and `created.items` as `CartItemSchemaV1[]`. Pass the wrong shape to `client.create(...)` and it is a compile error — the contract is enforcing the boundary from both sides.

> Implementing the cart is the same loop as chapter 2
>
> This chapter stops at the contract and a typed client on purpose — the point is the design discipline. When you want a running cart service, the implementation is the exact same loop products used:
>
> v1.cart.$context<{ db }>()
>
> , bind
>
> .handler(...)
>
> functions, aggregate into a router, and serve with
>
> defineService(...)
>
> . See
>
> chapter 2
>
> .

## Verify your progress

The contract is code, so the real verification is that it type-checks and that the typed client compiles against it. From the workspace root:

```sh
deno task check
```

A clean check proves the cart schemas, routes, and the CLI-generated `mod.ts` registration all line up, and that the typed client in `scripts/cart-client.ts` is consistent with `CartContractV1`.

- [ ] `contracts/versions/v1/cart.contract.ts` exists with `list` / `getById` / `create` / `update`.
- [ ] Every route is built from `baseContract`, so it carries the shared typed errors.
- [ ] `netscript contract inspect cart` lists all four procedures.
- [ ] `CartV1` is wired into `contracts/versions/v1/mod.ts` and reachable as `v1.cart`.
- [ ] The typed client in `scripts/cart-client.ts` compiles — `created` is typed without a running server.
- [ ] `deno task check` passes.

## What you built

- A brand-new `cart` domain defined **contract-first** — schemas, a `list` / `getById` / `create` / `update` procedure set, and `baseContract` typed errors — modeled on the playground's `orders` contract.
- The contract scaffolded and its procedures added with `netscript contract add` / `contract add-route`, which regenerated `contracts/versions/v1/mod.ts` following the `CartContractV1` (routes) → `CartV1` (implemented) convention — reachable as `v1.cart` from the `@my-shop/contracts` barrel and the `@my-shop/contracts/versions/v1` subpath, with no hand-wiring.
- A typed `@orpc/client` derived from the contract alone, fully type-locked with no codegen.

You now have a cart whose every interaction is described by a contract. In the next chapter that contract becomes the input to the riskiest part of any shop — **checkout** — which you make reliable with a durable saga.

[2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/) [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/storefront/03-cart-contracts/_

---

# Durable checkout

In [chapter 3](https://rickylabs.github.io/netscript/tutorials/storefront/03-cart-contracts/) you designed the cart contract. Checkout is what turns a cart into an order — and it is the one place in a shop where a crash mid-flight costs real money. A naive `async` function that charges a card, reserves inventory, then books shipment is a liability: if the process dies after the charge but before the reservation, you have taken money and shipped nothing. This chapter rebuilds checkout as a **durable saga** — a state machine that checkpoints its progress, reacts to payment and inventory messages, and runs a **compensation** path when a step fails.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)
2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)
3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)
4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)
5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)
6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)
7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

## What you will build

You will add the runtime plugins checkout depends on, then author a `CheckoutSaga` with `defineSaga(...)`: typed per-instance state, a correlation key, and message handlers that walk a checkout from `OrderCreated` through payment toward fulfillment. You will also author the `process-payment` worker job that the saga drives, and you will wire the **failure path** so a declined payment cancels the order instead of stranding it. By the end you can drive a checkout to a **paid** order and watch a failed payment **compensate to cancelled** — both observable on the Sagas API at `:8092`.

## Before you begin

You should have finished [chapter 3](https://rickylabs.github.io/netscript/tutorials/storefront/03-cart-contracts/), so:

- `my-shop/` has the `products` service and the `cart` contract.
- `aspire start` is up (the dashboard answers at [https://localhost:18888](https://localhost:18888)). The saga registry and durable instance store both depend on Aspire-managed resources — Deno KV for the registry, and either KV or Postgres for instance state.

> Aspire must already be running
>
> The Sagas API service and its KV-backed registry come up as part of the orchestrated app. If you closed your
>
> aspire start
>
> terminal, restart it from the
>
> aspire/
>
> folder (
>
> cd aspire && aspire start
>
> )
>
> before
>
> running any
>
> netscript
>
> command in this chapter — the durable store and registry only exist while Aspire is up.

## Step 1 — Add the checkout runtime plugins

Checkout spans three official runtime plugins, and you install each one explicitly: **`sagas`** (the durable workflow), **`workers`** (the background jobs the saga drives), and **`streams`** (the durable transport that carries messages between them). Add them from the project root, with samples so you have working modules to adapt:

```sh
netscript plugin install worker --name workers --samples
netscript plugin install saga --name sagas --samples
netscript plugin install stream --name streams --samples
```

Each plugin lands at its canonical location (**`plugins/sagas/`**, `plugins/workers/`, `plugins/streams/`), and `netscript.config.ts` is updated to reference each `mod.ts`. A slimmer top-level staging copy (e.g. `sagas/`) is also created for the background processor — you author against `plugins/<name>/`.

Confirm they registered:

```sh
netscript plugin list
```

You should see `workers`, `sagas`, and `streams` in the list.

## Step 2 — Read the saga builder

NetScript sagas are authored with a **fluent builder** imported from `@netscript/plugin-sagas-core`. Each call narrows the saga's type and configuration; `.build()` produces the definition the runtime consumes. The methods you will use:

**SagaBuilder methods (from @netscript/plugin-sagas-core)**

| Name | Type | Description |
| --- | --- | --- |
| `defineSaga(id)` | `start the chain` | Begins a saga definition with a stable id used in the registry and instance keys. |
| `.durability(tier)` | `persistence tier` | Selects the durability tier (defaults to T1). The persisted tier checkpoints instance state so an in-flight workflow survives a restart. |
| `.state(initial)` | `per-instance state` | Declares the state shape and its initial value. Every correlated instance gets its own copy. Must come before any handler. |
| `.correlate(fn)` | `instance routing` | Extracts the correlation key from an incoming message so it reaches the right instance — e.g. correlate by orderId. |
| `.on(type, handler)` | `message handler` | Subscribes to a message type. The handler reads state + message and returns an array of effects. |
| `.compensate(type, handler)` | `compensation handler` | Registers a handler for a FAILED event type — the undo path. Same shape as .on(), reserved for compensation. |
| `.build()` | `finalize` | Produces the frozen SagaDefinition the runner executes. Requires at least one handler. |

The other primitive you need is **`send(target, payload)`** — also from `@netscript/plugin-sagas-core` — which a handler returns to drive the next step: it sends a command (to a worker job) or emits an event. Handlers return an **array** of these effects.

## Step 3 — Scaffold the checkout saga

Start with the saga definition and config scaffold:

The `add-saga` verb uses the spaced `add saga` shell syntax:

> ns-sagas is a shorthand you install once
>
> ns-sagas
>
> is a name
>
> you
>
> give the sagas plugin's CLI — the scaffold does not create it. Install it once, globally, and every
>
> ns-sagas
>
> command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-sagas jsr:@netscript/plugin-sagas@0.0.1-beta.11/cli
> ```
>
> Rather not install it? Each
>
> ns-sagas <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-sagas@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```sh
ns-sagas add saga checkout --message-type=OrderCreated --durability=t1 --topic=checkout
```

The command writes `sagas/checkout-saga.ts` plus `sagas/checkout.config.ts`, including a normal handler and a compensation-handler skeleton, and refreshes the saga registry. Extend that generated definition with the checkout state and lifecycle below. It correlates by `orderId`, starts `pending`, and walks the lifecycle. Crucially, it has explicit **failure branches**: if payment fails or inventory is unavailable, it transitions to `cancelled` and emits a cancellation — this is compensation.

```ts
// sagas/checkout-saga.ts
import { defineSaga, send } from '@netscript/plugin-sagas-core';
import type { SagaState } from '@netscript/plugin-sagas-core/domain';

type OrderStatus =
  | 'pending'
  | 'payment_pending'
  | 'paid'
  | 'inventory_reserved'
  | 'shipped'
  | 'completed'
  | 'cancelled';

// Per-instance checkout state. Runtime metadata is handled for you.
interface CheckoutState extends SagaState {
  orderId: string;
  customerId: string;
  status: OrderStatus;
  items: Array<{ productId: string; quantity: number }>;
  total: number;
  transactionId?: string;
  cancelReason?: string;
}

const initialState: CheckoutState = {
  orderId: '',
  customerId: '',
  status: 'pending',
  items: [],
  total: 0,
};

export const checkoutSaga = defineSaga('CheckoutSaga')
  .state(initialState)
  // Route every message to the instance whose orderId matches.
  .correlate((message) => String((message.payload as { orderId?: string }).orderId ?? ''))

  // OrderCreated → charge the card via the process-payment worker job.
  .on('OrderCreated', (saga, event) => {
    const msg = event.payload as { orderId: string; customerId: string; items: CheckoutState['items']; total: number };
    saga.state = {
      ...saga.state,
      orderId: msg.orderId,
      customerId: msg.customerId,
      items: msg.items,
      total: msg.total,
      status: 'payment_pending',
    };
    return [send('process-payment', { orderId: msg.orderId, amount: msg.total })];
  })

  // PaymentCompleted → reserve inventory.
  .on('PaymentCompleted', (saga, event) => {
    if (saga.state.status !== 'payment_pending') return [];
    const msg = event.payload as { transactionId: string };
    saga.state = { ...saga.state, status: 'paid', transactionId: msg.transactionId };
    return [send('reserve-inventory', { orderId: saga.state.orderId, items: saga.state.items })];
  })

  // InventoryReserved → book shipment.
  .on('InventoryReserved', (saga) => {
    if (saga.state.status !== 'paid') return [];
    saga.state = { ...saga.state, status: 'inventory_reserved' };
    return [send('create-shipment', { orderId: saga.state.orderId })];
  })

  // ShipmentCreated → done.
  .on('ShipmentCreated', (saga) => {
    if (saga.state.status !== 'inventory_reserved') return [];
    saga.state = { ...saga.state, status: 'completed' };
    return [];
  })

  // === Compensation: PaymentFailed → cancel the order. ===
  .compensate('PaymentFailed', (saga, event) => {
    if (saga.state.status !== 'payment_pending') return [];
    const msg = event.payload as { reason: string };
    saga.state = { ...saga.state, status: 'cancelled', cancelReason: `Payment failed: ${msg.reason}` };
    return [send('OrderCancelled', { orderId: saga.state.orderId, reason: msg.reason })];
  })

  .build();

export default checkoutSaga;
```

Read the shape, not the line count:

- **State is a typed state machine.** `status` is a union; every handler guards on it (`if (saga.state.status !== 'paid') return []`) so a redelivered or out-of-order message is a no-op, not a corruption. [Durable workflows are state machines](https://rickylabs.github.io/netscript/explanation/durability-model/) is a NetScript axiom, not a slogan.
- **Steps are driven by `send(...)` effects.** A handler does not call the payment service directly — it returns `send('process-payment', { … })`, and the runtime delivers that command to the worker job. This is what lets the workflow be paused, checkpointed, and resumed.
- **Compensation is a failure branch.** The `PaymentFailed` handler is the undo path: it transitions the same state machine to `cancelled` and emits `OrderCancelled`. The scaffolded order saga in the playground models compensation exactly this way — as failure-event handlers that walk the state machine backward.

> Two ways to express compensation
>
> The builder also exposes a dedicated
>
> .compensate(eventType, handler)
>
> method — same handler shape as
>
> .on()
>
> , but registered as the compensation path for a failed event type. You can write
>
> .compensate('PaymentFailed', ...)
>
> instead of an
>
> .on('PaymentFailed', ...)
>
> branch to make the undo intent explicit in the chain. The playground's order saga uses plain
>
> .on()
>
> failure handlers; both compile and both run. Choose the one that reads clearest for your team — see
>
> Durability model
>
> .

## Step 4 — Author the payment worker job

The saga `send`s a `process-payment` command; a **worker job** is what actually does the work and reports back. The job processes the payment, then publishes `PaymentCompleted` (or `PaymentFailed`) back to the saga. This is the half of the choreography that closes the loop.

```ts
// workers/jobs/process-payment.ts
import {
  createFailureResult,
  createSuccessResult,
  defineJobHandler,
} from '@netscript/plugin-workers-core';
import { createSagaPublisher } from '@netscript/plugin-sagas/runtime';
import { z } from 'zod';
import type { OrderSagaMessage } from '../saga-message-types.ts';

// Publishes results back to the saga bus.
const sagaPublisher = createSagaPublisher<OrderSagaMessage>();

const PayloadSchema = z.object({
  orderId: z.string().min(1),
  amount: z.number().positive(),
});

const handler = defineJobHandler(async (ctx) => {
  const { orderId, amount } = PayloadSchema.parse(ctx.payload ?? {});

  try {
    // ... charge the card via your provider (mock here) ...
    const transactionId = `txn_${Date.now()}`;

    // Tell the saga payment succeeded — it advances to inventory.
    await sagaPublisher.publish({ type: 'PaymentCompleted', payload: { orderId, transactionId } });

    return createSuccessResult({ orderId, transactionId, amount });
  } catch (error) {
    const reason = error instanceof Error ? error.message : String(error);

    // Tell the saga payment failed — its compensation branch cancels the order.
    await sagaPublisher.publish({ type: 'PaymentFailed', payload: { orderId, reason } });

    return createFailureResult(`${reason} (orderId: ${orderId})`);
  }
});

export default Object.assign(handler, { id: 'process-payment' });
```

The contract between the two halves is the **message type string**. The job publishes `PaymentCompleted` / `PaymentFailed`; the saga `.on('PaymentCompleted', …)` and `.on('PaymentFailed', …)` listen for exactly those. There is no shared function call — they are isolated background processors joined only by the message traveling through the streams transport. Keep the strings identical on both sides.

**Worker job primitives (from @netscript/plugin-workers-core)**

| Name | Type | Description |
| --- | --- | --- |
| `defineJobHandler(fn)` | `define a job` | Wraps an async handler that receives a typed ctx (payload, logging, tracing) and returns a result. |
| `createSuccessResult(data)` | `success` | The handler's return for a completed job; carries result data. |
| `createFailureResult(reason)` | `failure` | The handler's return for a failed job; the message string is recorded on the execution. |
| `createSagaPublisher()` | `from @netscript/plugin-sagas/runtime` | Publishes typed messages onto the saga bus so a running saga can react — how the job reports back. |

## Step 5 — Type-check the workflow

The Sagas API service lists sagas from a KV-backed registry, and the scaffold's saga runtime registers your built definition on startup. Because `aspire start` already brings the sagas processor and API up together, you do not start anything by hand — your saga is picked up when the orchestrated app (re)starts. First, prove it compiles against the builder's generic signatures:

```sh
deno task check
```

A clean check means `defineSaga`, `.state()`, `.correlate()`, `.on()`, and `.build()` all line up with the message and state types you declared, and that the worker job's publish calls match the saga message types.

## Verify your progress

With Aspire up, confirm the saga registered through the **Sagas API on `:8092`**:

```sh
ns-sagas list --registered --json
```

You should see `CheckoutSaga` in the list, with `OrderCreated`, `PaymentCompleted`, and `PaymentFailed` among its handled message types. Now drive an instance directly by publishing messages to the saga bus — `ns-sagas publish` sends `{ type, payload }`, and the saga correlates on `payload.orderId`. Start an order, then complete its payment:

```sh
# 1. Open the checkout — instance goes to payment_pending and sends process-payment.
ns-sagas publish OrderCreated \
  --payload='{ "orderId": "ord_1001", "customerId": "cust_1001", "items": [{ "productId": "1", "quantity": 2 }], "total": 4999 }' \
  --correlation-key=ord_1001

# 2. Payment succeeds — instance advances to paid, carrying its transactionId.
ns-sagas publish PaymentCompleted \
  --payload='{ "orderId": "ord_1001", "transactionId": "txn_777" }' \
  --correlation-key=ord_1001
```

Inspect that instance and confirm it reached `paid`:

```sh
ns-sagas list --instances --saga=CheckoutSaga --json
```

Now prove **compensation**. Open a second order and fail its payment — the `PaymentFailed` branch walks the state machine to `cancelled`:

```sh
ns-sagas publish OrderCreated \
  --payload='{ "orderId": "ord_2002", "customerId": "cust_2002", "items": [{ "productId": "1", "quantity": 1 }], "total": 1999 }' \
  --correlation-key=ord_2002

ns-sagas publish PaymentFailed \
  --payload='{ "orderId": "ord_2002", "reason": "card_declined" }' \
  --correlation-key=ord_2002

ns-sagas list --instances --saga=CheckoutSaga --json
```

The first instance shows `status: 'paid'` carrying its `transactionId`; the second shows `status: 'cancelled'` carrying the `cancelReason` your compensation branch stamped. (The forward path continues to `completed` once you also author the `reserve-inventory` and `create-shipment` jobs the saga `send`s — this track stops at the payment leg, so `paid` is checkout's observable checkpoint.)

- [ ] `netscript plugin install worker/saga/stream ... --samples` landed `plugins/workers/`, `plugins/sagas/`, and `plugins/streams/`.
- [ ] `checkout-saga.ts` defines state, a correlation key, the forward handlers, and a `PaymentFailed` compensation branch.
- [ ] `workers/jobs/process-payment.ts` publishes `PaymentCompleted` / `PaymentFailed` back to the saga.
- [ ] `ns-sagas list --registered --json` lists `CheckoutSaga`.
- [ ] Publishing `OrderCreated` + `PaymentCompleted` yields an instance at `status: 'paid'`; `PaymentFailed` yields one at `status: 'cancelled'`.
- [ ] `deno task check` passes.

> Durability is not free correctness
>
> The durability tier persists instance state so a workflow survives a restart, but it does
>
> not
>
> dedupe inbound messages for you. That is why every handler above guards on
>
> saga.state.status
>
> before acting — a redelivered
>
> PaymentCompleted
>
> must not charge twice or double-advance. Make handlers idempotent; durability remembers state, it does not deduplicate delivery.

## What you built

- The `workers`, `sagas`, and `streams` runtime plugins, each installed explicitly with `netscript plugin install <kind> --name <name> --samples` — the workflow, its jobs, and the transport between them.
- A `CheckoutSaga` built with `defineSaga().state().correlate().on().build()` — a durable state machine that walks order → payment → fulfillment, with a `PaymentFailed` **compensation branch** that cancels the order.
- A `process-payment` worker job (`defineJobHandler`, `createSuccessResult` / `createFailureResult`) that publishes results back to the saga with `createSagaPublisher`, closing the choreography.
- A workflow observable as instances on the Sagas API at `:8092`.

Checkout is now reliable: it survives restarts and undoes itself on failure. The last piece is letting the outside world — a shipping or payment provider — tell your shop what happened, which you do with a verified webhook next.

[3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/) [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/_

---

# A verified shipping webhook

In [chapter 4](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/) your checkout saga `send`s a `create-shipment` command and waits for a `ShipmentCreated` message. But the real signal that a parcel shipped comes from *outside* your shop — from a carrier or payment provider posting a webhook. This chapter adds that ingress: an HMAC-verified webhook endpoint that the provider `POST`s to, which hands each inbound event straight to a background job. Triggers are how NetScript receives events from the world.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)
2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)
3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)
4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)
5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)
6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)
7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

## What you will build

You will add the `triggers` plugin, then author a webhook with `defineWebhook(...)` that is **HMAC-SHA256 verified** against a shared secret and, on each accepted request, `enqueueJob(...)`s a worker job to process the shipping update off the request path. You will start the triggers API on `:8093` and `POST` a real payload to it, watching the inbound event get recorded and the job enqueued.

## Before you begin

You should have finished [chapter 4](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/), so:

- `my-shop/` has the `products` service, the `cart` contract, and the `sagas` plugin with your `CheckoutSaga` and the `process-payment` worker job.
- `aspire start` is up (the dashboard answers at [https://localhost:18888](https://localhost:18888)). The triggers processor and its job hand-off depend on Deno KV and the workers runtime, so Aspire must be up before you start.

Confirm the plugins you have so far:

```sh
netscript plugin list
```

You should see `workers`, `sagas`, and `streams` from the previous chapter. You will add `triggers` next.

## Step 1 — Add the triggers plugin

From the project root, add the official triggers plugin with its sample modules:

```sh
netscript plugin install trigger --name triggers --samples
```

This command lands a new workspace at `plugins/triggers/` and registers it in `netscript.config.ts` (`./plugins/triggers/mod.ts`) and `appsettings.json`. The `--samples` flag also drops in working webhook modules and a small `jobs/` folder you can study. Confirm it registered:

```sh
netscript plugin list
```

You should now see `triggers` alongside `sagas`.

> Where the plugin really lives
>
> The canonical install is
>
> plugins/triggers/
>
> — the path
>
> netscript.config.ts
>
> points at. You may also see a slimmer top-level
>
> triggers/
>
> staging copy; author and read your webhooks under
>
> plugins/triggers/
>
> .

## Step 2 — Author the shipping-update job and the verified webhook

The webhook hands each inbound event to a background job, so scaffold that job first:

> ns-workers / ns-triggers are shorthands you install once
>
> ns-workers
>
> and
>
> ns-triggers
>
> are names
>
> you
>
> give the workers and triggers plugin CLIs — the scaffold does not create them. Install them once, globally, and every shorthand command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> deno install -gArf -n ns-triggers jsr:@netscript/plugin-triggers@0.0.1-beta.11/cli
> ```
>
> Rather not install them? Each
>
> ns-<plugin> <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-<plugin>@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```sh
ns-workers add job process-shipping-update
```

Extend the generated payload schema with `orderId`, `status`, and `trackingNumber`, then replace the starter handler body with the validation and application logic. A real integration would advance the order; here it validates and records the update:

```ts
// workers/jobs/process-shipping-update.ts
import { createSuccessResult, defineJobHandler } from '@netscript/plugin-workers-core';
import { z } from 'zod';

const PayloadSchema = z.object({
  orderId: z.string().min(1),
  status: z.string().min(1),
  trackingNumber: z.string().optional(),
});

const handler = defineJobHandler(async (ctx) => {
  const update = PayloadSchema.parse(ctx.payload ?? {});
  // ... advance the order / notify the customer ...
  return createSuccessResult(update);
});

export default Object.assign(handler, { id: 'process-shipping-update' });
```

Scaffold the webhook and its worker-job action with the triggers CLI first:

The `add-webhook` verb uses the spaced `add webhook` shell syntax:

```bash
ns-triggers add webhook shipping-status-webhook \
  --path=shipping/status \
  --job=process-shipping-update \
  --verifier=hmac-sha256 \
  --secret-env=WEBHOOK_SHIPPING_SECRET \
  --description="Receives carrier shipping-status callbacks and enqueues a processing job." \
  --tags=webhook,shipping,saga
```

The command writes `triggers/shipping-status-webhook-trigger.ts` and recompiles the generated trigger registry. The generated definition uses `defineWebhook(handler, spec)` from `@netscript/plugin-triggers-core/builders`: the handler resolves to an **array of effects**, and the spec names the webhook and — for a real provider callback — declares HMAC verification so forged requests are rejected before your handler runs. The job reference is an inline object typed with `satisfies JobDefinition` — no helper needed. Its relevant shape is:

```ts
// triggers/shipping-status-webhook-trigger.ts
import { defineWebhook, enqueueJob } from '@netscript/plugin-triggers-core/builders';
import type { JobDefinition } from '@netscript/plugin-workers-core';

// A typed reference to the worker job authored above.
const processShippingJob = {
  id: 'process-shipping-update' as JobDefinition<'process-shipping-update'>['id'],
  name: 'Process Shipping Update',
  topic: 'default',
} satisfies JobDefinition<'process-shipping-update'>;

export default defineWebhook(
  // The handler returns effects. Here: enqueue one job with the inbound payload.
  (event) => Promise.resolve([enqueueJob(processShippingJob, { payload: event.payload })]),
  {
    id: 'shipping-status-webhook',
    path: 'shipping/status',
    verifier: 'hmac-sha256',
    secretEnv: 'WEBHOOK_SHIPPING_SECRET',
    description: 'Receives carrier shipping-status callbacks and enqueues a processing job.',
    tags: ['webhook', 'shipping', 'saga'],
    metadata: {
      direction: 'inbound',
      pipeline: 'shipment-fulfillment',
      provider: 'carrier',
    },
  },
);
```

Three things to read off this:

- **`defineWebhook(handler, spec)`** takes the handler first, then the static spec. The handler resolves to an **array of effects** — return a `Promise` of the effect array (never a bare `function`-keyword declaration).
- **`verifier: 'hmac-sha256'` + `secretEnv`** is the security seam. The triggers ingress verifies the request's HMAC signature against the secret named by `secretEnv` (here `WEBHOOK_SHIPPING_SECRET`) *before* your handler is invoked. A request that fails verification never reaches your code. For local experiments you can use `verifier: 'memory'` (the open, no-signature verifier), but a real provider callback should be `hmac-sha256`.
- **`enqueueJob(jobRef, { payload })`** is the effect that bridges to the worker system. Each effect the handler returns is applied after the request is accepted; this one enqueues the `process-shipping-update` job with the verified inbound payload.

**defineWebhook spec fields**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable identifier for the webhook in the registry. |
| `path` | `string` | URL segment the router mounts it under — here shipping/status, reached at /api/v1/webhooks/shipping/status. |
| `verifier` | `'hmac-sha256' \| 'memory' \| string` | Signature verifier. hmac-sha256 checks the request HMAC against secretEnv; memory is the open local-dev verifier. |
| `secretEnv` | `string (optional)` | Name of the env var holding the shared secret used by the hmac-sha256 verifier. |
| `tags / metadata` | `optional` | Discovery metadata — not behavior. Useful for grouping and dashboards. |

> An effect array, not a response body
>
> A webhook handler does not write an HTTP response itself — it returns the
>
> effects
>
> to run. Returning
>
> []
>
> accepts the request but enqueues nothing; returning one or more
>
> enqueueJob(...)
>
> entries hands that many jobs to the workers runtime. This keeps inbound HTTP thin and pushes the real work onto the durable background queue.

## Step 3 — Know which trigger actions are supported

A handler returns an array of **trigger actions** (effects). Be precise about which ones the runtime actually dispatches today, so you do not author against a stub:

**Trigger actions**

| Name | Type | Description |
| --- | --- | --- |
| `enqueueJob(jobRef, opts)` | `Live` | Places a worker job on the queue. The supported way to turn an inbound event into durable background work. |
| `defer({ until })` | `Defined, not yet supported` | The action type exists in the builder surface, but the runtime processor throws on dispatch and routes the event to the dead-letter queue. There is no deferred replay yet — do not rely on it. |

In other words: build with `enqueueJob(...)`. If you return a `defer(...)` action, the trigger runtime raises an unsupported-operation error and the event lands in the DLQ rather than being scheduled — reach for the scheduling features of the [triggers capability](https://rickylabs.github.io/netscript/durable-workflows/triggers/) (cron and file-watch triggers) when you need time-based work, not `defer`.

## Step 4 — Route shape (raw webhook ingress)

The triggers service serves a typed v1 oRPC contract for trigger and event introspection plus management, but the **webhook ingress endpoint** is deliberately a **raw route**, not an oRPC procedure. Webhooks come from third parties posting plain JSON to a fixed path, and the endpoint must verify an HMAC signature over the raw request bytes, so a typed contract would buy nothing. The ingress handler resolves a `POST /:triggerId` path: a request to `/api/v1/webhooks/shipping/status` resolves `:triggerId` to `shipping/status`, which matches the `path` on your webhook — so the handler runs and its effects are applied.

> Why the webhook ingress endpoint stays a raw route
>
> oRPC gives the rest of the triggers surface a typed contract shared with its clients. Webhooks have no NetScript client — the sender is a third party — so the ingress endpoint stays an ordinary, signature-verifying route you can point any webhook source at. See
>
> the triggers capability
>
> for verifiers, scheduling, and file-watch triggers.

## Step 5 — Set the secret and start the triggers service

The `hmac-sha256` verifier needs its secret in the environment. Set it before starting the service (use the same value when you sign your test request):

```sh
export WEBHOOK_SHIPPING_SECRET=dev-shipping-secret
```

If `aspire start` is up it orchestrates the triggers API and its background processor for you (look for the `triggers-api` and `triggers` resources in the [dashboard](https://localhost:18888)). To run the API on its own during development, start it from the plugin workspace:

```sh
deno task --cwd plugins/triggers dev
```

The triggers API listens on port **`:8093`** by default. Confirm it is alive:

```sh
curl http://localhost:8093/health
```

## Verify your progress

Send an inbound request to your webhook's path. Because the webhook is `hmac-sha256`-verified, a real sender includes an **`x-hub-signature-256`** header — a hex HMAC-SHA256 of the raw body under the shared secret (optionally `sha256=`-prefixed); the carrier's dashboard computes it for you. For a quick local smoke, flip `verifier` to `'memory'` (the open, no-signature verifier) so a bare `POST` is accepted; switch back to `'hmac-sha256'` for anything real. With verification satisfied:

```sh
curl -X POST http://localhost:8093/api/v1/webhooks/shipping/status \
  -H "content-type: application/json" \
  -d '{"orderId":"ord_1001","status":"shipped","trackingNumber":"1Z999"}'
```

An accepted request returns **`202`**.

The request resolves the trigger id `shipping/status`, your handler runs, and its single `enqueueJob(...)` effect places the `process-shipping-update` job on the workers queue. Confirm both sides of the hand-off:

```sh
# 1. The trigger recorded the inbound event (Hono, :8093)
curl "http://localhost:8093/api/v1/events?limit=10"

# 2. The worker job it enqueued has executed (workers API, :8091)
ns-workers executions --limit=10 --json
```

You should see the inbound event listed by the triggers events endpoint and a fresh execution of `process-shipping-update` in the workers executions list. One verified webhook hit, handed off to a durable job.

- [ ] `netscript plugin install trigger --name triggers --samples` landed `plugins/triggers/`.
- [ ] `shipping-status-webhook.ts` uses `verifier: 'hmac-sha256'` with a `secretEnv`.
- [ ] `WEBHOOK_SHIPPING_SECRET` is set in the environment running the triggers service.
- [ ] `curl http://localhost:8093/health` answers.
- [ ] A verified `POST` records an event (`:8093`) and produces a worker execution (`:8091`).

> If the job does not appear
>
> - Make sure `aspire start` is up — the workers runtime and KV must be live for the enqueued job to execute.
> - Check that `WEBHOOK_SHIPPING_SECRET` is set and that your request's signature matches; a failed HMAC verification rejects the request before the handler runs.
> - Confirm the job id in `enqueueJob(...)` matches a registered worker job. An unknown id is accepted at the webhook but has nothing to run.
> - Check the `triggers` processor resource in the Aspire [dashboard](https://localhost:18888) for errors — the background processor, not the API, drains the effects.

## What you built

- The `triggers` plugin under `plugins/triggers/`.
- An **HMAC-SHA256 verified** webhook authored with `defineWebhook(handler, { id, path, verifier, secretEnv, ... })` that rejects forged requests and `enqueueJob(...)`s a `process-shipping-update` job on each accepted one.
- A verified inbound `POST` confirmed end to end: an event recorded on the triggers API (`:8093`) and a worker execution on the workers API (`:8091`).

Your storefront now spans the full arc — catalog, cart, durable checkout, and a verified webhook from the outside world. The last chapter runs the whole thing as one orchestrated system on your machine.

[4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/) [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/storefront/05-shipping-webhook/_

---

# The storefront page

Every chapter so far built the backend: a typed catalog, a contract-first cart, a durable checkout, a verified webhook. All of it is reachable by `curl` — and none of it has a face. This chapter puts one on it, and in doing so closes the loop the whole track has been building toward: **the same oRPC contract that types the server handler also types the page's query and its checkout mutation.** Write a wrong field in the browser and it is a compile error, exactly as it is on the server. No second copy of "what a cart is", no hand-written fetch wrapper, no DTO that drifts.

You will build a customer's cart page as a Fresh route with a **typed route contract**, then drive its catalog query and its checkout mutation through the SDK's contract-derived query utilities inside an island. This is the frontend half of NetScript's typed spine — the part the storefront backend never showed you until now.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)
2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)
3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)
4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)
5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)
6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)
7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

## What you will build

A `GET /cart/[customer]` page. One **bound route contract** declares its URL pattern, its typed `{ customer }` path param, and its typed pagination search — so a link to the page and the handler that answers it can never disagree about its shape. A single clients module exposes a typed `productsClient` and `cartClient` plus their query utilities, each derived from the chapter-2 and chapter-3 contracts. An island then reads the catalog with `useIslandQuery` and begins checkout — a new cart — with `useIslandMutation`, both keyed off those contract-derived helpers. The catalog query runs live against the `products` service you have had up since chapter 2; the checkout mutation is typed end to end against the cart contract from chapter 3.

## Prerequisites

- The `products` service on `:3001` (from [chapter 2](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/)) and the `cart` contract and its typed client (from [chapter 3](https://rickylabs.github.io/netscript/tutorials/storefront/03-cart-contracts/)).
- `aspire start` up, so the `products` service is discoverable by name (the dashboard answers at [https://localhost:18888](https://localhost:18888)).
- The route contract and query utilities are built into `@netscript/fresh/route`, `@netscript/sdk/client`, and `@netscript/sdk/query-client`; none needs Aspire to type-check, though you run under Aspire to exercise the catalog query live.

> The cart page reuses your Fresh app
>
> Chapter 1 scaffolded a Fresh app alongside the services — that is where routes and islands live. This chapter adds files under
>
> apps/storefront/
>
> (use your app's actual folder name); the imports are what matter, not the exact path. If you stopped chapter 3 at the contract and never stood up a running
>
> cart
>
> service, the checkout mutation still type-checks end to end — the client is built from the contract alone. Running it live is the same
>
> defineService
>
> loop chapter 2 used, pointed at the cart handlers.

## Step 1 — Declare the bound route contract

Give the page a typed identity before any UI. A route contract from `@netscript/fresh/route` is the single source of truth for a route's pattern, its path params, and its search params. `createRouteReference` infers the `{ customer }` param straight from the pattern; `defineRouteContract`

- `bindRoutePattern` add typed pagination search with safe defaults. Put it in the shared `contracts/` tree so the page and any link import the *same* object:

```ts
// contracts/routes/cart-page.ts
import {
  bindRoutePattern,
  createRouteReference,
  defineRouteContract,
  fallback,
  paginationSearchSchema,
} from '@netscript/fresh/route';
import { z } from 'zod';

/** The one place the cart page pattern is written. */
export const CART_PAGE_PATTERN = '/cart/[customer]';

// createRouteReference infers the typed { customer } param from the pattern.
export const cartPageRef = createRouteReference(CART_PAGE_PATTERN);

/**
 * The bound cart page: typed `{ customer }` path param + typed `limit`/`offset`
 * pagination, all inferred from this one declaration.
 */
export const cartRoute = bindRoutePattern(
  defineRouteContract({
    pathSchema: z.object({ customer: z.string().min(1) }),
    searchSchema: paginationSearchSchema({ defaultLimit: 12 }).extend({
      // A junk ?highlight= falls back to undefined instead of throwing.
      highlight: fallback(z.string().optional(), undefined),
    }),
  }),
  CART_PAGE_PATTERN,
);
```

`bindRoutePattern` returns one object with everything downstream needs: `cartRoute.parsePath(...)` and `cartRoute.parseSearch(...)` turn raw request params into typed values, and `cartRoute.href({ path: { customer } })` builds the URL for a link — so navigation and the handler that answers it share one definition of the route.

**@netscript/fresh/route — the bound route contract surface**

| Name | Type | Description |
| --- | --- | --- |
| `createRouteReference(pattern)` | `RouteReference` | Infers typed path params directly from a Fresh route pattern — `/cart/[customer]` yields `{ customer: string }`. |
| `defineRouteContract({ pathSchema?, searchSchema? })` | `DefineRouteContract` | Declares typed path and search schemas; bind it to one or more concrete patterns. |
| `bindRoutePattern(contract, pattern)` | `BoundRouteContract` | Binds the contract to a pattern, returning one object with .parsePath / .parseSearch / .href. |
| `paginationSearchSchema(opts) / fallback(schema, default)` | `search schema` | Typed limit/offset with computed defaults; fallback() catches junk query strings instead of 500-ing the page. |

## Step 2 — One typed clients module

A client needs only a contract to be fully typed. Build one `createServiceClient` per service in a single module — the "one place all clients live" pattern — and wrap each in `createServiceQueryUtils`, which turns a client into per-procedure TanStack Query helpers:

```ts
// apps/storefront/lib/api-clients.ts
import { CartContractV1, ProductsContractV1 } from '@my-shop/contracts/versions/v1';
import { createServiceClient } from '@netscript/sdk/client';
import { createServiceQueryUtils } from '@netscript/sdk/query-client';

// One typed client per service. `serviceName` is the discovery key — how the
// client finds the service URL at call time; you never hardcode a port.
export const productsClient = createServiceClient<typeof ProductsContractV1>({
  contract: ProductsContractV1,
  serviceName: 'products',
});
export const cartClient = createServiceClient<typeof CartContractV1>({
  contract: CartContractV1,
  serviceName: 'cart',
});

// Contract-derived query/mutation utilities: one entry per procedure, each with
// a typed queryKey/queryOptions and mutationKey/mutationOptions.
export const productsQueries = createServiceQueryUtils(productsClient);
export const cartQueries = createServiceQueryUtils(cartClient);
```

`productsClient.list(input)` now has the exact signature `ProductsContractV1.list` declared, and `productsQueries.list.queryOptions({ input })` hands you the **contract-derived cache key** the island reads and invalidates through. Change a field in the contract and this module re-type-checks — there is no second definition of a product or a cart to keep in sync.

> How serviceName becomes a URL
>
> You never write
>
> http://localhost:3001
>
> .
>
> serviceName: 'products'
>
> resolves at call time from an Aspire-injected env var — server-side
>
> services__products__http__0
>
> and its browser mirror — so the same client works in a page loader and in a hydrated island. Aspire sets those when the app lists
>
> products
>
> as a reference; the client just reads them. Full mechanics in
>
> Discover services
>
> .

## Step 3 — Read and mutate in the island

The island is where the typed contract meets the browser. `useIslandQuery` reads the catalog; `useIslandMutation` begins checkout by creating a cart. Both come from `@netscript/fresh/query` — island code imports query hooks from there, never from TanStack directly, so the dependency stays centralized:

```tsx
// apps/storefront/islands/CheckoutIsland.tsx
import {
  QueryIsland,
  useIslandMutation,
  useIslandQuery,
  useQueryClient,
} from '@netscript/fresh/query';
import {
  cartClient,
  cartQueries,
  productsClient,
  productsQueries,
} from '../lib/api-clients.ts';

interface CheckoutIslandProps {
  customer: string;
  input: { limit: number; offset: number };
  initialProducts?: { items: Array<{ id: number; name: string }> };
}

function CheckoutInner({ customer, input, initialProducts }: CheckoutIslandProps) {
  const queryClient = useQueryClient();

  // READ — the catalog. The util gives the contract-derived cache key; the typed
  // client makes the call. initialData seeds the first paint from a server loader.
  const catalog = useIslandQuery({
    queryKey: productsQueries.list.queryOptions({ input }).queryKey,
    queryFn: () => productsClient.list(input),
    initialData: initialProducts,
    staleTime: 10_000,
  });

  // WRITE — begin checkout by creating the customer's cart, typed off CartContractV1.
  // On success, invalidate the cart's query key so any cart view refetches.
  const checkout = useIslandMutation({
    mutationFn: (line: { productId: number; quantity: number }) =>
      cartClient.create({ customerId: customer, items: [line] }),
    onSuccess: () =>
      queryClient.invalidateQueries({ queryKey: cartQueries.list.key({ type: 'query' }) }),
  });

  const products = catalog.data?.items ?? [];
  return (
    <ul class='ns-stack'>
      {products.map((product) => (
        <li key={product.id}>
          <span>{product.name}</span>
          <button
            type='button'
            disabled={checkout.isPending}
            onClick={() => checkout.mutate({ productId: product.id, quantity: 1 })}
          >
            {checkout.isPending ? 'Adding…' : 'Add to cart'}
          </button>
        </li>
      ))}
    </ul>
  );
}

export default function CheckoutIsland(props: CheckoutIslandProps) {
  return (
    <QueryIsland>
      <CheckoutInner {...props} />
    </QueryIsland>
  );
}
```

The moves that make this typed end to end:

- **`queryKey` from the utility, `queryFn` calling the client.** `productsQueries.list.queryOptions(...)` computes the same cache key the server uses, so a server-seeded row and a client-refetched row share one key. The island hook wants a zero-argument `queryFn`, so you invoke the typed `productsClient.list(input)` there — the call is checked against `ProductsContractV1`, not a loose `fetch`.
- **`mutationFn` is a typed contract call.** `cartClient.create({ customerId, items })` is checked against `CartContractV1.create`; pass an item without a `productId` and it fails `deno task check`, not in production.
- **Invalidation is keyed off the contract too.** `cartQueries.list.key({ type: 'query' })` is the prefix-matchable cache key for every cart list query, so one line refetches the cart after checkout.

> Why the queryFn wraps the client instead of spreading queryOptions
>
> The island hooks (
>
> useIslandQuery
>
> /
>
> useIslandMutation
>
> ) take a deliberately small option surface with a zero-argument
>
> queryFn
>
> . The SDK's
>
> queryOptions()
>
> /
>
> mutationOptions()
>
> produce a fuller TanStack shape whose functions expect a call context, so they are not spread wholesale into the island hooks. You use the utilities for the parts that must stay contract-derived — the
>
> keys
>
> — and let the typed client be the function body. Same type source, honest seam.

## Step 4 — Wire the route to the page

The page reads its params **through the contract** and hands the island a typed slice. The route the Fresh app registers (`/cart/:customer`) and the contract's pattern (`/cart/[customer]`) name the same segment — `cartRoute.parsePath` bridges them:

```tsx
// apps/storefront/routes/cart/[customer].tsx
import { cartRoute } from '../../../contracts/routes/cart-page.ts';
import CheckoutIsland from '../../islands/CheckoutIsland.tsx';

export default function CartPage(props: { params: { customer: string }; url: URL }) {
  // Typed off the ONE route contract — no hand-parsing the URL.
  const { customer } = cartRoute.parsePath(props.params);
  const { limit, offset } = cartRoute.parseSearch(props.url.searchParams);

  return (
    <main class='ns-page'>
      <h1>Cart for {customer}</h1>
      <CheckoutIsland customer={customer} input= />
    </main>
  );
}
```

`cartRoute.parseSearch` applies the `paginationSearchSchema` defaults, so `/cart/cust_1001` with no query string still yields a typed `{ limit: 12, offset: 0 }`. A link elsewhere builds the URL with `cartRoute.href({ path: { customer: 'cust_1001' } })` — the pattern is written once, in the contract.

## Test it out

Type-check first — the whole typed chain is proven by the compiler, no server required:

```sh
# From the workspace root.
deno task check
```

A clean check means the route contract, both service clients, the query utilities, and the island all line up with the chapter-2 and chapter-3 contracts. Now exercise the **catalog query** live. With `aspire start` up and at least one product created (chapter 2), the `products` service answers by discovery, so the page's query returns real rows:

```sh
# The query the island runs, against the live products service.
curl "http://localhost:3001/api/products?page=1&limit=12"
```

You get the page-shaped catalog back — the same `items` the island renders. Open the page in your Fresh app (the app's port shows in the Aspire dashboard resource list) at `/cart/cust_1001`, and each product carries an **Add to cart** button wired to the typed checkout mutation.

- [ ] `contracts/routes/cart-page.ts` exports `cartRoute`, a bound route contract with a typed `{ customer }` param and pagination search.
- [ ] `apps/storefront/lib/api-clients.ts` exports `productsClient`, `cartClient`, `productsQueries`, and `cartQueries`, each derived from a contract.
- [ ] `CheckoutIsland.tsx` reads with `useIslandQuery` and mutates with `useIslandMutation`, keyed off the contract-derived helpers.
- [ ] The page reads `customer`, `limit`, and `offset` via `cartRoute.parsePath` / `.parseSearch`, not by hand.
- [ ] `deno task check` passes.
- [ ] `curl` against `:3001/api/products` returns the catalog the island renders.

## What you built

- A `GET /cart/[customer]` page whose route is a **bound route contract**: one object owns the pattern, the typed `{ customer }` path param, and the pagination search, and it produces both the page's typed params and the URL a link would call.
- A single clients module with one typed `createServiceClient` per service, each wrapped in `createServiceQueryUtils` — the contract-derived query and mutation helpers.
- An island that **reads** the catalog with `useIslandQuery` and **begins checkout** with `useIslandMutation`, both keyed off those helpers, with cache invalidation keyed off the cart contract too.

That is the differentiator this chapter exists to prove: the oRPC contract you wrote once on the backend is the *same* type source for the URL, the query, and the mutation on the frontend — checked by the compiler from the database to the button, never a second hand-maintained copy that can drift.

## Next Steps

- **Ship it.** [Chapter 7 · Deploy](https://rickylabs.github.io/netscript/tutorials/storefront/07-deploy/) runs the whole storefront — services, plugins, and this page — under one `aspire start`.
- **Go cache-first and live.** The [live-dashboard track](https://rickylabs.github.io/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/) takes the same query utilities further: KV-backed stale-while-revalidate reads and real-time streamed updates.
- **Reference.** The [SDK reference](https://rickylabs.github.io/netscript/reference/sdk/) and [contracts explanation](https://rickylabs.github.io/netscript/explanation/contracts/) cover the full typed client-and-query surface.

[5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/) [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/storefront/06-storefront-ui/_

---

# Run the whole storefront

Across the previous six chapters you built the storefront one piece at a time, usually starting a single service in its own terminal. This final chapter zooms out: you run the **entire** `my-shop/` — the products service, the cart contract's consumers, the storefront page, the checkout saga, the shipping webhook, Postgres, and the cache — as one coherent system under a single `aspire start`, and watch all of it from one dashboard.

This is the payoff of the whole track, and it is one command. Everything you added chapter by chapter — a service, three runtime plugins, a webhook, a Fresh page — the scaffold has been wiring into a single resource graph the entire time. You never edited an orchestrator by hand. `aspire start` reads that graph and boots all of it at once: **`netscript init` scaffolded it, `aspire start` runs it — from an empty folder to a complete, observable stack in two commands, no deploy YAML in between.** That one-command-from-scaffold story *is* NetScript's local topology.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/01-scaffold/)
2. [2 · Catalog service](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)
3. [3 · Cart contracts](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/)
4. [4 · Checkout saga](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)
5. [5 · Shipping webhook](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)
6. [6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/)
7. [7 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/07-deploy/)

## What you will build

You will bring the complete storefront up under one orchestrator: `aspire start` translates your `appsettings.json` plus the installed plugins into a single resource graph and boots all of it — infrastructure, services, plugin APIs, and background processors — then gives you a dashboard over the whole thing. You will read the live port map from the dashboard and confirm every resource is healthy.

> This is the LOCAL story — not a production deployer
>
> aspire start
>
> exists to make one command produce a complete, correctly-wired stack on
>
> one machine
>
> . The Postgres and Redis it starts are throwaway Docker containers for dev convenience —
>
> not
>
> your production database or cache. NetScript does not ship a cloud deployer for your app; for a remote target you point processes at managed infrastructure yourself. This chapter teaches the local topology. See the
>
> Deploy
>
> and
>
> Deploy locally with Aspire
>
> how-to guides for the production-vs-local split.

## Before you begin

You should have finished [chapter 6](https://rickylabs.github.io/netscript/tutorials/storefront/06-storefront-ui/), so `my-shop/` has:

- The `products` service, the `cart` contract, and the storefront page that reads and mutates through the typed clients from chapter 6.
- The `workers`, `sagas`, and `streams` plugins (with `CheckoutSaga` and the `process-payment` job) and the `triggers` plugin (with the shipping webhook and its `process-shipping-update` job).

Confirm the full plugin set is installed:

```sh
netscript plugin list
```

You should see `workers`, `sagas`, `streams`, and `triggers`. If `aspire start` from earlier chapters is still up, you can stop it now — this chapter starts the whole graph fresh.

## Step 1 — Confirm the AppHost was scaffolded

The orchestrator's entry point is a small **TypeScript/Node** program (not C#) at `aspire/apphost.mts`, configured by `aspire/aspire.config.json`. `netscript init` generated it back in chapter 1; you never hand-write it. Verify it is on disk:

```sh
# From the workspace root — these two files are the orchestration entry point.
ls aspire/apphost.mts aspire/aspire.config.json
```

The graph inside the AppHost is **derived from your installed plugins** at boot — adding the `sagas` and `triggers` plugins in chapters 4 and 5 is exactly why their APIs and background processors now appear in the graph, with no edit to `apphost.mts` required.

> There is no `netscript generate aspire`
>
> The AppHost is produced by
>
> netscript init
>
> only.
>
> netscript generate
>
> covers
>
> runtime-schemas
>
> and
>
> plugins
>
> , not the AppHost. To change the graph, add or remove a plugin (or edit
>
> appsettings.json
>
> ) and let the contributions re-derive it.

## Step 2 — Restore the AppHost SDK (once)

The AppHost runs on its own isolated Node runtime inside `aspire/` so its dependency graph never leaks into your Deno workspace. Restore that runtime once per machine (you did this in chapter 1; it is idempotent):

```sh
cd aspire
aspire restore
```

## Step 3 — Start the whole resource graph

A single `aspire start` translates `appsettings.json` plus the plugin contributions into a coherent resource graph and boots all of it — infrastructure first, then services, plugin APIs, and background processors, with cross-references resolved into injected environment variables:

```sh
# Still inside aspire/. Boots the whole graph; prints the dashboard URL + a login token.
aspire start
```

When boot finishes, `aspire start` prints the dashboard address and a one-time login token. Here is the graph a single run stands up for the storefront:

**What `aspire start` brings up for my-shop/**

| Name | Type | Description |
| --- | --- | --- |
| `aspire (dashboard)` | `https://localhost:18888 / http://localhost:18889` | Live resource list, console logs, structured logs and traces. A login token is printed on start. |
| `OTLP collector` | `http://localhost:4318` | OpenTelemetry endpoint the dashboard runs; framework spans and structured logs land here automatically. |
| `postgres` | `Container` | Provisioned via Docker. The database your products handlers and saga store target — reachable only while Aspire is up. |
| `redis` | `Container (cache)` | Redis cache — the default `--cache-backend`; Redis-compatible. Backs KV/queue workloads for the runtime plugins. |
| `products (service)` | `:3001 (SERVICE range, from :3000)` | Your catalog service. OpenAPI at /api/products/* and RPC at /api/rpc/*. |
| `sagas API` | `:8092 (PLUGIN_API range)` | Lists sagas and instances — where you watched CheckoutSaga in chapter 4. |
| `triggers API` | `:8093 (PLUGIN_API range)` | The Hono webhook ingress from chapter 5 — /api/v1/webhooks/shipping/status. |
| `workers API` | `:8091 (PLUGIN_API range)` | Lists job executions — where the enqueued shipping and payment jobs run. |
| `streams` | `:4437` | The durable streams transport that carries cross-plugin messages between the saga and the workers. |
| `background processors` | `executables (no port)` | Each plugin's isolated runners (workers, sagas, triggers) — separate processes, not threads inside the API. |

> Plugin API ports are range-allocated, not fixed
>
> The runtime plugins publish their APIs from the
>
> :8091–8099
>
> PLUGIN_API
>
> range, and services from the
>
> :3000–3099
>
> SERVICE
>
> range. The conventional assignments (products
>
> :3001
>
> , workers
>
> :8091
>
> , sagas
>
> :8092
>
> , triggers
>
> :8093
>
> ) are what this workspace lands on — but the dashboard's resource list is the authority for the exact port each resource bound, not a memorized number. Read it from there.

## Step 4 — Use the dashboard

Open `https://localhost:18888`, paste the login token `aspire start` printed, and you have a single pane over the running storefront:

**Aspire dashboard surfaces**

| Name | Type | Description |
| --- | --- | --- |
| `Resources` | `tab` | Every container and executable above with status, endpoints, and resolved environment. The authority for which port each resource bound. |
| `Console logs` | `tab` | stdout/stderr per resource — a failing background processor is one click away, not buried in a terminal. |
| `Structured logs + Traces` | `tab` | Spans and structured logs your handlers emit, correlated by traceparent across services. Collected via the OTLP endpoint at :4318. |

Because Aspire starts each resource with its `OTEL_SERVICE_NAME` and an OTLP endpoint, framework-level spans — job dispatch, job execution, saga steps — surface here with no extra wiring. Driving a checkout end to end (chapter 4) and firing the shipping webhook (chapter 5) now both show up as correlated traces in one place.

## Verify your progress

With the graph up, confirm the whole storefront is live from one terminal. The dashboard resource list should show `postgres`, `redis`, `products`, and the `workers` / `sagas` / `triggers` APIs all healthy. Spot-check a few endpoints:

```sh
# Catalog service
curl http://localhost:3001/health

# Saga registry lists your checkout saga
curl http://localhost:8092/api/v1/sagas/sagas

# Triggers ingress is alive
curl http://localhost:8093/health
```

- [ ] `ls aspire/apphost.mts aspire/aspire.config.json` shows both files.
- [ ] `aspire start` boots and prints a dashboard URL + login token.
- [ ] The dashboard at `https://localhost:18888` lists `postgres`, `redis`, `products`, and the `workers` / `sagas` / `triggers` plugin APIs, all healthy.
- [ ] `curl` against `:3001`, `:8092`, and `:8093` all answer.
- [ ] A checkout and a webhook fire show up as correlated traces in the dashboard.

> Footguns when `aspire start` will not boot
>
> - **Docker not running.** Aspire provisions Postgres + Redis through Docker; no daemon means the happy path does not start.
> - **Wrong directory.** `aspire restore` and `aspire start` run from inside `aspire/`; `netscript db` commands run from the workspace root. Mixing them up is the most common first-run error.
> - **db command before `aspire start`.** Every `netscript db` command needs a live Postgres. Bring the graph up first.
> - **Ports in use.** A stale prior run holding `:18888`, `:3001`, or an `:8091–8099` port blocks boot — check the dashboard resource list (or your process table) and free it.

## What you built

- The entire `my-shop/` storefront running as one orchestrated resource graph under a single `aspire start` — Postgres, Redis, the `products` service, the streams transport, and the workers, sagas, and triggers plugin APIs plus their background processors.
- A dashboard at `https://localhost:18888` giving you the live port map, per-resource console logs, and correlated traces across the whole app.
- A precise mental model: this is the **local** topology Aspire stands up for development, not a production deployer for your app.

You have built and run a complete NetScript storefront backend — contract-first throughout, durable where it counts, and verified at its edges.

## Where to go next

- **Ship it somewhere real** → the [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/) how-to (production targets) and [Deploy locally with Aspire](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy-local-aspire/) (the full local recipe with every flag).
- **Add observability** → [Add OpenTelemetry](https://rickylabs.github.io/netscript/observability/how-to/add-opentelemetry/) and the [Observability explanation](https://rickylabs.github.io/netscript/explanation/observability/).
- **Go deeper on the ideas** → [Durability model](https://rickylabs.github.io/netscript/explanation/durability-model/), [Contracts & type flow](https://rickylabs.github.io/netscript/explanation/contracts/), and [The plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/).
- **Solve a specific task** → the full [How-to guides](https://rickylabs.github.io/netscript/how-to/).

[6 · Storefront UI](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/06-storefront-ui/) [How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/storefront/07-deploy/_

---

# Team Workspace

Picture the app this track is modeled on: a production context-accumulator chat application built on NetScript. An operations team lives in it during an ERP cutover — projects and channels full of live incident context, diagnostics, and half-finished conclusions about a production system that is misbehaving *right now*. Underneath all of that sits an unglamorous layer that decides everything: **who is on the team, where their data lives, and which routes they may touch**. Get it wrong in one direction and an off-boarded contractor can still read incident channels; get it wrong in the other and the engineer you just paged is locked out while production burns.

The differentiator this track proves is that **the identity layer is NetScript's to ship, not yours to rebuild**: a pluggable auth backend, a normalized session, and a typed `.withAuthn()` / `.withAuthz()` route seam — in place of the bespoke sign-in flow and hand-rolled route middleware most stacks reimplement, and re-secure, once per app.

That layer is what you build here, from an empty folder to a running, session-protected app under Aspire: you scaffold a workspace (Postgres by default, swappable to `mysql`, `mssql`, or `sqlite` via `--db`), sign users in through a pluggable auth backend, give team records their own isolated database, provision new members with a background job that never blocks the caller, and gate your service routes with the real `.withAuthz()` seam. It is one continuous app — your `my-workspace/` grows with every chapter.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)
2. [2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)
3. [3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)
4. [4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)
5. [5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

## What you will build

By the end of this track you will have a NetScript workspace that signs a real user in through an OAuth/OIDC provider, mints a session cookie, stores team records in their own isolated Postgres (the default; or `mysql` / `mssql` / `sqlite` via `--db`), provisions a new member off the request path with a background job, and rejects unauthenticated requests to its guarded routes with a `401` — all running locally under one Aspire dashboard. The central idea: **authentication in NetScript is a pluggable backend, a session, and a route-authz seam — not a bespoke rewrite you carry yourself.**

> What NetScript ships — and what stays your code
>
> NetScript ships
>
> pluggable auth backends
>
> (an
>
> auth-api
>
> service with a single active backend chosen by an env var), a normalized
>
> session
>
> , and a provider-agnostic
>
> route-authz seam
>
> (
>
> .withAuthn()
>
> /
>
> .withAuthz()
>
> ). It does
>
> not
>
> ship first-class organizations, tenants, or RBAC roles. The "team workspace" app framing is real, but the data model is single-tenant: when this track touches multi-tenant org scoping, it does so as a clearly-marked
>
> app-level extension
>
> (you add your own
>
> orgId
>
> column and filter in your own queries), never as a framework-managed primitive. Read those asides as "here is how you would extend it," not "NetScript does this for you."

> Where this track's patterns come from
>
> The data shape is borrowed from a real app: a production chat application built on NetScript splits an
>
> org-catalog
>
> datasource (who exists, which projects and channels there are) from the data each channel accumulates — the dual-database pattern you build in chapter 3, and the same
>
> workers
>
> -plugin background jobs you use in chapter 4. The
>
> auth chapters are the exception
>
> : they are grounded in the framework's own packages and its
>
> builder-auth
>
> test suite (the 401/403/200 pattern in chapter 5), because that is where the authentication seam is actually defined and proven.

## The arc: auth → session → authz

Three ideas carry the whole track, and each chapter adds exactly one:

- **Auth** — a *backend* turns a sign-in into an identity. You pick one of three backends (`kv-oauth`, `workos`, `better-auth`) with an environment variable; the contract is identical across all three.
- **Session** — a successful sign-in mints a normalized `AuthSession` and sets a session cookie. Every later request resolves the current session from that cookie.
- **Authz** — a service gates its own routes with `.withAuthn()` (resolve a `Principal`) and `.withAuthz()` (decide from it). This is route-level authorization, scoped to route-level — not org/role RBAC.

## Who this is for

You should be comfortable with the basics from the [core tutorial ladder](https://rickylabs.github.io/netscript/tutorials/) — scaffolding a workspace, the contract → service flow, and bringing up Aspire. This track does not re-teach those; it assumes you can scaffold and boot, then layers authentication on top. If `netscript init` and `aspire start` are new to you, walk the [Quickstart](https://rickylabs.github.io/netscript/quickstart/) first.

## The six chapters

[1 · Scaffold  Create `my-workspace/` with an example service and Postgres, then boot it under Aspire. The base your authenticated app grows from.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)

[2 · Auth  Add the `auth` plugin, choose the interactive `kv-oauth` backend, run the `auth.prisma` migration, and verify a live session on the `auth-api` service at :8094.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)

[3 · Workspace data  Give the workspace its own isolated database with `netscript db add` and a per-datasource schema. The app-level `orgId` column appears here as an Extend aside.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)

[4 · Provision job  Move member provisioning off the request path: author a `defineJobHandler` job that creates a workspace membership, and trigger it over the Workers API at :8091.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)

[5 · Route authz  Protect your service routes with the real, tested `.withAuthn()` / `.withAuthz()` seam — an authenticated request succeeds, an unauthenticated one gets a 401.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)

[6 · Deploy  Run the whole workspace locally under Aspire — including the :8094 auth service — and read it from one dashboard. Shows the local-vs-production topology clearly.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

## What you built

A clear map of the track: the team layer that a real operations tool stands on — a pluggable auth backend, a session, isolated team data, off-path provisioning, and a route-authz seam that fails closed. Single-tenant by design, with org scoping as an explicit app-level extension. Start at chapter 1 and keep the same `my-workspace/` through to deploy.

[Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)

After this track, keep building in **Build › [Identity & Access](https://rickylabs.github.io/netscript/identity-access/)** — the guides and recipes there pick up where these chapters stop.

_Canonical: https://rickylabs.github.io/netscript/tutorials/workspace/_

---

# Scaffold the workspace

You are building the team layer of an operations workspace — the part that will decide who is on the team, where team records live, and which routes a caller may reach. Every chapter in this track adds one layer to that single app. This first chapter lays the foundation: a real NetScript workspace on disk named `my-workspace/`, with an example service and a Postgres database, booted under Aspire. You will not write auth yet — you will create the base that the auth backend, the team database, the provisioning job, and the route guards all attach to in the chapters that follow. Everything that later fails closed or provisions off-path attaches to what you scaffold here, so the checkpoint at the end of this chapter — a healthy service and a clean type-check — is the ground truth the rest of the track builds on.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)
2. [2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)
3. [3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)
4. [4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)
5. [5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

## What you will build

A working `my-workspace/` directory: a typed `workspace` service on its own port, a Postgres database, the Aspire orchestration that provisions Postgres and the Redis cache, and a clean `deno task check`. By the end you will have the Aspire dashboard open on `https://localhost:18888` showing your service, database, and cache running together — the control plane you keep up for the rest of the track.

## Before you begin

This is the first chapter, so there is no prior project state to check — but your local toolchain must be ready. You need **[Deno](https://deno.com/) 2.x**, the **[Aspire CLI](https://aspire.dev)**, and **Docker** running so Aspire can start the Postgres and Redis containers. Verify all three:

```sh
deno --version     # Deno 2.x
aspire --version   # the .NET Aspire CLI
docker info        # prints engine details, not a connection error
```

Install the NetScript CLI from JSR once, then confirm it is on your `PATH`:

```sh
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11
netscript --help
```

`netscript --help` should list the command groups `init`, `contract`, `db`, `deploy`, `generate`, `marketplace`, `plugin`, `service`, `ui:add`, and `ui:init`. If `netscript` is not found, make sure Deno's install directory (printed by `deno install`) is on your `PATH`, then open a fresh terminal.

> Prefer not to install globally?
>
> Run any command ad-hoc with
>
> deno x jsr:@netscript/cli@0.0.1-beta.11 <command>
>
> . The rest of this track assumes the installed
>
> netscript
>
> form.

## Step 1 — Preview the scaffold

Before writing files, ask the CLI what it *would* create. `--dry-run` plans the scaffold and prints per-phase file and directory totals without touching disk:

```sh
netscript init my-workspace --service --service-name workspace --service-port 3001 --db postgres --dry-run
```

A clean dry run validates your flag combination — it rejects bad mixes (an unknown `--db` engine, for example) here, before any files exist. Treat a clean plan as a green light to scaffold for real.

This track uses `--db postgres`, the recommended default. The database is polyglot, so you can swap `--db postgres` for `mysql`, `mssql`, or `sqlite` and follow along the same way (sqlite is file-backed, so it has no Aspire container).

## Step 2 — Create `my-workspace/`

Run the same command without `--dry-run`. This track uses an example service named `workspace` on port `3001` and a Postgres database, so you have something real to authenticate and protect later:

```sh
netscript init my-workspace --service --service-name workspace --service-port 3001 --db postgres
cd my-workspace
```

This scaffolds `my-workspace/`, formats the output with `deno fmt`, and initializes a git repository. On completion the CLI prints a **next steps** summary tailored to your options.

**netscript init options used here**

| Name | Type | Description |
| --- | --- | --- |
| `--service --service-name workspace --service-port 3001` | `example service` | Include an example oRPC service named 'workspace' on port 3001 — the service you protect in chapter 5. |
| `--db postgres` | `database workspace` | Scaffold a Postgres database workspace. The auth plugin's auth.prisma migration (chapter 2) aggregates into this primary datasource. |
| `--dry-run` | `plan only` | Plan the scaffold and print totals without writing any files (Step 1). |

## Step 3 — Tour what you got

Open `my-workspace/` and you will find this shape. These are the directories the rest of the track edits:

- my-workspace/

  - apps/dashboard/ # Fresh frontend (defineFreshApp)
  - contracts/ # Shared oRPC + Zod contracts, versioned under versions/v1/
  - services/workspace/ # The example oRPC service (src/main.ts, router.ts) — guarded in chapter 5
  - plugins/ # Plugin registry — empty until you add the auth plugin in chapter 2
  - database/ # The primary Postgres workspace; a second db is added in chapter 3
  - aspire/ # Aspire TypeScript orchestration (isolated Node runtime)
  - appsettings.json # Infrastructure config (Services / Databases / Persistent)
  - deno.json # Workspace root (members, tasks, dependency catalog)
  - netscript.config.ts # Framework config (defineConfig)

The two pieces you will return to most: **`services/workspace/`** is the oRPC service whose routes you protect in chapter 5, and **`plugins/`** is where the `auth` plugin lands in chapter 2. Everything derives its types from `contracts/` — the typed seam between your services and any client.

> Where is packages/?
>
> If you scaffolded from a checkout of the NetScript repo you may see a vendored
>
> packages/
>
> directory. A normal JSR install does not have one — your project pulls
>
> @netscript/*
>
> from the registry. Ignore
>
> packages/
>
> throughout this track.

## Step 4 — Bring up orchestration

This is the step that turns a folder of files into a running system. **Aspire provisions your database and cache; you do not start containers by hand, and you run it before any `netscript db` command.** Run it from the `aspire/` subfolder so the CLI finds `apphost.mts`:

```sh
cd aspire
aspire restore   # once per machine: restores the Aspire SDK modules
aspire start       # starts the AppHost and every declared resource
```

`aspire start` brings up the Postgres database, the Redis cache, and your `workspace` service together, then prints the **Aspire dashboard** URL and a one-time login token. Open it:

```
https://localhost:18888
```

Leave `aspire start` running in this terminal — it is your app's control plane for the entire track. The dashboard's resource list is the authority for the exact port each resource bound.

> Aspire is step 2 — database commands need it running
>
> The Postgres container only exists while
>
> aspire start
>
> is up. So
>
> netscript db init
>
> ,
>
> db generate
>
> , and
>
> db seed
>
> — which you use from chapter 2 onward — must run
>
> after
>
> Aspire has started, never before. A db command with no Aspire up fails fast: there is no Postgres for it to reach.

## Verify your progress

In a second terminal (leave `aspire start` going in the first), confirm the `workspace` service is up and the workspace type-checks:

```sh
curl http://localhost:3001/health
deno task check
```

`curl` should return a healthy JSON response, and `deno task check` should finish clean — confirming the scaffold, contracts, and service all line up.

- [ ] `netscript --help` lists the public command groups.
- [ ] `my-workspace/` exists with `services/workspace/`, `plugins/`, `database/`, and `aspire/`.
- [ ] `aspire start` is up; `postgres` and `redis` are green in the dashboard at `https://localhost:18888`.
- [ ] `curl http://localhost:3001/health` returns a healthy response.
- [ ] `deno task check` passes.

> If something is not green
>
> Three checks cover most first-run snags: (1) is
>
> aspire start
>
> still up, with
>
> postgres
>
> and
>
> redis
>
> healthy in the dashboard? (2) is Docker running (
>
> docker info
>
> )? (3) did you
>
> cd aspire
>
> before
>
> aspire start
>
> , so it found
>
> apphost.mts
>
> ? A failed
>
> curl
>
> usually means the service has not finished starting — wait a few seconds and retry.

## What you built

A real NetScript workspace at `my-workspace/`: a typed `workspace` service on `:3001`, shared contracts, a Postgres database, and a Redis cache — all orchestrated by Aspire and visible in one dashboard. This is the base — and right now it answers absolutely anyone. Next you fix that: you add an identity layer, so the app can tell a team member from a stranger.

[Team Workspace](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/) [2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/workspace/01-scaffold/_

---

# Add auth and a session

You have a running workspace, but anyone can hit it — and for the app this track is building, that is not a cosmetic gap. A team workspace exists to hold things the whole internet must not read: member lists, project records, the operational context a team accumulates while something is on fire. Before any of that data lands (chapter 3), the app needs to answer one question reliably: *who is this?* This chapter gives it that identity layer: you add the official `auth` plugin, choose an authentication **backend**, run its database migration, and verify a live **session** through the `auth-api` service on `:8094`. The lesson underneath the steps: **auth in NetScript is a pluggable backend plus a session** — you pick the backend with one environment variable, and the contract is identical no matter which one you pick. Swapping providers later is a config change, not a rewrite you carry through every route.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)
2. [2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)
3. [3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)
4. [4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)
5. [5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

## What you will build

A working sign-in surface for `my-workspace/`: the `auth` plugin installed, the interactive `kv-oauth` backend selected, the `auth.prisma` migration applied, and the `auth-api` service answering on `:8094`. By the end you can hit `GET /api/v1/auth/session` and `GET /api/v1/auth/me` and watch the service correctly report "no session yet" before login — proof the backend is composed and the session endpoints are wired.

## Before you begin

You need the workspace from [chapter 1](https://rickylabs.github.io/netscript/tutorials/workspace/01-scaffold/) with **Aspire running** — the auth plugin contributes a service and a Prisma schema that Aspire and `netscript db` reach through the running graph. Confirm the base is up:

```sh
# In my-workspace/, with `aspire start` up in another terminal
curl http://localhost:3001/health   # the workspace service from chapter 1
```

> Aspire is the control plane — start it first
>
> The
>
> auth-api
>
> service and its Postgres/KV dependencies are resources in the Aspire graph. Bring orchestration up
>
> before
>
> any
>
> netscript db
>
> command or auth endpoint call: from the project root,
>
> cd aspire && aspire start
>
> (dashboard at
>
> https://localhost:18888
>
> ). DB commands need Aspire running first.

## Step 1 — Add the `auth` plugin

The `auth` plugin is a first-class official plugin, installed the same way as `workers`, `sagas`, and `triggers`. From the workspace root:

```sh
netscript plugin install @netscript/plugin-auth
```

This scaffolds the unified `@netscript/plugin-auth` plugin into `plugins/`, registers it, and contributes three things to your workspace: a Prisma schema (`auth.prisma`), a service entry that becomes the `auth-api` service, and the `/api/v1/auth/*` routes. Confirm it landed:

```sh
netscript plugin list
```

> One plugin, one active backend
>
> @netscript/plugin-auth
>
> is a thin composition layer. The real authentication logic lives in a
>
> backend adapter
>
> — one of
>
> @netscript/auth-kv-oauth
>
> ,
>
> @netscript/auth-workos
>
> , or
>
> @netscript/auth-better-auth
>
> . The plugin selects
>
> exactly one
>
> active backend at runtime; there is no multi-active routing or cross-backend account linking in v1. You pick the backend in Step 2.

> Alpha package pins
>
> The scaffold emits exact alpha specifiers such as
>
> jsr:@netscript/plugin-auth-core@0.0.1-beta.11
>
> . Add auth through
>
> netscript plugin install @netscript/plugin-auth
>
> , which wires the workspace correctly for the aligned alpha train.

## Step 2 — Choose a backend with `NETSCRIPT_AUTH_BACKEND`

The active backend is selected by the `NETSCRIPT_AUTH_BACKEND` environment variable (or the `auth.backend` appsettings key). Three backends are valid; the default is **`kv-oauth`**, the only one that drives an interactive sign-in.

**Auth backends — capability matrix (NETSCRIPT_AUTH_BACKEND)**

| Name | Type | Description |
| --- | --- | --- |
| `kv-oauth` | `interactive (default)` | Full OAuth/OIDC redirect flow. Real signin + callback, KV-backed sessions with refresh-on-read, signout. The only backend that implements InteractiveFlowPort. Package @netscript/auth-kv-oauth. |
| `workos` | `non-interactive` | WorkOS AuthKit sealed wos-session cookie. Validates an existing session; signin/callback return AUTH_PROVIDER_ERROR. Package @netscript/auth-workos. |
| `better-auth` | `non-interactive` | better-auth over Prisma. Validates an existing session; signin/callback return AUTH_PROVIDER_ERROR. Package @netscript/auth-better-auth. |

A team workspace needs users to *log in*, so this track uses the interactive default. Make the choice explicit in your environment:

```sh
export NETSCRIPT_AUTH_BACKEND=kv-oauth
```

> Only kv-oauth is interactive — choose accordingly
>
> The
>
> signin
>
> and
>
> callback
>
> endpoints require a backend that implements the optional
>
> InteractiveFlowPort
>
> .
>
> Only `kv-oauth` does.
>
> On
>
> workos
>
> and
>
> better-auth
>
> ,
>
> POST /api/v1/auth/signin
>
> or
>
> POST /api/v1/auth/callback
>
> returns a typed
>
> AUTH_PROVIDER_ERROR
>
> (502) — those backends are for environments where sign-in already happened elsewhere and you only need NetScript to
>
> validate
>
> the session (
>
> session
>
> /
>
> me
>
> ). To drive the login redirect from NetScript, stay on
>
> kv-oauth
>
> .

## Step 3 — Run the auth database migration

The `auth` plugin contributes a package-provided **`auth.prisma`** schema that aggregates into your primary Postgres at `db generate`. With Aspire running, run the standard database loop from the workspace root:

```sh
netscript db init --name init    # first time only — create the migration
netscript db generate            # generate the Prisma client + Zod schemas
netscript db seed                # optional seed data
netscript db status              # confirm the migration is applied
```

> Which backends actually use these tables
>
> auth.prisma
>
> defines four better-auth-shaped models —
>
> User
>
> →
>
> auth_users
>
> ,
>
> Session
>
> →
>
> auth_sessions
>
> ,
>
> Account
>
> →
>
> auth_accounts
>
> ,
>
> Verification
>
> →
>
> auth_verifications
>
> . The migration runs regardless, but storage differs by backend:
>
> kv-oauth
>
> keeps sessions in Deno KV (not these tables),
>
> workos
>
> is effectively stateless (sealed cookie), and
>
> better-auth
>
> is the one that reads/writes these tables through Prisma.

## Step 4 — Configure the kv-oauth backend

The `kv-oauth` backend needs a real OAuth/OIDC provider (a client id, secret, and redirect URI) plus a key for the session token at rest. Set these in your environment before starting the service:

```sh
# Selects the interactive backend
export NETSCRIPT_AUTH_BACKEND=kv-oauth

# Provider credentials (e.g. a Google or GitHub OAuth app)
export NETSCRIPT_AUTH_CLIENT_ID=your-client-id
export NETSCRIPT_AUTH_CLIENT_SECRET=your-client-secret
export NETSCRIPT_AUTH_REDIRECT_URI=http://localhost:8094/api/v1/auth/callback

# Required for kv-oauth: missing key material is a startup error
export NETSCRIPT_AUTH_KV_OAUTH_KEY=<base64url-encoded-32-byte-secret>

export PORT=8094
```

> Provider presets fill the OIDC endpoints for you
>
> You rarely hand-type issuer/authorization/token/userinfo URLs. The
>
> kv-oauth
>
> package ships provider presets —
>
> github
>
> ,
>
> google
>
> ,
>
> gitlab
>
> ,
>
> discord
>
> ,
>
> slack
>
> ,
>
> spotify
>
> ,
>
> facebook
>
> ,
>
> twitter
>
> , plus tenant-based
>
> auth0
>
> ,
>
> okta
>
> ,
>
> awsCognito
>
> ,
>
> azureAd
>
> ,
>
> logto
>
> ,
>
> clerk
>
> — that encode the correct endpoints. You pass one to
>
> createKvOAuthBackend
>
> in Step 5.

## Step 5 — Compose the backend in code

When you wire the backend yourself — for a custom service entry or a test — the interactive `kv-oauth` backend is one `await` call. You pass a provider preset from `providers.*`, and you get back something that satisfies the `AuthBackendPort` seam that `@netscript/plugin-auth-core` defines (and, because it is `kv-oauth`, the optional `InteractiveFlowPort` too):

```ts
// services/auth/src/backend.ts
import { createKvOAuthBackend, getRequiredEnv, providers } from '@netscript/auth-kv-oauth';

// providers.google(...) is a preset that fills the OIDC endpoints for you.
export const backend = await createKvOAuthBackend({
  provider: providers.google({
    clientId: getRequiredEnv('NETSCRIPT_AUTH_CLIENT_ID'),
    clientSecret: getRequiredEnv('NETSCRIPT_AUTH_CLIENT_SECRET'),
    redirectUri: getRequiredEnv('NETSCRIPT_AUTH_REDIRECT_URI'),
  }),
});

// backend implements AuthBackendPort AND the optional InteractiveFlowPort,
// so the auth-api signin + callback endpoints are live on this backend.
console.log(backend.name); // 'kv-oauth'
```

```ts
// Same factory, but define the OIDC provider yourself when your IdP is
// not one of the built-in presets.
import { createKvOAuthBackend, defineOAuthProvider, getRequiredEnv } from '@netscript/auth-kv-oauth';

const provider = defineOAuthProvider({
  id: 'my-idp',
  clientId: getRequiredEnv('NETSCRIPT_AUTH_CLIENT_ID'),
  clientSecret: getRequiredEnv('NETSCRIPT_AUTH_CLIENT_SECRET'),
  authorizationEndpoint: getRequiredEnv('NETSCRIPT_AUTH_AUTHORIZATION_ENDPOINT'),
  tokenEndpoint: getRequiredEnv('NETSCRIPT_AUTH_TOKEN_ENDPOINT'),
  userInfoEndpoint: getRequiredEnv('NETSCRIPT_AUTH_USERINFO_ENDPOINT'),
  redirectUri: getRequiredEnv('NETSCRIPT_AUTH_REDIRECT_URI'),
  scopes: ['openid', 'profile', 'email'],
});

export const backend = await createKvOAuthBackend({ provider });
```

The core seam is small and contract-only. `@netscript/plugin-auth-core` defines the `AuthBackendPort` and the registry helpers that resolve one backend from many — these are the types the auth plugin composes against, confirmed on the package's public surface:

**@netscript/plugin-auth-core — the seam the backend satisfies**

| Name | Type | Description |
| --- | --- | --- |
| `AuthBackendPort` | `type` | The contract every backend implements — the auth-api surface is identical across all three backends because they all satisfy this port. |
| `createAuthBackendRegistry / resolveBackend` | `function` | Build a registry of named backends and resolve the single active one (DEFAULT_AUTH_BACKEND_NAME is the fallback). |
| `AuthSession` | `type` | The normalized session the store persists — id, subject, state, scopes, claims, issuedAt / expiresAt. |
| `createHmacSessionTokenCrypto` | `function` | HMAC-signs the opaque session token so the cookie value cannot be forged. |
| `authContractV1` | `contract` | The five-route auth contract: signin, signout, callback, session, me. |

## Step 6 — Verify a session

With Aspire running, the `auth-api` service binds **port 8094** and mounts the five auth endpoints under `/api/v1/auth/*`. On a fresh, unauthenticated request, `session` reports no active session — which proves the endpoint is wired even before you complete a login:

```sh
# Service is alive
curl http://localhost:8094/health/ready

# No session yet — confirms the endpoint is mounted and reachable
curl http://localhost:8094/api/v1/auth/session

# Identity endpoint: { "authenticated": false } (HTTP 200) before login
curl http://localhost:8094/api/v1/auth/me
```

To exercise the full interactive flow on `kv-oauth`, drive the redirect from a browser: open `POST /api/v1/auth/signin` (the service issues the provider redirect), authenticate with your provider, let it call back to `/api/v1/auth/callback`, then re-check the session with the cookie the flow set:

```sh
# After completing the browser sign-in, the __Host-ns_session cookie is set.
curl -b cookies.txt http://localhost:8094/api/v1/auth/session
curl -b cookies.txt http://localhost:8094/api/v1/auth/me
```

A successful `GET /api/v1/auth/me` after sign-in returns `{ authenticated: true, user, session }`. That round trip is the proof the backend is composed, the migration is applied, and the provider credentials are correct.

- [ ] `netscript plugin list` shows the `auth` plugin.
- [ ] `netscript db status` reports the `auth.prisma` migration applied.
- [ ] `NETSCRIPT_AUTH_BACKEND=kv-oauth` and the provider env vars are set.
- [ ] `curl http://localhost:8094/health/ready` succeeds.
- [ ] `curl http://localhost:8094/api/v1/auth/me` returns `{ "authenticated": false }` before login.

> Local smoke without real credentials
>
> If provider env is missing, the
>
> kv-oauth
>
> backend falls back to a non-functional local-default endpoint set so the service still boots and
>
> /health
>
> ,
>
> session
>
> , and
>
> me
>
> answer. Real
>
> signin
>
> /
>
> callback
>
> require genuine provider credentials — the fallback is a stub path, not a working login.

## What you built

Your workspace now has an identity layer: the `auth` plugin composed onto the interactive `kv-oauth` backend, the `auth.prisma` migration applied, and the `auth-api` service answering on `:8094` with the five-route contract. You proved the session endpoints are wired — the app can now tell a signed-in team member from a stranger. Next you give it something worth protecting: its own isolated database for team records.

[1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/) [3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/workspace/02-auth/_

---

# Workspace data

Your app can sign users in, but it has nothing of its own to store yet. This chapter gives the workspace its own data: a **second, isolated database** with its own Prisma schema, migration history, and generated client — separate from the primary Postgres the auth plugin migrated into. The reason to isolate it is the same reason teams isolate any domain: an independent lifecycle you can migrate, scale, and back up on its own. It also bounds the blast radius — a bad migration to your team schema cannot take the auth tables down with it, and vice versa.

What makes this a NetScript capability and not just "run two Postgres containers" is the **typed data layer**: one `netscript db add` scaffolds the datasource, joins it to the Aspire graph, and — after a single migrate/generate loop — hands you a fully typed Prisma client scoped to *that* datasource, with its own migration history. The isolation is real at the type level, not just the connection string, and the whole `db` toolchain is multi-database-aware, so every command takes a `--db` target rather than leaving you to juggle two schemas by hand.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)
2. [2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)
3. [3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)
4. [4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)
5. [5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

## What you will build

A second Postgres datasource named `workspace`, scaffolded by `netscript db add`, with its own `Member` and `Workspace` models, its own migration, and its own typed Prisma client. By the end you can import that client at `database/workspace/schema/.generated/client.server.ts` and query workspace records — fully independent from the primary database and the auth tables.

## Before you begin

You need the auth layer from [chapter 2](https://rickylabs.github.io/netscript/tutorials/workspace/02-auth/) and **Aspire running**. The second database is provisioned as its own container in the Aspire graph, so Docker must be up too. Confirm the primary is migrated and Aspire is live:

```sh
# In my-workspace/, with `aspire start` up in another terminal
netscript db status        # primary datasource is migrated (chapter 2)
docker info                # Docker engine is running
```

> A second database is a deliberate choice
>
> A second datasource is the right tool when you need an
>
> isolated
>
> data domain — a separate migration lifecycle and a datasource you can scale and back up independently. If you only wanted a new
>
> table
>
> , you would add a model to the primary schema instead. Adding a whole datasource means a second migration history and a second generated client to manage. This track adds one on purpose, to keep workspace records cleanly separate from auth.

> This split is how a real NetScript app stores its data
>
> A production context-accumulator chat application built on NetScript uses exactly this shape: one
>
> org-catalog
>
> datasource (Prisma-managed: who exists, which projects and channels there are) kept separate from the datastores each channel accumulates context into. Not everything is one database. The catalog answers "what is there and who belongs to it"; the domain data lives on its own lifecycle. Your
>
> workspace
>
> datasource here plays the catalog role for your team records.

## Step 1 — Scaffold the second database

From the workspace root, run `netscript db add <engine>`. The `--name` flag sets the **config key** the datasource is registered under — use `workspace` so it does not collide with the primary `postgres`:

```sh
# Add a second Postgres for workspace records. Registered under
# NetScript.Databases.workspace, scaffolded into database/workspace/.
netscript db add postgres --name workspace
```

In one pass, `db add` scaffolds a workspace at `database/workspace/` (its own `schema/schema.prisma`, `prisma.config.ts`, and `scripts/`), registers the datasource in `appsettings.json` under `NetScript.Databases.workspace`, adds it as a project member, and regenerates the Aspire config so the new container joins the resource graph.

> The engine is swappable
>
> This track uses
>
> postgres
>
> , but
>
> db add
>
> is polyglot: swap
>
> postgres
>
> for
>
> mysql
>
> ,
>
> mssql
>
> , or
>
> sqlite
>
> to scaffold that engine instead. Postgres, MySQL, and SQL Server each provision an Aspire container; SQLite is file-backed and adds no container resource. Keep
>
> postgres
>
> to follow the rest of this tutorial as written.

> The new datasource starts empty
>
> db add
>
> scaffolds the workspace and registers the datasource, but it does
>
> not
>
> run a migration or generate a client — the new
>
> database/workspace/schema/schema.prisma
>
> ships a starter schema and no
>
> .generated/
>
> directory yet. You run the migration loop yourself in Step 4, targeting the new datasource with
>
> --db
>
> .

## Step 2 — Restart Aspire so the container joins the graph

Because `db add` regenerated the Aspire config, the new database becomes a container in the resource graph. Restart the AppHost so it provisions:

```sh
cd aspire
aspire start
```

Open the dashboard at [https://localhost:18888](https://localhost:18888) and confirm the new `workspace` resource goes green alongside the existing `postgres` and `redis`.

> Restart is not optional
>
> The new container only appears because
>
> db add
>
> regenerated the Aspire helpers
>
> . If you skip the restart, the AppHost will not know about the datasource and the resource never shows up — and the migration in Step 4 has nothing to reach.

## Step 3 — Define the workspace models

Edit the second datasource's schema to hold workspace records. A `Workspace` row is a team; a `Member` row links a signed-in user (by their auth `subject`) to a workspace:

```prisma
// database/workspace/schema/schema.prisma — add these models
model Workspace {
  id        String   @id @default(cuid())
  name      String
  createdAt DateTime @default(now())
  members   Member[]
}

model Member {
  id          String    @id @default(cuid())
  // The auth Principal.subject from chapter 2 — the stable user identifier.
  subject     String
  role        String    @default("member")
  workspace   Workspace @relation(fields: [workspaceId], references: [id])
  workspaceId String
  createdAt   DateTime  @default(now())

  @@unique([workspaceId, subject])
}
```

The `subject` column is the link back to auth: it stores the `Principal.subject` value the auth backend resolves for a signed-in user, so a workspace member is "this auth identity, in this workspace."

## Step 4 — Migrate and generate the second datasource

The `netscript db` operations are **multi-database aware**: every one takes a `--db <target>` flag, where the target is a config key, a database name, or `all`. Point each command at the `workspace` datasource. Run these from the workspace root with `aspire start` up:

```sh
# Create + apply the first migration for the SECOND datasource only.
netscript db init --db workspace --name init
```

```sh
# Generate the Deno-runtime Prisma client + zod schemas into
# database/workspace/schema/.generated for the workspace datasource.
netscript db generate --db workspace
```

```sh
# Confirm the workspace datasource is migrated and in sync.
netscript db status --db workspace
```

Each datasource keeps its **own** migration history and generated client. Migrating `--db workspace` never touches the primary Postgres (or the auth tables), and vice versa.

> Omitting --db targets the primary
>
> A
>
> db
>
> command with no
>
> --db
>
> resolves to the
>
> primary
>
> datasource (the default Postgres the auth plugin migrated into). Always pass
>
> --db workspace
>
> when you mean the second one, or
>
> --db all
>
> to fan out across every registered datasource.

## Step 5 — Query the workspace client

After `db generate --db workspace`, the second datasource has its own typed client. Import it exactly like the primary — just from the new path. It is an independent `PrismaClient`, typed off the `Workspace`/`Member` models:

```ts
// services/workspace/src/db.ts
// The SECOND datasource generates its OWN client. Import it from its path.
import { PrismaClient as WorkspacePrisma } from '../../database/workspace/schema/.generated/client.server.ts';

export const workspaceDb = new WorkspacePrisma();

// Fully typed off the workspace schema — separate from the primary client.
const teams = await workspaceDb.workspace.findMany({ take: 20 });
console.log(teams.length);
```

> Import the right client
>
> The primary client lives at
>
> database/postgres/schema/.generated/client.server.ts
>
> ; the workspace client at
>
> database/workspace/schema/.generated/client.server.ts
>
> . They are distinct
>
> PrismaClient
>
> s — crossing the imports queries the wrong database. Re-run
>
> netscript db generate --db workspace
>
> after every schema edit, or your code is typed against the old shape.

## Extend — app-level org scoping

The data model above is **single-tenant**: every `Member` belongs to a `Workspace`, but there is no framework-managed notion of an organization that owns many workspaces. NetScript does not ship orgs, tenants, or RBAC roles — if you want multi-tenant scoping, you add it yourself, in your own schema and your own queries.

> Org scoping is your code, not a framework primitive
>
> To scope data to an organization, add an
>
> orgId
>
> column to your own models and filter every query by it — for example
>
> workspaceDb.workspace.findMany({ where: { orgId } })
>
> . NetScript has
>
> no
>
> first-class organization, tenant, or role primitive: the
>
> auth
>
> plugin resolves an identity (a
>
> Principal
>
> with a
>
> subject
>
> ), and the route-authz seam in
>
> chapter 5
>
> checks
>
> scopes
>
> , not org membership. Multi-tenant isolation, role hierarchies, and per-org access control are
>
> application logic you own
>
> — treat any
>
> orgId
>
> here as a column you maintain, not a behavior the framework enforces.

## Verify your progress

Confirm the second datasource is migrated and its client generated:

```sh
netscript db status --db workspace
ls database/workspace/schema/.generated/client.server.ts
```

`db status --db workspace` should report it migrated and in sync, and the generated client file should exist.

- [ ] `netscript db add postgres --name workspace` scaffolded `database/workspace/`.
- [ ] The `workspace` resource is green in the Aspire dashboard.
- [ ] `database/workspace/schema/schema.prisma` defines `Workspace` and `Member`.
- [ ] `netscript db status --db workspace` reports migrated and in sync.
- [ ] The generated client exists at `database/workspace/schema/.generated/client.server.ts`.

## What you built

Your workspace now owns its data: a second, isolated Postgres datasource with `Workspace` and `Member` models, its own migration history, and its own typed client — the same catalog-versus-domain split a real NetScript app runs on, cleanly separate from auth and the primary database. You also saw the boundary: org scoping is app-level, not a framework primitive. Next comes the moment this data model exists for — adding a member to a team — and you do it off the request path with a background job.

[2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/) [4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/workspace/03-workspace-data/_

---

# Provision with a background job

Think about when a team actually adds a member. Often it is the worst possible moment: something is broken, and the one person who understands the failing subsystem is not in the workspace yet. The admin who pages them should get an instant "done" — not sit on a request that is writing a membership row, warming a cache, and sending a welcome email before it answers. Provisioning is real work, and none of it should block the request that triggered it. This chapter moves that work off the request path: you add the **workers** plugin and author a `defineJobHandler` job that provisions a member into the workspace database from chapter 3, then trigger it over the Workers API on `:8091`. This is the same background-work seam a real NetScript app leans on — a production chat application built on NetScript runs its embedding and vision jobs through the same `workers` plugin.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)
2. [2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)
3. [3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)
4. [4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)
5. [5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

## What you will build

A `provision-member` background job: a handler authored with `defineJobHandler` that parses a payload, creates a `Member` in the workspace datasource, and returns a success result. By the end you trigger it over the Workers API and watch its execution appear in the executions feed and its trace in the Aspire dashboard.

## Before you begin

You need the workspace database from [chapter 3](https://rickylabs.github.io/netscript/tutorials/workspace/03-workspace-data/) with **Aspire running**. The workers plugin ships an API service and a background processor that Aspire orchestrates. Confirm the workspace datasource is ready:

```sh
# In my-workspace/, with `aspire start` up in another terminal
netscript db status --db workspace   # the workspace datasource from chapter 3
```

> Aspire first, then everything else
>
> The Workers API on
>
> :8091
>
> and its background processor are resources in the Aspire graph, and so is the
>
> dashboard on `:18888`
>
> where you read job traces. Start
>
> aspire start
>
> from
>
> aspire/
>
> before
>
> you add the plugin or trigger a job, and leave it running.

## Step 1 — Add the workers plugin

Add the workers plugin with its sample jobs so you have a working reference to read and adapt:

```sh
deno run -A packages/cli/bin/netscript-dev.ts plugin install worker --name workers --samples
netscript plugin list
```

The local-source contributor command lands the plugin at **`plugins/workers/`** — the canonical, config-referenced install location — and registers it in `netscript.config.ts`. On disk you get a `jobs/` directory (the job-authoring surface), a `services/src/` API on `:8091`, and `bin/combined.ts` (the background processor entrypoint).

> Author jobs in plugins/workers/
>
> A scaffold may also create a slimmer top-level
>
> workers/
>
> directory that stages a subset of files for the background processor. The real, config-referenced plugin lives at
>
> `plugins/workers/`
>
> — that is what
>
> netscript.config.ts
>
> points at and where you author jobs.

## Step 2 — Read the job-authoring API

A job is a function wrapped by `defineJobHandler`, given a stable `id`, and exported as the module default. Inside the handler you receive a `ctx`, do the work, and return a result built with `createSuccessResult` or `createFailureResult`. The sample `plugins/workers/jobs/health-check.ts` shows the shape and the `createJobTools(ctx)` helper surface:

```ts
import {
  createSuccessResult,
  createFailureResult,
  defineJobHandler,
} from '@netscript/plugin-workers-core';
import { createJobTools } from './job-tools.ts';

const handler = defineJobHandler(async (ctx) => {
  const { log } = createJobTools(ctx);
  log.info('doing work');

  // ...do the work, return a result...
  return createSuccessResult({ status: 'ok' });
});

export default Object.assign(handler, { id: 'my-job' as const });
```

```ts
// createJobTools(ctx) returns three helpers:
//
//   log.info / log.warn / log.error  — structured logging (REAL)
//   progress(percent, message)        — handler-side progress hook
//   trace.addEvent / trace.withChildSpan
//
// `id` is attached to the handler with Object.assign so the runtime
// registry can address the job by a stable string.
```

> How tracing actually works here (read this once)
>
> Two layers, and they behave differently.
>
> The framework instruments the job for you.
>
> When the background processor dispatches your handler it wraps the whole execution in real OpenTelemetry spans — dispatch, execution, duration, status — which show up in the
>
> Aspire dashboard
>
> automatically. What is
>
> not
>
> yet wired are the
>
> createJobTools(ctx)
>
> helpers you call
>
> inside
>
> the handler:
>
> trace.addEvent
>
> ,
>
> trace.withChildSpan
>
> , and
>
> progress(...)
>
> are currently no-op stubs in the scaffold (tracked debt). They will not throw and your code keeps working; they just do not yet add custom spans.
>
> log.*
>
> emits real structured logs in every case. For custom spans today, import from
>
> @netscript/telemetry
>
> directly.

## Step 3 — Scaffold the provision-member job

Start from the workers scaffold instead of creating the module by hand:

The workers CLI calls this the `add-job` verb; its shell syntax uses the spaced `add job` form:

> ns-workers is a shorthand you install once
>
> ns-workers
>
> is a name
>
> you
>
> give the workers plugin's CLI — the scaffold does not create it. Install it once, globally, and every
>
> ns-workers
>
> command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> ```
>
> Rather not install it? Each
>
> ns-workers <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-workers@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```sh
ns-workers add job provision-member
```

The command writes `workers/jobs/provision-member.ts` with the stable export, payload-schema block, and handler wrapper already in place, then refreshes the worker registry. Extend the generated payload schema with `workspaceId`, `subject`, and `role`; import `createFailureResult`; add the workspace Prisma import and client; then replace only the starter handler body with this application logic:

```ts
const handler = defineJobHandler(async (ctx) => {
  const parsed = PayloadSchema.safeParse(ctx.payload ?? {});
  if (!parsed.success) {
    return createFailureResult('invalid provision-member payload');
  }

  const { workspaceId, subject, role } = parsed.data;

  const member = await workspaceDb.member.create({
    data: { workspaceId, subject, role },
  });

  return createSuccessResult({ memberId: member.id, workspaceId, subject });
});
```

This is the whole job — small on purpose. The membership write happens off the request path, so the caller that triggered provisioning never waits for it.

> Triggering a job from your own code
>
> This chapter triggers the job through
>
> ns-workers
>
> (Step 5) so you can watch it run. From inside another NetScript runtime — a trigger or a scheduled job — you enqueue work with the builder's
>
> enqueueJob(...)
>
> step rather than an HTTP call; that path is covered in the
>
> webhook tutorial
>
> and the
>
> background-jobs capability
>
> . For this track, the runtime-backed CLI trigger is the clearest way to prove the job ran.

## Step 4 — Confirm the generated registry

The Workers API addresses jobs by `id`, so the scaffold command refreshes the generated registry before it returns. `provision-member` is already discoverable; do not run a second generation step.

> Restart the processor if it was already running
>
> If
>
> aspire start
>
> was up before you generated the registry, restart it (or let it hot-reload) so the Workers API and its background processor pick up the new job.

## Step 5 — Trigger the job

With Aspire up, the Workers API is live on **`:8091`**. Confirm the service is healthy and the job is registered, then trigger it by its `id`. You need a real `workspaceId` — create a `Workspace` row first (or use one your seed created) and pass its id:

```sh
# Health is still a plain liveness probe.
curl http://localhost:8091/health

# Inspect metadata, then enqueue through the durable workers API.
ns-workers show-job provision-member --json
ns-workers trigger provision-member \
  --payload='{ "workspaceId": "ws-1", "subject": "user:alice", "role": "member" }'
```

## Verify your progress

A trigger returns quickly because the work runs in the background. Confirm it actually executed by reading the executions feed:

```sh
ns-workers executions --limit=10 --json
```

You should see an execution record for `provision-member` with a succeeded status and a result payload carrying the new `memberId`. Then watch the same run in the Aspire **Traces** view at [https://localhost:18888](https://localhost:18888) — the framework emits the dispatch/execution span automatically.

**Workers API · :8091 (endpoints used here)**

| Name | Type | Description |
| --- | --- | --- |
| `GET /health` | `HTTP` | Liveness check for the Workers API service. |
| `ns-workers show-job {id} --json` | `CLI` | Inspect local job metadata by id. |
| `ns-workers trigger {id} --payload=…` | `CLI → :8091` | Enqueue an execution through the durable workers API. |
| `ns-workers executions --limit=10 --json` | `CLI → :8091` | Recent executions and their result payloads. |

- [ ] `netscript plugin list` shows the `workers` plugin.
- [ ] `plugins/workers/jobs/provision-member.ts` exists and exports an `id`.
- [ ] `ns-workers show-job provision-member --json` shows its metadata.
- [ ] `ns-workers trigger` returns quickly, and `ns-workers executions` shows it succeeded with a `memberId`.
- [ ] The job-dispatch trace appears in the Aspire Traces view.

> If the execution never appears
>
> - **Aspire isn't running** — the background processor that drains the queue is an Aspire resource. Start `aspire start` from `aspire/` and retry.
> - **The job isn't registered** — re-run `netscript generate plugins` so `provision-member` is in the registry, then restart Aspire.
> - **Wrong id** — the trigger path uses the job's `id` (`provision-member`), not its filename. Check `GET /api/v1/workers/jobs`.

## What you built

A `provision-member` background job that writes a workspace membership off the request path, triggered over the Workers API on `:8091` and observable in the Aspire dashboard. The caller gets an instant acknowledgment; the membership write happens reliably in the background. One gap remains, and it is the serious one: the `workspace` service itself still answers anyone who asks. Next you close the loop and make its routes fail closed.

[3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/) [5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/workspace/04-provision-job/_

---

# Protect routes with authz

Your `workspace` service still answers anyone — and after chapters 3 and 4 it fronts data with real consequences: the member list of a specific team. The route that returns it has to do two things at once, and both must be typed. It has to know *which* team is being asked for — a `workspace` id in the path, not a string you fish out of the URL by hand — and it has to **fail closed**: no credential means `401` before the handler runs, and a valid credential without the right scope means `403`.

This chapter builds exactly that pair. You declare the members route once as a **bound route contract** — `createRouteReference` / `defineRouteContract` + `bindRoutePattern` from `@netscript/fresh/route` — so the URL pattern, the typed `{ workspace }` path param, and the pagination search all come from a single object your service and any client share. Then you layer the `.withAuthn()` / `.withAuthz()` guard from `@netscript/service/auth` on top of it — the seam NetScript ships and proves in its own `builder-auth` test suite. The result is the combination this chapter's title promises: a **typed route and its authorization gate, from one source of truth.**

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)
2. [2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)
3. [3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)
4. [4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)
5. [5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

## What you will build

A guarded `GET /api/workspace/:workspace/members` route. One bound route contract declares its pattern, its typed `{ workspace }` path param, and its typed `limit`/`offset` pagination. The service registers that route, reads its params **through the contract** (no hand-parsing), and gates it with `.withAuthn()` (which turns each request into a `Principal`) and `.withAuthz()` (which decides whether that principal may reach the route). By the end an unauthenticated request returns `401 UNAUTHORIZED`, a request with the wrong scope returns `403 FORBIDDEN`, and a correctly-scoped request returns `200` with a typed member list — the exact three outcomes the framework's own test asserts.

## Prerequisites

- The `workspace` service and its typed contracts from [chapter 1](https://rickylabs.github.io/netscript/tutorials/workspace/01-scaffold/).
- The `Member` model and the `workspaceDb` client from [chapter 3](https://rickylabs.github.io/netscript/tutorials/workspace/03-workspace-data/) — the route lists members from that datasource.
- The route-authz seam is built into `@netscript/service`, and the route contract into `@netscript/fresh/route`; neither needs Aspire or the auth plugin to type-check, though you run the service under Aspire to exercise it live.

Confirm the workspace still builds before you change it:

```sh
# In my-workspace/
deno task check
```

> Two layers, one Principal
>
> The
>
> auth plugin
>
> (chapter 2) signs
>
> human users
>
> in and resolves their sessions. The seam in
>
> this
>
> chapter gates a
>
> service's own routes
>
> — it is provider-agnostic and built into
>
> @netscript/service
>
> . Both layers speak the same
>
> Principal
>
> type, so they compose: the plugin establishes identity, and a service's
>
> .withAuthn()
>
> turns a request into that
>
> Principal
>
> for an authorization decision.

## Step 1 — Declare the bound route contract

Before the guard, give the route a typed identity. A route contract from `@netscript/fresh/route` is the single source of truth for a route's shape: its pattern, its path params, and its search params. `createRouteReference` infers the `{ workspace }` param straight from the pattern; `defineRouteContract`

- `bindRoutePattern` add typed pagination search with safe defaults. Create the contract in the shared `contracts/` tree so the service and any future client import the *same* object:

```ts
// contracts/routes/workspace-members.ts
import {
  bindRoutePattern,
  createRouteReference,
  defineRouteContract,
  fallback,
  paginationSearchSchema,
} from '@netscript/fresh/route';
import { z } from 'zod';

/** The one place the members route pattern is written. */
export const MEMBERS_ROUTE_PATTERN = '/api/workspace/[workspace]/members';

/**
 * The bound members route: typed `{ workspace }` path param + typed
 * `limit`/`offset` pagination, all inferred from this one declaration.
 */
export const membersRoute = bindRoutePattern(
  defineRouteContract({
    // A path schema types the dynamic `[workspace]` segment as a non-empty id.
    pathSchema: z.object({ workspace: z.string().min(1) }),
    // paginationSearchSchema() gives limit/offset with computed defaults.
    searchSchema: paginationSearchSchema({ defaultLimit: 20 }).extend({
      // A junk ?role=banana falls back to undefined instead of throwing.
      role: fallback(z.enum(['member', 'admin']).optional(), undefined),
    }),
  }),
  MEMBERS_ROUTE_PATTERN,
);
```

`bindRoutePattern` returns one object with everything downstream needs: `membersRoute.parsePath(...)` and `membersRoute.parseSearch(...)` turn raw request params into typed values, and `membersRoute.href({ path: { workspace } })` builds the URL for a client — so a link and the handler that answers it can never disagree about the route's shape.

**@netscript/fresh/route — the bound route contract surface**

| Name | Type | Description |
| --- | --- | --- |
| `createRouteReference(pattern)` | `RouteReference` | Infers typed path params directly from a Fresh route pattern — `/api/workspace/[workspace]/members` yields `{ workspace: string }`. |
| `defineRouteContract({ pathSchema?, searchSchema? })` | `DefineRouteContract` | Declares typed path and search schemas; bind it to one or more concrete patterns. |
| `bindRoutePattern(contract, pattern)` | `BoundRouteContract` | Binds the contract to a pattern, returning one object with .parsePath / .parseSearch / .href. |
| `paginationSearchSchema(opts) / fallback(schema, default)` | `search schema` | Typed limit/offset with computed defaults; fallback() catches junk query strings instead of 500-ing the route. |

> One param name, two path syntaxes
>
> Route contracts use Fresh's
>
> [workspace]
>
> pattern syntax; a service (Hono) route registers the same segment as
>
> :workspace
>
> . It is the
>
> same param name
>
> either way — the contract owns the typed shape, and
>
> membersRoute.parsePath(c.req.param())
>
> in Step 3 bridges the runtime params the service router collected into that typed shape. You write the pattern once, in the contract.

## Step 2 — Build the authenticator and scope authorizer

Now the guard. Define the credentials and the scope rule. This mirrors the framework's own `builder-auth_test.ts`: a `read` credential carries the `workspace:read` scope, and the authorizer requires that scope on the members route. The rule matches the **same prefix** the contract declares, so what the contract types and what the guard protects stay in lockstep:

```ts
// services/workspace/src/auth.ts
import {
  createScopeAuthorizer,
  createStaticCredentialAuthenticator,
} from '@netscript/service/auth';

export const authenticator = createStaticCredentialAuthenticator({
  credentials: {
    read: {
      subject: 'user:reader',
      scopes: ['workspace:read'],
      roles: ['reader'],
    },
    write: {
      subject: 'user:writer',
      scopes: ['workspace:write'],
      roles: ['writer'],
    },
  },
});

export const authorizer = createScopeAuthorizer({
  rules: [{
    // Guards every /api/workspace/<id>/members request the contract addresses.
    match: (request) => request.path.startsWith('/api/workspace/'),
    requireScopes: ['workspace:read'],
  }],
});
```

**@netscript/service/auth — the route-authz surface**

| Name | Type | Description |
| --- | --- | --- |
| `createStaticCredentialAuthenticator(opts)` | `AuthenticatorPort` | Maps bearer tokens to principals — each credential carries a subject, scopes, and roles. Good for tests and machine-to-machine callers. |
| `createScopeAuthorizer(opts)` | `AuthorizerPort` | Rules of { match, requireScopes } — the principal must carry every required scope for a matched route. |
| `.withAuthn({ authenticator, protect?, allowAnonymous? })` | `builder stage` | protect defaults to ['/api']; allowAnonymous defaults to ['/health']. |
| `.withAuthz({ authorizer, denyByDefault? })` | `builder stage` | denyByDefault defaults to true — fail closed when no decision is reachable. |

## Step 3 — Register the typed route and layer the guard

Register the members route on the service builder, then apply `.withAuthz()` and `.withAuthn()`. The handler runs only for an authenticated, authorized caller — and it reads its params **through the contract**, so `workspace`, `limit`, and `offset` arrive typed, never hand-sliced from the URL:

```ts
// services/workspace/src/main.ts
import { createService } from '@netscript/service';
import type { Principal } from '@netscript/service/auth';
import { membersRoute } from '../../../contracts/routes/workspace-members.ts';
import { workspaceDb } from './db.ts'; // the chapter 3 workspace client
import { authenticator, authorizer } from './auth.ts';

type RouteCtx = {
  get(key: string): unknown;
  json(data: unknown): Response;
  req: { param(): Record<string, string>; url: string };
};

const app = createService({}, { name: 'workspace' })
  .route('get', '/api/workspace/:workspace/members', async (c: unknown) => {
    const ctx = c as RouteCtx;
    // .withAuthn injected the resolved principal; the handler only sees allowed callers.
    const principal = ctx.get('principal') as Principal;

    // Typed off the ONE route contract — no manual URL parsing.
    const { workspace } = membersRoute.parsePath(ctx.req.param());
    const { limit, offset } = membersRoute.parseSearch(new URL(ctx.req.url).searchParams);

    const members = await workspaceDb.member.findMany({
      where: { workspaceId: workspace },
      take: limit,
      skip: offset,
      orderBy: { createdAt: 'asc' },
    });

    return ctx.json({ workspace, limit, offset, subject: principal.subject, members });
  })
  .withAuthz({ authorizer })
  .withAuthn({ authenticator })
  .build();

export { app };
```

The route pattern the service registers (`:workspace`) and the contract's pattern (`[workspace]`) name the same segment; `membersRoute.parsePath(ctx.req.param())` is what turns the router's raw params into the typed `{ workspace }` the handler uses.

> Health stays public
>
> By default
>
> .withAuthn()
>
> protects
>
> /api
>
> and leaves
>
> /health
>
> anonymous — so liveness and readiness probes answer without a credential even under a guarded API prefix. That is why the service's
>
> /health
>
> endpoint kept working through every earlier chapter while
>
> /api/workspace/:workspace/members
>
> is now guarded.

## Test it out

The guard produces three distinct responses, each a real assertion in the framework's `builder-auth_test.ts`. Drive them against the running service — start it under Aspire (`aspire start` from `aspire/`), then call the route for team `ws-1`:

```sh
# No Authorization header -> authn rejects before the handler runs.
curl -i http://localhost:3001/api/workspace/ws-1/members

# HTTP/1.1 401 Unauthorized
# { "error": "UNAUTHORIZED", "message": "missing-credential" }
```

```sh
# 'write' authenticates (valid credential) but lacks workspace:read,
# so authz denies the scope-guarded route.
curl -i -H 'authorization: Bearer write' \
  http://localhost:3001/api/workspace/ws-1/members

# HTTP/1.1 403 Forbidden
# { "error": "FORBIDDEN", "message": "authz.missing-scope:workspace:read" }
```

```sh
# 'read' carries workspace:read -> authn resolves the principal, authz allows it.
# The contract parses ?limit=2 into a typed page.
curl -i -H 'authorization: Bearer read' \
  'http://localhost:3001/api/workspace/ws-1/members?limit=2'
```

The `200` body echoes the values the contract parsed — the typed `workspace` path param, the typed `limit`/`offset` page, the authenticated `subject`, and the member rows from chapter 3:

```json
{
  "workspace": "ws-1",
  "limit": 2,
  "offset": 0,
  "subject": "user:reader",
  "members": [
    { "id": "mem_01", "workspaceId": "ws-1", "subject": "user:alice", "role": "member" }
  ]
}
```

An empty `members` array is still a `200` — it means the guard passed and the team simply has no rows yet (provision one with the [chapter 4](https://rickylabs.github.io/netscript/tutorials/workspace/04-provision-job/) job). A `401` or `403` means the request never reached the query at all.

> Scope: route-level authz, not org/role RBAC
>
> .withAuthz()
>
> decides from a
>
> Principal
>
> 's
>
> scopes
>
> on a matched route. It is
>
> not
>
> organization-aware or role-hierarchy-aware: there is no framework-managed notion of "this user belongs to that org" or "admins inherit member permissions." A scope is a flat string the authenticator attached to the principal. The
>
> { workspace }
>
> path param tells you
>
> which
>
> team was requested, but confirming the caller may see
>
> that
>
> team is app-level logic from
>
> chapter 3
>
> — you filter your own queries by your own
>
> orgId
>
> and derive your own roles. The seam gates the route; the tenancy is yours.

## Verify your progress

The three `curl` calls above are the verification. The unauthenticated call must fail closed, and the scoped call must succeed with a typed body:

- [ ] `contracts/routes/workspace-members.ts` exports `membersRoute`, a bound route contract with a typed `{ workspace }` param and pagination search.
- [ ] `services/workspace/src/auth.ts` defines the authenticator and a scope authorizer.
- [ ] The `workspace` service registers `GET /api/workspace/:workspace/members` and applies `.withAuthn()` and `.withAuthz()`.
- [ ] The handler reads params via `membersRoute.parsePath(...)` / `.parseSearch(...)`, not by hand.
- [ ] An unauthenticated request returns `401 UNAUTHORIZED` (`missing-credential`).
- [ ] `Bearer write` returns `403 FORBIDDEN` (`authz.missing-scope:workspace:read`).
- [ ] `Bearer read` returns `200` with a body carrying `workspace`, `limit`, and `subject`.
- [ ] `GET /health` still answers without a credential.

## What you built

A guarded, typed members route: one bound route contract in `contracts/routes/workspace-members.ts` owns the pattern, the `{ workspace }` path param, and the pagination search; the `workspace` service registers that route, parses its params through the contract, and gates it with `.withAuthn()` and `.withAuthz()` — proven by a `401` for an anonymous request, a `403` for the wrong scope, and a `200` for a correctly-scoped one. That is the differentiator this chapter exists to show: the URL, its typed params, and its authorization gate are **not three hand-maintained facts that can drift** — they are one contract plus one guard, checked by the compiler and by the framework's own `builder-auth` test. You also saw the boundary: this is route-level scope authz, not org/role RBAC — the tenancy stays yours.

## Next Steps

- **Ship it.** [Chapter 6 · Deploy](https://rickylabs.github.io/netscript/tutorials/workspace/06-deploy/) runs the whole authenticated workspace locally under Aspire and takes it to production.
- **Reuse the contract on the client.** `membersRoute.href({ path: { workspace } })` builds the same URL a frontend link would call — see the typed route contract in action on a page in [the live-dashboard track](https://rickylabs.github.io/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/).
- **Go deeper on identity.** The [auth plugin guide](https://rickylabs.github.io/netscript/tutorials/workspace/02-auth/) covers resolving real human sessions into the `Principal` this guard authorizes.

[4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/) [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/workspace/05-route-authz/_

---

# Deploy locally

You have built every layer of the team workspace: scaffold, an identity layer, isolated team data, a provisioning job that never blocks the caller, and routes that fail closed. This final chapter runs the whole thing as one coherent system — the point where the app stops being a set of chapters and becomes something a team could actually sit inside. A single `aspire start` stands up Postgres, the Redis cache, your `workspace` service, the `auth-api` service on `:8094`, the Workers API on `:8091`, and every background processor — all wired together and visible in one dashboard. It is the **local** story, and this chapter is precise about exactly that: a complete observable stack on one machine, not a production deployer.

The one-command reach is the differentiator, and you hand-wrote none of it: `netscript init` generated the AppHost in Chapter 1, each plugin you installed since — `auth`, then `workers` — contributed its own service and processor to the resource graph, and one `aspire start` boots the whole thing with cross-references resolved into injected environment. Scaffold to a running, observable stack, with no orchestration wiring you maintain by hand.

1. [1 · Scaffold](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/01-scaffold/)
2. [2 · Auth](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/)
3. [3 · Workspace data](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)
4. [4 · Provision job](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/04-provision-job/)
5. [5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/)
6. [6 · Deploy](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/06-deploy/)

## What you will build

Your complete `my-workspace/` running under one Aspire AppHost: every service, plugin API, background processor, and backing container in a single resource graph, observable from the dashboard on `:18888` — including the `:8094` auth service you added in chapter 2. By the end you can read the whole running topology, including the exact port each resource bound, from one pane.

## Before you begin

You need everything from chapters 1–5: the scaffolded workspace, the `auth` plugin, the second database, the workers plugin and `provision-member` job, and the guarded `workspace` service. The AppHost was scaffolded by `netscript init` in chapter 1 (you did not pass `--no-aspire`). Confirm the orchestration entry point is on disk and the workspace type-checks:

```sh
# From the workspace root
ls aspire/apphost.mts aspire/aspire.config.json
deno task check
```

> The order is: scaffold → orchestrate → database
>
> Aspire is
>
> step 2
>
> , before any database command.
>
> netscript init
>
> wrote the
>
> aspire/
>
> AppHost;
>
> aspire start
>
> provisions Postgres and Redis and starts every process;
>
> only then
>
> do
>
> netscript db
>
> commands work, because they migrate
>
> through
>
> the running AppHost. The graph is derived from your installed plugins — adding the
>
> auth
>
> and
>
> workers
>
> plugins in earlier chapters is exactly why their services and processors now appear in it.

## Step 1 — Restore the AppHost SDK (once)

The AppHost runs on its own isolated Node runtime inside `aspire/`, so its dependency graph never leaks into your Deno workspace. Restore that runtime once per machine (and after an SDK bump):

```sh
cd aspire
aspire restore
```

## Step 2 — Start the whole graph

A single `aspire start` translates `appsettings.json` plus your plugin contributions into a coherent resource graph and boots all of it — infrastructure first, then services, plugin APIs, and background processors, with cross-references resolved into injected environment variables:

```sh
# Still inside aspire/. Boots the whole graph; prints the dashboard URL + a login token.
aspire start
```

When boot finishes, `aspire start` prints the dashboard address and a one-time login token. This is the graph your complete app stands up:

**The local resource graph aspire start brings up**

| Name | Type | Description |
| --- | --- | --- |
| `aspire (dashboard)` | `https://localhost:18888` | The Aspire dashboard — live resource list, console logs, structured logs, and traces. A login token is printed on start. |
| `OTLP collector` | `http://localhost:4318` | OpenTelemetry endpoint; framework spans (job dispatch/execution, scheduler runs) land here automatically. |
| `postgres` | `Container` | The primary datasource — the auth.prisma migration from chapter 2 lives here. |
| `workspace (second db)` | `Container` | The isolated workspace datasource from chapter 3, provisioned alongside the primary. |
| `redis` | `Container (cache)` | Redis cache — the default `--cache-backend`; Redis-compatible. Backs KV/queue workloads and the kv-oauth session store. |
| `workspace (service)` | `:3001` | Your guarded oRPC service from chapter 5 — /api/workspace requires a scoped principal, /health stays public. |
| `auth-api` | `:8094` | The auth plugin's service from chapter 2 — /api/v1/auth/* (signin, callback, signout, session, me). |
| `workers-api` | `:8091` | The Workers API from chapter 4 — triggers and inspects the provision-member job. |
| `background processors` | `executables (no port)` | The workers processor that drains the job queue — a separate process, not a thread in the API. |

> Plugin API ports are range-allocated
>
> The runtime plugins publish their APIs from the
>
> :8091–8099
>
> PLUGIN_API range, and services from the
>
> :3000–3099
>
> SERVICE range. The conventional assignments — workers
>
> :8091
>
> , sagas
>
> :8092
>
> , triggers
>
> :8093
>
> , auth
>
> :8094
>
> — are what a default workspace lands on, but the dashboard's resource list is the authority for the exact port each resource bound. Read it from there, not from memory.

## Step 3 — Use the dashboard

Open `https://localhost:18888`, paste the login token `aspire start` printed, and you have one pane over the running graph:

**Aspire dashboard surfaces**

| Name | Type | Description |
| --- | --- | --- |
| `Resources` | `tab` | Every container and executable above with status, endpoints, and the resolved environment. The authority for which port each resource bound. |
| `Console logs` | `tab` | stdout/stderr per resource — a failing auth-api or workers processor is one click away. |
| `Structured logs + Traces` | `tab` | Spans and structured logs correlated by traceparent across services — collected via the OTLP endpoint at :4318. |

## Verify your progress

With the graph up, walk the whole app end to end — the auth service, the guarded route, and the job:

```sh
# Auth service is up (chapter 2)
curl http://localhost:8094/health/ready

# The guarded route rejects an anonymous caller (chapter 5)
curl -i http://localhost:3001/api/workspace            # 401 UNAUTHORIZED

# ...and allows a correctly-scoped one
curl -i -H 'authorization: Bearer read' http://localhost:3001/api/workspace   # 200

# The Workers API is live (chapter 4)
curl http://localhost:8091/api/v1/workers/jobs         # provision-member appears
```

- [ ] `aspire restore` and `aspire start` succeed from inside `aspire/`.
- [ ] The dashboard on `:18888` lists `postgres`, `workspace` (db), `redis`, `workspace` (service), `auth-api`, and `workers-api` — all green.
- [ ] `curl http://localhost:8094/health/ready` succeeds.
- [ ] An anonymous `GET /api/workspace` returns `401`; `Bearer read` returns `200`.
- [ ] `GET /api/v1/workers/jobs` lists `provision-member`.

> Aspire is the LOCAL story — not a production deployer
>
> aspire start
>
> exists to make
>
> git clone
>
> → one command produce a complete, observable, correctly-wired stack on
>
> one machine
>
> . The Postgres and Redis it starts are throwaway Docker containers for dev convenience —
>
> not
>
> your production database or cache, and the
>
> kv-oauth
>
> session store and auth credentials here are local-dev values. For a remote target you point processes at managed infrastructure and let your platform own lifecycle; that is the
>
> Deploy
>
> recipe.

> Footguns when aspire start will not boot
>
> - **Docker not running.** Aspire provisions Postgres + Redis (and the second workspace db) through Docker; no daemon means the happy path does not start.
> - **Wrong directory.** `aspire restore` and `aspire start` run from inside `aspire/`; `netscript db` commands run from the workspace root.
> - **db command before aspire start.** Every `netscript db` command needs a live Postgres — bring the graph up first.
> - **Ports in use.** The dashboard wants `:18888`/`:18889` and OTLP `:4318`; services and plugin APIs claim the `:3000+` and `:8091–8099` ranges. A stale prior run holding a port blocks boot.

## What you built

The complete authenticated team-workspace backend, running locally as one orchestrated system: Postgres, an isolated workspace database, Redis, the guarded `workspace` service, the `auth-api` service on `:8094`, and the Workers API and its processor — all in one Aspire resource graph, observable from one dashboard. You walked the whole arc: a pluggable auth backend, a session, team data on its own catalog datasource, off-path provisioning, and a route-authz seam that fails closed — single-tenant by design, with org scoping an explicit app-level extension. The off-boarded contractor gets a `401`; the engineer you paged gets provisioned without anyone waiting on the write.

## Where to go next

- **Ship it remotely** → [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/) — the production companion: deployable units, managed backing services, and the `--no-aspire` path.
- **Go deeper on auth** → [Authentication capability](https://rickylabs.github.io/netscript/capabilities/auth/) and [The authentication model](https://rickylabs.github.io/netscript/explanation/auth-model/).
- **Understand the orchestrator** → [Orchestration with Aspire](https://rickylabs.github.io/netscript/explanation/aspire/).
- **Browse more recipes** → the [how-to guides](https://rickylabs.github.io/netscript/how-to/).

[5 · Route authz](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/05-route-authz/) [How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/)

_Canonical: https://rickylabs.github.io/netscript/tutorials/workspace/06-deploy/_

---

# All recipes

Recipes live inside their pillar in the sidebar — each area's **Recipes** section sits below the guides that teach the basics it assumes. This page is the cross-area index: every recipe in the docs, grouped by pillar, so you can scan the whole catalog in one place. Each one is goal-first — it starts from a concrete intent and ends with a command that proves the change works.

> One prerequisite spans almost every recipe
>
> Anything that touches Postgres, Redis/Garnet, or a plugin service expects Aspire to be running first. From your workspace:
>
> cd aspire && aspire start
>
> brings up the dependencies and the dashboard on
>
> `https://localhost:18888`
>
> before
>
> any
>
> netscript db
>
> command or service call. The recipes call this out where it matters, but it is the single most common missing step.

## Web Layer

- [Customize the Fresh UI](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/customize-fresh-ui/) — bring the dashboard components into your workspace with `ui:init` / `ui:add` and edit them directly.
- [Build a server-validated form](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/build-a-server-validated-form/) — route-bound form state, server validation, mutation, and success handling in one typed page definition with `definePage().withForm()`.
- [Build a desktop frontend](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/build-a-desktop-frontend/) — one Fresh frontend that runs as an ordinary browser app and gains native capabilities on the desktop.

## Services & SDK

- [Add a service](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/add-a-service/) — define a typed contract, implement the handlers, and confirm the service answers on `/api/rpc/*`.
- [Discover services](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/discover-services/) — call another plugin's or workspace member's typed service without hardcoding its address.
- [Expose OpenAPI & Scalar](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/expose-openapi-scalar/) — publish an OpenAPI document and browsable Scalar docs for a service.

## Background jobs

- [Run a polyglot task](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/run-a-polyglot-task/) — define a non-TypeScript script (Python, shell, .NET, any executable) as a task with a permission sandbox and run it through the executor.
- [Tune the worker runtime](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/tune-worker-runtime/) — trade throughput against isolation with concurrency, runner mode, per-task permissions, and timeouts/retries.
- [Restrict worker task permissions](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/restrict-worker-task-permissions/) — give every Deno task explicit permissions; an omitted permission object compiles to `--allow-all`.
- [Add a task runtime adapter](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/add-a-task-runtime-adapter/) — advanced: add a custom runtime adapter to the built-in task executor.

## Durable workflows

- [Build a validated ingestion queue](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/build-a-validated-ingestion-queue/) — a typed queue whose messages are schema-checked before they enter the queue and again before a consumer handles them.
- [Publish a durable stream](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/publish-a-durable-stream/) — let server-side state be subscribed to by browsers and other consumers through a durable stream service.

## AI & Agents

- [Build a durable chat](https://rickylabs.github.io/netscript/netscript/ai/how-to/build-a-durable-chat/) — an AI chat on a Fresh route whose transcript survives reload and reconnect, with one server-side tool.

## Data & Persistence

- [Database & migration](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/) — initialize, generate, seed, and inspect the Postgres schema with the `netscript db` commands.
- [Queue / KV / cron](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/queue-kv-cron/) — the reactive KV store, the durable queue, and cron schedules, including `--unstable-kv`.
- [Choose a queue provider](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/) — pick the right queue backend, and either let auto-discovery select one or pin one explicitly.
- [Use a second database](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/use-a-second-database/) — add a second Postgres, or a MySQL/SQL Server instance, alongside the default database.

## Identity & Access

- [Add authentication](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/add-authentication/) — install the official auth plugin, pick one active backend via `NETSCRIPT_AUTH_BACKEND`, migrate, and sign in.

## Orchestration & Runtime

- [Add a plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/) — install a first-party plugin, regenerate the registry, and verify the service answers.
- [Deploy locally with Aspire](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-local-aspire/) — run the full local resource graph from the generated Aspire AppHost.
- [Deploy](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy/) — the portability story: raw `deno task` entry points and the `--no-aspire` escape hatch when you provision dependencies yourself.
- [Deploy to Deno Deploy](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-deno-deploy/) — push a preview, promote to prod, and read status and logs with the first-class deploy command.
- [Graceful shutdown](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/graceful-shutdown/) — drain in-flight requests and jobs, run teardown hooks, and close connections on `SIGINT`/`SIGTERM`.
- [Roll out runtime overrides](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/roll-out-runtime-overrides/) — change a deployed behavior without rebuilding the workspace.
- [Author a plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/author-a-plugin/) — advanced: build a custom plugin with the same manifest and `mod.ts` contract the first-party plugins use.
- [Deno LSP code intelligence](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deno-lsp-code-intelligence/) — keep go-to-definition, hover, and diagnostics aligned across CLI and editors.

## Observability

- [Add OpenTelemetry](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/) — emit custom spans and structured logs, propagate `traceparent`, and read the traces in the Aspire dashboard.

---

Not sure which recipe you want? Name the outcome first. *"Users must sign in"* → [Add authentication](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/add-authentication/). *"This event should fan out to a background job"* → [Add a plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/). *"It has to run where there is no Aspire"* → [Deploy](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy/). The recipes are deliberately small and composable; most real features chain two or three of them.

_Canonical: https://rickylabs.github.io/netscript/how-to/_

---

# Background Processing

**Work that outlives the request, from one handler file.** In NetScript, moving work off the request path means authoring a single typed handler — the queue, retry policy, scheduler, execution history, trigger API, and OpenTelemetry traces come from the worker runtime, so there is no separate queue-and-worker stack to assemble (or to explain to an AI agent) before the first job runs.

Two page-level stories anchor this pillar. [Background jobs](https://rickylabs.github.io/netscript/background-processing/workers/) opens with a production one: a vision job that turns a pasted alert-email screenshot into structured diagnosis fields — and the two contract properties (queue-borne payloads, compute-only workers) that shaped it, plus a factual side-by-side with Trigger.dev and Temporal. [Polyglot tasks](https://rickylabs.github.io/netscript/background-processing/polyglot-tasks/) covers the step that is *not* TypeScript: an existing Python, .NET, or shell script that keeps its language and gains the same queue, retry, and trace behavior as everything else.

Background Processing covers worker tasks, queue providers, scheduled work, runtime adapters, and per-task permissions. Start here when work should run outside the request path but does not need the durable saga state model — for that, see [durable workflows](https://rickylabs.github.io/netscript/durable-workflows/).

[Overview & Concepts   Workers and queues  Worker tasks consume queued work with provider and runtime choices kept inside the leaf.](https://rickylabs.github.io/netscript/netscript/background-processing/workers/) [Quickstart   Polyglot transform  Run a task step from the ERP Sync tutorial.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/03-polyglot-transform/) [How-To   Queue, KV, and cron  Create the queue and scheduler loop used by background work.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/queue-kv-cron/) [How-To   Choose a queue provider  Select the provider that fits your local and deployed runtime.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/) [How-To   Run a polyglot task  Execute work in a non-TypeScript task runtime.](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/run-a-polyglot-task/) [API Reference   workers, queue, cron  Generated symbols for task, queue, scheduler, and watcher packages.](https://rickylabs.github.io/netscript/netscript/reference/workers/)

## Learn, do, look up

[Learn  ERP sync tutorial  An import job, a polyglot transform, and a queue-driven cron.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/) [Look up  `@netscript/workers` reference  Generated API reference. Related units: `queue`, `cron`, `watchers`.](https://rickylabs.github.io/netscript/netscript/reference/workers/) [Understand  The durability model  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/)

_Canonical: https://rickylabs.github.io/netscript/background-processing/_

---

# Background jobs — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/background-processing/how-to/_

---

# Add a task runtime adapter

`createDefaultTaskExecutor({ adapters, customAdapters })` lets you keep the built-in task executor while adding a controlled runtime adapter. Use this when a task must run through a host runtime that NetScript does not ship by default.

## Prerequisites

- A `TaskRuntimeAdapterLike` implementation.
- A task `type` string reserved for your adapter.
- A clear sandbox story for the external runtime.
- A test task that exercises stdout, stderr, timeout, and failure.

## Start from the real adapter contract

The executor consumes `TaskRuntimeAdapterLike`: `id`, `runtime`, `supports(task)`, and `execute(task, options)`.

```ts
import type {
  ResolvedTaskExecutionOptions,
  TaskDefinition,
  TaskResult,
  TaskRuntimeAdapterLike,
} from '@netscript/plugin-workers-core/executor';

export const nodeAdapter: TaskRuntimeAdapterLike = {
  id: 'node-runtime-adapter',
  runtime: null,

  supports(task: TaskDefinition): boolean {
    return task.type === 'node';
  },

  async execute(
    task: TaskDefinition,
    options: ResolvedTaskExecutionOptions,
  ): Promise<TaskResult> {
    const startedAt = new Date().toISOString();
    const started = performance.now();
    const command = new Deno.Command('node', {
      args: [task.entrypoint ?? '', ...(options.args ?? [])],
      cwd: options.cwd || undefined,
      env: options.env,
      stdout: 'piped',
      stderr: 'piped',
      signal: options.signal,
    });

    const output = await command.output();
    const duration = Math.round(performance.now() - started);
    const stdout = new TextDecoder().decode(output.stdout);
    const stderr = new TextDecoder().decode(output.stderr);

    options.onStdout?.(stdout);
    options.onStderr?.(stderr);

    return {
      taskId: task.id,
      status: output.success ? 'completed' : 'failed',
      exitCode: output.code,
      stdout,
      stderr,
      duration,
      success: output.success,
      error: output.success ? null : stderr || `node exited ${output.code}`,
      result: null,
      startedAt,
      completedAt: new Date().toISOString(),
      attempt: 1,
    };
  },
};
```

## Register the adapter

Use `customAdapters` when your task type is not one of the built-in `TaskType` values. The default adapter map still covers `deno`, `python`, `dotnet`, `shell`, `powershell`, `cmd`, and `executable`.

```ts
import { createDefaultTaskExecutor } from '@netscript/plugin-workers-core/executor';
import { nodeAdapter } from './node-adapter.ts';

const executor = createDefaultTaskExecutor({
  customAdapters: {
    node: nodeAdapter,
  },
  defaults: {
    cwd: Deno.cwd(),
    timeout: 300_000,
  },
});

const result = await executor.execute(
  {
    id: 'render-invoice',
    type: 'node',
    entrypoint: './tasks/render-invoice.mjs',
    args: ['--invoice', 'inv_123'],
  },
  {
    correlationId: 'invoice.inv_123',
    onStdout: (line) => console.log(line),
    onStderr: (line) => console.error(line),
  },
);

if (!result.success) {
  throw new Error(result.error ?? 'task failed');
}
```

## Run it end to end

The adapter and its registration above, run against a real task file. Copy the two files, then run the command sequence from the workspace root:

```js
// tasks/render-invoice.mjs — the external Node task the adapter spawns
const idx = process.argv.indexOf('--invoice');
const invoice = idx >= 0 ? process.argv[idx + 1] : 'unknown';
console.log(`rendered ${invoice}`);
```

```ts
// run-invoice.ts — register the adapter and execute one task
import { createDefaultTaskExecutor } from '@netscript/plugin-workers-core/executor';
import { nodeAdapter } from './node-adapter.ts';

const executor = createDefaultTaskExecutor({
  customAdapters: { node: nodeAdapter },
  defaults: { cwd: Deno.cwd(), timeout: 300_000 },
});

const result = await executor.execute(
  {
    id: 'render-invoice',
    type: 'node',
    entrypoint: './tasks/render-invoice.mjs',
    args: ['--invoice', 'inv_123'],
  },
  { correlationId: 'invoice.inv_123', onStdout: (line) => console.log(line) },
);

if (!result.success) throw new Error(result.error ?? 'task failed');
console.log('status', result.status, 'exit', result.exitCode);
```

```bash
# From the workspace root. --allow-run=node lets the adapter spawn the Node
# binary; --allow-read lets it read the task file. Node must be on PATH.
deno run --allow-run=node --allow-read run-invoice.ts
#   rendered inv_123
#   status completed exit 0
```

`supports(task)` matches `task.type === 'node'`, so the executor routes `render-invoice` to your adapter, which spawns `node ./tasks/render-invoice.mjs --invoice inv_123`, streams stdout through `onStdout`, and returns a `TaskResult` with `status: 'completed'` and `exitCode: 0`.

## Failure modes

- `supports(task)` returns `false`: the executor returns a failed `TaskResult` for unsupported runtimes.
- The host binary is missing: return a failed `TaskResult` with stderr or an error message.
- Timeout handling is adapter-owned. Respect `options.timeout` and `options.signal` in your adapter.
- Permission sandboxing is Deno-specific. Python, .NET, shell, PowerShell, cmd, executable, and custom adapters inherit the worker process OS permissions unless your adapter adds its own sandbox.

## Next steps

- Restrict Deno task permissions with [Restrict worker task permissions](https://rickylabs.github.io/netscript/background-processing/how-to/restrict-worker-task-permissions/).
- See built-in runtime behavior in [Run a polyglot task](https://rickylabs.github.io/netscript/background-processing/how-to/run-a-polyglot-task/).
- Look up the executor surface in [workers reference](https://rickylabs.github.io/netscript/reference/workers/).

[Roll out runtime overrides](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/roll-out-runtime-overrides/) [Build a server-validated form](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/build-a-server-validated-form/)

_Canonical: https://rickylabs.github.io/netscript/background-processing/how-to/add-a-task-runtime-adapter/_

---

# Restrict worker task permissions

Deno tasks are the worker runtime path that can receive Deno permission flags. Use `.permissions()` or `permissions` presets for every Deno task you ship; an omitted permission object compiles to `--allow-all`.

## Prerequisites

- A `deno` task definition.
- A list of hosts, files, env vars, and subprocesses the task actually needs.
- A production review step that rejects omitted permissions.

## Start from a restrictive preset

The public `permissions` constant exposes `minimal`, `none`, `network`, `filesystem`, `readOnly`, `subprocess`, `full`, and `allAccess`.

```ts
import { defineTask, permissions } from '@netscript/plugin-workers-core';

export default defineTask('charge-customer')
  .runtime('deno')
  .entrypoint('./charge-customer.ts')
  .permissions({
    ...permissions.network,
    net: ['api.stripe.com'],
    read: ['./config'],
    env: ['STRIPE_KEY'],
  })
  .build();
```

## Know the emitted flags

The Deno adapter helper `buildDenoPermissionFlags(permissions?)` emits these flags:

| Permission field | Example value | Emitted flag |
| --- | --- | --- |
| omitted object | `undefined` | `--allow-all` |
| `net` | `true` | `--allow-net` |
| `net` | `['api.stripe.com']` | `--allow-net=api.stripe.com` |
| `read` | `['./config']` | `--allow-read=./config` |
| `write` | `['./out']` | `--allow-write=./out` |
| `env` | `['STRIPE_KEY']` | `--allow-env=STRIPE_KEY` |
| `run` | `['git']` | `--allow-run=git` |
| `ffi` | `true` | `--allow-ffi` |
| `import` | `['jsr.io']` | `--allow-import=jsr.io` |

The helper does not emit a flag for `false` or an empty allowlist. Deny by leaving the field false or empty, not by passing a broad `true`.

## Runtime boundary

Only the `deno` task adapter converts `permissions` into Deno `--allow-*` flags. Python, .NET, shell, PowerShell, cmd, executable, and custom task adapters inherit the worker process OS permissions unless the adapter adds its own sandbox.

## Production checklist

- [ ] Every `deno` task has `.permissions(...)` or a declarative `permissions` object.
- [ ] `net`, `read`, `write`, `env`, and `run` use allowlists instead of `true` where possible.
- [ ] No task ships with `permissions.allAccess` unless it is explicitly accepted for that task.
- [ ] Non-Deno tasks are reviewed as OS-permission workloads, not Deno-sandboxed workloads.
- [ ] Timeout and retry settings are explicit for high-impact tasks.

## Failure modes

- Omitted permissions: the Deno adapter emits `--allow-all`.
- Missing required grant: the task fails at runtime with a Deno permission error.
- Overbroad `run`: the task can spawn any allowed command; prefer a command allowlist.
- Non-Deno runtime: `.permissions()` does not sandbox it.

## Next steps

- Tune process isolation with [Tune the worker runtime](https://rickylabs.github.io/netscript/background-processing/how-to/tune-worker-runtime/).
- Add a custom adapter with [Add a task runtime adapter](https://rickylabs.github.io/netscript/background-processing/how-to/add-a-task-runtime-adapter/).
- Look up worker symbols in [workers reference](https://rickylabs.github.io/netscript/reference/workers/).

[Publish a durable stream](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/publish-a-durable-stream/) [How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/)

_Canonical: https://rickylabs.github.io/netscript/background-processing/how-to/restrict-worker-task-permissions/_

---

# Run a polyglot task

Define a non-TypeScript script — a Python program, a shell script, a .NET tool, or any executable — as a NetScript task, give it a permission sandbox, and run it through the multi-runtime executor with its `stdout`/`stderr` captured and its result parsed.

alpha

This is the task-focused **DO** companion to the [polyglot tasks](https://rickylabs.github.io/netscript/capabilities/polyglot-tasks/) hub — read that first for the WHY (what a task is, how the subprocess seam works, the full `TaskResult` shape). This page wires one up.

## Prerequisites

**What you need before defining a task**

| Name | Type | Description |
| --- | --- | --- |
| `@netscript/plugin-workers-core` | `package (alpha)` | Provides defineTask (./builders) and createDefaultTaskExecutor (./executor). |
| `The target toolchain` | `host binary` | The interpreter the task spawns must exist on the worker HOST: python3 (or a venv / py on Windows), bash, pwsh/powershell, the .NET SDK, or your prebuilt binary. |
| `An entrypoint script` | `file path` | The script or executable to run, e.g. ./scripts/score.py. The task passes it input as argv + env, never stdin. |
| `(deno tasks only) a permission set` | `BuilderPermissions` | net/read/write/env/run/ffi/import. Enforced ONLY for the deno runtime — see the sandbox note below. |

## Steps

### 1. Define the task

`defineTask(id)` returns a typestate builder; the default `runtime` is `'deno'`, so call `.runtime(type)` to target another language. Input reaches the script as **argv** (`.args(...)`) and **environment variables** (`.env({...})`). `.build()` is only callable once an `.entrypoint(path)` (subprocess) or `.handler(fn)` (in-process) has been set.

```ts
// workers/tasks/score-batch.ts
import { defineTask } from '@netscript/plugin-workers-core/builders';

// python runtime, script entrypoint, explicit inputs.
export const scoreBatch = defineTask('score-batch')
  .runtime('python')
  .entrypoint('./scripts/score.py')
  .env({ MODEL_PATH: './models/scorer.pkl' })
  .args('--threshold', '0.8')
  .timeout(120_000) // ms; defaults to 300_000
  .build();

// Spawns: python3 -u ./scripts/score.py --threshold 0.8
```

```ts
// workers/tasks/rotate-logs.ts
import { defineTask } from '@netscript/plugin-workers-core/builders';

// shell runtime runs the entrypoint under bash (no -c).
export const rotateLogs = defineTask('rotate-logs')
  .runtime('shell')
  .entrypoint('./scripts/rotate-logs.sh')
  .args('--keep', '7')
  .timeout(30_000)
  .build();

// Spawns: bash ./scripts/rotate-logs.sh --keep 7
```

```ts
// workers/tasks/score-batch.ts — prefer a pinned venv over $PATH discovery
import { defineTask } from '@netscript/plugin-workers-core/builders';

export const scoreBatch = defineTask('score-batch')
  .runtime('python')
  .entrypoint('./scripts/score.py')
  // Resolution order: pythonConfig.pythonPath -> venvPath -> NETSCRIPT_PYTHON_PATH -> python3/py
  .metadata({ pythonConfig: { venvPath: './.venv' } })
  .build();
```

### 2. Write the script so its result crosses the process boundary

The subprocess returns structured data by printing **one JSON object as the last line of `stdout`**. Everything else on `stdout`/`stderr` is captured as logs. Print diagnostics to `stderr`; emit the JSON result last, with no trailing output.

```python
# scripts/score.py
import json, os, sys

# Input arrives as argv + env (NOT stdin).
threshold = float(sys.argv[sys.argv.index('--threshold') + 1])
model_path = os.environ['MODEL_PATH']

# ... do the work ...
scored = {'kept': 42, 'dropped': 3, 'threshold': threshold}

# Diagnostics go to stderr; the result is the LAST stdout line and must be a
# single JSON OBJECT (not an array) to populate result.result.
print('scoring complete', file=sys.stderr)
print(json.dumps(scored))
```

```bash
#!/usr/bin/env bash
# scripts/rotate-logs.sh
set -euo pipefail

keep="${2:-7}"
# ... rotate ...
echo "rotated logs, keeping ${keep}" >&2   # diagnostics -> stderr

# Last stdout line = JSON object result. Non-python runtimes are not -u'd, so
# flush by emitting the JSON as the final write with nothing after it.
printf '{"rotated": true, "kept": %s}\n' "$keep"
```

### 3. Run it through the workers CLI

> ns-workers is a shorthand you install once
>
> ns-workers
>
> is a name
>
> you
>
> give the workers plugin's CLI — the scaffold does not create it. Install it once, globally, and every
>
> ns-workers
>
> command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> ```
>
> Rather not install it? Each
>
> ns-workers <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-workers@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

`ns-workers run-task` resolves the generated task metadata and delegates to the same `MultiRuntimeTaskExecutor` used by the worker runtime. Pass argv and environment as JSON; stdout and stderr stream while the subprocess runs, followed by the complete `TaskResult`.

```sh
ns-workers run-task score-batch \
  --args='["--threshold","0.8"]' \
  --env='{"MODEL_PATH":"./models/scorer.pkl"}' \
  --timeout=120000 \
  --json
```

The programmatic `createDefaultTaskExecutor()` API remains available for runtime integrations and custom adapters; ordinary task execution no longer needs a hand-written runner module.

### 4. Sandbox a `deno` task with explicit permissions

The `deno` runtime is the **only** one NetScript sandboxes: the `.permissions({...})` set is translated into `--allow-*` flags on the `deno run` command line. For `python`, `shell`, `powershell`, `cmd`, `dotnet`, and `executable`, those keys are ignored — the subprocess inherits the worker process's OS-level access. Gate those at the OS layer instead.

```ts
// workers/tasks/parse-feed.ts — a sandboxed deno task (least privilege)
import { defineTask } from '@netscript/plugin-workers-core/builders';

export const parseFeed = defineTask('parse-feed')
  .runtime('deno') // the default; shown here for clarity
  .entrypoint('./scripts/parse-feed.ts')
  .permissions({
    net: ['api.example.com'], // -> --allow-net=api.example.com
    read: ['./feeds'],        // -> --allow-read=./feeds
    write: false,
    env: ['FEED_TOKEN'],      // -> --allow-env=FEED_TOKEN
  })
  .build();

// Spawns: deno run --allow-net=api.example.com --allow-read=./feeds --allow-env=FEED_TOKEN ./scripts/parse-feed.ts
```

> Omitting permissions on a deno task widens the sandbox to --allow-all
>
> Calling
>
> .build()
>
> on a
>
> deno
>
> task
>
> without
>
> .permissions(...)
>
> produces an
>
> --allow-all
>
> command line — full access. Always pass an explicit, least-privilege permission set for untrusted or third-party Deno task code. The
>
> permissions
>
> preset export (
>
> permissions.readOnly
>
> ,
>
> .network
>
> ,
>
> .none
>
> , …) gives you ready-made starting points.

## In-production pitfalls

> The result is the LAST stdout line — and only if it is a JSON object
>
> A trailing log line, a pretty-print, a JSON
>
> array
>
> , or a stray newline after the payload all make
>
> result.result
>
> null
>
> even though
>
> result.success
>
> is
>
> true
>
> . Emit the JSON object last, send everything else to
>
> stderr
>
> , and flush your own output — for Python the runtime runs
>
> python3 -u
>
> (unbuffered) for exactly this reason; other runtimes are not unbuffered.

> The runtime must exist on the worker host; read the exit code
>
> A missing interpreter surfaces as a failed task, not a thrown error. Exit code
>
> 127
>
> is reported as
>
> command not found
>
> and
>
> 126
>
> as
>
> command not executable
>
> ; both land in
>
> result.error
>
> with the first
>
> stderr
>
> line appended.
>
> cmd
>
> and (on Windows)
>
> powershell
>
> are platform-specific. A task that exceeds its
>
> timeout
>
> resolves with status
>
> timeout
>
> and exit code
>
> -1
>
> ; passing an already-aborted
>
> signal
>
> yields status
>
> cancelled
>
> before any process starts.

> Non-Deno runtimes are a trust boundary — there is no per-task sandbox
>
> A
>
> python
>
> /
>
> shell
>
> /
>
> executable
>
> task spawns an arbitrary process with the worker's OS privileges;
>
> .permissions(...)
>
> does nothing there. Pin entrypoints to known scripts, prefer a pinned interpreter or venv (
>
> pythonConfig.venvPath
>
> ) over
>
> $PATH
>
> discovery, and never interpolate untrusted input into
>
> args
>
> or the entrypoint path. Trace context (
>
> TRACEPARENT
>
> /
>
> TRACESTATE
>
> /
>
> CORRELATION_ID
>
> ) is injected into the subprocess environment so cross-runtime spans stitch together; env precedence is
>
> Deno.env
>
> < task
>
> env
>
> < call
>
> options.env
>
> .

> Alpha surface
>
> NetScript is in alpha; the polyglot task API can still shift. Treat the import subpaths (
>
> /builders
>
> ,
>
> /executor
>
> ) and the runtime-specific
>
> metadata
>
> configs as the current shape, and pin the version you build against.

## See also

[Polyglot tasks](https://rickylabs.github.io/netscript/netscript/background-processing/polyglot-tasks/)

[Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/)

[workers](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[Tune the worker runtime](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/tune-worker-runtime/) [Graceful shutdown](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/graceful-shutdown/)

_Canonical: https://rickylabs.github.io/netscript/background-processing/how-to/run-a-polyglot-task/_

---

# Tune the worker runtime

Trade throughput against isolation by tuning four real knobs — worker **concurrency**, the **runner mode**, per-task **Deno permissions**, and **timeouts/retries** — without touching a single job handler.

The same `process-payment` handler runs unchanged whether you give it one in-process slot or ten subprocess-isolated workers. Everything below is a deployment setting: it lives in `config/official-plugins/mod.ts` (`defineWorkers(...)`), in per-task runtime config, or in an environment variable read by the worker entrypoint. See [Background jobs](https://rickylabs.github.io/netscript/capabilities/background-jobs/) for the handler-authoring side.

## Prerequisites

**What you need before tuning**

| Name | Type | Description |
| --- | --- | --- |
| `workers plugin` | `plugins/workers/` | Public install: netscript plugin install @netscript/plugin-workers. Local contributor samples: deno run -A packages/cli/bin/netscript-dev.ts plugin install worker --name workers --samples. The :8091 API enqueues; a separate background process executes. |
| `config/official-plugins/mod.ts` | `defineWorkers(...)` | The generated worker config block — where concurrency, queueProvider, and per-topic scaling live. |
| `@netscript/plugin-workers-core/config` | `import` | defineWorkers, defineJobs, and the WorkersConfig / ScalingConfig / TaskConfig types. |
| `Aspire up (for live runs)` | `cd aspire && aspire start` | The background runner needs Postgres + KV. Aspire injects the worker env vars; see Production pitfalls. |

## Knob 1 — Default concurrency

`concurrency` on the workers config is the size of the Web Worker pool the runner spins up: each slot is its own V8 isolate, so raising it buys parallelism at roughly 20–40 MB per isolate. The schema default is `2`.

Show the type before the call site:

**WorkersConfigData — top-level worker config (@netscript/plugin-workers-core/config)**

| Name | Type | Description |
| --- | --- | --- |
| `concurrency` | `number` | Default worker pool size (V8 isolates running jobs in parallel). Schema default 2. |
| `queueProvider` | `'auto' \| 'deno-kv' \| 'redis' \| 'postgres' \| 'amqp'` | Queue backend. 'auto' resolves one for you. Default 'auto'. |
| `queueName` | `string` | Queue the runner consumes from. Default 'jobs'. |
| `jobsDir / tasksDir` | `string` | Directories scanned for default-exported job and task modules. Defaults ./workers/jobs and ./workers/tasks. |
| `groups` | `WorkerGroupData[]` | Per-topic worker groups, each with its own scaling and retention (Knob 2). |
| `enabled` | `boolean` | Whether workers run at all. Default true. |

```ts
// config/official-plugins/mod.ts
import { defineWorkers } from '@netscript/plugin-workers-core/config';

export const workers = defineWorkers({
  jobsDir: './workers/jobs',
  tasksDir: './workers/tasks',
  queueProvider: 'auto',
  queueName: 'jobs',
  concurrency: 4, // pool size: 4 isolates → ~80-160 MB. Raise for throughput, lower to bound memory.
  enabled: true,
  groups: [],
});
```

## Knob 2 — Per-topic scaling (concurrency + mode)

Different topics deserve different parallelism. A `WorkerGroup` binds a queue `topic` to its own `scaling` policy, so you can run a hot `webhooks` topic at concurrency 10 while a heavy `reports` topic stays at 1. The `mode` selects whether the worker and scheduler share one runner (`combined`) or run as separate processes (`distributed`).

**ScalingConfigData — per-topic scaling (WorkerGroupData.scaling)**

| Name | Type | Description |
| --- | --- | --- |
| `concurrency` | `number` | Max concurrent workers for this topic. Minimum 1, schema default 2. |
| `mode` | `'combined' \| 'distributed'` | Runner deployment: one combined runner vs. distributed runners. Default 'combined'. |

**TopicRetentionConfigData — per-topic execution retention (WorkerGroupData.retention)**

| Name | Type | Description |
| --- | --- | --- |
| `kvDays` | `number` | Days execution history stays in KV. Minimum 1, schema default 7. |
| `dbDays` | `number` | Days execution history stays in the database. Minimum 1, schema default 90. |

```ts
// config/official-plugins/mod.ts
import { defineWorkers } from '@netscript/plugin-workers-core/config';

export const workers = defineWorkers({
  jobsDir: './workers/jobs',
  tasksDir: './workers/tasks',
  queueProvider: 'auto',
  queueName: 'jobs',
  concurrency: 2,
  enabled: true,
  groups: [
    {
      topic: 'webhooks',
      scaling: { mode: 'combined', concurrency: 10 }, // burst-tolerant ingest
      retention: { kvDays: 7, dbDays: 90 },
      jobs: [
        {
          id: 'process-webhook-payload',
          name: 'Process Webhook Payload',
          entrypoint: './process-webhook-payload.ts',
          timeout: 30_000,
          maxRetries: 3,
          tags: ['webhook'],
        },
      ],
    },
  ],
});
```

## Knob 3 — The per-task Deno worker runtime & permissions

A **polyglot task** (`defineTask`, or a `TaskConfig` entry in `workers/runtime/`) runs as a spawned process. For the `deno` runtime, the task's `permissions` object is compiled **directly into the child `deno run` command's `--allow-*` flags** — a `deno` task with no `permissions` set falls back to `--allow-all`, so set them deliberately. The shape mirrors Deno's permission model: each field is `boolean` (grant/deny all) or a `string[]` allowlist.

**WorkerConfigPermissions — per-task Deno grants (compiled to --allow-* flags)**

| Name | Type | Description |
| --- | --- | --- |
| `net` | `boolean \| string[]` | Network access. true → --allow-net; ['api.stripe.com'] → --allow-net=api.stripe.com. |
| `read` | `boolean \| string[]` | Filesystem read. Pass a path allowlist to scope it. |
| `write` | `boolean \| string[]` | Filesystem write. Scope to an output dir in production. |
| `env` | `boolean \| string[]` | Environment variable access. |
| `run` | `boolean \| string[]` | Subprocess access (--allow-run). Needed when the task shells out. |
| `ffi` | `boolean` | Foreign-interface access (--allow-ffi). Leave false unless a native binding is required. |
| `import` | `string[]` | Allowed specifiers for dynamic imports (--allow-import=…). |

**TaskConfig — runtime, timeout & retry knobs (@netscript/plugin-workers-core/config)**

| Name | Type | Description |
| --- | --- | --- |
| `type` | `'deno' \| 'python' \| 'dotnet' \| 'cmd' \| 'powershell' \| 'shell' \| 'executable'` | Runtime that executes the task. Each maps to a runtime adapter. Default 'deno'. |
| `timeout` | `number` | Execution timeout in ms. Schema default 300000 (5 min). |
| `maxRetries` | `number` | Max retry attempts. Schema default 1. |
| `retryDelay` | `number` | Delay between retries in ms. Schema default 1000. |
| `maxConcurrency` | `number` | Max concurrent runs of this one task. Schema default 1. |
| `priority` | `number` | Dispatch priority 0–100. Schema default 50. |
| `permissions` | `WorkerConfigPermissions` | Deno grants for the task (above). Omit on a 'deno' task and it runs with --allow-all. |

The framework also ships named presets so you do not hand-roll the object. `permissions` from `@netscript/plugin-workers-core` exposes `minimal`, `none`, `network`, `filesystem`, `readOnly`, `subprocess`, `full`, and `allAccess`.

Start a new Deno task from the CLI, then tune the generated builder instead of creating its file by hand. The `add-task` verb uses the spaced `add task` shell syntax:

> ns-workers is a shorthand you install once
>
> ns-workers
>
> is a name
>
> you
>
> give the workers plugin's CLI — the scaffold does not create it. Install it once, globally, and every
>
> ns-workers
>
> command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> ```
>
> Rather not install it? Each
>
> ns-workers <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-workers@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```sh
ns-workers add task charge-customer --runtime=deno
```

For a non-Deno entrypoint, choose its runtime and path explicitly, for example `ns-workers add task sync-report --runtime=python --entrypoint=scripts/sync-report.py`.

```ts
// workers/tasks/charge-customer.task.ts
import { defineTask } from '@netscript/plugin-workers-core';

// Grant only what the task needs: outbound to Stripe, read its config, nothing else.
export default defineTask('charge-customer')
  .runtime('deno')
  .entrypoint('./charge-customer.ts')
  .timeout(30_000)
  .retry(3)
  .permissions({ net: ['api.stripe.com'], read: ['./config'], env: ['STRIPE_KEY'] })
  .build();
```

```ts
// workers/tasks/sync-report.task.ts
import { defineTask, permissions } from '@netscript/plugin-workers-core';

// 'network' preset = net + env only; spread to tighten one field further.
export default defineTask('sync-report')
  .runtime('deno')
  .entrypoint('./sync-report.ts')
  .timeout(120_000)
  .permissions({ ...permissions.network, read: ['./data'] })
  .build();
```

```json
// workers/runtime/tasks/v1.0.0.json — declarative, no rebuild
{
  "version": "1.0.0",
  "tasks": [
    {
      "id": "charge-customer",
      "name": "Charge Customer",
      "runtime": "deno",
      "entrypoint": "./charge-customer.ts",
      "timeout": 30000,
      "maxRetries": 3,
      "permissions": { "net": ["api.stripe.com"], "env": ["STRIPE_KEY"] }
    }
  ]
}
```

> Jobs have their own timeout/retry defaults
>
> A
>
> job
>
> (
>
> JobConfig
>
> ) and a
>
> task
>
> (
>
> TaskConfig
>
> ) carry the same permission shape but
>
> different
>
> schema defaults: a job defaults to
>
> timeout: 60000
>
> (60s) and
>
> maxRetries: 3
>
> , while a task defaults to
>
> timeout: 300000
>
> (5 min) and
>
> maxRetries: 1
>
> . Set both explicitly in production rather than relying on the default that happens to apply.

## Knob 4 — Runner pool size at the process level

The numbers above configure *definitions*. The actual pool the background process spins up is read from an environment variable when `plugins/workers/bin/combined.ts` (or `worker.ts`) starts. That entrypoint reads **`WORKERS_CONCURRENCY`** (default `1`) and passes it to the Web Worker pool.

```bash
# Override the running pool size for the background worker process.
WORKERS_CONCURRENCY=8 deno run -A plugins/workers/bin/combined.ts
```

> Two concurrency env vars — know which one wins
>
> There are
>
> two
>
> concurrency env names in play and they are
>
> not
>
> the same variable. The worker entrypoint (
>
> plugins/workers/bin/runtime.ts
>
> ) reads
>
> WORKERS_CONCURRENCY
>
> (note the
>
> S
>
> ) and defaults it to
>
> 1
>
> . The Aspire contribution, however, declares and injects
>
> WORKER_CONCURRENCY
>
> (no S, value
>
> 2
>
> ) via its
>
> concurrencyEnvVar
>
> . Under
>
> aspire start
>
> today, the injected
>
> WORKER_CONCURRENCY
>
> does
>
> not
>
> feed the entrypoint's
>
> WORKERS_CONCURRENCY
>
> read, so the process pool falls back to its default. Set
>
> WORKERS_CONCURRENCY
>
> explicitly on the background resource if you need a specific pool size, and treat the per-topic
>
> scaling.concurrency
>
> in
>
> defineWorkers
>
> as the durable, config-driven control. This naming seam is a known rough edge.

## Choosing a runner mode

How a handler is isolated is the `WORKER_RUNTIMES` tunable — three modes, same handler. The scaffold default is the Web Worker isolate path (one V8 isolate per pool slot).

**WORKER_RUNTIMES — runner isolation modes (WorkerRuntime type)**

| Name | Type | Description |
| --- | --- | --- |
| `in-process` | `WorkerRuntime` | Handler runs in the same process. Lowest overhead, no isolation. Best for tests, compiled single-binary deploys, single-tenant local composition. |
| `web-worker` | `WorkerRuntime` | Each pool slot is its own Web Worker / V8 isolate (~20-40 MB). The scaffold default; pool size = concurrency. Keep it low to bound memory. |
| `subprocess` | `WorkerRuntime` | Handler runs in a spawned subprocess. Strongest process isolation; only Deno tasks get permission sandboxing through .permissions(). Python, .NET, shell, PowerShell, and cmd inherit the worker process's OS permissions. |

## In-production pitfalls

> A 'deno' task with no permissions runs --allow-all
>
> The Deno runtime adapter (
>
> buildDenoPermissionFlags
>
> ) returns
>
> --allow-all
>
> when a task's
>
> permissions
>
> object is absent. That is convenient for local scaffolding and dangerous in production: an unpinned task can read your whole disk and reach any host. Always set an explicit
>
> permissions
>
> object (or a tightened preset) on every
>
> deno
>
> task you ship. Path-scope
>
> read
>
> /
>
> write
>
> and host-scope
>
> net
>
> rather than passing bare
>
> true
>
> .

> Concurrency is a memory multiplier
>
> Each
>
> web-worker
>
> slot is a separate V8 isolate at roughly 20–40 MB. A
>
> concurrency
>
> of 20 is up to ~800 MB of isolates before your jobs allocate a byte. Raise concurrency to chase throughput, but profile memory under load and prefer
>
> per-topic
>
> scaling so a hot topic does not starve the rest of the host. Drop to
>
> in-process
>
> for tests and compiled single-binary deploys where isolation is not worth the per-isolate cost.

> Timeouts and retries interact — bound them together
>
> A task with
>
> timeout: 300000
>
> and
>
> maxRetries: 3
>
> can occupy a worker slot for up to ~15 minutes of wall time before it gives up, and each retry waits
>
> retryDelay
>
> first. Under a saturated pool that is real head-of-line blocking. Size
>
> timeout
>
> to the work, keep
>
> maxRetries
>
> small for slow tasks, and pair retries with an
>
> idempotencyKey
>
> on enqueue so a re-delivery after a forced restart does not double-charge. See
>
> Choose a queue provider
>
> for delivery semantics.

## See also

[Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/)

[Polyglot tasks](https://rickylabs.github.io/netscript/netscript/background-processing/polyglot-tasks/)

[Choose a queue provider](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/)

[Run a polyglot task](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/run-a-polyglot-task/)

[workers](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[Choose a queue provider](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/) [Run a polyglot task](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/run-a-polyglot-task/)

_Canonical: https://rickylabs.github.io/netscript/background-processing/how-to/tune-worker-runtime/_

---

# Polyglot tasks

**Keep the script, gain the runtime.** A working Python, .NET, or shell step becomes a queued, retried, traced unit of work by declaring it with `defineTask` — the script itself does not change, and nothing about your platform has to stop being TypeScript for one step that is not.

A **polyglot task** runs non-TypeScript work — a Python script, a .NET program, a shell or PowerShell script, or any executable — as a **managed subprocess** spawned by the worker runtime. NetScript hands the task its input as command-line arguments and environment variables, captures every line of `stdout`/`stderr`, parses a final JSON line into a structured result, and normalizes the exit code into a `TaskResult`. It is the escape hatch for the moments your platform is otherwise all-TypeScript: an ML model in Python, a legacy .NET DLL, a system `pwsh` script. alpha

![The worker runtime resolves a TaskDefinition to a runtime adapter, which builds an argv and spawns a python/node/dotnet subprocess; input flows in as args and env, the subprocess streams stdout/stderr back, and the last JSON line of stdout becomes the structured result returned to the queue and database.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/polyglot-task-execution.svg)

*A task is dispatched to a runtime adapter that spawns a subprocess. Input arrives as argv + env; the last JSON line of stdout is parsed into the result; the exit code, captured logs, and duration become a TaskResult.*

The typical story is an import pipeline with one step that already exists in another language: a legacy-data transform owned by a Python script, say, sitting in the middle of an otherwise-TypeScript flow. Rewriting it buys nothing; running it ad hoc loses the queue, retry, and trace behavior every other step has. Declaring it as a task resolves that tension — the [ERP Sync tutorial](https://rickylabs.github.io/netscript/tutorials/erp-sync/03-polyglot-transform/) walks exactly this step, and trace context is injected into the subprocess environment so the Python span stitches into the same trace as the TypeScript steps around it.

## What it is

A **job** runs in-process TypeScript on a worker; a **task** runs a *subprocess* in another runtime. Tasks share the worker plugin's queue, retry, and telemetry machinery with [background jobs](https://rickylabs.github.io/netscript/background-processing/workers/) — the difference is purely the execution surface. The `MultiRuntimeTaskExecutor` keeps a map of **runtime adapters** (one per `TaskType`) and dispatches a `TaskDefinition` to the adapter that supports its `type`. Each adapter builds an `argv` for its runtime (e.g. `python3 -u script.py …`, `pwsh -File script.ps1 …`) and runs it through a Dax-backed process runner that streams output and times the process out. This page covers that subprocess seam; for in-process TS handlers, runtime modes, and the queue lifecycle, start at [background jobs](https://rickylabs.github.io/netscript/background-processing/workers/).

> Use this when
>
> Reach for a polyglot task when the work
>
> must
>
> run in another runtime — a Python data/ML script, a .NET tool, an existing shell or PowerShell automation, or a prebuilt binary — and you want it queued, retried, traced, and result-captured like any other unit of work. If the work is plain TypeScript, use an in-process
>
> background job
>
> instead — it avoids a process spawn entirely.

## Learn → / Do →

[Learn — Workers track  Tutorial Track C builds the worker plugin end to end; lesson 03 adds a polyglot task with explicit permissions.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/)

[Do — Run a polyglot task  Task recipe: define a python (or shell) task, wire its entrypoint and permissions, and execute it through the runtime.](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/run-a-polyglot-task/)

[Understand — Background jobs  The queue, worker-runtime modes, retry, and shutdown machinery that polyglot tasks share with in-process jobs.](https://rickylabs.github.io/netscript/netscript/background-processing/workers/)

## Minimal example

A task is authored with the `defineTask` typestate builder, then run through the default multi-runtime executor. The builder's default `runtime` is `'deno'`; call `.runtime(type)` to target another language. Input reaches the script as **argv** (`.args(...)`) and **environment variables** (`.env({...})`); the script returns a result by writing a single JSON object as the **last line of `stdout`**.

```ts
// workers/tasks/score-batch.ts
import { defineTask } from '@netscript/plugin-workers-core/builders';
import { createDefaultTaskExecutor } from '@netscript/plugin-workers-core/executor';

// Build a task definition: python runtime, script entrypoint, explicit inputs.
const scoreBatch = defineTask('score-batch')
  .runtime('python')
  .entrypoint('./scripts/score.py')
  .env({ MODEL_PATH: './models/scorer.pkl' })
  .args('--threshold', '0.8')
  .timeout(120_000) // ms; defaults to 300_000
  .build();

// The executor resolves the python adapter and spawns: python3 -u ./scripts/score.py --threshold 0.8
const executor = createDefaultTaskExecutor();
const result = await executor.execute(scoreBatch, {
  onStdout: (line) => console.log('[score]', line),
});

if (result.success) {
  // result.result is the parsed JSON object from the LAST stdout line, or null.
  console.log('scored', result.result);
} else {
  console.error('task failed', result.exitCode, result.error);
}
```

```python
# scripts/score.py
import json, os, sys

# Input arrives as argv + env (NOT stdin).
threshold = float(sys.argv[sys.argv.index('--threshold') + 1])
model_path = os.environ['MODEL_PATH']

# ... do the work ...
scored = {'kept': 42, 'dropped': 3, 'threshold': threshold}

# Any prior prints become captured logs. The result is the LAST line of stdout,
# and must be a single JSON object (not an array) to populate result.result.
print('scoring complete', file=sys.stderr)
print(json.dumps(scored))
```

> How input and output cross the process boundary
>
> Input is passed as
>
> command-line arguments
>
> (
>
> args
>
> ) and
>
> environment variables
>
> (
>
> env
>
> ) — there is no JSON-over-stdin channel. The runtime merges
>
> Deno.env
>
> , the task's
>
> env
>
> , and the call's
>
> options.env
>
> , and injects
>
> TRACEPARENT
>
> ,
>
> TRACESTATE
>
> , and
>
> CORRELATION_ID
>
> for trace propagation. Output is the reverse: the subprocess returns a structured value by printing
>
> one JSON object as the final line of `stdout`
>
> ; the runtime parses that line into
>
> result.result
>
> (a non-object or non-final-line value yields
>
> null
>
> ). All other lines are captured into
>
> stdout
>
> /
>
> stderr
>
> and streamed to the
>
> onStdout
>
> /
>
> onStderr
>
> /
>
> onLog
>
> callbacks.

## Key types first — TaskResult

Every task — whatever its runtime — resolves to one `TaskResult`. This is the shape your calling code reads; check it before writing per-runtime branches.

**TaskResult — returned by executor.execute()**

| Name | Type | Description |
| --- | --- | --- |
| `taskId` | `string` | The TaskDefinition.id this result belongs to. |
| `status` | `string` | Lifecycle status: 'completed' \| 'failed' \| 'timeout' \| 'cancelled' (running/pending used in-flight). |
| `success` | `boolean` | True only when status is 'completed' (exit code 0). Branch on this. |
| `exitCode` | `number` | Subprocess exit code; -1 when the process never started (spawn error, cancelled, timeout). |
| `stdout` | `string` | All captured stdout lines, joined by newlines. |
| `stderr` | `string` | All captured stderr lines (and the error message on a spawn failure). |
| `result` | `Record \| null` | The JSON object parsed from the LAST line of stdout, or null if that line is not a JSON object. |
| `error` | `string \| null` | Human-readable failure message (includes exit code and first stderr line); null on success. |
| `duration` | `number` | Wall-clock execution time in milliseconds. |
| `startedAt / completedAt` | `string` | ISO-8601 timestamps bracketing the run. |
| `attempt` | `number` | Attempt index for this execution (0 from the executor itself). |

## TaskDefinition & runtimes

`defineTask(id)` returns a typestate builder; `.build()` is only callable once an `.entrypoint(path)` (subprocess) or `.handler(fn)` (in-process) is set. The resulting `TaskDefinition` carries the runtime `type`, entrypoint, args, env, timeout, and permissions. The seven supported runtimes (`TaskType`) and how each is launched:

**TaskType — built-in runtime adapters**

| Name | Type | Description |
| --- | --- | --- |
| `deno` | `default` | Spawns `deno run` with permission flags built from .permissions(...). The only runtime that is sandboxed by per-task Deno permissions. |
| `python` | `subprocess` | Spawns `python3 -u ` (or `py` on Windows); honors metadata.pythonConfig.venvPath / pythonPath and NETSCRIPT_PYTHON_PATH. |
| `dotnet` | `subprocess` | Runs a .cs via `dotnet run`, a project via `dotnet run --project`, or a built executable directly; metadata.dotnetConfig.runtimeArgs/useDotnetRun. |
| `shell` | `subprocess` | Runs the entrypoint under bash (metadata.shellConfig.shell / loginShell); resolves Git Bash util paths on Windows. |
| `powershell` | `subprocess` | Spawns `powershell` (Windows) or `pwsh` with -NoProfile -NonInteractive -ExecutionPolicy Bypass -File. |
| `cmd` | `subprocess` | Spawns `cmd.exe /c ` (Windows). |
| `executable` | `subprocess` | Runs the entrypoint directly as a prebuilt binary with the task's args. |

The per-task permission set passed to `.permissions(...)` mirrors the Deno permission model. **It is enforced only for the `deno` runtime** — those keys are translated into `--allow-*` flags on the `deno run` command line. For `python`, `shell`, and the other external runtimes there is no Deno sandbox; the subprocess inherits the OS-level access of the worker process.

**permissions() options — applied to the deno runtime**

| Name | Type | Description |
| --- | --- | --- |
| `net` | `boolean \| string[]` | --allow-net (true) or --allow-net=HOSTS (array). Network access. |
| `read` | `boolean \| string[]` | --allow-read or --allow-read=PATHS. Filesystem read. |
| `write` | `boolean \| string[]` | --allow-write or --allow-write=PATHS. Filesystem write. |
| `env` | `boolean \| string[]` | --allow-env or --allow-env=VARS. Environment-variable access. |
| `run` | `boolean \| string[]` | --allow-run or --allow-run=CMDS. Subprocess spawn. |
| `ffi` | `boolean` | --allow-ffi. FFI access to native libraries. |
| `import` | `string[]` | --allow-import=SPECIFIERS. Allowed dynamic-import sources. |

> Omitting permissions widens the Deno sandbox
>
> For a
>
> deno
>
> task, calling
>
> .build()
>
> without
>
> .permissions(...)
>
> produces an
>
> --allow-all
>
> command line. Always pass an explicit, least-privilege permission set for untrusted or third-party Deno task code. Non-Deno runtimes ignore these keys entirely — gate those at the OS level instead.

## Production notes

> The result contract is the LAST stdout line
>
> A subprocess returns structured data
>
> only
>
> by printing a single JSON
>
> object
>
> as its final
>
> stdout
>
> line. A trailing log line, a pretty-print, a JSON
>
> array
>
> , or a stray newline after the payload all cause
>
> result.result
>
> to be
>
> null
>
> even though the task
>
> succeeded
>
> . Print diagnostics to
>
> stderr
>
> , and emit the JSON result last with no trailing output. Buffering can also reorder this — for Python the runtime runs
>
> python3 -u
>
> (unbuffered) for exactly this reason; flush your own output in other runtimes.

> Runtimes must exist on the host; exit codes are diagnostic
>
> Each non-Deno runtime requires its toolchain on the
>
> worker host
>
> : a Python interpreter (or a configured venv), the .NET SDK,
>
> pwsh
>
> /
>
> powershell
>
> , or
>
> bash
>
> . A missing interpreter surfaces as a failed task — exit code
>
> 127
>
> is reported as
>
> command not found
>
> and
>
> 126
>
> as
>
> command not executable
>
> .
>
> cmd
>
> and
>
> powershell.exe
>
> are Windows-only;
>
> shell
>
> uses bash and resolves Git Bash utility paths on Windows. A task that exceeds its
>
> timeout
>
> resolves with status
>
> timeout
>
> and exit code
>
> -1
>
> ; passing an already-aborted
>
> signal
>
> yields
>
> cancelled
>
> .

> Tasks run external code — treat them as a trust boundary
>
> Polyglot tasks spawn arbitrary processes with the worker's OS privileges. Pin entrypoints to known scripts, prefer a pinned interpreter / venv (
>
> pythonConfig.venvPath
>
> ) over
>
> $PATH
>
> discovery, and avoid interpolating untrusted input into
>
> args
>
> or the entrypoint path. Trace context (
>
> TRACEPARENT
>
> /
>
> CORRELATION_ID
>
> ) is injected into the subprocess environment so cross-runtime spans stitch together in telemetry.

## Reference →

The full generated API — `defineTask`, `MultiRuntimeTaskExecutor`, `createDefaultTaskExecutor`, every runtime adapter, and the executor option types — lives in the workers reference.

[workers](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[Look up — Workers reference  defineTask, the multi-runtime executor, runtime adapters, TaskDefinition / TaskResult / TaskExecutionOptions, and permission types.](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[Do — Run a polyglot task  Step-by-step recipe for a python and a shell task with explicit permissions and result capture.](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/run-a-polyglot-task/)

[Understand — Background jobs  The queue, worker-runtime modes, retry, and graceful-shutdown drain shared with in-process jobs.](https://rickylabs.github.io/netscript/netscript/background-processing/workers/)

[Next — Runtime configuration  How worker, service, and adapter settings resolve from schema defaults, config files, env vars, and overrides.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/runtime-config/)

[Typed SDK & client](https://rickylabs.github.io/netscript/netscript/services-sdk/sdk/) [Runtime configuration](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/runtime-config/)

_Canonical: https://rickylabs.github.io/netscript/background-processing/polyglot-tasks/_

---

# Background jobs

**One typed handler file is the whole job.** Registration, dispatch, retry, execution tracking, scheduling, tracing, and the HTTP trigger API all come from the worker runtime — so shipping a working background job (whether you write it or an AI agent does) means authoring a single `defineJobHandler` module, not first assembling a queue, a worker pool, and an inspection UI around it.

A NetScript **background job** is a durable, KV-backed TypeScript handler that runs in its own thread-isolated worker, separate from your request-serving services. You author a job as one `defineJobHandler(...)` callable, give it an `id`, and the runtime takes care of registration, dispatch, retry, execution tracking, scheduling, and an HTTP API to enqueue and inspect runs. It is the unit you reach for whenever work should happen *after* a request returns — charging a payment, sending a welcome email, processing an upload — without blocking the caller.

![An enqueue call (from a trigger, an HTTP POST to the workers API, or the scheduler) places a job on the durable queue; the worker runtime pulls it and runs the handler in one of three runner modes — in-process, web-worker (one V8 isolate per worker), or subprocess — then writes a JobResult to the KV-backed execution store, which streams updates back over SSE.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/queue-worker-scheduler.svg)

*Enqueue → durable queue → worker runtime (in-process / web-worker / subprocess) → result store. The scheduler fires cron-defined jobs onto the same queue; graceful shutdown drains in-flight runs before the runner stops.*

## The story: a screenshot becomes a diagnosis

The clearest picture of what this contract buys comes from a production incident-diagnosis assistant built on NetScript for a legacy ERP estate. A support engineer pastes an alert-email screenshot into a chat channel; a background job runs a vision model over the image and extracts the structured fields (program, error number, table, timestamp) that downstream tooling needs to trace the failure.

Two properties of the job contract shaped that worker into its correct form:

- **The payload is queue-borne, so it stays small.** The first version enqueued the raw image bytes and hit Deno KV's 64 KB enqueue limit. The fix — carry only a small reference through the queue and fetch the bytes back over a typed service client inside the handler — is exactly the shape the contract steers you toward: the queue moves *references to work*, not blobs.
- **Workers stay compute-only.** The app's channel database holds an exclusive OS file lock, so a second process opening it crashes outright. Because a job handler receives a `ctx` and returns a `JobResult` — rather than a database connection — writing results back through the owning service's typed client was the natural default, not a discipline the team had to invent. The single writer keeps owning its database; the worker never touches it.

The same run is traced end to end: dispatch, execution, progress events, and the subprocess hop (if any) land in the [Aspire dashboard](https://rickylabs.github.io/netscript/explanation/aspire/) without handler-side wiring. The rest of this page is the mechanism behind that story.

## What it is

A job is plain TypeScript that runs **in the worker process, not the request process**. The headline surface — `defineJobHandler`, `createSuccessResult`, and `createFailureResult` from `@netscript/plugin-workers-core` — lets you write a typed handler over a `ctx`, do the work, and return a structured `JobResult`. Job dispatch and execution are instrumented with real OpenTelemetry spans that show up in the [Aspire dashboard](https://rickylabs.github.io/netscript/explanation/aspire/) automatically, so a queued run is observable end to end without wiring. The runner mode (how the handler is isolated) is a **user-tunable** — see the runtime-mode table below — and the same queue and scheduler also drive [polyglot tasks](https://rickylabs.github.io/netscript/background-processing/polyglot-tasks/) when the work is owned by another runtime. The why-behind-the-choreography lives in [Durability model](https://rickylabs.github.io/netscript/explanation/durability-model/).

> Jobs vs. tasks vs. sagas vs. services
>
> Reach for a
>
> background job
>
> when the work is
>
> fire-and-forget or deferrable
>
> and written in TypeScript: it should survive the request that started it, run on its own schedule or trigger, and be retried and observed independently. If the work must run in
>
> another runtime
>
> (Python, .NET, a shell script, a binary), use a
>
> polyglot task
>
> — it shares this same queue, retry, and telemetry machinery but spawns a subprocess. If the work
>
> coordinates several steps across time
>
> (waiting for messages, compensating on failure), model it as a
>
> durable saga
>
> ; jobs and sagas compose. For a
>
> synchronous request/response API
>
> , author a
>
> service
>
> instead.

## Learn → / Do →

[Learn — ERP Sync, lesson 02  The tutorial rung: add the worker plugin to the running app, author an import job, and trigger it over :8091 as part of the ERP-sync narrative.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)

[Do — Tune the worker runtime  Recipe: pick the in-process / web-worker / subprocess runner, set WORKERS_CONCURRENCY, and choose a queue provider for your deployment.](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/tune-worker-runtime/)

[Understand — Polyglot tasks  Run non-TypeScript work (Python, .NET, shell) on the same durable queue and scheduler as a managed subprocess.](https://rickylabs.github.io/netscript/netscript/background-processing/polyglot-tasks/)

## Minimal example

Add the workers plugin to a published workspace with the public package install flow:

```bash
netscript plugin install @netscript/plugin-workers
```

> Historical: import-map patch no longer required
>
> Projects scaffolded with an early published CLI (
>
> --package-source jsr
>
> ) on
>
> 0.0.1-beta.7
>
> generated a root
>
> deno.json
>
> whose import map omitted the
>
> @netscript/sdk
>
> and
>
> @netscript/sdk/client
>
> entries, requiring a manual patch before the background worker could load jobs. The scaffold generator now emits both entries in JSR mode, so no manual fix is needed on current releases.

For local-source contributor work inside this monorepo, use the maintainer binary when you need first-party samples:

```bash
deno run -A packages/cli/bin/netscript-dev.ts plugin install worker --name workers --samples
```

That local path lands real, compiling modules you can read and trigger immediately — including `plugins/workers/jobs/health-check.ts` (a job handler) and `plugins/workers/tasks/validate-payload.ts` (a polyglot task). The plugin's API service comes up on **port 8091**.

A job handler is an async callable over a `ctx` object that returns a `JobResult`. Parse the payload with a Zod schema, do the work, and return `createSuccessResult(...)` or `createFailureResult(...)`. The job's identity is attached with `Object.assign(handler, { id })`.

```ts
// plugins/workers/jobs/process-payment.ts
import {
  createFailureResult,
  createSuccessResult,
  defineJobHandler,
} from '@netscript/plugin-workers-core';
import { z } from 'zod';

// Payload contract — parse ctx.payload before doing any work.
const ProcessPaymentPayloadSchema = z.object({
  orderId: z.string().min(1),
  amountCents: z.number().int().positive(),
});

const handler = defineJobHandler(async (ctx) => {
  const { orderId, amountCents } = ProcessPaymentPayloadSchema.parse(ctx.payload ?? {});

  // Optional progress callback — the runtime wires reportProgress on real runs.
  ctx.reportProgress?.(10, 'charging customer');

  const charge = await chargeCustomer(orderId, amountCents);
  if (!charge.ok) {
    // A failure result is recorded and feeds the retry policy.
    return createFailureResult(`charge declined: ${charge.reason}`);
  }

  ctx.reportProgress?.(100, 'charged');
  // The success payload (data) is persisted on the execution record.
  return createSuccessResult({ orderId, chargeId: charge.id, amountCents });
});

// The id is how the runtime registers, lists, and triggers the job.
export default Object.assign(handler, { id: 'process-payment' });
```

Once the workers API is up (Aspire first — see Production notes), enqueue a run by `id`:

> ns-workers is a shorthand you install once
>
> ns-workers
>
> is a name
>
> you
>
> give the workers plugin's CLI — the scaffold does not create it. Install it once, globally, and every
>
> ns-workers
>
> command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> ```
>
> Rather not install it? Each
>
> ns-workers <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-workers@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```bash
# Enqueue through the workers API (port 8091), without hand-writing HTTP.
ns-workers trigger process-payment \
  --payload='{"orderId":"o_42","amountCents":4999}'

# Watch it land in the KV-backed execution history.
ns-workers executions --limit=10 --json
```

## Key types first — `JobHandlerContext` & `JobResult`

A handler is `(ctx: JobHandlerContext<TPayload>) => JobResult<TResult> | Promise<…>`. These two shapes are the contract you write against; read them before the option tables.

**JobHandlerContext — the ctx passed to defineJobHandler**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | The execution id for this run. Stable per dispatched run. |
| `job` | `{ id: string } \| undefined` | The job definition reference (its id), when available. |
| `payload` | `TPayload` | The enqueued payload. Parse it with your Zod schema before use. |
| `correlationId` | `string \| undefined` | Correlation id propagated across the dispatch for tracing. |
| `traceparent` | `string \| undefined` | W3C traceparent of the dispatching span; child spans nest under it. |
| `tracestate` | `string \| undefined` | W3C tracestate accompanying the traceparent. |
| `reportProgress` | `(percent, message?) => void \| Promise` | Optional progress callback wired by the runtime on real runs; emits job.progress events. |

**JobResult — return createSuccessResult() or createFailureResult()**

| Name | Type | Description |
| --- | --- | --- |
| `success` | `true \| false` | Discriminant. createSuccessResult sets true; createFailureResult sets false. Branch on this. |
| `data` | `TResult \| undefined` | The result payload, persisted on the execution record (present on success, optional on failure). |
| `error` | `string` | Failure message — required when success is false (the first arg to createFailureResult). |

## Worker runtime modes (`WORKER_RUNTIMES`)

How a handler is isolated from the API process is a tunable: `WORKER_RUNTIMES` enumerates the three runner modes the worker runtime supports. The scaffold default is **web-worker**, where each worker is its own V8 isolate sized by the `WORKERS_CONCURRENCY` env var. Pick the mode that matches your isolation, memory, and parallelism needs.

**WORKER_RUNTIMES — runner isolation modes (WorkerRuntime type)**

| Name | Type | Description |
| --- | --- | --- |
| `in-process` | `WorkerRuntime` | Runs the handler in the same process via the in-process runner (registry-first). Lowest overhead, no isolation — best for tests, compiled binaries, and single-tenant local composition. |
| `web-worker` | `WorkerRuntime` | Runs each worker in its own Web Worker / V8 isolate (~20-40 MB each). The scaffold default; WORKERS_CONCURRENCY sets the process pool size for parallel job execution. Keep it low to bound memory. |
| `subprocess` | `WorkerRuntime` | Runs the handler in a spawned subprocess. Strongest process isolation; only Deno tasks get permission sandboxing through .permissions(). Python, .NET, shell, PowerShell, and cmd inherit the worker process's OS permissions. |

**Deployment & scaling knobs (workers config)**

| Name | Type | Description |
| --- | --- | --- |
| `WORKERS_CONCURRENCY` | `env (number)` | Runtime worker process pool size. The entrypoint reads this plural variable; current Aspire metadata also emits WORKER_CONCURRENCY, but the runtime does not consume it. |
| `concurrency` | `number` | Per-topic max concurrent workers (WorkersConfigData.concurrency / per-group scaling). |
| `mode` | `'combined' \| 'distributed'` | Per-topic deployment mode: one combined runner vs. distributed runners. Defaults to 'combined'. |
| `queueProvider` | `'auto' \| 'deno-kv' \| 'redis' \| 'postgres' \| 'amqp'` | Queue backend. 'auto' resolves a provider; see Choose a queue provider. |
| `jobsDir / tasksDir` | `string` | Directories scanned for default-exported job and task modules. |

> Tune it without touching code
>
> The runner mode and pool size are deployment settings, not handler concerns — the same
>
> process-payment
>
> handler runs unchanged under any
>
> `WORKER_RUNTIMES` mode
>
> . Start on the
>
> web-worker
>
> default with a small
>
> WORKERS_CONCURRENCY
>
> , move to
>
> subprocess
>
> when you need hard isolation, and drop to
>
> in-process
>
> for tests and compiled single-binary deployments. Resolution precedence (schema default → config file → env → override) is covered in
>
> runtime configuration
>
> .

## Enqueue from a trigger

The HTTP `…/trigger` endpoint is one way in; the other is **declaratively, from a trigger handler**, which returns an `enqueueJob(...)` action. `enqueueJob(job, options)` comes from `@netscript/plugin-triggers-core` and binds an imported job definition to a payload, so an inbound webhook or a scheduled trigger drops work onto this same runtime.

```ts
// plugins/triggers/triggers/payment-webhook.ts
import { defineWebhook, enqueueJob } from '@netscript/plugin-triggers-core';
// Import the job definition you want to dispatch (its default export carries the id).
import processPayment from '../../workers/jobs/process-payment.ts';

const handler = defineWebhook(
  // The handler returns trigger actions; enqueueJob is the most common one.
  (event) => [
    enqueueJob(processPayment, {
      payload: { orderId: event.payload.orderId, amountCents: event.payload.amountCents },
      idempotencyKey: event.payload.orderId, // optional: collapse duplicate deliveries
    }),
  ],
  { id: 'payment-webhook', path: '/webhooks/payment', verifier: 'hmac-sha256', secretEnv: 'WEBHOOK_SECRET' },
);

export default handler;
```

**enqueueJob(job, options) — EnqueueJobOptions (from @netscript/plugin-triggers-core)**

| Name | Type | Description |
| --- | --- | --- |
| `payload` | `TPayload` | The payload handed to the job's ctx.payload. Parse it with the job's Zod schema. |
| `idempotencyKey` | `string` | Collapses duplicate deliveries — at-most-once effect per key. |
| `concurrencyKey` | `string` | Serializes runs that share a key (e.g. per-order) so they do not overlap. |
| `priority` | `number` | Dispatch priority for this enqueue action. |

## Trigger a job from a typed client

The `ns-workers trigger` command above calls the same OpenAPI route. Because the workers API is a **plugin service**, the same trigger is reachable with a generated typed client over the RPC route `/api/rpc/*` — no OpenAPI-only fallback and no transport `404`. A first-party plugin API mounts its router under a named segment, so the client takes a `routerName` alongside `serviceName`; Aspire injects the URL under `services__workers-api__http__0`.

```ts
// Reach the workers plugin API with a generated typed client.
import { createServiceClient } from '@netscript/sdk/client';
import { workersContract } from '@netscript/plugin-workers/contracts';

const workers = createServiceClient<typeof workersContract>({
  contract: workersContract,
  serviceName: 'workers-api',
  routerName: 'workers',
});

// triggerJob is served over /api/rpc/* and returns { jobId, triggered }.
// Over REST the {id} path segment carries the target job; over RPC (no path
// segment) it travels in this input object. Either way it resolves to
// input.id — with no id at all the call fails with a 422 VALIDATION_ERROR.
const { jobId, triggered } = await workers.triggerJob({
  id: 'process-payment',
  payload: { orderId: 'o_42', amountCents: 4999 },
});

// triggerTask is the polyglot-task twin, returning { taskId, triggered }.
const task = await workers.triggerTask({ id: 'validate-payload', payload: {} });
```

**Trigger procedures — served over /api/rpc/* (typed client) and /api/v1/... (OpenAPI/REST)**

| Name | Type | Description |
| --- | --- | --- |
| `triggerJob({ id, payload?, priority?, delay?, correlationId? })` | `{ jobId, triggered }` | POST /jobs/{id}/trigger — enqueue a run of the job named by the {id} path segment; resolves the jobId and a triggered flag. |
| `triggerTask({ id, payload?, priority?, delay?, correlationId? })` | `{ taskId, triggered }` | POST /tasks/{id}/trigger — enqueue a run of the polyglot task named by the {id} path segment; resolves the taskId and a triggered flag. |

> Declare the plugin dependency with pluginReferences
>
> When a Service depends on a plugin API — the workers plugin, say — declare it in that Service's config section with
>
> pluginReferences?: string[]
>
> , a list of the plugin resource names it consumes (alongside the existing
>
> dependsOn
>
> ). The Aspire helper generation wires those references so the Service can discover and load the user jobs the plugin API exposes at runtime, and so the typed client above resolves the plugin's injected URL (
>
> services__workers-api__http__0
>
> ). It is the config seam behind Service→plugin-API job discovery.

> The {id} path segment is authoritative
>
> triggerJob
>
> /
>
> triggerTask
>
> resolve the target id from
>
> input.id
>
> . On the REST route (
>
> POST /jobs/{id}/trigger
>
> ) oRPC merges the
>
> {id}
>
> URL path segment into
>
> input.id
>
> , so the path is authoritative and a body
>
> id
>
> is a redundant fallback that can never disagree with it; on the RPC transport there is no path segment, so the
>
> id
>
> you pass in the input object is used directly. If neither resolves an id, the handler short-circuits to a typed
>
> VALIDATION_ERROR
>
> (HTTP 422) through the centralized
>
> validationFailed
>
> contract helper
>
> before any KV write
>
> — it never persists an
>
> undefined
>
> -keyed run. Handle it as the contract's typed error on the client, not a generic
>
> 500
>
> .

## Graceful shutdown

Background runners must drain in flight work before they exit, or a redeploy loses jobs mid-run. The `@netscript/plugin-workers-core/shutdown` subpath provides a `ShutdownManager` that registers stoppable resources and stops them in priority order, with a timeout, when a shutdown is requested.

```ts
// plugins/workers/bin/with-shutdown.ts
import { ShutdownManager } from '@netscript/plugin-workers-core/shutdown';
import { startWorkers } from '@netscript/plugin-workers-core';

const runtime = await startWorkers({ autoStart: true });
const shutdown = new ShutdownManager({ timeoutMs: 10_000 });

// Register the runtime so a drain stops it gracefully (lower priority stops first).
shutdown.register({ id: 'workers-runtime', priority: 100, stop: (reason) => runtime.stop(reason) });

// Tie OS signals to the drain, then report what stopped / failed / timed out.
Deno.addSignalListener('SIGTERM', async () => {
  const report = await shutdown.shutdown('SIGTERM');
  console.info('shutdown', report.state, { stopped: report.stopped, timedOut: report.timedOut });
  Deno.exit(0);
});
```

**ShutdownManager — @netscript/plugin-workers-core/shutdown**

| Name | Type | Description |
| --- | --- | --- |
| `register(resource)` | `void` | Register a ShutdownResource ({ id, stop(reason?), priority? }) to be stopped on drain. |
| `unregister(id)` | `void` | Remove a resource from the drain set. |
| `shutdown(reason?, { timeoutMs })` | `Promise` | Stop registered resources in priority order; returns { state, stopped, failed, timedOut }. |
| `waitForShutdown()` | `Promise` | Resolves once shutdown has started — await it in long-running loops. |
| `createAbortController()` | `AbortController` | An AbortController that aborts when shutdown begins; pass its signal into in-flight async work. |
| `state` | `'running' \| 'shutting-down' \| 'stopped'` | Current lifecycle state of the manager. |

## Workers API & where jobs come from

Once Aspire is up and the schema is wired, the workers API on **`:8091`** registers your job by `id` and exposes HTTP endpoints to seed, trigger, and inspect runs. These are the endpoints the CLI E2E suite validates live.

**Workers API — port 8091 (full generated surface in the workers reference)**

| Name | Type | Description |
| --- | --- | --- |
| `GET /health` | `liveness` | Health probe for the workers API service. |
| `GET /api/v1/workers/jobs` | `list` | All registered job definitions (id, name, topic) discovered from the jobs directories. |
| `POST /api/v1/workers/jobs/{id}/trigger` | `enqueue` | Enqueue a run of the job with this id, passing a JSON payload body. |
| `GET /api/v1/workers/executions?limit=10` | `history` | Recent executions and outcomes (KV-backed execution state). |
| `GET /api/v1/workers/tasks` | `list` | Task registry view (polyglot defineTask entries). |
| `POST /api/v1/workers/seed` | `seed` | Seed the workers store with the registered jobs. |
| `GET /api/v1/workers/subscribe` | `SSE` | Server-sent-events stream of execution updates (KV-watch). |

> Where jobs come from
>
> Each handler file under your jobs directory (
>
> workers/jobs
>
> by default,
>
> *.ts
>
> ) is discovered and compiled into one generated registry at
>
> .netscript/generated/plugin-workers/job-registry.ts
>
> , keyed by the source filename — so
>
> workers/jobs/process-payment.ts
>
> registers as
>
> process-payment
>
> . Both the
>
> :8091
>
> API service
>
> and
>
> the background runner load that single registry at startup: the API service registers the generated user job definitions
>
> before it serves
>
> , so your jobs — not just the built-in
>
> workers-plugin-health-check
>
> — appear in
>
> GET /api/v1/workers/jobs
>
> and resolve on trigger. Registration order decides id collisions: the plugin's own jobs register first, then the generated user definitions load and
>
> skip any id already present
>
> , so a user file that reuses a built-in id (such as
>
> workers-plugin-health-check
>
> ) leaves the plugin job in place rather than overwriting it — first registration wins. Background execution runs from
>
> plugins/workers/bin/combined.ts
>
> , a
>
> separate
>
> process from the API service — the API enqueues, the runner executes. A missing generated registry is tolerated as an empty set, so a fresh workspace boots before you author any job. Set
>
> WORKERS_CONCURRENCY
>
> on the worker background process when you need a specific process pool size. Current Aspire metadata also emits
>
> WORKER_CONCURRENCY
>
> , but the runtime entrypoint does not consume it; use
>
> Tune the worker runtime
>
> for the mismatch details.

## Observability: real job traces out of the box

Job-level observability is **not** a stub. The workers runtime instruments the scheduler → queue → worker → subprocess path with real OpenTelemetry spans, and those traces appear in the [Aspire dashboard](https://rickylabs.github.io/netscript/explanation/aspire/) automatically once Aspire is up.

**What the worker runtime traces automatically (framework layer — real today)**

| Name | Type | Description |
| --- | --- | --- |
| `Job dispatch + execution` | `span` | Each enqueued run gets a span with attributes, duration, status, and job.started / job.completed / job.failed / job.exception events. |
| `Step + progress events` | `event` | job.step.* and job.progress (current / total / percentage) events are emitted on real job runs. |
| `Subprocess trace continuation` | `context` | W3C traceparent / tracestate is propagated into the subprocess runner, so the child trace links back to the dispatching span. |
| `Scheduler + cron spans` | `span` | Scheduler-start, schedule-job, dispatch, and cron-run spans cover the timer/cron path that fires scheduled jobs. |

For spans you author *inside* a handler, import directly from **`@netscript/telemetry`** (e.g. `@netscript/telemetry/instrumentation` for `withChildSpan`). These nest correctly under the automatic dispatch span. See [Observability](https://rickylabs.github.io/netscript/explanation/observability/) for the model and [Add OpenTelemetry](https://rickylabs.github.io/netscript/observability/how-to/add-opentelemetry/) for the recipe.

## How it compares

Trigger.dev is a managed platform for background jobs and agent workflows; Temporal is a durable-execution system you self-host or rent as Temporal Cloud; NetScript's worker runtime is a plugin that lives inside your own repository and process tree. Each model carries a real tradeoff — a managed platform removes operations, a replay-based cluster gives the strongest durability guarantees, a local-first plugin keeps everything in code you own. The rows below are structural facts drawn from each project's public documentation (as of mid-2026), not rankings.

|  | NetScript workers | Trigger.dev | Temporal |
| --- | --- | --- | --- |
| Handler code | Plain async TypeScript (`defineJobHandler`); failed runs are retried, never replayed | TypeScript tasks in your repo, executed by the platform | Workflow code replayed from event history; side effects live in activities |
| Determinism constraint on orchestration code | None — handlers may call `Date.now()`, `Math.random()`, and do direct I/O | Not required | Required in workflow code: no `Date.now()`, `Math.random()`, or direct I/O |
| Where handlers execute | Your own processes: in-process, web-worker, or subprocess runner | Managed cloud; self-hosting via Docker Compose | Self-hosted cluster or Temporal Cloud |
| Backing stores | Pluggable queue (`deno-kv`, `redis`, `postgres`, `amqp`); Deno KV execution state; Postgres job definitions | Platform-managed | Database, Elasticsearch, server, and workers (self-hosted) |
| Control plane | None separate — the workers API is one of your services (`:8091`) | The Trigger.dev platform | The Temporal cluster |

The practical consequence of the first two rows: a NetScript job handler is ordinary TypeScript with no replay-safety rules to learn, so code an agent writes for a service moves into a worker unchanged — the isolation question is deferred to the runner mode (the `WORKER_RUNTIMES` table above), a deployment setting rather than a handler concern.

## Production notes

> Aspire first, then jobs
>
> The workers plugin persists job definitions to Postgres and uses Deno KV for execution state, so bring orchestration up before you exercise it. Step 1 is the database service; step 2 is Aspire:
>
> cd aspire && aspire start
>
> provisions Postgres and Redis, then
>
> netscript db init --name init
>
> /
>
> netscript db generate
>
> wire the schema. Only after Aspire is up will
>
> :8091
>
> resolve jobs and record executions. See
>
> Database & migration
>
> .

> Drain on redeploy, or lose in-flight runs
>
> A runner that exits without draining abandons jobs mid-execution. Wire a
>
> ShutdownManager
>
> to
>
> SIGTERM
>
> (above), bound it with a
>
> timeoutMs
>
> , and check
>
> report.timedOut
>
> in your logs. Pair the drain with an
>
> idempotencyKey
>
> on enqueue so a retried delivery after a forced exit does not double-charge. For the full recipe see
>
> Tune the worker runtime
>
> .

partial

> Deferred: the scaffold createJobTools helper is a no-op
>
> The scaffold's
>
> createJobTools(ctx)
>
> helper (in
>
> plugins/workers/jobs/job-tools.ts
>
> ) exposes
>
> log
>
> ,
>
> progress
>
> , and
>
> trace
>
> shims — but in the generated copy its
>
> progress and trace methods are no-op stubs
>
> (only
>
> log
>
> writes to the console), and it is
>
> not
>
> a published
>
> @netscript/plugin-workers-core
>
> export. This is a known, tracked limitation with a fix planned, not a permanent design choice, and it is
>
> only
>
> in that scaffold-facing helper: job dispatch and execution themselves emit real spans automatically (above). For custom handler spans today, call
>
> @netscript/telemetry
>
> helpers directly. Do not say "worker tracing is a no-op" — that is false for the framework layer.

## Reference →

This hub is intentionally thin — the full generated API for `@netscript/plugin-workers` (`defineJobHandler`, the job/task builders, the runtime, the shutdown manager, and every exported type and subpath) lives in the reference.

[workers](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[Learn — ERP Sync, lesson 02  Author an import job and trigger it over :8091 as part of the continuous ERP-sync tutorial narrative.](https://rickylabs.github.io/netscript/netscript/tutorials/erp-sync/02-import-job/)

[Do — Tune the worker runtime  Pick the runner mode, set WORKERS_CONCURRENCY, choose a queue provider, and wire graceful shutdown.](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/tune-worker-runtime/)

[Look up — workers reference  The full generated deno doc API for @netscript/plugin-workers — every exported symbol, type, and subpath.](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[Understand — Durability model  How jobs compose with sagas: a job publishes a message a saga consumes. The why behind the choreography.](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/)

[Services & contracts](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) [Durable sagas](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/)

_Canonical: https://rickylabs.github.io/netscript/background-processing/workers/_

---

# Data & Persistence

**Edit one schema file, run one generate, and every consumer follows** — the typed Prisma client, the matching zod validation schemas, and the migration all come out of the same `netscript db` workflow. That matters most when the one doing the editing is an AI agent: persistence is where a generated backend usually drifts, because a model change normally fans out into separate client, validation, and migration updates — each one a turn that can be missed. NetScript folds those into one cycle.

The pillar splits state along one line. **Records** — durable, relational, queried with a typed client — live in the [database layer](https://rickylabs.github.io/netscript/data-persistence/database/), where every plugin contributes its own models to the same datasource. **Execution state** — caches, sessions, work queues, scheduled ticks — lives in [KV, queues & cron](https://rickylabs.github.io/netscript/data-persistence/kv-queues-cron/), provider-agnostic packages that run on zero-config local backends until [Aspire](https://rickylabs.github.io/netscript/explanation/aspire/) provisions the production ones. The scaffold uses both from day one: Postgres for records, Redis/KV for execution state.

Start here when the question is where state lives, how schema changes ship, or how the workspace resolves a second database.

[Overview & Concepts   Database and KV  The persistence layer behind services, queues, and workflow state.](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) [Quickstart   Data contracts  Follow the Storefront data step before service and saga work expand it.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/03-cart-contracts/) [How-To   Database and migration  Initialize and migrate the primary datasource.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/) [How-To   Second database  Add and address another datasource from the workspace.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/use-a-second-database/) [API Reference   database  Generated database package symbols.](https://rickylabs.github.io/netscript/netscript/reference/database/) [API Reference   kv and Prisma adapter  Generated KV and adapter package symbols.](https://rickylabs.github.io/netscript/netscript/reference/kv/)

## Learn, do, look up

[Learn  Storefront tutorial  Cart contracts back a real database schema from chapter 3 on.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/) [Look up  `@netscript/database` reference  Generated API reference. Related units: `kv`, `prisma-adapter-mysql`.](https://rickylabs.github.io/netscript/netscript/reference/database/) [Understand  Architecture  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/architecture/)

_Canonical: https://rickylabs.github.io/netscript/data-persistence/_

---

# Database & Prisma

A schema change is never just a schema change. Add one field to a model and three other things are now stale: the client types your services compile against, the runtime validation that guards your contract boundary, and the migration that has to reach the database before any of it works. Do those in separate tools and each one is a separate keep-in-sync step — and when an AI agent is writing the backend, each separate step is another turn where the pieces can drift apart. NetScript's answer is to make the `.prisma` file the single source: **one edit, one `netscript db generate`, and the Deno-runtime typed client and the matching zod schemas regenerate together**, with the migration created and applied by the same `netscript db` workflow.

NetScript's persistence layer is **Prisma 7 over a driver adapter** (Postgres is the recommended engine, with MSSQL and MySQL adapters shipped alongside), generated for the Deno runtime and provisioned for you by **Aspire**. Every plugin contributes its own `.prisma` models, which are aggregated into a single generated client over one primary datasource.

![Per-plugin .prisma schema files (root ExampleRecord, workers, sagas, triggers, auth) under database/postgres/schema/plugins are aggregated by netscript db generate into a single Deno-runtime Prisma client and matching zod schemas; the client talks to one datasource through a selected driver adapter — postgres, mssql, or mysql.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/database-schema-aggregation.svg)

*One generated client, many contributors. Each plugin's .prisma file is aggregated into the same datasource; an adapter (postgres / mssql / mysql) selects the driver underneath.*

> Aspire is step 2 — before any db command
>
> Every
>
> netscript db
>
> command talks to Postgres
>
> through Aspire
>
> . In the default layout Postgres is a container that
>
> Aspire
>
> provisions, so
>
> cd aspire && aspire start
>
> must be up
>
> before
>
> you run
>
> netscript db init
>
> . Run a
>
> db
>
> command against a stopped AppHost and it fails with
>
> aspire start failed: … Project file does not exist
>
> . That is the dependency, not a bug — bring orchestration up first, then run the db workflow from the workspace root. See
>
> Orchestration with Aspire
>
> for why.

> Use this when
>
> Reach for the database layer when you need
>
> durable, relational state
>
> — records that survive restarts, are queried with a typed client, and are shared across your service and its plugins. The engine is polyglot: pick it at scaffold time with
>
> --db
>
> — Postgres (the recommended engine; or
>
> mysql
>
> /
>
> mssql
>
> /
>
> sqlite
>
> ). For
>
> ephemeral or high-throughput
>
> state (counters, locks, work queues, scheduled triggers) reach for
>
> KV, queues & cron
>
> instead; the scaffold uses both — Postgres for records, Redis/KV for execution state. Postgres can
>
> also
>
> back the work queue itself — see
>
> the Postgres queue backend
>
> below.

## Learn → / Do →

- **Learn** — the [Team Workspace tutorial, step 03](https://rickylabs.github.io/netscript/tutorials/workspace/03-workspace-data/) wires workspace data through the database from scratch.
- **Do** — the [Use a second database](https://rickylabs.github.io/netscript/data-persistence/how-to/use-a-second-database/) recipe adds a second adapter-backed datasource (MSSQL or MySQL) beside the primary Postgres.

## How persistence is wired

The scaffold engine is chosen with the `--db` flag — `netscript init my-app --db postgres|mysql|mssql|sqlite`. Postgres is the recommended engine (and what every tutorial uses); `mysql`, `mssql`, and `sqlite` are first-class alternatives. `postgres` / `mysql` / `mssql` provision an Aspire container; `sqlite` is file-backed with **no** Aspire container resource. The `--db postgres` scaffold lays down a `database/postgres/` workspace (a different engine lays down `database/<engine>/`). A few facts are worth internalizing before you run anything, because they differ from a typical single-file Prisma setup.

```text
my-app/
├── appsettings.json              # NetScript.Databases.postgres — Engine/Mode/DatabaseName (the real config)
├── netscript.config.ts           # databases.config is intentionally EMPTY here
└── database/postgres/
    ├── schema/
    │   ├── schema.prisma          # root: generator client (runtime="deno"), generator zod, datasource db
    │   └── plugins/               # per-plugin .prisma models aggregated here
    │       ├── workers/workers.prisma
    │       ├── sagas/sagas.prisma
    │       ├── triggers/triggers.prisma
    │       └── auth/auth.prisma   # appears once the auth plugin is added (better-auth backend)
    ├── prisma.config.ts           # schema dir + migrations path + datasource url
    ├── scripts/                   # migrate.ts, seed.ts, generate-zod.ts, fix-zod-imports.ts, …
    └── schema/.generated/         # appears after `db generate`: Prisma client + zod schemas
```

- **The datasource is driven by `appsettings.json`, not `netscript.config.ts`.** In the scaffold, `netscript.config.ts` has `databases: { config: [] }` (empty). The connection details live in `appsettings.json` under `NetScript.Databases.postgres` — `Engine: "Postgres"`, `Mode: "Container"`, a generated `DatabaseName`, and a persistent `DataPath` of `.data/postgres`, with `PrimaryDatabase: "postgres"`. Aspire reads that block to provision the container.
- **One datasource, many contributors.** There is a single primary Postgres datasource. Each first-party plugin ships its own `database/<plugin>.prisma`, and those models are aggregated under `database/postgres/schema/plugins/<plugin>/`. After adding `workers`, `sagas`, and `triggers`, their tables (for example `model JobDefinition` from workers) join the root `ExampleRecord` model in the same database — one `db init` / `db generate` cycle covers the app and its plugins together.
- **The client is generated for Deno.** `schema.prisma` sets `generator client` with `runtime = "deno"` and `output = "./.generated"`, plus a `generator zod` (prisma-zod-generator) emitting matching zod schemas to `./.generated/zod`. You get a type-safe client *and* runtime validation schemas from one generate.

## Headline API: a model and a query

Define models in Prisma schema files, then query them through the generated Deno client. The root `schema.prisma` ships a single sample model, `ExampleRecord`; plugin schema files add their own. The tabs below show a model alongside the typed query you'd write against the generated client.

```prisma
// database/postgres/schema/schema.prisma
generator client {
  provider = "prisma-client"
  output   = "./.generated"
  runtime  = "deno"
}

generator zod {
  provider = "prisma-zod-generator"
  output   = "./.generated/zod"
}

datasource db {
  provider = "postgresql"
  // The datasource URL is resolved by prisma.config.ts (POSTGRES_URI / DATABASE_URL),
  // not declared here.
}

model ExampleRecord {
  id        String   @id @default(uuid())
  name      String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}
```

```ts
// Import the Deno-runtime client generated by `netscript db generate`.
import { PrismaClient } from '../database/postgres/schema/.generated/client.server.ts';

const prisma = new PrismaClient();

// Insert a record, then read it back — fully typed off the model above.
const created = await prisma.exampleRecord.create({
  data: { name: 'first' },
});

const recent = await prisma.exampleRecord.findMany({
  orderBy: { createdAt: 'desc' },
  take: 10,
});

console.log(created.id, recent.length);
```

> Generate after every schema change
>
> The generated client under
>
> database/postgres/schema/.generated/
>
> is a build artifact. Edit a
>
> .prisma
>
> file and your code is still typed against the
>
> old
>
> shape until you re-run
>
> netscript db generate
>
> . Generate after every schema change, and re-run
>
> netscript db migrate
>
> to create and apply the matching migration.

## The database workflow

With `aspire start` up (Postgres reachable), run the public `netscript db` commands from the workspace root in this order. The first three are the create-and-fill cycle; `status` confirms it landed and `migrate` evolves the schema later.

```bash
# Create the first migration from the current Prisma schema and apply it.
# --name labels the migration directory (here: a migration called "init").
netscript db init --name init
```

```bash
# Generate the Deno-runtime Prisma client (and the zod schemas) into
# database/postgres/schema/.generated so your code can import typed models.
netscript db generate
```

```bash
# Run the workspace seed scripts (database/postgres/scripts/seed.ts)
# to populate baseline rows.
netscript db seed
```

```bash
# Show migration / tooling status: which migrations are applied and
# whether the database is in sync with the schema.
netscript db status
```

```bash
# Later, when the schema evolves: create + apply the next migration.
# Edit a .prisma file, then:
netscript db migrate --name add_orders
netscript db generate    # re-generate the client against the new shape
```

## Plugins contribute models

Adding a first-party plugin installs its Prisma models to the *same* datasource — there is no second database. The aggregated tables land under `database/postgres/schema/plugins/<plugin>/` and migrate in the same `db init`/`migrate` cycle as your app.

**Plugin-contributed Prisma models (same primary datasource)**

| Name | Type | Description |
| --- | --- | --- |
| `workers` | `@netscript/plugin-workers` | Job and schedule definitions (for example JobDefinition) backing the durable background-job runtime. |
| `sagas` | `@netscript/plugin-sagas` | Durable saga state — saga_runtime_state / saga_runtime_transition / saga_runtime_correlation — when the saga store backend is prisma (vs kv). See Durable sagas. |
| `triggers` | `@netscript/plugin-triggers` | Trigger definitions and delivery bookkeeping for the inbound webhook/ingest runtime. |
| `auth` | `@netscript/plugin-auth` | auth.prisma: auth_users / auth_sessions / auth_accounts / auth_verifications — used by the better-auth backend. (kv-oauth stores sessions in KV; WorkOS is stateless.) |

> auth.prisma is backend-specific
>
> The
>
> auth plugin
>
> contributes
>
> auth.prisma
>
> with
>
> auth_users
>
> ,
>
> auth_sessions
>
> ,
>
> auth_accounts
>
> , and
>
> auth_verifications
>
> . Those tables are the persistence shape for the
>
> better-auth
>
> backend. The default
>
> kv-oauth
>
> backend keeps sessions in
>
> KV
>
> and
>
> WorkOS
>
> is stateless (sealed cookie), so they do not depend on these tables. Run the auth migration only when you select the better-auth backend via
>
> NETSCRIPT_AUTH_BACKEND
>
> .

> Postgres can also back the work queue
>
> Persistence is not the only place Postgres shows up. The queue runtime now ships a
>
> PostgreSQL backend
>
> alongside Deno KV, Redis, and RabbitMQ — a durable, row-claimed (
>
> FOR UPDATE SKIP LOCKED
>
> ) queue table in the same Postgres you already provision. It is selectable only via an
>
> explicit
>
> provider: 'postgres'
>
> (auto-discovery never picks it). See
>
> KV, queues & cron
>
> for
>
> connection.postgres.{url, tableName}
>
> and the full backend matrix.

## Adapter selection — postgres, mssql, mysql

Prisma 7 talks to the database through a **driver adapter**. NetScript wraps each driver in a small `DatabaseAdapter` that gives every backend the same lifecycle surface (`getDriverAdapter` → `setClient` → `connect`/`disconnect`/`healthCheck`/`getStatus`). The recommended scaffold is Postgres, but MSSQL and MySQL ship as sub-exports so you can target — or add — a second engine without changing how your code consumes the client.

The shared options shape comes from `DatabaseConnectionOptions` (`@netscript/database/ports`): every adapter accepts either a `connectionString` or the structured `host` / `port` / `database` / `username` / `password` / `ssl` / `poolSize` / `timeout` parts, plus a few engine-specific extras.

**Driver adapters (each implements DatabaseAdapter)**

| Name | Type | Description |
| --- | --- | --- |
| `adapters/postgres` | `createPostgresAdapter(opts)` | PostgreSQL via @prisma/adapter-pg. Re-exported from the @netscript/database/adapters barrel. PostgresConnectionOptions adds schema and applicationName. Builds a connection string under the hood. |
| `adapters/mssql` | `createMssqlAdapter(opts)` | SQL Server via @prisma/adapter-mssql. Import from @netscript/database/adapters/mssql (sub-export — NOT in the barrel). MssqlConnectionOptions adds instanceName, trustServerCertificate, encrypt, integratedSecurity, applicationName, connectTimeout, requestTimeout. Accepts ADO.NET-style connection strings. |
| `adapters/mysql` | `createMysqlAdapter(opts)` | MySQL 8.x / MariaDB via @netscript/prisma-adapter-mysql (a native-Deno driver). Import from @netscript/database/adapters/mysql (sub-export). MysqlConnectionOptions adds charset, timezone, connectionLimit, multipleStatements. |

**DatabaseAdapter surface (every adapter)**

| Name | Type | Description |
| --- | --- | --- |
| `provider` | `'postgres' \| 'mssql' \| 'mysql'` | Readonly provider identity used in status reporting. |
| `getDriverAdapter()` | `→ driver adapter` | Returns the Prisma driver adapter to pass as `new PrismaClient({ adapter })`. Lazily constructs it from the options. |
| `setClient(client)` | `(client) => void` | Hand the constructed PrismaClient back to the adapter so connect / health / raw calls have a client to use. |
| `getClient()` | `→ PrismaClient` | Return the configured Prisma client. Throws if setClient() has not been called — see the callout below. |
| `connect() / disconnect()` | `→ Promise` | Explicit $connect / $disconnect. Prisma auto-connects on first query, so these are optional. |
| `healthCheck()` | `→ Promise` | Lightweight `SELECT 1` probe; true when the connection answers. |
| `getStatus()` | `→ Promise` | Snapshot: { connected, provider, database, host, lastConnected, error }. |
| `executeRaw() / executeRawUnsafe()` | `(query, ...params) => Promise` | Raw query escape hatches routed through the configured client. |

> getClient() needs setClient() first
>
> The adapter does not own the
>
> PrismaClient
>
> — you construct it. The flow is always: build the adapter, call
>
> getDriverAdapter()
>
> , pass that to
>
> new PrismaClient({ adapter })
>
> , then call
>
> adapter.setClient(client)
>
> . Only then does
>
> adapter.getClient()
>
> (and
>
> connect
>
> /
>
> healthCheck
>
> /
>
> executeRaw
>
> ) work — call
>
> getClient()
>
> before
>
> setClient()
>
> and it throws
>
> "… client not initialized. Call setClient() …"
>
> .

## Tracing — Prisma OpenTelemetry spans

Prisma query spans are wired through a lightweight tracing helper exported from `@netscript/database/tracing`. It is a drop-in for `@prisma/instrumentation` that avoids the CJS-heavy `@opentelemetry/instrumentation` dependency (which breaks Deno bundle/compile). Call `enablePrismaTracing()` **once, before you construct any Prisma client**, and engine spans dispatch into your OpenTelemetry tracer with the standard W3C `traceparent`.

**@netscript/database/tracing — PrismaTracingConfig + hooks**

| Name | Type | Description |
| --- | --- | --- |
| `enablePrismaTracing(config?)` | `(PrismaTracingConfig) => void` | Register the tracing helper. Call once, before creating any PrismaClient. |
| `config.tracerProvider` | `PrismaTracingProvider` | Tracer provider to use. Defaults to the globally registered OpenTelemetry provider. |
| `config.ignoreSpanTypes` | `(string \| RegExp)[]` | Span-name patterns to drop (string match or regex). Defaults to []. |
| `disablePrismaTracing()` | `() => void` | Clear the global tracing helper. |
| `isPrismaTracingEnabled()` | `() => boolean` | True when a tracing helper is currently registered. |
| `enableInstrumentation()` | `() => boolean (@netscript/database)` | Convenience toggle from the package root: enables Prisma OTEL instrumentation only when OTEL_DENO=true; returns whether it was enabled. |

```ts
// services/orders/src/tracing.ts
import { enablePrismaTracing } from '@netscript/database/tracing';

// Call ONCE, before constructing any PrismaClient. Engine spans then dispatch
// into the globally registered OpenTelemetry tracer with a W3C traceparent.
enablePrismaTracing({
  // tracerProvider defaults to the global provider; override only if you manage
  // your own. ignoreSpanTypes drops noisy internal spans by name or regex.
  ignoreSpanTypes: ['prisma:client:serialize', /detect_platform/],
});

// ... now construct the client (see the adapter example below).
import { PrismaClient } from '../database/postgres/schema/.generated/client.server.ts';
const prisma = new PrismaClient();
```

```ts
// Alternatively, gate instrumentation on the OTEL_DENO flag from the package root.
import { enableInstrumentation } from '@netscript/database';

// Returns true only when OTEL_DENO=true and wiring succeeded.
const tracing = enableInstrumentation();
console.log('prisma tracing on:', tracing);
```

## Runnable example: wiring a second database (MySQL)

The adapters let you stand up a **second** datasource beside the primary Postgres — for example a reporting MySQL instance — without leaving the typed-client model. The pattern is the same for every engine: create the adapter, pass `getDriverAdapter()` into a `PrismaClient`, then `setClient()` so the adapter can manage lifecycle and health. Swap the import to `adapters/mssql` and `createMssqlAdapter` for SQL Server — the surface is identical. The MySQL adapter is a sub-export (not in the `adapters` barrel), so import it from its own path.

```ts
// services/reporting/src/db.ts
// MySQL ships as a sub-export — import from /adapters/mysql, not the barrel.
import { createMysqlAdapter } from '@netscript/database/adapters/mysql';
import { PrismaClient } from '../database/mysql/schema/.generated/client.server.ts';

// 1) Build the adapter from structured parts (or pass { connectionString }).
const adapter = createMysqlAdapter({
  host: Deno.env.get('MYSQL_HOST') ?? 'localhost',
  port: 3306,
  database: 'reporting',
  username: Deno.env.get('MYSQL_USER') ?? 'root',
  password: Deno.env.get('MYSQL_PASSWORD'),
  ssl: false,
});

// 2) Pass the driver adapter into Prisma, then hand the client back.
export const reporting = new PrismaClient({ adapter: adapter.getDriverAdapter() });
adapter.setClient(reporting);

// 3) Now adapter lifecycle + health work off the same client.
await adapter.connect();
const ok = await adapter.healthCheck(); // SELECT 1
console.log('mysql healthy:', ok, await adapter.getStatus());
```

```ts
// services/reporting/src/db.ts — SQL Server variant (same shape)
import { createMssqlAdapter } from '@netscript/database/adapters/mssql';
import { PrismaClient } from '../database/mssql/schema/.generated/client.server.ts';

const adapter = createMssqlAdapter({
  host: Deno.env.get('MSSQL_SERVER') ?? 'localhost',
  port: 1433,
  database: 'reporting',
  username: 'sa',
  password: Deno.env.get('MSSQL_PASSWORD'),
  // local-dev TLS knobs; tighten for production
  encrypt: true,
  trustServerCertificate: true,
});

export const reporting = new PrismaClient({ adapter: adapter.getDriverAdapter() });
adapter.setClient(reporting);
await adapter.connect();
```

```ts
// Prefer env-driven config? Each engine ships a getter that reads structured
// vars (MYSQL_HOST/…) and falls back to a connection-string env var.
import { createMysqlAdapter } from '@netscript/database/adapters/mysql';
import { getMysqlConfig } from '@netscript/database/adapters/mysql';

// getMysqlConfig() → MysqlAdapterConfig from MYSQL_* or MYSQLDB_URI / DATABASE_URL.
const cfg = getMysqlConfig();
const adapter = createMysqlAdapter({
  host: cfg.hostname,
  port: cfg.port,
  database: cfg.db,
  username: cfg.username,
  password: cfg.password,
});
// (getMssqlConfig / getPostgres equivalents exist per adapter.)
```

> A second datasource is a second schema dir
>
> A second engine is a separate Prisma schema workspace (for example
>
> database/mysql/schema/
>
> ) with its own
>
> generate
>
> output and its own migrations — it does
>
> not
>
> merge into the Postgres aggregation above. Generate and migrate each datasource independently. The full step-by-step lives in the
>
> Use a second database
>
> recipe.

## Endpoints & ports

The database itself isn't an HTTP service you call — it's a Postgres container Aspire provisions and the generated Prisma client connects to. The relevant surfaces are the Aspire resources and the connection-string env vars the workspace resolves.

**Database surface (provisioned by Aspire)**

| Name | Type | Description |
| --- | --- | --- |
| `postgres` | `Aspire resource` | The Postgres container Aspire provisions from appsettings.json NetScript.Databases.postgres. Watch it go green in the dashboard. |
| `redis` | `Aspire resource` | Redis cache — the default `--cache-backend`; Redis-compatible — backing KV/queues. A separate concern from Postgres; see KV, queues & cron. (`garnet` and `deno-kv` are alternative backends.) |
| `https://localhost:18888` | `dashboard` | Aspire dashboard (token printed by `aspire start`) — confirm the postgres resource is healthy. |
| `POSTGRES_URI / DATABASE_URL` | `env` | Connection string resolved by prisma.config.ts and normalized to a URL. Set these yourself under --no-aspire. |

> Production pitfalls
>
> - **Forgetting Aspire.** The most common failure: running `netscript db init` with no `aspire start` up. Start orchestration first, from the `aspire/` folder.
> - **Wrong directory.** Run `aspire start` from `aspire/`, but run the `netscript db` commands from the workspace **root** (or pass `--project-root`).
> - **Stale client after a schema change.** Editing a `.prisma` file without re-running `netscript db generate` leaves your code typed against the old model.
> - **Calling getClient() before setClient().** A second-database adapter throws until you hand it the constructed `PrismaClient` via `setClient()`.
> - **Tracing wired too late.** `enablePrismaTracing()` must run *before* the first `PrismaClient` is constructed, or early query spans are lost.
> - **Docker not running.** Aspire provisions Postgres and Redis as containers; if Docker/Podman is down the `postgres` resource never goes green.

> MSSQL & MySQL are sub-exports
>
> Postgres is the recommended engine and lives in the
>
> @netscript/database/adapters
>
> barrel. The
>
> SQL Server
>
> and
>
> MySQL
>
> adapters are imported from their own sub-paths —
>
> @netscript/database/adapters/mssql
>
> and
>
> @netscript/database/adapters/mysql
>
> — so a Postgres-only app never pulls in the heavier
>
> mssql
>
> / native-Deno MySQL drivers. The MySQL driver itself lives in the standalone
>
> `@netscript/prisma-adapter-mysql`
>
> package.

## How it compares

Backend platforms answer the persistence question differently, and each answer is a real trade-off. **Convex** replaces the relational engine with its own reactive datastore and a TypeScript-declared schema; **Supabase** standardizes on hosted Postgres with a SQL schema. NetScript keeps the engine decision with you and makes the Prisma schema the contract everything else is generated from.

|  | NetScript | Convex | Supabase |
| --- | --- | --- | --- |
| Choice of relational engine (Postgres / MySQL / MSSQL / SQLite) | Yes — `--db` at scaffold time | No — Convex is its own datastore | No — Postgres |
| Schema authored in Prisma files | Yes — aggregated per plugin | No — declared in TypeScript | No — SQL migrations |
| Database runs in your own infrastructure by default | Yes — Aspire-provisioned container, or a server you point at | No — Convex Cloud by default (self-hosting available) | No — hosted Postgres by default (self-hosting available) |

If your product wants a managed reactive datastore, those platforms are built for it. If your product needs to sit on a specific relational engine — an existing MSSQL estate, a Postgres you already operate, a file-backed SQLite for the desktop case — the driver adapters above are the mechanism that keeps your query code identical across all of them.

## Where to go next

This hub is intentionally thin — the full generated API lives in the reference. Pick the lane that matches what you're doing.

[Learn — Workspace data (Track B 03)  Guided tutorial: wire workspace data through Prisma, end to end, in the Team Workspace track.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/03-workspace-data/)

[Do — Use a second database  Task recipe: add an MSSQL or MySQL datasource beside Postgres with a driver adapter.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/use-a-second-database/)

[Do — Database & migration  Task recipe: bring up Postgres with Aspire, then run db init → generate → seed → status → migrate.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/)

[Look up — @netscript/database reference  The full generated API: ports, the postgres/mssql/mysql adapters, extensions, and tracing.](https://rickylabs.github.io/netscript/netscript/reference/database/)

[Understand — Orchestration with Aspire  Why the AppHost (aspire/apphost.mts) provisions Postgres and Redis, and how the resource graph fits together.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

[MySQL — prisma-adapter-mysql  The native-Deno MySQL Prisma driver adapter surface, generated.](https://rickylabs.github.io/netscript/netscript/reference/prisma-adapter-mysql/)

[Durable streams](https://rickylabs.github.io/netscript/netscript/durable-workflows/streams/) [KV, queues & cron](https://rickylabs.github.io/netscript/netscript/data-persistence/kv-queues-cron/)

_Canonical: https://rickylabs.github.io/netscript/data-persistence/database/_

---

# Data & Persistence — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/data-persistence/how-to/_

---

# Choose a queue provider

**Scope:** how to pick the right backend for `@netscript/queue` — the in-memory test adapter, the zero-config Deno KV default, Redis, RabbitMQ (AMQP), and PostgreSQL — and how to either let auto-discovery select one or pin one explicitly with `provider` + `connection`. This is the *decision* recipe; for the enqueue/consume/cron mechanics see [Queue / KV / cron](https://rickylabs.github.io/netscript/data-persistence/how-to/queue-kv-cron/).

A NetScript queue is provider-agnostic by design: the same `createQueue("jobs")` runs on an in-memory adapter in a unit test, on Deno KV on your laptop, and on a real broker under Aspire — without touching the call site. The only thing that changes is which backend the factory resolves. This recipe is about making that choice deliberately.

## Prerequisites

**Before you start**

| Name | Type | Description |
| --- | --- | --- |
| `A NetScript workspace` | `netscript init` | Created per the Quickstart. Import @netscript/queue from any workspace member. |
| `Start Aspire (for real backends)` | `cd aspire && aspire start` | Aspire provisions Postgres, Redis/Garnet, and any AMQP broker BEFORE your service connects. The in-memory and Deno KV adapters need nothing extra; Redis, RabbitMQ, and the Postgres queue all expect Aspire up first. |
| `Deno KV unstable flag` | `--unstable-kv` | The Deno KV backend (the auto-discovery fallback) uses Deno KV. The scaffold's deno.json sets unstable: ['raw-imports', 'kv']; add --unstable-kv to any ad-hoc deno run/check that touches the queue. |

## The five backends at a glance

There are **four** selectable production providers in the `QueueProvider` enum — Deno KV, Redis, RabbitMQ, and PostgreSQL — plus the `MemoryQueueAdapter` from `@netscript/queue/testing` for tests and examples. Pick by the row that matches your deployment, then jump to the matching step.

**Queue backends in @netscript/queue**

| Backend | How you select it | Reach for it when |
| --- | --- | --- |
| `MemoryQueueAdapter` | `new MemoryQueueAdapter()` from `@netscript/queue/testing` (never auto-discovered) | Unit tests and isolated examples — volatile, in-process, zero setup; data is lost on restart. |
| Deno KV `(provider: 'deno-kv')` | Auto-discovery **fallback**, or pin `QueueProvider.DenoKv` | Local dev and single-instance apps with no broker; durable to the Deno KV store. Needs `--unstable-kv`. |
| Redis `(provider: 'redis')` | Auto-discovered when a Redis/Garnet connection is present; or pin `QueueProvider.Redis` | High-throughput production with a Redis/Garnet resource already provisioned by Aspire. |
| RabbitMQ `(provider: 'rabbitmq')` | Auto-discovered **first** when an AMQP broker is present; or pin `QueueProvider.RabbitMQ` | Broker-grade routing and reliability via Fedify's AMQP adapter; the top of the auto-discovery probe. |
| PostgreSQL `(provider: 'postgres')` | **Explicit only** — pass `QueueProvider.Postgres`; never auto-discovered | You already run Postgres and want one fewer moving part, or want the queue to share your transactional store. Row-claim via `FOR UPDATE SKIP LOCKED`. |

## Step 1 — Default: let auto-discovery pick

If you pass no `provider`, the factory probes the Aspire environment and selects the first available backend in a fixed order. Write provider-neutral code and let the environment decide:

```ts
// queue.ts
import { createTypedQueue } from "@netscript/queue";
import { z } from "zod";

const JobSchema = z.object({ id: z.string(), kind: z.string() });

// No provider → auto-discovery. Probe order: RabbitMQ → Redis → Deno KV.
export const jobs = createTypedQueue("jobs", JobSchema);
```

The probe order is **RabbitMQ (AMQP) → Redis → Deno KV**. Deno KV is the always-available fallback when no broker is discoverable, so the same code runs unchanged from laptop to production as you provision real backends under Aspire.

> PostgreSQL is the deliberate exception
>
> Auto-discovery probes
>
> RabbitMQ → Redis → Deno KV only
>
> . It will
>
> never
>
> fall through to PostgreSQL — even when a Postgres connection is present in the environment. The SQL-durable queue is opt-in: you must pass
>
> provider: 'postgres'
>
> (Step 3) or you will quietly land on the Deno KV adapter.

## Step 2 — Pin a provider explicitly

To take auto-discovery out of the loop, pass `provider` from the `QueueProvider` enum. Connection details go under `connection.<provider>`; every URL is optional and falls back to Aspire service discovery when omitted.

```ts
// queue.ts
import { createQueue, QueueProvider } from "@netscript/queue";

const jobs = createQueue("jobs", {
  provider: QueueProvider.Redis,
  connection: {
    redis: {
      // url optional → falls back to getRedisConnectionFromEnv() / Aspire.
      url: Deno.env.get("REDIS_URL"),
      // options are passed through to ioredis.
      options: {},
    },
  },
});
```

```ts
// queue.ts
import { createQueue, QueueProvider } from "@netscript/queue";

const jobs = createQueue("jobs", {
  provider: QueueProvider.RabbitMQ,
  connection: {
    rabbitmq: {
      // url optional → derived from Aspire's rabbitmq service (amqp://).
      url: Deno.env.get("AMQP_URL"),
      // queueName defaults to the queue's logical name.
      queueName: "jobs",
    },
  },
});
```

```ts
// queue.ts
import { createQueue, QueueProvider } from "@netscript/queue";

const jobs = createQueue("jobs", {
  provider: QueueProvider.DenoKv,
  connection: {
    denoKv: {
      // path optional → Aspire discovery or the default shared Deno KV.
      path: Deno.env.get("DENO_KV_URL"),
      verbose: false,
    },
  },
});
```

## Step 3 — Select the PostgreSQL backend

The PostgreSQL provider gives you a SQL-durable queue with row-claim semantics (`FOR UPDATE SKIP LOCKED`), a visibility timeout, ack/nack, and a dead-letter store — so concurrent consumers never double-claim a message. Because it is never auto-discovered, you must name it:

```ts
// queue.ts
import { createQueue, QueueProvider } from "@netscript/queue";

// provider: QueueProvider.Postgres is the ONLY way to select this backend.
const jobs = createQueue("jobs", {
  provider: QueueProvider.Postgres,
  connection: {
    postgres: {
      // url optional → falls back to Aspire's getPostgresUri().
      url: Deno.env.get("DATABASE_URL"),
      // tableName defaults to 'message_queue'.
      tableName: "message_queue",
    },
  },
});

await jobs.enqueue({ id: "job-1", kind: "reindex" });
```

Reach for Postgres when you already run it under Aspire and want the queue and your application data in one transactional store, rather than standing up a dedicated broker.

## Step 4 — Use the in-memory backend in tests

For unit tests and examples, construct the `MemoryQueueAdapter` directly from the testing sub-path. It is volatile and in-process — nothing to provision, and it is never selected by auto-discovery, so production code paths stay untouched:

```ts
// jobs_test.ts
import { MemoryQueueAdapter } from "@netscript/queue/testing";

const queue = new MemoryQueueAdapter<{ id: string }>();

await queue.enqueue({ id: "job-1" });
await queue.listen(async (message) => {
  // assert on `message` here
});
```

## Step 5 — Add concurrency with createParallelQueue

Any provider can be wrapped for concurrent processing with `createParallelQueue`. Pass a `concurrency` greater than 1 and a single listener processes that many messages at once — ideal for I/O-bound work (HTTP calls, DB queries). At `concurrency: 1` (the default) it is identical to `createQueue`.

```ts
// queue.ts
import { createParallelQueue, QueueProvider } from "@netscript/queue";

// 8 messages processed concurrently on one listener, pinned to Redis.
const queue = createParallelQueue("notifications", {
  concurrency: 8,
  provider: QueueProvider.Redis,
});

await queue.listen(async (message) => {
  await deliver(message); // these run in parallel
});
```

For CPU-bound work, prefer Web Workers over queue concurrency — see [Tune the worker runtime](https://rickylabs.github.io/netscript/background-processing/how-to/tune-worker-runtime/).

## Prove it end to end — same call site, two backends

The pluggability claim is only convincing if you can watch one file run unchanged on two backends. Write the producer/consumer against the factory (no `provider`), then run it first on the Deno KV fallback locally and again on Redis under Aspire — the file never changes.

```ts
// jobs.ts — the resulting file: provider-neutral producer + consumer
import { createTypedQueue } from '@netscript/queue';
import { z } from 'zod';

const JobSchema = z.object({ id: z.string(), kind: z.string() });

// No provider → auto-discovery. Probe order: RabbitMQ → Redis → Deno KV.
export const jobs = createTypedQueue('jobs', JobSchema);

if (import.meta.main) {
  await jobs.enqueue({ id: 'job-1', kind: 'reindex' });
  await jobs.listen(async (message) => {
    console.log('processed', message.id, message.kind);
  });
}
```

```bash
# From the workspace root, in order:

# 1. Local run — no Aspire, no broker. Auto-discovery falls through to Deno KV.
#    The scaffold's deno.json already sets unstable: ['raw-imports', 'kv'];
#    add --unstable-kv to any ad-hoc run that touches the queue.
deno run --unstable-kv -A jobs.ts
#    -> processed job-1 reindex   (on the Deno KV fallback)

# 2. Provision the real backend, then run the SAME file untouched.
cd aspire && aspire start && cd ..   # brings up Redis/Garnet
deno run --unstable-kv -A jobs.ts
#    -> processed job-1 reindex   (now auto-discovered onto Redis)
```

The call site — `createTypedQueue('jobs', JobSchema)`, `enqueue`, `listen` — is identical in both runs; only the resolved backend changed. Pin a specific provider with `provider: QueueProvider.*` (Step 2) when you want to take auto-discovery out of the loop.

## In-production pitfalls

> Choosing a provider — read before you ship
>
> - **Local default is Deno KV, not a broker.** If you never start Aspire, auto-discovery silently lands on the Deno KV fallback. Fine for dev — but don't assume broker-grade ordering or fan-out until you've provisioned and confirmed the real backend.
> - **PostgreSQL is opt-in, never auto-selected.** The probe is RabbitMQ → Redis → Deno KV; it will **not** choose Postgres even when a Postgres connection exists. Pin `provider: QueueProvider.Postgres` or you'll quietly run on Deno KV.
> - **Remote Deno KV (KV Connect) switches adapters.** A Deno KV path that is an `http(s)://` URL is treated as KV Connect, which has no native queue ops — the factory transparently swaps in a polling adapter (configurable `pollInterval`, `visibilityTimeout`, `maxRetries` under `connection.denoKv`). A local/SQLite KV path uses native queue ops. Know which one you're on before tuning.
> - **Make handlers idempotent.** A thrown `QueueHandlerError` follows each backend's own ack/retry policy, so the same message can be redelivered. An idempotent handler can't double-charge or double-send on a retry.

> Validate at the boundary
>
> Prefer
>
> createTypedQueue
>
> (Zod-validated at enqueue and dequeue) over the untyped
>
> createQueue
>
> whenever the payload shape matters. An unvalidated queue can carry malformed messages until the consumer fails inside the handler; validation at enqueue time fails fast at the producer, regardless of which provider you chose.

## See also

[KV, queues & cron](https://rickylabs.github.io/netscript/netscript/data-persistence/kv-queues-cron/) — the concept-level tour of queues, KV, and cron, and how Aspire wires the four queue backends.

[Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/) — when you want a managed worker job (persistence, retries, an HTTP trigger) instead of a raw queue.

[Queue / KV / cron](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/queue-kv-cron/) — the mechanics recipe: enqueue, consume, and schedule. This page pairs with it: choose the backend here, run it there.

For the full `QueueProvider` enum, the `QueueConnectionOptions` shape, `createParallelQueue` / `ParallelQueueOptions`, the `MessageQueue` interface, and the `QueueError` hierarchy, see

[queue](https://rickylabs.github.io/netscript/netscript/reference/queue/) .

[Use a second database](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/use-a-second-database/) [Tune the worker runtime](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/tune-worker-runtime/)

_Canonical: https://rickylabs.github.io/netscript/data-persistence/how-to/choose-a-queue-provider/_

---

# Database & migration

**Goal:** take a freshly scaffolded NetScript workspace and stand up its database — bring up the AppHost, create the first migration, generate the typed Prisma client, seed it, and confirm the schema is applied — using only the public `netscript db` commands.

This recipe uses **Postgres**, the recommended default and the engine every tutorial builds on. The database is polyglot, though: NetScript scaffolds a Prisma-backed database for four engines, chosen at scaffold time with `--db` — `netscript init my-app --db postgres|mysql|mssql|sqlite`. Postgres, MySQL, and MSSQL come up as Aspire container resources; SQLite is file-backed and needs no container. The migration loop below is identical on every engine; only the provisioning differs.

This is a task-oriented recipe. The single most important fact, and the one most people trip over: **`netscript db` commands provision and talk to Postgres *through* Aspire**. Aspire is step 2, not an afterthought. You bring the database up first with `cd aspire && aspire start`, *then* the `db` commands have something to connect to. Skip that ordering and `db init` fails with `aspire start failed` before it ever reaches Prisma. Everything below assumes the default Aspire layout; the `--no-aspire` escape hatch is called out where it differs.

> Aspire must be running first
>
> Every
>
> netscript db
>
> command needs a live Postgres instance. In the default (Aspire) layout, Postgres is a container that
>
> Aspire
>
> provisions — so
>
> cd aspire && aspire start
>
> has to be up
>
> before
>
> you run
>
> netscript db init
>
> . Running a
>
> db
>
> command against a stopped AppHost fails with
>
> aspire start failed: … Project file does not exist
>
> . That is the dependency, not a bug — see
>
> Orchestration with Aspire
>
> for why the AppHost owns the database container.

## What you'll end up with

By the end of this recipe you will have a running Postgres container, a first migration on disk and applied, a generated Prisma client (with matching zod schemas) under `database/postgres/schema/.generated/`, seeded baseline rows, and a green `netscript db status`. The whole loop is four commands, run once, against a database that Aspire is keeping alive in a second terminal.

**The migration workflow at a glance**

| Name | Type | Description |
| --- | --- | --- |
| `aspire start` | `from aspire/` | Provisions the Postgres + Redis containers. Must be up first and stay running. |
| `netscript db init --name init` | `from workspace root` | Initializes tooling, creates the first migration from schema.prisma, applies it to Postgres. |
| `netscript db generate` | `from workspace root` | Generates the Deno-runtime Prisma client + zod schemas into .generated. Re-run after every schema edit. |
| `netscript db seed` | `from workspace root` | Runs database/postgres/scripts/seed.ts to populate baseline rows. |
| `netscript db status` | `from workspace root` | Reports which migrations are applied and whether the database is in sync — the authoritative verification. |

## Before you start

**Prerequisites**

| Name | Type | Description |
| --- | --- | --- |
| `NetScript workspace` | `netscript init …` | A workspace scaffolded with a database. This recipe uses --db postgres (the recommended default), which lays down database/postgres/ with a Prisma schema, prisma.config.ts, and seed scripts. Swap --db postgres for mysql, mssql, or sqlite for a different engine — the workflow is the same, only the database// directory differs. |
| `netscript CLI` | `on PATH` | Install with deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11 — then netscript --help should print. |
| `Aspire CLI` | `aspire` | Used to provision Postgres and Redis as containers via Docker. Confirm with aspire --version. Docker/Podman must be running. |
| `Deno` | `2.x` | deno --version. Prisma generation runs under the Deno runtime (the schema sets runtime="deno"). |

If you scaffolded with `--no-aspire`, you are responsible for pointing the workspace at your own Postgres via `POSTGRES_URI` / `DATABASE_URL` (see [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/)); there is no AppHost to start, so you skip Step 2, but the migration commands in Step 3 are otherwise identical and talk to whatever database those variables resolve to.

Run every command from your workspace root unless a step says otherwise. To target a workspace other than the current directory, pass `--project-root <path>` — useful in CI or when scripting against a checkout you are not `cd`-ed into.

## Step 1 — Confirm the database wiring

A scaffolded workspace already contains the database workspace at `database/postgres/`. You do not author any of this by hand; the point of this step is to recognize the moving parts so the later commands make sense:

```text
my-app/
├── appsettings.json              # NetScript.Databases.postgres — Engine/Mode/DatabaseName
├── netscript.config.ts           # databases.config is intentionally empty here
└── database/postgres/
    ├── schema/
    │   ├── schema.prisma          # root: generator client (runtime="deno"), generator zod, datasource db
    │   ├── plugins/               # per-plugin .prisma models aggregated here
    │   │   ├── workers/workers.prisma
    │   │   ├── sagas/sagas.prisma
    │   │   └── triggers/triggers.prisma
    │   └── .generated/            # created by `db generate`: Prisma client + zod
    ├── prisma.config.ts           # schema dir + migrations path + datasource url
    ├── migrations/                # created by `db init`: timestamped migration dirs
    └── scripts/                   # migrate.ts, seed.ts, generate-zod.ts, …
```

Two things worth internalizing before you run anything:

- **The datasource is Postgres, driven by `appsettings.json` — not by `netscript.config.ts`.** In the scaffold, `netscript.config.ts` has `databases: { config: [] }` (empty). The real connection details live in `appsettings.json` under `NetScript.Databases.postgres` (`Engine: "Postgres"`, `Mode: "Container"`, a generated `DatabaseName`, and a persistent `DataPath` of `.data/postgres`). Aspire reads that block to provision the container, and `prisma.config.ts` resolves its datasource URL from the same source. If you ever wonder "where does the connection string come from?", the answer is this block, not the config file.
- **Plugin schemas are split out and aggregated.** Each first-party plugin ships its own `database/<plugin>.prisma`; those are aggregated under `database/postgres/schema/plugins/<plugin>/`. So after adding the `workers`, `sagas`, and `triggers` plugins you'll see their tables (e.g. `model JobDefinition` from workers) join the root `ExampleRecord` model in the same Postgres datasource. One migration covers them all.

> One datasource, many contributors
>
> NetScript uses a single primary Postgres datasource. Plugins contribute Prisma models into it rather than each owning a separate database, so one
>
> db init
>
> /
>
> db generate
>
> cycle covers the app and its plugins together. Adding a plugin later that ships its own
>
> .prisma
>
> means re-running
>
> netscript db migrate
>
> and
>
> netscript db generate
>
> to fold its tables in.

## Step 2 — Bring up Postgres with Aspire (do this first)

From the workspace root, change into the isolated Aspire folder and start the AppHost. The TypeScript AppHost (`aspire/apphost.mts`) lives in `aspire/` to keep its Node graph separate from the Deno workspace, so the commands run from there:

```bash
cd aspire
aspire restore   # one-time: downloads the AppHost SDK modules
aspire start       # provisions Postgres + Redis containers and starts the resource graph
```

Leave `aspire start` running in this terminal. It provisions both the Postgres database and the Redis cache (your KV/queue backend) as Docker containers — no manual `docker run` and no local Postgres install required. When it settles you'll have:

- The **Aspire dashboard** at [https://localhost:18888](https://localhost:18888) — the access token is printed in the `aspire start` output. Open it and confirm the `postgres` and `redis` resources are green.
- Resources named `postgres`, `redis`, and the per-capability services/processors (`workers-api`, `workers`, `sagas-api`, `sagas`, `triggers-api`, `triggers`). If you also scaffolded auth and streams, you'll see `auth-api` (:8094) and the streams service (:4437) join the graph.

> If db commands fail with "aspire start failed"
>
> That error means the AppHost is not running, or you ran the
>
> db
>
> command from a directory where Aspire can't find
>
> aspire/apphost.mts
>
> . Fix: start
>
> aspire start
>
> from the
>
> aspire/
>
> folder
>
> first
>
> , keep it running, and run the
>
> netscript db
>
> commands from the
>
> workspace root
>
> in a separate terminal.

## Step 3 — Run the migration workflow

Open a **second terminal** at the workspace root (keep `aspire start` going in the first). Now Postgres is reachable, run the four-command database workflow in order:

```bash
# Create the first migration from the current Prisma schema and apply it.
# --name labels the migration directory (here: a migration called "init").
netscript db init --name init
```

```bash
# Generate the Deno-runtime Prisma client (and the zod schemas) into
# database/postgres/schema/.generated so your code can import typed models.
netscript db generate
```

```bash
# Run the workspace seed scripts (database/postgres/scripts/seed.ts)
# to populate baseline rows.
netscript db seed
```

```bash
# Show migration / tooling status: which migrations are applied and
# whether the database is in sync with the schema.
netscript db status
```

What each step does, in plain terms:

- **`netscript db init --name init`** — initializes database tooling and creates the first migration from `database/postgres/schema/schema.prisma`, writing it to the migrations path declared in `prisma.config.ts` (`migrations: { path: 'migrations' }`) and applying it to the running Postgres container. The `--name` value names the migration directory; pick something descriptive for later migrations (`add-orders`, `index-email`), not just `init`.
- **`netscript db generate`** — runs database code generation: the Prisma client (`generator client` with `runtime="deno"`, output `./.generated`) plus the zod schemas (`generator zod` → `./.generated/zod`). Re-run this whenever the schema changes, because the generated types are how your application code stays in lockstep with the database.
- **`netscript db seed`** — executes the seed scripts under `database/postgres/scripts/`. Seeds are ordinary Deno scripts, so they can insert baseline rows, reference data, or a first admin record using the freshly generated client.
- **`netscript db status`** — reports migration/tooling status so you can confirm the schema is applied and in sync. This is the command you'll reach for most often once you start iterating.

> Iterating on the schema later
>
> After the first
>
> init
>
> , evolve the schema by editing the
>
> .prisma
>
> files and running
>
> netscript db migrate
>
> to create and apply the next migration, then
>
> netscript db generate
>
> to refresh the client. The pair is the rhythm of day-to-day schema work:
>
> migrate then generate, every time
>
> .
>
> netscript db reset
>
> drops and re-applies everything (destructive — dev only), and
>
> netscript db studio
>
> opens a visual browser over the data.

## Step 4 — Verify

Confirm the database is migrated and seeded three ways, from most to least authoritative:

1. **CLI status.** `netscript db status` reports the `init` migration as applied and the schema in sync. This is the authoritative check — if it is green, the rest is corroboration.
2. **Generated client exists.** `database/postgres/schema/.generated/` now contains the Prisma client and the `zod` schemas — proof `db generate` succeeded and your typed models are importable from application code.
3. **Aspire dashboard.** The `postgres` resource at [https://localhost:18888](https://localhost:18888) is green and shows recent activity from the migration and seed runs. Use it to eyeball that the container is healthy.

If all three line up, your database is provisioned, migrated, and seeded — you can now import the generated client in a service or worker and read the rows the seed wrote.

> Production pitfalls
>
> - **Forgetting Aspire.** The most common failure: running `netscript db init` with no `aspire start` up. Start Aspire first.
> - **Wrong directory.** Run `aspire start` from `aspire/`, but run the `netscript db` commands from the workspace root (or pass `--project-root`).
> - **Stale client after a schema change.** Editing a `.prisma` file without re-running `netscript db generate` leaves your code typed against the old shape. Generate after every schema change.
> - **Docker not running.** Aspire provisions Postgres and Redis as containers; if Docker/Podman is down, the `postgres` resource never goes green.
> - **Treating `db reset` as routine.** It is destructive — it drops the database. Keep it to local dev.

## Where the data goes next

Once the schema is live, the generated client is what every other capability reads and writes through. Queue jobs persist their `message_queue` rows (the [PostgreSQL queue backend](https://rickylabs.github.io/netscript/data-persistence/how-to/queue-kv-cron/) shares this same datasource), durable sagas persist runtime state when configured with the Prisma store backend, and your services query their models directly. The migration loop you just ran is the foundation the rest of the workspace stands on.

## See also

Reference — database

The full generated @netscript/database API: schema helpers, the Prisma adapter surface, and migration tooling.

Capability — Database & Prisma

How NetScript wires Prisma 7 + Postgres, per-plugin schema aggregation, and the appsettings-driven datasource.

Orchestration with Aspire

Why the AppHost (aspire/apphost.mts) provisions Postgres and Redis, and how the resource graph fits together.

Queue / KV / cron

The next recipe: use the KV and queue backends — including the PostgreSQL queue provider that shares this datasource.

Deploy without Aspire

Point the workspace at your own Postgres via POSTGRES_URI / DATABASE_URL using the --no-aspire escape hatch.

For the MySQL adapter surface, see [`prisma-adapter-mysql`](https://rickylabs.github.io/netscript/reference/prisma-adapter-mysql/).

_Canonical: https://rickylabs.github.io/netscript/data-persistence/how-to/database-migration/_

---

# Queue / KV / cron

**Scope:** three task recipes for the runtime primitives every NetScript app reaches for sooner or later — enqueueing and consuming a **queue** message, reading and writing **KV**, and scheduling a **cron** job. Each primitive is a small, provider-agnostic package (`@netscript/queue`, `@netscript/kv`, `@netscript/cron`) that resolves its backend from the environment, so the same code runs against an in-memory adapter on your laptop and a real broker or store under Aspire. This page shows the minimal, copy-able shape for each, calls out the one place where you must pick a backend by hand (the **PostgreSQL** queue provider), then points you at the full generated API.

These primitives are lower-level than the [background-jobs](https://rickylabs.github.io/netscript/capabilities/background-jobs/) plugin: a worker job is a managed handler with persistence, retries, and an HTTP trigger, whereas a raw queue is just a typed pipe. Use the plugin when you want lifecycle management; use these primitives when you want a thin abstraction you control. For the concept-level tour, read [Capabilities — KV, queues & cron](https://rickylabs.github.io/netscript/capabilities/kv-queues-cron/).

## Prerequisites

**Before you start**

| Name | Type | Description |
| --- | --- | --- |
| `A NetScript workspace` | `netscript init` | Created per the Quickstart. Run these recipes from the workspace root or any workspace member. |
| `Start Aspire (for real backends)` | `cd aspire && aspire start` | Aspire is step 2 of local dev — it provisions Postgres, Redis (cache), and any broker BEFORE your service connects. In-memory and Deno KV adapters need nothing extra; Redis, RabbitMQ, and the Postgres queue all expect Aspire up first. |
| `Deno KV unstable flag` | `--unstable-kv` | KV (and the KV-backed queue/cron fallbacks) use Deno KV. The scaffold's deno.json sets unstable: ['raw-imports', 'kv']; add --unstable-kv to any ad-hoc deno run/check that touches these packages. |

> Backends auto-discover — with one deliberate exception
>
> Each package resolves its provider from the environment at first use, so you write provider-neutral code and let Aspire wire the connection strings.
>
> KV
>
> auto-detects across
>
> 'deno-kv'
>
> ,
>
> 'redis'
>
> ,
>
> 'nitro'
>
> , or
>
> 'auto'
>
> ;
>
> queue
>
> probes RabbitMQ (AMQP) → Redis → Deno KV;
>
> cron
>
> uses native
>
> Deno.cron
>
> with an in-memory scheduler for tests. The one provider auto-discovery will
>
> never
>
> pick for you is the queue's
>
> PostgreSQL
>
> backend — it is selectable only via an explicit
>
> provider: 'postgres'
>
> (see Recipe 2, Step 4).

## Recipe 1 — KV: read and write durable state

`@netscript/kv` is a reactive key-value store with one API across **Deno KV**, **Redis**, and an in-memory backend. The shared lifecycle resolves a provider once and hands back a `WatchableKv` — a `KvStore` with `get` / `set` / `delete` / `has` / `list` / `atomic`, plus reactive `watch` / `watchPrefix`.

### Step 1 — Get the shared store

```ts
// some-module.ts
import { getKv } from "@netscript/kv";

// Resolves (and initializes on first call) the shared WatchableKv singleton.
// Provider is auto-detected from the environment unless you pass a config.
const kv = await getKv();
```

`getKv()` takes an optional `SharedKvConfig` if you want to pin a provider or a Deno KV path. The provider set is `'redis' | 'deno-kv' | 'nitro' | 'auto'`; leaving it unset means `'auto'`.

### Step 2 — Write, read, and expire

```ts
// Keys are KvKey = readonly Deno.KvKeyPart[] — a portable tuple key.
await kv.set(["users", 42, "profile"], { name: "Ada", status: "active" });

const entry = await kv.get<{ name: string; status: string }>(["users", 42, "profile"]);
console.log(entry?.value?.name); // "Ada"

// KvSetOptions.expireIn sets a TTL in milliseconds.
await kv.set(["session", "tok_123"], { userId: 42 }, { expireIn: 60_000 });

await kv.delete(["session", "tok_123"]);
```

### Step 3 — List a prefix and watch for changes

```ts
// list() takes a KvListOptions selector — here, every key under ["users"].
for await (const item of kv.list({ prefix: ["users"] })) {
  console.log(item.key, item.value);
}

// watchPrefix() returns an AsyncIterable; iterate it with for-await, cancel via AbortSignal.
const controller = new AbortController();
for await (const event of kv.watchPrefix(["users"], { signal: controller.signal })) {
  console.log("changed:", event.key);
}
// …to stop:
controller.abort();
```

**KV adapters (@netscript/kv)**

| Name | Type | Description |
| --- | --- | --- |
| `DenoKvAdapter` | `@netscript/kv (provider 'deno-kv')` | Deno-native, backed by Deno.Kv, with native watch support. The default for local dev. Needs --unstable-kv. |
| `MemoryKvAdapter` | `@netscript/kv (provider 'auto' in tests)` | Volatile in-process store. Nothing to provision; data is lost on restart. Ideal for tests and isolated runs. |
| `Redis adapter` | `@netscript/kv/redis (provider 'redis')` | Importing the sub-path self-registers the 'redis' provider. Backed by the Redis/Garnet resource Aspire provisions. Reads its connection via getRedisConnectionFromEnv(). |

See the full surface — `getRawKv`, `getActiveProvider`, `atomic` compare-and-swap, the `WatchableKv` contract — in [`@netscript/kv`](https://rickylabs.github.io/netscript/reference/kv/).

## Recipe 2 — Queue: enqueue and consume a message

`@netscript/queue` wraps battle-tested adapters behind one `MessageQueue` interface with optional Zod validation. A queue has exactly two operations: `enqueue` (producer) and `listen` (consumer). There are **four** backends — Deno KV, Redis, RabbitMQ (AMQP), and **PostgreSQL**. Backend auto-discovery probes **RabbitMQ (AMQP)** first, then **Redis**, then **Deno KV**; PostgreSQL is opt-in only (Step 4).

### Step 1 — Create a typed queue

Prefer `createTypedQueue` so messages are validated with Zod at both enqueue and dequeue time. (`createQueue` gives you the untyped pipe if you don't want validation.)

```ts
// queue.ts
import { createTypedQueue } from "@netscript/queue";
import { z } from "zod";

const EmailJobSchema = z.object({
  to: z.string().email(),
  subject: z.string().min(1),
  body: z.string(),
});

// Name is the logical queue; the backend is auto-discovered (RabbitMQ → Redis → Deno KV).
export const emailQueue = createTypedQueue("welcome-emails", EmailJobSchema);
```

### Step 2 — Enqueue from a producer

```ts
import { emailQueue } from "./queue.ts";

await emailQueue.enqueue({
  to: "ada@example.com",
  subject: "Welcome",
  body: "Thanks for signing up.",
});

// EnqueueOptions supports a delay (e.g. retry-after, scheduled send).
await emailQueue.enqueue(
  { to: "grace@example.com", subject: "Reminder", body: "Don't forget." },
  { delay: 30_000 },
);
```

### Step 3 — Consume with a listener

```ts
import { emailQueue } from "./queue.ts";

// listen() runs the handler per message; MessageContext carries metadata + ack controls.
await emailQueue.listen(async (message, context) => {
  // `message` is already validated against EmailJobSchema.
  await sendEmail(message.to, message.subject, message.body);
  // Throwing here surfaces a QueueHandlerError; the adapter handles retry/ack semantics.
});
```

### Step 4 — Pin the PostgreSQL backend explicitly

The PostgreSQL provider gives you a SQL-durable queue — useful when you already run Postgres (under Aspire) and want one fewer moving part than a dedicated broker, or when you want the queue and your application data to share a transactional store. Because auto-discovery is **RabbitMQ → Redis → Deno KV only**, Postgres never wins the probe; you must name it.

```ts
import { createQueue, QueueProvider } from "@netscript/queue";

// provider: 'postgres' (or QueueProvider.Postgres) is the only way to select it.
const jobs = createQueue("jobs", {
  provider: QueueProvider.Postgres,
  connection: {
    postgres: {
      // url is optional — when omitted it falls back to Aspire's getPostgresUri().
      url: Deno.env.get("DATABASE_URL"),
      // tableName defaults to 'message_queue'.
      tableName: "message_queue",
    },
  },
});

await jobs.enqueue({ id: "job-1", kind: "reindex" });
await jobs.listen(async (message, context) => {
  await handle(message);
});
```

The adapter uses row-claim semantics (`FOR UPDATE SKIP LOCKED`) with a visibility timeout plus ack/nack and a dead-letter store, so concurrent consumers don't double-claim a message. `createTypedQueue` accepts the same `provider`/`connection` options if you want Zod validation on the Postgres-backed queue too.

**Queue backends (@netscript/queue) — four selectable providers**

| Name | Type | Description |
| --- | --- | --- |
| `Deno KV` | `provider 'deno-kv' — auto-discovery fallback` | Zero-dependency local default when no broker is present. Durable to the Deno KV store. Last in the auto-discovery probe. Needs --unstable-kv. |
| `Redis` | `provider 'redis' — second probe` | Backed by the Redis/Garnet resource Aspire provisions. Selected when a Redis connection is discoverable and no AMQP broker is. |
| `RabbitMQ (AMQP)` | `provider 'rabbitmq' — first probe` | Full broker semantics via Fedify's AMQP adapter (amqplib). Preferred when an AMQP connection is available. Use createParallelQueue for concurrent processing. |
| `PostgreSQL` | `provider 'postgres' — EXPLICIT only` | SQL-durable queue over npm:pg with FOR UPDATE SKIP LOCKED row-claim, visibility timeout, ack/nack, and a dead-letter store. connection.postgres.{url,tableName} (url optional → Aspire getPostgresUri(); tableName defaults to 'message_queue'). Never chosen by auto-discovery — you must set provider:'postgres'. |

> Production pitfalls
>
> - **Validate at the boundary.** Prefer `createTypedQueue` over `createQueue` — an unvalidated queue can carry malformed messages until the consumer fails inside the handler. Validation at enqueue time fails fast at the producer.
> - **Local default is Deno KV, not a broker.** If you never start Aspire, your queue silently runs on the Deno KV fallback. That is fine for dev, but it is not RabbitMQ — don't assume broker-grade ordering or fan-out semantics until you've provisioned the real backend.
> - **PostgreSQL is opt-in, never auto-selected.** Auto-discovery is RabbitMQ → Redis → Deno KV; it will **not** fall through to Postgres even when a Postgres connection is present. If you want the SQL-durable queue you must pass `provider: 'postgres'` — otherwise you'll quietly land on the Deno KV adapter.
> - **Handler throws are not free retries.** A thrown `QueueHandlerError` follows the adapter's ack/retry policy, which differs per backend. Make handlers idempotent so a redelivery can't double-charge or double-send.

For `createParallelQueue`, the typed/parallel options, the full `QueueProvider` enum, the `connection.postgres` shape, the `QueueError` hierarchy, and the standalone `safeValidate` / `validateOrThrow` helpers, see [`@netscript/queue`](https://rickylabs.github.io/netscript/reference/queue/).

## Recipe 3 — Cron: schedule a recurring job

`@netscript/cron` is a runtime-agnostic scheduler over native **`Deno.cron`** and an **in-memory** scheduler for tests, with timezone support and job-lifecycle events. You get a scheduler from the factory and register jobs with a cron expression.

### Step 1 — Get a scheduler

```ts
// scheduler.ts
import { getScheduler } from "@netscript/cron";

// Shared singleton, created on first call, auto-detecting the runtime backend.
const scheduler = getScheduler();
```

`createScheduler(options?)` builds a fresh scheduler if you'd rather not use the shared instance; `stopScheduler()` tears the default one down (handy between tests).

### Step 2 — Schedule with a cron expression or a preset

```ts
import { getScheduler, CronPresets, isValidCronExpression } from "@netscript/cron";

const scheduler = getScheduler();

// Standard 5-field cron expression. Validate untrusted input first.
const expr = "*/15 * * * *"; // every 15 minutes
if (!isValidCronExpression(expr)) throw new Error(`bad cron: ${expr}`);

const cleanup = async () => {
  await purgeExpiredSessions();
};

await scheduler.schedule("session-cleanup", expr, cleanup);

// Or use a named preset instead of a raw expression.
await scheduler.schedule("nightly-report", CronPresets.EVERY_DAY, async () => {
  await emitDailyReport();
});
```

> Cron runs in-process — match it to your runtime
>
> Native
>
> Deno.cron
>
> requires the schedule to be registered while the process is alive; a cron job in a short-lived request handler will never fire. Register schedules during startup of a long-running service (a worker background processor or a
>
> defineService
>
> entry), not inside a per-request path. The in-memory backend is for tests only — it does not survive a restart.

The scheduler contract, `parseCronExpression`, the full `CronPresets` set (`EVERY_MINUTE`, `EVERY_5_MINUTES`, `EVERY_HOUR`, `EVERY_DAY`, `WEEKDAYS_9AM`, …), and the adapter classes are documented in [`@netscript/cron`](https://rickylabs.github.io/netscript/reference/cron/).

## See also

[Capabilities — KV, queues & cron  The concept-level tour of these primitives, when to reach for them, and how Aspire wires the four queue backends.](https://rickylabs.github.io/netscript/netscript/capabilities/kv-queues-cron/)

[Reference — @netscript/kv  Full generated API: the WatchableKv contract, adapters, atomic operations, and the shared lifecycle helpers.](https://rickylabs.github.io/netscript/netscript/reference/kv/)

[Reference — @netscript/queue  createQueue / createTypedQueue / createParallelQueue, the MessageQueue interface, the QueueProvider enum (incl. postgres), and the validation helpers.](https://rickylabs.github.io/netscript/netscript/reference/queue/)

[Reference — @netscript/cron  The scheduler factory, cron-expression utilities, CronPresets, and the per-backend adapter classes.](https://rickylabs.github.io/netscript/netscript/reference/cron/)

[Background jobs (workers)  When you want managed handlers with persistence, retries, and an HTTP trigger instead of a raw queue.](https://rickylabs.github.io/netscript/netscript/capabilities/background-jobs/)

[Database & migration  The previous recipe — provision Postgres under Aspire and run the db init → generate → seed flow.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/)

[Database & migration](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/) [Add OpenTelemetry](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/)

_Canonical: https://rickylabs.github.io/netscript/data-persistence/how-to/queue-kv-cron/_

---

# Use a second database

**Goal:** add a *second* database — a second Postgres, or a MySQL/SQL Server instance — to a NetScript workspace that already has its primary datasource, so each datasource gets its own Prisma schema, migrations, and generated client.

This recipe assumes the primary datasource is Postgres (the recommended default — every tutorial scaffolds with `--db postgres`), but the primary engine is itself chosen at scaffold time: pass `--db mysql`, `--db mssql`, or `--db sqlite` to `netscript init` for a MySQL, SQL Server, or file-backed SQLite primary instead. Everything below applies regardless of which engine your primary uses; the examples simply show the common Postgres-primary case.

NetScript's default scaffold gives you **one primary datasource** that every plugin aggregates its `.prisma` models into (see [Database & migration](https://rickylabs.github.io/netscript/data-persistence/how-to/database-migration/)). A second database is the opposite shape: a **separate** Prisma schema workspace with its own `generate` output and its own migration history. It never merges into the primary aggregation.

The second datasource is polyglot the same way the primary is: `netscript db add <engine>` accepts the same four engines as `netscript init` — `postgres`, `mysql`, `mssql`, and `sqlite`. The container-mode engines (`postgres`/`mysql`/`mssql`) are provisioned as an Aspire container resource (`addPostgres` / `addMySql` / `addSqlServer`); `sqlite` is **file-backed and has no Aspire container resource**, so the Aspire/Docker prerequisites below apply only to the container engines.

There are two ways to add one, and they answer different needs:

- **Scaffold it (`netscript db add`)** — when you want NetScript to own the second datasource: its own schema dir, migrations, seed scripts, and an Aspire-provisioned container. This is the recommended path and the bulk of this recipe.
- **Wire an adapter by hand** — when the second database is *external* (a managed MySQL, a reporting warehouse) that you only read/write from application code, with no NetScript-managed migrations. Covered in [Connect an external database by hand](#connect-an-external-database-by-hand).

## Before you start

**Prerequisites**

| Name | Type | Description |
| --- | --- | --- |
| `A scaffolded workspace` | `with a primary db` | An existing NetScript project whose primary datasource is already wired (Postgres, the recommended engine, or whichever engine you passed to netscript init via --db) — ideally migrated once via the Database & migration recipe so you know the single-datasource loop. |
| `netscript CLI` | `on PATH` | deno install --global --allow-all --name netscript jsr:@netscript/cli. netscript db add --help should print. |
| `Aspire CLI + Docker` | `for container mode` | The scaffolded second database is provisioned as a container by Aspire (addMySql / addPostgres / addSqlServer). Docker or Podman must be running. Skip only for an external/hand-wired database. |
| `Deno` | `2.x` | Prisma client generation runs under the Deno runtime (the generated schema sets runtime="deno"). |

> One datasource, or several — pick deliberately
>
> A second database is the right tool when you need an
>
> isolated
>
> data domain: a different engine (MySQL/SQL Server beside Postgres), a separate migration lifecycle, or a datasource you can scale and back up independently. If you only want a new
>
> table
>
> , add a model to the primary schema instead — adding a whole datasource means a second migration history, a second generated client, and a second connection to manage. See
>
> [Database & Prisma](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) for why the default is a single aggregated datasource.

## Step 1 — Scaffold the second database

From the workspace root, run `netscript db add <engine>`. The engine is one of `postgres`, `mysql`, `mssql`, or `sqlite`. The `--name` flag sets the **config key** the datasource is registered under (it defaults to the engine name):

```bash
# Add a MySQL datasource. Registered under NetScript.Databases.mysql,
# scaffolded into database/mysql/, provisioned by Aspire's addMySql (image 8.4).
netscript db add mysql
```

```bash
# A second Postgres for an isolated domain. --name gives it a distinct config
# key (and workspace), so it does not collide with the primary 'postgres'.
netscript db add postgres --name analytics
```

```bash
# SQL Server via Aspire's addSqlServer. Same shape — its own schema + migrations.
netscript db add mssql --name reporting
```

What `netscript db add` does, in one pass:

- **Scaffolds a workspace** at `database/<engine>/` (for `mysql`, `database/mysql/`) — its own `schema/schema.prisma`, `prisma.config.ts`, `scripts/`, and (after generate) `schema/.generated/`.
- **Registers the datasource** in `appsettings.json` under `NetScript.Databases.<configKey>` with the engine, mode, and a generated `DatabaseName` — the same appsettings-driven model the primary Postgres uses.
- **Adds the workspace** as a member of the project so tooling discovers it.
- **Regenerates the Aspire config and AppHost helper files** so the new container (for example the MySQL resource via `addMySql`) joins the resource graph the next time you run `aspire start`.

> The new datasource starts empty
>
> db add
>
> scaffolds the workspace and registers the datasource, but it does
>
> not
>
> run a migration or generate a client — the new
>
> database/mysql/schema/schema.prisma
>
> ships a starter schema and no
>
> .generated/
>
> directory yet. You run the migration loop yourself in Step 3, targeting the new datasource with
>
> --db
>
> .

## Step 2 — Bring the new container up with Aspire

Because `db add` regenerated the Aspire config, the new database becomes a container in the resource graph. Start (or restart) the AppHost so it provisions:

```bash
# database/migration recipe covers this in full — restart so Aspire picks up
# the regenerated config and provisions the new container (e.g. the mysql resource).
cd aspire
aspire start
```

Open the Aspire dashboard at [https://localhost:18888](https://localhost:18888) (the access token is printed by `aspire start`) and confirm the new resource — `mysql`, `analytics`, or whatever your config key is — goes green alongside the existing `postgres` and `redis`.

> If you skipped db add and only edited appsettings
>
> The container only appears because
>
> db add
>
> regenerated the Aspire helpers
>
> . If you register a datasource by hand-editing
>
> appsettings.json
>
> without re-running the generator, the AppHost will not know about it and the resource never shows up. Let the CLI own the appsettings + Aspire wiring — that is the whole point of
>
> db add
>
> .

## Step 3 — Migrate and generate the second datasource

The `netscript db` operations are **multi-database aware**: every one takes a `--db <target>` flag, where the target is a **config key**, a database name, or `all`. With the second database registered under `NetScript.Databases.mysql`, point each command at it with `--db mysql`. Run these from the workspace root, with `aspire start` up in another terminal:

```bash
# Create + apply the first migration for the SECOND datasource only.
# --db selects the config key; --name labels the migration directory.
netscript db init --db mysql --name init
```

```bash
# Generate the Deno-runtime Prisma client + zod schemas into
# database/mysql/schema/.generated for the mysql datasource.
netscript db generate --db mysql
```

```bash
# Run that datasource's seed scripts (database/mysql/scripts/seed.ts).
netscript db seed --db mysql
```

```bash
# Confirm the mysql datasource is migrated and in sync — the authoritative check.
netscript db status --db mysql
```

```bash
# Operate on EVERY registered datasource at once (primary + second).
netscript db migrate --db all --name add_reports
netscript db generate --db all
```

Each datasource keeps its **own** migration history under `database/<engine>/migrations/` and its **own** generated client. Editing the second schema and re-running `netscript db migrate --db mysql` never touches the primary Postgres, and vice versa.

> Omitting --db targets the primary
>
> Run a
>
> db
>
> command with no
>
> --db
>
> and it resolves to the
>
> primary
>
> datasource (the default Postgres). Always pass
>
> --db <configKey>
>
> when you mean the second one, or
>
> --db all
>
> to fan out across every registered datasource. The resolver matches on config key first, then database name.

## Step 4 — Query the second client from application code

After `db generate --db mysql`, the second datasource has its own typed client at `database/mysql/schema/.generated/client.server.ts`. Import it exactly like the primary — just from the new path. The two clients are independent `PrismaClient` instances, so a service can read from both:

```ts
// services/reporting/src/db.ts
// Each datasource generates its OWN client. Import the second one from its path.
import { PrismaClient as ReportingPrisma } from '../database/mysql/schema/.generated/client.server.ts';

export const reporting = new ReportingPrisma();

// Fully typed off the SECOND schema's models — separate from the primary client.
const rows = await reporting.report.findMany({ take: 20 });
console.log(rows.length);
```

```ts
// services/reporting/src/sync.ts
// A service can hold both clients side by side — one per datasource.
import { PrismaClient as AppPrisma } from '../database/postgres/schema/.generated/client.server.ts';
import { PrismaClient as ReportingPrisma } from '../database/mysql/schema/.generated/client.server.ts';

const app = new AppPrisma();
const reporting = new ReportingPrisma();

// Copy a record from the primary Postgres into the MySQL reporting datasource.
const order = await app.exampleRecord.findFirstOrThrow();
await reporting.report.create({ data: { sourceId: order.id, name: order.name } });
```

## Connect an external database by hand

If the second database is **external** — a managed MySQL you do not want NetScript to migrate or provision — skip `db add` and wire a driver adapter in application code. NetScript wraps each Prisma 7 driver in a small `DatabaseAdapter` with a uniform lifecycle (`getDriverAdapter` → `setClient` → `connect`/`healthCheck`/`getStatus`). The MySQL and SQL Server adapters are **sub-exports** (not in the `@netscript/database/adapters` barrel), so a Postgres-only app never pulls in their drivers:

**Second-database adapter factories (each implements DatabaseAdapter)**

| Name | Type | Description |
| --- | --- | --- |
| `createMysqlAdapter(opts)` | `@netscript/database/adapters/mysql` | MySQL 8.x / MariaDB via the native-Deno @netscript/prisma-adapter-mysql driver. MysqlConnectionOptions adds charset, timezone, connectionLimit, multipleStatements over the shared parts. |
| `createMssqlAdapter(opts)` | `@netscript/database/adapters/mssql` | SQL Server via @prisma/adapter-mssql. MssqlConnectionOptions adds instanceName, encrypt, trustServerCertificate, integratedSecurity, connectTimeout, requestTimeout. |
| `createPostgresAdapter(opts)` | `@netscript/database/adapters` | PostgreSQL via @prisma/adapter-pg. The only adapter in the barrel; PostgresConnectionOptions adds schema and applicationName. |

The shared options come from `DatabaseConnectionOptions` (`@netscript/database/ports`): pass a `connectionString`, or the structured `host` / `port` / `database` / `username` / `password` / `ssl` / `poolSize` / `timeout` parts.

```ts
// services/reporting/src/external-db.ts
// Sub-export — import from /adapters/mysql, NOT the barrel.
import { createMysqlAdapter } from '@netscript/database/adapters/mysql';
import { PrismaClient } from '../database/mysql/schema/.generated/client.server.ts';

// 1) Build the adapter from structured parts (or pass { connectionString }).
const adapter = createMysqlAdapter({
  host: Deno.env.get('MYSQL_HOST') ?? 'localhost',
  port: 3306,
  database: 'reporting',
  username: Deno.env.get('MYSQL_USER') ?? 'root',
  password: Deno.env.get('MYSQL_PASSWORD'),
  ssl: false,
});

// 2) Pass the driver adapter into Prisma, then hand the client BACK to the adapter.
export const reporting = new PrismaClient({ adapter: adapter.getDriverAdapter() });
adapter.setClient(reporting);

// 3) Lifecycle + health now run off the same client.
await adapter.connect();
const ok = await adapter.healthCheck(); // SELECT 1
console.log('mysql healthy:', ok, await adapter.getStatus());
```

```ts
// Prefer reading config from the environment? getMysqlConfig() reads structured
// MYSQL_HOST / MYSQL_PORT / MYSQL_DATABASE / MYSQL_USER / MYSQL_PASSWORD vars and
// falls back to a connection-string env var (MYSQLDB_URI, then DATABASE_URL).
import { createMysqlAdapter, getMysqlConfig } from '@netscript/database/adapters/mysql';

const cfg = getMysqlConfig(); // → MysqlAdapterConfig, or throws if nothing is set
const adapter = createMysqlAdapter({
  host: cfg.hostname,
  port: cfg.port,
  database: cfg.db,
  username: cfg.username,
  password: cfg.password,
});
// (getMssqlConfig has the same shape for SQL Server, reading MSSQL_* / MSSQLDB_URI.)
```

```ts
// services/reporting/src/external-db.ts — SQL Server (same lifecycle)
import { createMssqlAdapter } from '@netscript/database/adapters/mssql';
import { PrismaClient } from '../database/mssql/schema/.generated/client.server.ts';

const adapter = createMssqlAdapter({
  host: Deno.env.get('MSSQL_SERVER') ?? 'localhost',
  port: 1433,
  database: 'reporting',
  username: 'sa',
  password: Deno.env.get('MSSQL_PASSWORD'),
  encrypt: true,              // local-dev TLS knobs; tighten for production
  trustServerCertificate: true,
});

export const reporting = new PrismaClient({ adapter: adapter.getDriverAdapter() });
adapter.setClient(reporting);
await adapter.connect();
```

> getClient() throws until you call setClient()
>
> The adapter does
>
> not
>
> own the
>
> PrismaClient
>
> — you construct it. The order is always: build the adapter, call
>
> getDriverAdapter()
>
> , pass that to
>
> new PrismaClient({ adapter })
>
> , then call
>
> adapter.setClient(client)
>
> . Only then do
>
> getClient()
>
> ,
>
> connect()
>
> ,
>
> healthCheck()
>
> , and
>
> executeRaw()
>
> work — call
>
> getClient()
>
> before
>
> setClient()
>
> and it throws
>
> "… client not initialized. Call setClient() …"
>
> .

## In-production pitfalls

> Watch for these
>
> - **Forgetting `--db`.** A bare `netscript db migrate` targets the **primary** datasource. Always pass `--db <configKey>` (e.g. `--db mysql`) for the second one, or `--db all` to fan out — otherwise you migrate the wrong database.
> - **Aspire not restarted after `db add`.** The new container only joins the resource graph after the regenerated Aspire config is loaded. Restart `aspire start` before the new datasource is reachable.
> - **Stale second client.** Each datasource has its *own* `.generated/`. Editing `database/mysql/schema/schema.prisma` without `netscript db generate --db mysql` leaves your code typed against the old shape — same trap as the primary, once per datasource.
> - **Importing the wrong client.** The primary is `database/postgres/schema/.generated/client.server.ts`; the second is `database/mysql/schema/.generated/client.server.ts`. They are distinct `PrismaClient`s — crossing the imports queries the wrong database.
> - **Calling `getClient()` before `setClient()`** on a hand-wired adapter throws — see the callout above.
> - **Docker down.** A scaffolded (container-mode) second database is provisioned by Aspire; if Docker/Podman is not running, its resource never goes green. An external/hand-wired database does not need this.
> - **Alpha surface.** NetScript packages share the aligned `0.0.1-beta.11` version, and public subpaths can still be renamed. Pin versions and re-check the import paths after upgrades.

## See also

[Database & Prisma — capability hub](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) ·

[Database & migration — the primary-datasource loop](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/) ·

[@netscript/database reference](https://rickylabs.github.io/netscript/netscript/reference/database/) ·

[@netscript/prisma-adapter-mysql reference](https://rickylabs.github.io/netscript/netscript/reference/prisma-adapter-mysql/) ·

[Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) ·

[KV, queues & cron — the Postgres queue backend](https://rickylabs.github.io/netscript/netscript/data-persistence/kv-queues-cron/)

[Expose OpenAPI & Scalar](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/expose-openapi-scalar/) [Choose a queue provider](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/)

_Canonical: https://rickylabs.github.io/netscript/data-persistence/how-to/use-a-second-database/_

---

# KV, queues & cron

The integration trio. Most backends end up hand-assembling three boring-but-load-bearing seams: a **key-value store** for cache and session state, a **message queue** for fire-and-forget work, and a **cron scheduler** for time-driven jobs. NetScript ships all three as provider-agnostic packages — `@netscript/kv`, `@netscript/queue`, and `@netscript/cron` — each exposing one typed contract across several backends and **auto-detecting** the best available adapter from the Aspire environment, with a zero-config local fallback so the same code runs on a laptop and in production.

![A cron schedule fires a tick that enqueues work onto a provider-agnostic queue; one or more worker listeners drain the queue in parallel while a KV store holds cursors, dedupe keys, and counters that keep the loop idempotent.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/queue-worker-scheduler.svg)

*The trio in one loop: cron tick → enqueue → parallel queue listeners → KV state holds the cursor, dedupe keys, and counters.*

> Use this when
>
> Reach for
>
> KV
>
> when you need fast, typed read/write state — caches, sessions, feature flags, counters — with optional TTL and reactive watches. Reach for a
>
> queue
>
> when you have
>
> fire-and-forget
>
> or fan-out work that should not block a request: emails, webhooks, image processing. Reach for
>
> cron
>
> when work is
>
> time-driven
>
> : nightly reports, hourly cleanups, weekday digests. For
>
> message-driven, long-running orchestration with state
>
> , step up to a
>
> durable saga
>
> ; for
>
> inbound HTTP that kicks off work
>
> use a
>
> trigger
>
> .

## What it is

Each package is built on the same NetScript opinion: a single typed contract, several adapters behind it, and provider selection that resolves automatically from the environment so you never branch on "is this local or Aspire?" in product code. KV unifies **Deno KV and Redis-compatible caches (`redis` by default, or `garnet` via `--cache-backend`), plus in-memory**; the queue unifies **Deno KV, Redis, RabbitMQ (AMQP), and PostgreSQL** (plus a KV-polling fallback for remote KV Connect endpoints); cron unifies **native `Deno.cron()` and an in-memory** scheduler. None of the three requires you to operate Redis, RabbitMQ, or PostgreSQL during development — the local adapters carry the same code until [Aspire](https://rickylabs.github.io/netscript/explanation/aspire/) provisions the real backends. When [telemetry](https://rickylabs.github.io/netscript/observability/telemetry/) is on, queues are traced for you with no manual instrumentation.

[@netscript/kv  Reactive key-value storage. getKv() auto-detects Deno KV or Redis/Garnet; construct MemoryKvAdapter directly for tests. get/set/watch/atomic with per-key TTL.](https://rickylabs.github.io/netscript/netscript/reference/kv/)

[@netscript/queue  Provider-agnostic message queues. createQueue() wraps Deno KV, Redis, RabbitMQ (AMQP), and PostgreSQL behind one MessageQueue contract; createParallelQueue() adds concurrency.](https://rickylabs.github.io/netscript/netscript/reference/queue/)

[@netscript/cron  Runtime-agnostic scheduling. createScheduler() uses native Deno.cron() when available and an in-memory adapter for tests.](https://rickylabs.github.io/netscript/netscript/reference/cron/)

## Learn → / Do →

[Do — Choose a queue provider  Recipe: pick between Deno KV, Redis, RabbitMQ, and PostgreSQL — and wire the Aspire-provisioned, local-fallback, and explicit-provider paths.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/)

[Understand — Orchestration with Aspire  How the scaffold wires Redis (the default cache backend; or Garnet via --cache-backend) and message brokers as resources, and why auto-detection just works once aspire start is up.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

## One API, many backends

Each package keeps a single typed contract with several adapters behind it, and provider selection resolves automatically from the environment. The matrix below is the full provider surface — read across a capability to see which backends it supports and how each is chosen. Note one deliberate exception: the **PostgreSQL queue backend is explicit-provider only** — it is real and durable, but auto-detection never selects it (see the callout below).

For contrast: BullMQ is a Redis-backed queue library, and Celery requires a message broker such as RabbitMQ or Redis — in both cases that infrastructure must be running before the first job enqueues. `createQueue()` starts on local Deno KV with nothing to provision, and the upgrade to Redis or RabbitMQ is an environment change, not a code change.

**Adapter × capability — supported backends and how they are selected**

| Name | Type | Description |
| --- | --- | --- |
| `Deno KV` | `kv · queue · cron` | Default zero-config fallback. KV stores locally; the queue uses native Deno KV queue ops; cron shares the same local-first philosophy via Deno.cron(). No external service required. |
| `memory` | `kv · cron` | Process-local. MemoryKvAdapter for KV (must be constructed explicitly) and the in-memory cron adapter (provider: 'memory') — deterministic for tests. The KV default for local development without Redis is Deno KV (local file), not the in-memory adapter. |
| `Redis / Garnet` | `kv · queue` | Production cache and queue backend. Selected when CACHE_PROVIDER=redis\|garnet, REDIS_URI/GARNET_URI, or Aspire services__redis__*/services__garnet__* are present. Redis is the default cache Aspire provisions; Garnet is the Redis-compatible alternative via --cache-backend garnet. |
| `RabbitMQ (AMQP)` | `queue` | Durable broker for high-throughput, multi-consumer queues. Chosen first by auto-detection when Aspire reports a rabbitmq service. Imported via @netscript/queue/adapters/amqp for direct access. |
| `PostgreSQL` | `queue` | Durable SQL-backed queue (FOR UPDATE SKIP LOCKED row-claim, visibility timeout, ack/nack, DLQ). EXPLICIT-PROVIDER ONLY — set provider: QueueProvider.Postgres; never auto-detected. Configure connection.postgres.{url,tableName}. |
| `KV-polling` | `queue` | KvPollingAdapter — used automatically when the Deno KV path is a remote HTTP/HTTPS endpoint (KV Connect), where native queue ops are unavailable. Tunable via connection.denoKv.{pollInterval,visibilityTimeout,maxRetries}. |
| `Deno.cron()` | `cron` | Native runtime scheduler. Used by createScheduler() whenever the runtime exposes Deno.cron(); falls back to the in-memory adapter otherwise. |

> PostgreSQL queue is explicit-provider only
>
> The queue's auto-detection order is
>
> RabbitMQ → Redis → Deno KV
>
> — it never selects PostgreSQL. The Postgres backend is a real, durable adapter (
>
> FOR UPDATE SKIP LOCKED
>
> row-claiming, visibility timeout, ack/nack, dead-letter store), but you must opt in explicitly with
>
> provider: QueueProvider.Postgres
>
> (or the string
>
> 'postgres'
>
> ). The
>
> url
>
> in
>
> connection.postgres
>
> is optional — when omitted, the adapter falls back to the Aspire-provisioned Postgres URI — and
>
> tableName
>
> defaults to
>
> message_queue
>
> . Reach for it when you want queue state to live in the same transactional database as your domain data.

> Aspire first — then the production adapters appear
>
> Auto-detection upgrades to Redis/Garnet and RabbitMQ only when those resources are
>
> running
>
> . Bring orchestration up first:
>
> cd aspire && aspire start
>
> provisions Postgres, Redis, and any message broker (dashboard at
>
> https://localhost:18888
>
> )
>
> before
>
> any
>
> netscript db
>
> command or service that expects those backends. Without Aspire, KV falls back to local Deno KV, the queue falls back to Deno KV, and cron falls back to the in-memory adapter — your code is identical either way. See
>
> Orchestration with Aspire
>
> .

## KV — key types first

`getKv(config?)` returns a `WatchableKv` bound to the auto-detected backend. Keys are typed tuples, values are fully typed, and `KvSetOptions.expireIn` (milliseconds) gives per-key TTL on every adapter. Pass a `SharedKvConfig` to override provider selection on first access.

**SharedKvConfig — first-access overrides for getKv()**

| Name | Type | Description |
| --- | --- | --- |
| `provider` | `KvProvider?` | Force a specific provider. The default 'auto' inspects the environment and chooses the best available backend. |
| `path` | `string?` | Deno KV path or URL. |
| `redisUrl` | `string?` | Explicit Redis connection URL. |
| `redisNamespace` | `string?` | Prefix used for Redis-backed keys. |
| `skipServiceDiscovery` | `boolean?` | Skip environment-based provider detection. |

**KvSetOptions — per-key write options**

| Name | Type | Description |
| --- | --- | --- |
| `expireIn` | `number?` | Time-to-live in milliseconds; the key is removed after the window elapses. Honoured by every adapter. |

`getKv()` is the headline entrypoint; the same module also exposes `closeKv()`, `resetKv()` (for tests), `getRawKv()` (the underlying `Deno.Kv` when the provider is Deno KV), `getActiveProvider()`, `isKvInitialized()`, and the `isWatchable()` type guard.

```ts
// main.ts
import { getKv } from '@netscript/kv';

const kv = await getKv(); // picks Redis/Garnet under Aspire, else local Deno KV

await kv.set(['users', 'alice'], { name: 'Alice', role: 'admin' });

const entry = await kv.get<{ name: string; role: string }>(['users', 'alice']);
console.log(entry?.value.name); // "Alice"

// Per-key TTL works on every adapter — expire a session after one hour.
await kv.set(['sessions', 'tok_abc'], { userId: 'u1' }, { expireIn: 3_600_000 });
```

```ts
// watch-jobs.ts
import { getKv } from '@netscript/kv';

const kv = await getKv();

// Stream every change under a prefix, including newly created keys.
for await (const event of kv.watchPrefix(['jobs', 'order-processor'])) {
  console.log(`${event.key.join('/')} -> ${event.type}`, event.value);
}
```

```ts
// counter.ts
import { getKv } from '@netscript/kv';

const kv = await getKv();

const entry = await kv.get<number>(['counters', 'visits']);
const result = await kv.atomic(
  [{ key: ['counters', 'visits'], versionstamp: entry?.versionstamp ?? null }],
  [{ type: 'set', key: ['counters', 'visits'], value: (entry?.value ?? 0) + 1 }],
);

if (!result.ok) {
  // A concurrent write landed since the read — retry the cycle.
}
```

```ts
// kv.test.ts — deterministic, process-local store for tests.
import { MemoryKvAdapter } from '@netscript/kv';

const kv = new MemoryKvAdapter();
await kv.set(['test', 'key'], 'value');

// Or pin Redis explicitly via the subpath import (keeps ioredis out of other graphs).
import { RedisKvAdapter } from '@netscript/kv/redis';

const redisKv = new RedisKvAdapter({ url: 'redis://localhost:6379', namespace: 'myapp' });
await redisKv.set(['cache', 'featured'], items, { expireIn: 60_000 });
```

## Queues — key types first

`createQueue<T>(name, options?)` returns a `MessageQueue<T>` over the auto-detected backend. The factory stays synchronous; the heavy Redis, RabbitMQ (AMQP), and PostgreSQL adapters resolve lazily on first use and never enter your module graph until then. Producers call `enqueue(message, options?)`; consumers call `listen(handler, options?)`; `stop()` drains and releases the connection. The `QueueProvider` enum names the four backends — `DenoKv`, `Redis`, `RabbitMQ`, `Postgres`.

**QueueOptions — passed to createQueue / createTypedQueue / createParallelQueue**

| Name | Type | Description |
| --- | --- | --- |
| `provider` | `QueueProvider?` | Pin a backend. Omit to auto-discover (RabbitMQ → Redis → Deno KV). Set QueueProvider.Postgres to opt into the explicit-only Postgres adapter. |
| `autoDiscover` | `boolean? = true` | Enable Aspire-environment discovery. Priority: RabbitMQ > Redis > Deno KV. |
| `retryAttempts` | `number? = 3` | Max retries for failed messages — only applies when the backend has no native retry. |
| `retryDelay` | `number? = 1000` | Delay between retry attempts in milliseconds — only when the backend has no native retry. |
| `connection` | `QueueConnectionOptions?` | Provider-specific connection: connection.{denoKv,redis,rabbitmq,postgres}. KV Connect tuning lives under connection.denoKv (pollInterval, visibilityTimeout, maxRetries). |
| `deadLetterStore` | `DeadLetterStorePort?` | Custom terminal-failure store. When omitted, adapters use their provider-specific durable default. |
| `disableAutoTracing` | `boolean? = false` | Skip the automatic TracedQueue wrapper when you prefer to wire spans by hand. |

`createTypedQueue(name, schema, options?)` wraps a Zod schema and validates on enqueue/dequeue; its `TypedQueueOptions` adds `validateOnEnqueue` (default true), `validateOnDequeue` (default true), and `onValidationError` (`'discard'` default, `'dlq'`, or `'throw'`). `createParallelQueue` takes the same options plus a `concurrency` count.

```ts
// enqueue-email.ts
import { createQueue } from '@netscript/queue';

// Auto-detects: RabbitMQ (AMQP) under Aspire, else Redis, else Deno KV.
const emails = createQueue<{ to: string; body: string }>('emails');

await emails.enqueue({
  to: 'user@example.com',
  body: 'Welcome to NetScript.',
});

// Delay availability (e.g. a 5-minute reminder) via EnqueueOptions.
await emails.enqueue({ to: 'user@example.com', body: 'Still there?' }, { delay: 5 * 60 * 1000 });
```

```ts
// consume-email.ts
import { createQueue } from '@netscript/queue';

const emails = createQueue<{ to: string; body: string }>('emails');

// The handler receives the message and a MessageContext (messageId, deliveryCount, ack/nack).
await emails.listen(async (message, context) => {
  await sendEmail(message.to, message.body);
  // Some backends ack/retry natively (queue.nativeRetrial === true).
});

// On shutdown, drain in-flight work and release the backend connection.
await emails.stop();
```

```ts
// parallel-jobs.ts
import { createParallelQueue } from '@netscript/queue';

// Process up to 4 I/O-bound messages concurrently on a single listener.
const jobs = createParallelQueue<{ orderId: string }>('order-jobs', { concurrency: 4 });

await jobs.listen(async (message) => {
  await fulfilOrder(message.orderId); // these run in parallel, up to 4 at a time
});

// concurrency <= 1 behaves exactly like createQueue. For CPU-bound work prefer Web Workers.
```

```ts
// typed-notifications.ts
import { z } from 'zod';
import { createTypedQueue } from '@netscript/queue';

const NotificationSchema = z.object({
  type: z.enum(['email', 'sms']),
  to: z.string(),
  body: z.string(),
});

// Invalid payloads route to a dead-letter queue instead of being discarded.
const notifications = createTypedQueue('notifications', NotificationSchema, {
  onValidationError: 'dlq',
});
```

```ts
// pg-queue.ts
import { createQueue, QueueProvider } from '@netscript/queue';

// PostgreSQL is never auto-detected — opt in explicitly.
const jobs = createQueue<{ orderId: string }>('order-jobs', {
  provider: QueueProvider.Postgres,        // or provider: 'postgres'
  connection: {
    postgres: {
      // url is optional — falls back to the Aspire-provisioned Postgres URI.
      url: 'postgres://app:secret@localhost:5432/app',
      tableName: 'message_queue',           // default table name
    },
  },
});

await jobs.enqueue({ orderId: 'ord_123' });
```

```ts
// pin-provider.ts
import { createQueue, QueueProvider } from '@netscript/queue';

// Force Redis regardless of what auto-detection would pick.
const jobs = createQueue('jobs', { provider: QueueProvider.Redis });

// Or tune the Deno KV / KV-polling adapter for a remote KV Connect endpoint.
const remote = createQueue('jobs', {
  connection: {
    denoKv: { path: 'https://kv.example.com', pollInterval: 500, visibilityTimeout: 60_000 },
  },
});
```

> Queues are traced for you
>
> When telemetry is enabled,
>
> createQueue()
>
> auto-wraps the queue with
>
> @netscript/telemetry
>
> , so enqueue and consume spans show up in the Aspire dashboard alongside RPC and SSE work — no manual instrumentation. Opt out with
>
> disableAutoTracing: true
>
> when you want to wire spans by hand. See
>
> Telemetry & logging
>
> .

## Cron — key types first

`createScheduler(options?)` returns a `CronScheduler` that uses native `Deno.cron()` when the runtime exposes it and an in-memory adapter otherwise. `schedule(id, expression, handler, options?)` registers a job from a standard cron expression or a `CronPresets` constant and resolves to a `ScheduledJob`; `trigger(id)` fires it manually (handy in tests); `unschedule(id)` removes one; `stop()` tears the scheduler down. For simple single-scheduler apps, `getScheduler()` returns a shared singleton (`stopScheduler()` resets it). The handler may be a bare `JobHandler` or a `ContextualJobHandler` that receives a `JobContext` (`jobId`, `scheduledTime`, `actualTime`, `attempt`, `signal`).

**CreateSchedulerOptions — passed to createScheduler / getScheduler**

| Name | Type | Description |
| --- | --- | --- |
| `provider` | `CronProvider?` | Pin a provider. Omit to auto-detect by runtime — Deno.cron() when available, else the in-memory adapter. |
| `tickInterval` | `number? = 60000` | Poll interval in milliseconds for the memory adapter; only used when provider is 'memory'. |

**ScheduleOptions — per-job scheduling options**

| Name | Type | Description |
| --- | --- | --- |
| `timezone` | `string? = 'UTC'` | IANA timezone the cron expression is evaluated against, e.g. 'America/New_York'. |
| `runOnInit` | `boolean?` | Run the handler once immediately on registration, in addition to the schedule. |
| `enabled` | `boolean? = true` | Whether the job starts enabled. Register a job disabled and turn it on later. |
| `backoff` | `object?` | Retry backoff: { type: 'fixed' \| 'exponential' \| 'linear', initialDelay, maxDelay?, multiplier? }. Delays are milliseconds. |
| `maxRetries` | `number?` | Maximum retries on handler failure before the run is recorded as failed. |
| `metadata` | `Record?` | Arbitrary metadata stored with the job and surfaced on its ScheduledJob record. |

```ts
// daily-report.ts
import { createScheduler, CronPresets } from '@netscript/cron';

const scheduler = createScheduler(); // native Deno.cron() when available

const report = async () => {
  await generateDailyReport();
};

await scheduler.schedule('daily-report', CronPresets.WEEKDAYS_9AM, report, {
  timezone: 'America/New_York',
});

// Fire once on demand — useful for verifying wiring.
await scheduler.trigger('daily-report');
await scheduler.stop();
```

```ts
// hourly-cleanup.ts
import { createScheduler } from '@netscript/cron';

const scheduler = createScheduler({ provider: 'memory', tickInterval: 100 });

// Hourly cleanup; the contextual handler receives scheduling metadata.
const cleanup = async (context) => {
  console.log(context.jobId, context.attempt, context.scheduledTime.toISOString());
};

await scheduler.schedule('cleanup', '0 * * * *', cleanup);
```

```ts
// observe-jobs.ts
import { createScheduler } from '@netscript/cron';

const scheduler = createScheduler({ provider: 'memory' });

// Observe jobRun / jobError / jobScheduled / jobUnscheduled.
scheduler.on('jobRun', (event) => {
  if (!event.result.success) {
    console.error(`Job ${event.jobId} failed`, event.result.error);
  }
});
```

```ts
// validate-cron.ts
import { isValidCronExpression, parseCronExpression } from '@netscript/cron';

if (isValidCronExpression('0 9 * * 1-5')) {
  const parsed = parseCronExpression('0 9 * * 1-5');
  console.log(parsed?.hour, parsed?.dayOfWeek);
}
```

## How they compose

The trio is strongest together. A common pattern: a **cron** job wakes on a schedule and **enqueues** a batch of work; **queue** consumers process each message in parallel; and a **KV** store holds the cursor, dedupe keys, or rate-limit counters that keep the whole thing idempotent across restarts. None of these requires you to operate Redis, RabbitMQ, or PostgreSQL during development — the local Deno KV / in-memory adapters carry the same code until Aspire provisions the real backends (or until you opt in to the PostgreSQL queue explicitly).

One failure mode worth designing out from the start: **keep queue payloads small — enqueue a reference, not the bytes**. A job that carries a raw file or image in its payload works right up until the payload outgrows the backend's message limits (Deno KV caps values at 64 KiB), and the enqueue itself starts failing. The durable shape is to enqueue a small identifier, store the bytes behind a service, and have the consumer fetch them back over a [typed service call](https://rickylabs.github.io/netscript/services-sdk/sdk/) — the queue then only ever moves pointers, and the same payload works on every backend in the matrix above.

**Picking the right primitive**

| Name | Type | Description |
| --- | --- | --- |
| `Key-value state` | `@netscript/kv` | Synchronous-feeling read/write state: caches, sessions, flags, counters, cursors. Use TTL for ephemerality and watches for reactivity. |
| `Fire-and-forget work` | `@netscript/queue` | Decouple slow work from the request path. Fan out to multiple consumers; let the backend handle retries where nativeRetrial is true. Four backends: Deno KV, Redis, AMQP, PostgreSQL. |
| `Time-driven work` | `@netscript/cron` | Run handlers on a schedule. Pair with a queue to fan a scheduled tick out into many parallel jobs. |
| `Stateful orchestration` | `durable saga` | When work spans steps with correlation and compensation, a queue is not enough — model it as a durable saga instead. |

> Production notes
>
> Review these production constraints before deploying:
>
> (1)
>
> the PostgreSQL queue is
>
> never
>
> auto-detected — if you forget
>
> provider: QueueProvider.Postgres
>
> you silently get the Deno KV fallback.
>
> (2)
>
> retryAttempts
>
> /
>
> retryDelay
>
> apply
>
> only
>
> when the backend lacks native retry; check
>
> queue.nativeRetrial
>
> before assuming your config is in effect.
>
> (3)
>
> KV per-key TTL is set via
>
> expireIn
>
> (milliseconds), not an absolute timestamp.
>
> (4)
>
> cron
>
> timezone
>
> defaults to
>
> UTC
>
> — set it explicitly for business-hours schedules.
>
> (5)
>
> always
>
> await scheduler.stop()
>
> and
>
> await queue.stop()
>
> on shutdown so in-flight work drains and connections release.

## Reference →

[kv](https://rickylabs.github.io/netscript/netscript/reference/kv/) · [queue](https://rickylabs.github.io/netscript/netscript/reference/queue/) ·

[cron](https://rickylabs.github.io/netscript/netscript/reference/cron/)

[Do — Choose a queue provider  Task recipe: stand up each primitive in an existing workspace, with the Aspire-provisioned, local-fallback, and explicit-PostgreSQL paths spelled out.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/)

[Look up — @netscript/kv reference  Full generated API: getKv, WatchableKv, KvSetOptions, SharedKvConfig, the Deno KV / memory / Redis adapters, and the auto-detection table.](https://rickylabs.github.io/netscript/netscript/reference/kv/)

[Look up — @netscript/queue reference  createQueue, createTypedQueue, createParallelQueue, QueueProvider, QueueOptions, MessageQueue, and the Deno KV / Redis / AMQP / PostgreSQL / KV-polling adapters.](https://rickylabs.github.io/netscript/netscript/reference/queue/)

[Look up — @netscript/cron reference  createScheduler, getScheduler, CronPresets, CronScheduler, ScheduleOptions, JobContext, and the Deno.cron() and memory adapters.](https://rickylabs.github.io/netscript/netscript/reference/cron/)

[Understand — Orchestration with Aspire  How the scaffold wires Redis (the default cache backend; or Garnet via --cache-backend) and message brokers as resources, and why auto-detection just works once aspire start is up.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

[Understand — Telemetry & logging  Why queues are traced by default and how KV/queue/cron spans land in the Aspire dashboard.](https://rickylabs.github.io/netscript/netscript/observability/telemetry/)

[Database & Prisma](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) [Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/)

_Canonical: https://rickylabs.github.io/netscript/data-persistence/kv-queues-cron/_

---

# Durable Workflows

This pillar is about state that must outlive a request — and a process. A [saga](https://rickylabs.github.io/netscript/durable-workflows/sagas/) carries multi-step state across crashes, a [trigger](https://rickylabs.github.io/netscript/durable-workflows/triggers/) turns inbound events into durable work, and a [stream](https://rickylabs.github.io/netscript/durable-workflows/streams/) fans completed state out to live consumers. All three are declared as typed definitions in your workspace, so what a workflow does is readable from its definition — by you, by the registry tooling, and by a coding agent asked to change it.

The failure mode this pillar exists for is concrete: a checkout charges a card, the process dies before fulfillment confirms, and on restart nobody knows whether to refund. A retry loop cannot answer that question because the state between step three and step four lived only in memory. The [storefront checkout saga](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/) is the tutorial built around exactly that scenario; the pages in this pillar cover each piece it composes.

The scaffold ships the whole chain running, not as separate demos. A webhook lands on the triggers service (`:8093`) and enqueues a [workers](https://rickylabs.github.io/netscript/background-processing/workers/) job; the job publishes a `UserSettingsCreated` message; a saga on `:8092` consumes it and records completion in the durable store you chose. Every link is scaffold code that compiles, and every runtime exposes an HTTP surface you can query to confirm a message actually crossed — which is what makes the chain verifiable step by step instead of trusted end to end.

Use this pillar when an operation spans multiple steps, receives inbound events, or publishes a durable stream for consumers. Start from the failure mode you have:

- **State between steps must survive a crash** — a multi-step process with compensation: [Durable sagas](https://rickylabs.github.io/netscript/durable-workflows/sagas/).
- **The outside world starts the work** — webhooks, dropped files, cron: [Triggers & ingress](https://rickylabs.github.io/netscript/durable-workflows/triggers/).
- **Consumers need the latest state without polling** — a typed change-log read over HTTP/SSE: [Durable streams](https://rickylabs.github.io/netscript/durable-workflows/streams/).

For the conceptual model behind all three — why state must outlive the process, and how effect-based outcomes differ from a retry loop — read the

[The durability model](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) .

[Overview & Concepts   Durability model  How saga state, trigger ingress, retries, and durable streams fit together.](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) [Quickstart   Checkout saga  Build a multi-step checkout flow in the Storefront tutorial.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/) [How-To   Validated ingestion queue  Validate incoming work before handing it to durable processing.](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/build-a-validated-ingestion-queue/) [How-To   Durable stream  Publish stream events for consumers.](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/publish-a-durable-stream/) [API Reference   sagas  Generated saga API symbols.](https://rickylabs.github.io/netscript/netscript/reference/sagas/) [API Reference   triggers and streams  Generated trigger and stream package symbols.](https://rickylabs.github.io/netscript/netscript/reference/triggers/)

## Learn, do, look up

[Learn  Storefront tutorial  The checkout saga chapter models a multi-step flow with compensation.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/) [Look up  `@netscript/sagas` reference  Generated API reference. Related units: `triggers`, `streams`.](https://rickylabs.github.io/netscript/netscript/reference/sagas/) [Understand  The durability model  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/)

_Canonical: https://rickylabs.github.io/netscript/durable-workflows/_

---

# Durable workflows — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/durable-workflows/how-to/_

---

# Build a validated ingestion queue

Use `createTypedQueue(name, schema, options)` when inbound messages must be checked before they enter the queue and again before a consumer handles them.

## Prerequisites

- A Zod schema for the message payload.
- A queue provider decision: auto-discovery, Deno KV, Redis, RabbitMQ, or Postgres.
- A dead-letter policy for invalid messages.

## Create the queue

`TypedQueueOptions` extends the normal queue options with `validateOnEnqueue`, `validateOnDequeue`, and `onValidationError`.

```ts
import { createTypedQueue, QueueProvider } from '@netscript/queue';
import { z } from 'zod';

const ShipmentEventSchema = z.object({
  shipmentId: z.string().min(1),
  orderId: z.string().min(1),
  status: z.enum(['created', 'in_transit', 'delivered']),
});

const queue = createTypedQueue('shipment-events', ShipmentEventSchema, {
  provider: QueueProvider.Postgres,
  validateOnEnqueue: true,
  validateOnDequeue: true,
  onValidationError: 'dlq',
});
```

## Produce validated messages

With `validateOnEnqueue: true`, invalid producer input throws `QueueValidationError` before the message reaches the backend.

```ts
await queue.enqueue({
  shipmentId: 'ship_123',
  orderId: 'ord_123',
  status: 'in_transit',
});
```

## Consume validated messages

With `validateOnDequeue: true`, the queue parses the raw backend message before calling your handler. `onValidationError: 'dlq'` nacks invalid messages with `requeue: false`, `reason: 'validation_failed'`, and `errorCode: 'VALIDATION_ERROR'`.

```ts
await queue.listen(async (message, context) => {
  await updateShipmentProjection(message);
  await context.ack();
});
```

## Provider notes

- `QueueProvider.DenoKv`: good local default, no external broker.
- `QueueProvider.Redis`: high-throughput queueing when Redis is already deployed.
- `QueueProvider.RabbitMQ`: AMQP path for broker-centric deployments.
- `QueueProvider.Postgres`: transactional queue over the primary database; select it explicitly.

## Failure modes

- Producer validation failure: enqueue throws and no message is stored.
- Consumer validation failure with `discard`: the message is acknowledged without handler work.
- Consumer validation failure with `dlq`: the message is nacked without requeue for dead-letter handling.
- Consumer validation failure with `throw`: the queue throws `QueueValidationError` so the backend retry policy decides the next delivery.

## Next steps

- Compare providers in [Choose a queue provider](https://rickylabs.github.io/netscript/data-persistence/how-to/choose-a-queue-provider/).
- Use queues with KV and cron in [Queue / KV / cron](https://rickylabs.github.io/netscript/data-persistence/how-to/queue-kv-cron/).
- Look up the full API in [queue reference](https://rickylabs.github.io/netscript/reference/queue/).

[Build a server-validated form](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/build-a-server-validated-form/) [Publish a durable stream](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/publish-a-durable-stream/)

_Canonical: https://rickylabs.github.io/netscript/durable-workflows/how-to/build-a-validated-ingestion-queue/_

---

# Publish a durable stream

Use `createDurableStream(options)` when a server-side runtime owns entity state that browser clients or other consumers should subscribe to through a durable stream service.

## Prerequisites

- A stream schema from `defineStreamSchema(...)`.
- A stable `streamPath`.
- A stable `producerId` for idempotent delivery.
- The streams runtime service reachable for the stream path.

## Define the schema

`defineStreamSchema(...)` accepts collection definitions keyed by collection name. Each collection declares a `schema`, `type`, and `primaryKey`.

```ts
import { defineStreamSchema } from '@netscript/plugin-streams-core';

const standardShipmentSchema = {
  '~standard': {
    version: 1,
    vendor: 'example',
    validate: (value: unknown) => ({ value }),
  },
} as const;

export const shipmentStreamSchema = defineStreamSchema({
  shipments: {
    schema: standardShipmentSchema,
    type: 'shipment',
    primaryKey: 'id',
  },
});
```

## Create the producer

`createDurableStream({ streamPath, schema, producerId, signal })` returns a singleton producer for the stream path while it remains open.

```ts
import { createDurableStream } from '@netscript/plugin-streams-core';
import { shipmentStreamSchema } from './shipment-stream-schema.ts';

const shutdown = new AbortController();

const producer = createDurableStream({
  streamPath: '/shipments',
  schema: shipmentStreamSchema,
  producerId: 'shipping-service',
  signal: shutdown.signal,
});
```

## Upsert and delete state

The producer validates the collection key against the schema and reads the entity primary key from the configured `primaryKey` field.

```ts
producer.upsert('shipments', {
  id: 'ship_123',
  orderId: 'ord_123',
  status: 'in_transit',
  updatedAt: new Date().toISOString(),
});

producer.delete('shipments', 'ship_123');
```

## Flush on shutdown

Call `flush()` before a process exits so pending writes reach the stream runtime. `close()` flushes and removes the singleton producer for the stream path.

```ts
addEventListener('unload', async () => {
  shutdown.abort();
  await producer.flush();
  await producer.close();
});
```

## Failure modes

- Missing primary key: the producer skips the upsert for that entity.
- Unknown collection key: TypeScript catches it when the schema is typed; unchecked dynamic values should be validated before calling `upsert`.
- Runtime unavailable: `flush()` can throw the connection error. Treat this as a deploy/runtime failure, not proof of subprocess behavior.
- Duplicate stream path: `createDurableStream` reuses the open producer for the same `streamPath`.

## Next steps

- See the capability model in [Durable streams](https://rickylabs.github.io/netscript/capabilities/streams/).
- Build a live UI in [Live Dashboard, chapter 05](https://rickylabs.github.io/netscript/tutorials/live-dashboard/05-live-stream/).
- Look up the API in [streams reference](https://rickylabs.github.io/netscript/reference/streams/).

[Build a validated ingestion queue](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/build-a-validated-ingestion-queue/) [Restrict worker task permissions](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/restrict-worker-task-permissions/)

_Canonical: https://rickylabs.github.io/netscript/durable-workflows/how-to/publish-a-durable-stream/_

---

# 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.

The stakes are easiest to see in the [storefront checkout saga](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/): a payment is captured, fulfillment fails afterward, and the process restarts in between. Money has moved; the code that knew why is gone. A saga makes that in-between state durable and gives the undo — the refund — a declared place to live, so recovery is a matter of reading state, not reconstructing intent. And because the definition *is* data (typed state, enumerable handlers, enumerable compensations), the workflow is legible to more than the runtime: a coding agent asked to add a step can read the whole lifecycle from the builder chain, and verify the result against the `:8092` instances API instead of guessing.

![Saga state machine: an event advances the saga through typed states, a compensation branch unwinds a failed step, and every transition checkpoints to a kv or prisma store.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/saga-state-machine.svg)

*A saga is a state machine. Each inbound message runs a handler that mutates typed state and returns an effect ledger (advance, complete, fail, compensate); the runtime checkpoints state between messages to the durable store (kv or prisma) so an instance survives a crash.*

This is the third capability in the continuous-app thread. The [background jobs](https://rickylabs.github.io/netscript/background-processing/workers/) 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.

> Where it lives
>
> The plugin is installed at
>
> plugins/sagas/
>
> and referenced by
>
> netscript.config.ts
>
> as
>
> ./plugins/sagas/mod.ts
>
> . The fluent builder and effect helpers come from
>
> @netscript/plugin-sagas-core
>
> ; the config-time companion (
>
> defineSagaConfig
>
> ) comes from
>
> @netscript/plugin-sagas-core/config
>
> ; the durable runtime factory (
>
> createDurableSagaRuntime
>
> ) and the HTTP publisher (
>
> createSagaPublisher
>
> ) come from the
>
> @netscript/plugin-sagas/runtime
>
> subpath. Add it to a workspace with the public package install flow (
>
> netscript plugin install @netscript/plugin-sagas
>
> ). For local-source contributor samples inside this monorepo, run
>
> deno run -A packages/cli/bin/netscript-dev.ts plugin install saga --name sagas --samples
>
> .

## 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](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) , for why state must outlive the process and how effect-based outcomes differ from a retry loop.

## Learn → · Do →

[Learn — Build the checkout saga  The storefront tutorial rung that adds the sagas plugin, correlates the order events, and compensates a failed payment step.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)

[Do — Wire a durable workflow  Add the sagas plugin to a running app, consume a cross-plugin message, and emit sagaComplete end to end.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)

Fluent builder

defineSaga(id).durability().state().on().compensate().build() — id, durability tier, typed state, message handlers, compensations, then build(). One chain, fully type-checked.

Durable store backend

Runtime state persists to kv or prisma, chosen by NETSCRIPT_SAGA_STORE / appsettings. createDurableSagaRuntime({ backend, prisma }) owns the resources.

Effect-based outcomes

Every handler returns an array of effects — sagaComplete, sagaFail, sagaCompensate, send, schedule, spawn are named outcomes returned from handlers, never a fall-through.

Served on :8092

An oRPC API lists registered sagas, inspects running instances, publishes messages, and streams activity over SSE.

Cross-plugin choreography

The workers create-user-settings job publishes UserSettingsCreated; this saga consumes it — one message crossing the plugin boundary, type-checked on both sides.

Crash-survivable

State checkpoints between messages, so an instance picks up exactly where it left off after a restart. That survival is the entire point of a saga.

## 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.

```ts
// 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;
```

> Compensation: a .compensate() branch OR an effect
>
> There are
>
> two
>
> ways to compensate, and they work together. The builder exposes a first-class
>
> .compensate(eventType, handler)
>
> that registers an undo handler keyed by message type. A running handler routes into it by returning the
>
> sagaCompensate(message, reason?)
>
> effect. So a saga's whole lifecycle — advance,
>
> sagaComplete
>
> ,
>
> sagaFail
>
> ,
>
> sagaCompensate
>
> ,
>
> send
>
> ,
>
> schedule
>
> ,
>
> spawn
>
> — is
>
> named outcomes returned from handlers
>
> , never a fall-through or an unhandled throw. The undo logic itself lives in the
>
> .compensate()
>
> handler, not inline in the forward path.

## 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.

**Primary saga types (@netscript/plugin-sagas-core)**

| Name | Type | Description |
| --- | --- | --- |
| `SagaState` | `Readonly>` | Base state shape every saga's typed state must extend. Your State type is intersected with this. |
| `SagaMessage` | `{ type, payload, correlationKey?, idempotencyKey?, concurrencyKey?, occurredAt?, traceparent? }` | The event or command delivered to a handler. `type` discriminates; `payload` is your typed body. |
| `SagaContext` | `{ sagaId, instanceId, correlationKey, state, message, attempt, now, traceparent? }` | Read-only handler context. `now` is the injected clock; `attempt` is the retry count; trace fields carry W3C context. |
| `SagaHandler` | `(saga, event, context) => readonly CascadedMessage[]` | A synchronous handler: it mutates saga.state and RETURNS an effect ledger. No async, no direct I/O. |
| `SagaDefinition` | `Readonly<{ id, durability, initialState, handlers, compensations, correlations, retry?, concurrency?, schedule? }>` | The frozen definition build() produces. Registered into the runtime and into KV under ['saga','registry', id]. |
| `SAGA_DURABILITY_TIERS` | `readonly ['t1','t2','t3']` | The durability tiers a definition may declare via .durability(tier). 't1' is the scaffolded default. |

## 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`.

**defineSaga(id) — SagaBuilder methods**

| Name | Type | Description |
| --- | --- | --- |
| `.durability(tier)` | `SagaDurabilityTier ('t1' \| 't2' \| 't3')` | Set the persistence tier the runtime checkpoints state to. Defaults to t1. Distinct from the kv/prisma store backend (see below). |
| `.state(initial)` | `S extends SagaState` | Declare the typed initial state, seeded once at instance creation. MUST be called before any handler (typestate-enforced). |
| `.on(type, handler)` | `SagaHandler` | Register a forward handler for a message type. Receives (saga, event, context), mutates saga.state, returns an effect ledger. |
| `.compensate(type, handler)` | `SagaHandler` | Register a compensation (undo) handler keyed by message type. Routed when a handler returns sagaCompensate(...). |
| `.correlate(rule)` | `SagaCorrelation` | Extract a correlation key from an incoming message so it routes to the right running instance. |
| `.concurrency(opts)` | `{ limit: number; key?: (m) => string }` | Bound how many messages run at once, optionally per derived key. Overlapping publishes for one key are rejected. |
| `.schedule(cron)` | `string` | Attach a cron expression that ticks the saga definition on a schedule. |
| `.onSignal(signal, handler)` | `SignalDefinition, handler` | Register a reserved signal handler (defineSignal). Runtime dispatch is deferred in the alpha. |
| `.onQuery(query, handler)` | `QueryDefinition, handler` | Register a reserved synchronous read-only query handler (defineQuery). Promises are rejected at type level. |
| `.build()` | `=> SagaDefinition` | Freeze the chain into a SagaDefinition. Requires at least one .on(...) handler (typestate-enforced). |

```ts
// 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;
```

```ts
// 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.

**Effect helpers — saga handler outcomes**

| Name | Type | Description |
| --- | --- | --- |
| `sagaComplete(result?)` | `=> CascadedMessage<'complete'>` | Terminal success. Marks the instance finished and records the optional result payload. |
| `sagaFail(reason)` | `string \| Error => CascadedMessage<'fail'>` | Terminal failure. Records the reason; no further messages are applied to the instance. |
| `sagaCompensate(message, reason?)` | `=> CascadedMessage<'compensate'>` | Route into the matching .compensate(type, ...) handler to undo an already-applied step. |
| `send(target, payload, options)` | `=> CascadedMessage<'send'>` | Dispatch a command to a target (job, saga, or runtime adapter). options carry idempotencyKey / concurrencyKey / retry / queue. |
| `schedule(message, delay)` | `delay: Date \| number \| '5m' => CascadedMessage<'scheduled'>` | Deliver a wrapped message after a delay (a Date, ms, or a '30s'/'5m'/'2h'/'1d' string). |
| `spawn(child, input, options)` | `=> CascadedMessage<'spawn'>` | Start a child saga from a definition or id, passing typed input. options take idempotencyKey / concurrencyKey. |

## 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](https://rickylabs.github.io/netscript/netscript/reference/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.

**createParallelQueue(name, options) — ParallelQueueOptions (extends QueueOptions)**

| Name | Type | Description |
| --- | --- | --- |
| `concurrency` | `number (default 1)` | Number of concurrent processors. Must be >= 1; values > 1 wrap the queue for parallel listening. Use for I/O-bound work; for CPU-bound work prefer web-worker tasks. |
| `provider` | `QueueProvider ('deno-kv' \| 'redis' \| 'rabbitmq' \| 'postgres')` | Backing queue provider. Omit to auto-discover from the Aspire environment. |
| `autoDiscover` | `boolean (default true)` | Discover a queue service from Aspire. Priority RabbitMQ > Redis > Deno KV. |
| `retryAttempts` | `number (default 3)` | Max retry attempts for failed messages, when the backend lacks native retry. |
| `retryDelay` | `number ms (default 1000)` | Delay between retries, when the backend lacks native retry. |
| `connection` | `QueueConnectionOptions` | Provider-specific connection options (denoKv / redis / rabbitmq / postgres). |
| `deadLetterStore` | `DeadLetterStorePort` | Where terminal message failures land. Omit to use the provider's durable default. |
| `disableAutoTracing` | `boolean (default false)` | Skip the automatic TracedQueue wrapper when you trace manually. |

```ts
// 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);
});
```

> Concurrency lives in two places
>
> createParallelQueue({ concurrency })
>
> tunes how many
>
> queue
>
> messages a listener processes at once.
>
> defineSaga().concurrency({ limit, key })
>
> bounds how many messages run against one
>
> saga instance
>
> (or per derived key) — overlapping publishes for the same key are rejected. Use the queue knob for parallel fan-out; use the builder knob to serialize work on a single business entity (one order, one tenant).

## 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 in the recommended setup; 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.)

**Durable saga store backends — trait matrix**

| Name | Type | Description |
| --- | --- | --- |
| `kv` | `Deno KV` | Default for local/single-service. No extra schema. Provisioned by Aspire (Redis/KV). Resolved via NETSCRIPT_SAGA_STORE=kv or sagas.store.backend=kv. |
| `prisma` | `Relational / Prisma` | Writes saga_runtime_state, saga_runtime_transition, saga_runtime_correlation. Requires a Prisma client passed to createDurableSagaRuntime — so it follows whatever engine you scaffolded (Postgres in the recommended setup; mysql / mssql / sqlite all work). SQL-inspectable in-flight state. Resolved via NETSCRIPT_SAGA_STORE=prisma or sagas.store.backend=prisma. |
| `selection` | `mandatory` | No implicit default. resolveSagaStoreBackend(...) throws when neither NETSCRIPT_SAGA_STORE nor sagas.store.backend is set. |
| `client requirement` | `prisma only` | backend: 'prisma' (or passing prisma) without a Prisma client throws 'Prisma saga store backend requires a Prisma client.' |

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).

```ts
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
```

```ts
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();
```

```ts
import { createDurableSagaRuntime } from '@netscript/plugin-sagas/runtime';
import { resolveSagaStoreBackend } from '@netscript/plugin-sagas-core/stores';

// 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,
});
```

> Two durability concepts — don't conflate them
>
> .durability('t1')
>
> on the
>
> saga definition
>
> selects a
>
> durability tier
>
> (
>
> SAGA_DURABILITY_TIERS
>
> ) — a property of the saga itself. The
>
> store backend
>
> (
>
> kv
>
> |
>
> prisma
>
> ) is a
>
> runtime/deployment
>
> choice about
>
> which database
>
> holds durable state, resolved by
>
> NETSCRIPT_SAGA_STORE
>
> /
>
> sagas.store.backend
>
> . A saga keeps its declared tier regardless of which backend you deploy against.

> Read model vs. durable write path
>
> The Prisma backend's
>
> saga_runtime_*
>
> tables are the durable
>
> write path
>
> the engine checkpoints to. They are distinct from
>
> saga_instances
>
> (and
>
> saga_execution_history
>
> ) — a
>
> read-model projection
>
> into Postgres for API queries, analytics, and debugging. The runtime persists to the former; the API surface lists from the latter.

## 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.

**createSagaPublisher(options) — HttpSagaPublisherOptions**

| Name | Type | Description |
| --- | --- | --- |
| `serviceName` | `string` | Aspire service name to resolve a base URL from. Defaults to the sagas service discovery name. |
| `baseUrl` | `string` | Explicit base URL override; skips discovery when set. |
| `publishPath` | `string (default '/api/v1/sagas/publish')` | Path the publisher POSTs each message to. |
| `headers` | `Record` | Extra headers sent with every publish (auth, tenant routing). |
| `retryableStatusCodes` | `readonly number[] (default 408,409,425,429,5xx)` | HTTP statuses treated as retryable so the receipt is marked retryable. |
| `id` | `string (default 'http-saga-publisher')` | Stable publisher id surfaced in diagnostics. |
| `fetcher / readEnv` | `boundary fns` | Test/injection seams for the fetch implementation and the env reader used for discovery. |

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.

```ts
// 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' });
```

```ts
// 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](https://rickylabs.github.io/netscript/netscript/reference/sagas/) (e.g. `reference/sagas/presets`, `reference/sagas/transports`).

**Saga extension seams (@netscript/plugin-sagas-core subpaths)**

| Name | Type | Description |
| --- | --- | --- |
| `/presets` | `startSagas(), startSagaHandlers()` | Composition helpers that build a runtime from explicit definitions and return a { runtime, bus, sagaCount, shutdown } bundle. startSagaHandlers is the distributed-handler alias. |
| `/middleware` | `createSagaMiddleware(), createSSEEventsMiddleware()` | Hono middleware that injects saga helpers into request context, plus SSE event emission with optional durable history (SagaHistoryWriter). |
| `/transports` | `createGarnetListTransport(), createNetScriptRedisTransport()` | At-least-once delivery adapters: a Garnet/Redis LIST transport and a Redis Streams transport, both with immediate + delayed publish and ack/nack. |
| `/agent` | `agent surface` | Agent integration seam for the plugin's agent-facing surface (alpha). |
| `/integration/publisher` | `SagaPublisherPort` | The publisher boundary createSagaPublisher implements — publish() / publishMany() with typed receipts. |
| `/integration/workers` | `workers bridge` | The seam that lets a workers job emit and consume saga messages across the plugin boundary. |

> Default transport vs. Redis/Garnet
>
> The scaffolded sagas service runs over the in-process native runtime and Deno KV. The
>
> /transports
>
> adapters (
>
> createGarnetListTransport
>
> ,
>
> createNetScriptRedisTransport
>
> ) are for
>
> multi-process or distributed
>
> delivery — when saga handlers run as separate processes and need at-least-once delivery with consumer groups, delayed messages, and dead-letter handling. Reach for them only when a single process is no longer enough; the KV path covers local and single-service apps.

## 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](https://rickylabs.github.io/netscript/netscript/reference/sagas/) for the full generated surface.

**Sagas plugin — runtime endpoints (port :8092)**

| Name | Type | Description |
| --- | --- | --- |
| `GET /health/live` | `liveness` | Liveness probe for the sagas API service. |
| `GET /api/v1/sagas/sagas` | `registry` | List the saga definitions registered into KV (id, name, topic, handled message types, enabled). |
| `GET /api/v1/sagas/instances` | `instances` | List running and completed saga instances. Inspect one with /instances/{sagaName}/{correlationId}. |
| `POST /api/v1/sagas/publish` | `publish` | Publish a message to the saga bus — the same path createSagaPublisher POSTs to and the workers create-user-settings job uses. |
| `GET /api/v1/sagas/subscribe` | `stream (SSE)` | Server-sent-events stream of saga activity (saga:started / state_changed / completed / failed / compensating), KV-watch backed. |

## 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

> Aspire first, then anything stateful
>
> The sagas service needs Postgres and Redis up before it can persist and list instances. Bring orchestration up first —
>
> cd aspire && aspire start
>
> (dashboard at
>
> `https://localhost:18888`
>
> ) —
>
> before
>
> any
>
> netscript db
>
> command or before you expect
>
> /api/v1/sagas/instances
>
> to return durable state. This holds for both backends:
>
> kv
>
> needs Redis/KV up, and
>
> prisma
>
> needs Postgres up with the
>
> saga_runtime_*
>
> tables migrated. DB commands require Aspire running first.

> Handlers are synchronous and pure
>
> A
>
> SagaHandler
>
> returns
>
> readonly CascadedMessage[]
>
> — it is
>
> synchronous
>
> and does no direct I/O. All side effects (charging payment, sending mail, spawning a child) are expressed as
>
> effects
>
> the runtime applies, so the handler is replayable and crash-safe. Do not
>
> await
>
> a network call inside a handler; emit a
>
> send(...)
>
> effect and let the target do the work. Compensation follows the same rule — its undo runs in the
>
> .compensate()
>
> handler as more effects, not as inline cleanup.

## Recovery models, compared

Durable-workflow engines agree on the goal — a multi-step process that survives a crash — and differ on **what the author must keep deterministic** to get it. That difference is where the authoring models diverge, so it is the one comparison worth making precisely.

**How three durable-workflow models recover from a crash**

| Name | Type | Description |
| --- | --- | --- |
| `Temporal` | `replay-based` | Workflow code is re-executed against its recorded event history on recovery, so it must stay deterministic: I/O, time, and randomness move into activities, and a non-deterministic code change surfaces as a replay error. |
| `Inngest` | `step memoization` | step.run results are memoized per run; code between steps re-executes on each invocation, so side effects belong inside steps — a convention the author maintains. |
| `NetScript sagas` | `checkpointed state machine` | The runtime persists typed state between messages and resumes from that checkpoint. A SagaHandler is synchronous and returns effects, so I/O cannot appear in the recovery path by construction — the constraint is the handler's type, not a convention. |

The trade NetScript makes is explicitness: you model the state machine yourself — states, handlers, compensations — rather than writing linear code an engine replays. What you get back is that the determinism requirement never depends on discipline. The handler signature rejects `async`, effects are the only side-effect channel, and the whole lifecycle is named outcomes returned as data — which is also what keeps a saga reviewable when the author of the next handler is an agent working from the definition alone.

## Why a saga, and why not

> Reach for a saga when…
>
> You have a multi-step process where steps can fail independently and the
>
> state between steps must survive a crash
>
> — onboarding, checkout, provisioning. The correlation, persistence, and named completion/failure/compensation outcomes are exactly what a hand-rolled retry loop lacks. Pick
>
> prisma
>
> as the store backend when you also want that in-flight state queryable in your relational database.

> Don't reach for a saga when…
>
> The work is a single idempotent unit with no inter-step state — that is a
>
> background job
>
> , not a saga. And remember the alpha reality: durability and the instance store depend on the orchestration stack being up via Aspire (Redis/KV for
>
> kv
>
> , Postgres for
>
> prisma
>
> ), so a saga is not a substitute for a database transaction within one handler.

## Reference →

[Look up — sagas reference  The full generated @netscript/plugin-sagas API: the defineSaga builder, durability tiers, createDurableSagaRuntime, the kv/prisma store backends, effect helpers, presets/middleware/transports seams, and every :8092 route.](https://rickylabs.github.io/netscript/netscript/reference/sagas/)

[Understand — the durability model  Why a saga's state must outlive the process, how effect-based outcomes differ from a retry loop, and where the kv vs prisma backends fit.](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/)

[Learn — Storefront checkout saga  Build the order/checkout saga with a compensation branch as part of the storefront tutorial track.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/04-checkout-saga/)

[Look up — queue reference  createParallelQueue, createQueue, providers, and connection options for the fan-out concurrency primitive.](https://rickylabs.github.io/netscript/netscript/reference/queue/)

[Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/) [Triggers & ingress](https://rickylabs.github.io/netscript/netscript/durable-workflows/triggers/)

_Canonical: https://rickylabs.github.io/netscript/durable-workflows/sagas/_

---

# Durable streams

A NetScript **stream** is a typed, durable change-log: producers write entity state into a durable-stream server, and any number of HTTP/SSE consumers materialize the latest value per key. alpha

![A producer defines a typed stream schema and writes upsert/delete operations into the durable-stream server on port 4437; the durable log fans out over HTTP/SSE to Fresh consumers that materialize the latest value per key.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/streams-pipeline.svg)

*Streams pipeline: producer (defineStreamSchema + createDurableStream) → durable log on :4437 → HTTP/SSE → Fresh consumers (latest value per key).*

NetScript's streams capability is the typed, change-data backbone the other plugins lean on — workers, sagas, and the auth service all publish their live state through it. The producer half is implemented: you define a typed stream schema with [`defineStreamSchema`](https://rickylabs.github.io/netscript/reference/streams/), open a producer with `createDurableStream` (or the Service-facing `createServiceStreamProducer`), and `upsert`/`delete`/`flush` entity state over a durable-stream server that runs as an Aspire resource on port **:4437**.

The producer runtime in `@netscript/plugin-streams-core` writes through `@durable-streams/client` with idempotent delivery. The topic-centric **manifest sugar** in `@netscript/plugin-streams` (`defineStreamProducer` / `defineStreamConsumer`) is **not** wired to a transport: a producer's `publish()` returns a **rejected** promise and a consumer's `subscribe()` **throws** synchronously — both with `StreamUnsupportedOperationError`, pointing you at the core package. There is also no in-process consumer `subscribe()` yet — consumption is over the durable-stream server's HTTP/SSE protocol, which Fresh clients read. Build against the core producer package, not the manifest helpers.

> Status — producers write via the core package; manifest helpers fail loud
>
> The producer is implemented:
>
> createDurableStream(...)
>
> from
>
> @netscript/plugin-streams-core
>
> writes
>
> upsert
>
> /
>
> delete
>
> /
>
> flush
>
> through
>
> @durable-streams/client
>
> to the
>
> :4437
>
> Aspire service, and workers, sagas, and auth already mirror their state through it. What is
>
> not
>
> supported: the manifest helpers
>
> defineStreamProducer
>
> /
>
> defineStreamConsumer
>
> in
>
> @netscript/plugin-streams
>
> fail loud — a producer's
>
> publish()
>
> returns a
>
> rejected
>
> promise and a consumer's
>
> subscribe()
>
> throws
>
> synchronously, both with
>
> StreamUnsupportedOperationError
>
> — use
>
> @netscript/plugin-streams-core
>
> instead. There is also no in-process consumer
>
> subscribe()
>
> ; consumption is via the durable-stream HTTP/SSE server (read by Fresh clients).

## What it is

A NetScript stream is an **entity-oriented change log**. You describe a set of collections — each a named entity type with a primary key — and the producer publishes `upsert` and `delete` operations keyed by that primary key. Downstream readers materialize the latest value per key and observe a live, replayable view of your domain state. This is the same contracts-first instinct as oRPC services, but applied to **state replication** instead of request/response: the schema is the type contract that both producer and any HTTP/SSE consumer are locked to.

Streams sit alongside the other long-running capabilities rather than replacing them. Reach for a [durable saga](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/)

when you need message-driven orchestration with compensation; reach for a

[trigger](https://rickylabs.github.io/netscript/netscript/durable-workflows/triggers/) when inbound HTTP or a file-watch should kick off work. A stream is the **read-model fan-out**: each of those plugins runs a thin `streams/producer.ts` that mirrors its execution state through `createDurableStream`, so a Fresh dashboard can watch saga, worker, and trigger progress live without polling a request/response API.

The workflow this replaces is familiar: a dashboard polls `GET /executions` on an interval, the interval is always wrong — too fast for the server, too slow for the operator watching a stuck import — and every new consumer re-implements the same polling loop against a slightly different endpoint. With a stream, the contract moves to the data itself. The [live-dashboard tutorial](https://rickylabs.github.io/netscript/tutorials/live-dashboard/05-live-stream/) builds exactly this: worker execution state published once through a producer, read by a Fresh page that updates without a polling loop anywhere in it. And because the schema is a frozen, typed collection map, what a stream carries is enumerable from its definition — `inspectStreamTopic` renders it as a JSON-stable report, which is as useful to a CLI doctor or a coding agent as it is to a test.

## Learn → / Do →

[Learn — stream a live dashboard  Track D 05: publish execution state from a producer and read it over HTTP/SSE into a live Fresh dashboard.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)

[Do — add the streams plugin  Public package install adds the stream plugin dependency and user-owned glue; local netscript-dev scaffolding supports contributor-source samples.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/)

[Understand — the plugin system  How thread-isolated plugins like streams register contributions and wire into the Aspire resource graph.](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/)

## Minimal example — produce, then consume

The producer side is two calls: freeze a typed schema, open a stream, write entity state. The consumer side is an HTTP/SSE read of the same `:4437` stream path — there is no in-process `subscribe()` handle, so a Fresh island (or any SSE client) reads the durable log directly and materializes the latest value per key. This is deliberate: exposing one HTTP/SSE surface instead of an in-process `subscribe()` means a browser island and a server-side consumer read the durable log through the exact same path and wire format, with no separate in-VM subscription API to keep in sync.

```ts
// streams/executions-schema.ts
// Author against the core package — this is the live surface.
import { defineStreamSchema } from '@netscript/plugin-streams-core';
import { z } from 'zod';

// Each collection is an entity type with a primary key. The schema is the
// type contract producers and HTTP/SSE consumers are locked to.
export const executionsSchema = defineStreamSchema({
  execution: {
    schema: z.object({
      id: z.string().min(1),
      status: z.enum(['queued', 'running', 'succeeded', 'failed']),
      updatedAt: z.string().datetime(),
    }),
    type: 'execution',
    primaryKey: 'id',
  },
});
```

```ts
// streams/producer.ts
import { createDurableStream } from '@netscript/plugin-streams-core';
import { executionsSchema } from './executions-schema.ts';

// createDurableStream returns a singleton producer per streamPath and begins
// connecting to the :4437 durable-stream server immediately.
const producer = createDurableStream({
  streamPath: '/workers/executions',
  schema: executionsSchema,
  producerId: 'workers-service',
});

// upsert/delete are synchronous enqueues keyed by the collection primary key.
producer.upsert('execution', {
  id: 'exec-1',
  status: 'running',
  updatedAt: new Date().toISOString(),
});
producer.delete('execution', 'exec-0');

// flush before graceful shutdown; it rethrows the connect error if the
// producer never connected (see known limitations).
await producer.flush();
```

```ts
// islands/ExecutionsView.tsx — read the durable log directly
import { getStreamsUrl } from '@netscript/plugin-streams-core';

// There is no in-process subscribe(); consumption is an HTTP/SSE read of the
// same stream path the producer writes to. getStreamsUrl resolves the :4437
// base from Aspire discovery / VITE env (see runtime resolvers below).
const base = getStreamsUrl();
const source = new EventSource(`${base}/workers/executions`);

const latest = new Map<string, unknown>(); // materialize latest value per key
source.onmessage = (ev) => {
  const change = JSON.parse(ev.data) as { key: string; value?: unknown };
  if (change.value === undefined) latest.delete(change.key);
  else latest.set(change.key, change.value);
};
```

```ts
// @netscript/plugin-streams (the manifest root) re-exports topic-centric
// helpers that are NOT implemented. They fail loud, by design.
import {
  defineStreamProducer,
  defineStreamConsumer,
} from '@netscript/plugin-streams';

// The producer handle is returned, but publish() rejects.
const producer = defineStreamProducer(/* topic */);
// await producer.publish(event) // -> rejects with StreamUnsupportedOperationError

// The consumer's subscribe() throws synchronously the moment you call it.
const consumer = defineStreamConsumer(/* topic */);
// consumer.subscribe(handler) // -> throws StreamUnsupportedOperationError

// Correct path: import createDurableStream / defineStreamSchema from
// '@netscript/plugin-streams-core' instead (see the other tabs).
```

> Do not call the manifest topic helpers
>
> defineStreamProducer
>
> and
>
> defineStreamConsumer
>
> exported from
>
> @netscript/plugin-streams
>
> are
>
> not
>
> implemented: a producer's
>
> publish()
>
> returns a
>
> rejected
>
> promise and a consumer's
>
> subscribe()
>
> throws
>
> synchronously, both with
>
> StreamUnsupportedOperationError
>
> — they are not silent no-ops and they will not publish anything. Always reach for
>
> createDurableStream
>
> /
>
> defineStreamSchema
>
> from
>
> @netscript/plugin-streams-core
>
> for real producer work. See the
>
> streams reference
>
> for the full export map.

## Key types first — the stream definition API

A stream schema is a map of **collections**. Each collection is a `CollectionDefinition` — a Standard-Schema validator, a State-Protocol `type` discriminator, and the `primaryKey` property the producer keys writes by. `defineStreamSchema(collections)` freezes that map into a `StateSchema` that both the producer and any HTTP/SSE consumer are locked to.

**CollectionDefinition — one entry per collection in defineStreamSchema**

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `unknown (Standard Schema validator)` | Standard-Schema-compatible validator (e.g. a zod object) used by durable-streams to validate the collection payload. |
| `type` | `string (required)` | State Protocol type discriminator emitted for every event in this collection (e.g. 'execution'). |
| `primaryKey` | `string (required)` | Property name on the value used as the entity primary key; upsert/delete are keyed by this property. |

`defineStreamSchema` returns a frozen `StateSchema<TDef>` — the durable-streams runtime attaches per-collection event helpers (`insert`/`update`/`upsert`/`delete`, the `CollectionEventHelpers`) so the schema can both validate and emit State-Protocol `ChangeEvent`s. The supported `Operation` set is `insert | update | delete | upsert`.

## Producer options — `createDurableStream`

`createDurableStream(options)` takes a `DurableStreamProducerOptions` and returns a `DurableStreamProducer`. It is a **singleton factory keyed by `streamPath`**: calling it twice with the same path returns the same live producer (a closed one is replaced). Writes are idempotent via `@durable-streams/client`'s `IdempotentProducer` (stable `producerId` + auto-claim), so duplicate enqueues do not double-apply downstream.

**DurableStreamProducerOptions (createDurableStream argument)**

| Name | Type | Description |
| --- | --- | --- |
| `streamPath` | `string (required)` | Stream path relative to the base URL, e.g. '/workers/executions'. This is the singleton key and the path consumers read over HTTP/SSE. |
| `schema` | `StateSchema (required)` | The frozen schema returned by defineStreamSchema; binds the producer to its collection map. |
| `producerId` | `string (required)` | Stable producer identity used for idempotent delivery (IdempotentProducer auto-claim). Keep it stable across restarts for duplicate-safe writes. |
| `signal` | `AbortSignal?` | Optional abort signal consulted while opening the stream connection; aborting cancels the connect (an AbortError is treated as expected, not a failure). |

The `DurableStreamProducer` it returns exposes a small, synchronous-write surface with an async flush/close for shutdown. (`StreamProducerPort` is the implemented-by interface — the same four members, with `entityType` widened to `string`.)

**DurableStreamProducer — methods**

| Member | Shape | Behavior |
| --- | --- | --- |
| `upsert(entityType, value)` | `(K, Record) => void` | Enqueue an upsert keyed by the collection `primaryKey`; skipped (warns) if the key is missing/empty or the collection is unknown. |
| `delete(entityType, key)` | `(K, string) => void` | Enqueue a delete by primary key; skipped (warns) on an empty key. |
| `flush()` | `() => Promise<void>` | Await pending writes before shutdown; **rethrows** the connect error if the producer never connected. |
| `close()` | `() => Promise<void>` | Flush, close the underlying handle, and release the singleton for this `streamPath`. |
| `streamPath` | `string (readonly)` | The stream path this producer owns. |
| `closed` | `boolean (get)` | Whether shutdown has begun; further `upsert`/`delete` calls are ignored. |

## Service-side producers — `createServiceStreamProducer`

When the writer is a backend **Service** — for example an ingestion worker that emits a `doc.ready` completion event from the callback where the work finishes — reach for `createServiceStreamProducer` instead of wiring `createDurableStream` and the URL/auth resolvers by hand. It is a thin wrapper over `createDurableStream` that reuses the exact same singleton producer and Aspire discovery (`getStreamsUrl` / `getStreamsAuth`), and it adds one guard: `assertResolvable` (default `true`) eagerly resolves the streams URL and auth at construction, so a Service that forgot to declare the `streams` reference **throws immediately** rather than silently dropping every write.

```ts
// services/ingestion/emit-completion.ts
import {
  createServiceStreamProducer,
  defineStreamSchema,
} from "@netscript/plugin-streams-core";
import { z } from "zod";

const completions = defineStreamSchema({
  completion: {
    schema: z.object({ id: z.string().min(1), status: z.string() }),
    type: "completion",
    primaryKey: "id",
  },
});

// assertResolvable defaults to true: this throws now if neither
// DURABLE_STREAMS_URL nor services__streams__http__0 is wired.
const producer = createServiceStreamProducer({
  streamPath: "/support-chat/completions",
  schema: completions,
  producerId: "support-chat-ingestion",
});

producer.upsert("completion", { id: "run-1", status: "done" });
await producer.flush();
```

A Service that declares `ServiceReferences: ["streams"]` always has the streams endpoint wired, so the guard resolves without throwing. Set `assertResolvable: false` to keep the tolerant, lazy-connect behavior of `createDurableStream` when a Service may legitimately start before the streams service is reachable. `ServiceStreamProducerOptions` is `DurableStreamProducerOptions` plus this optional `assertResolvable` flag; the returned `DurableStreamProducer` is identical, so the write/flush/close surface below applies unchanged.

## Runtime & transport — URL and auth resolution

The producer never hardcodes a host. `createDurableStream` resolves the durable-stream base URL through `getStreamsUrl()` and the auth header through `getStreamsAuth()`, both of which read the environment so the same code works under Aspire, in a browser build, or against an explicit override. `buildStreamUrl` joins a stream path onto that base, and `inspectStreamTopic` returns a JSON-stable diagnostic report for a schema (handy in tests and CLI doctors).

**Runtime resolvers (@netscript/plugin-streams-core)**

| Name | Type | Description |
| --- | --- | --- |
| `getStreamsUrl()` | `() => string` | Resolves the durable-stream base URL. Server: DURABLE_STREAMS_URL override, else Aspire's services__streams__http__0 discovery var. Browser: VITE_services__streams__http__0 (or the VITE_STREAMS_URL shorthand). Throws a descriptive error if none resolve. |
| `getStreamsAuth()` | `() => Record` | Builds the auth header from STREAMS_SECRET (or DURABLE_STREAMS_SECRET) as { Authorization: 'Bearer ' }; returns {} when no secret is set. |
| `buildStreamUrl(path, baseUrl?)` | `(string, string?) => string` | Joins a stream path onto the resolved base (or an explicit baseUrl), trimming a trailing slash on the base. |
| `inspectStreamTopic(input)` | `(input) => StreamTopicInspectionReport` | Diagnostic: returns a JSON-stable report (package, target, summary, details with collections/streamPath/producerId) for a schema + optional producer metadata. |

**Environment variables read by the resolvers**

| Name | Type | Description |
| --- | --- | --- |
| `DURABLE_STREAMS_URL` | `server override` | Explicit base URL; takes precedence over Aspire discovery (e.g. http://localhost:4437). |
| `services__streams__http__0` | `Aspire (server)` | Injected by the Aspire resource graph; the default server-side discovery path. |
| `VITE_services__streams__http__0` | `browser` | Vite-injected reference for browser/Fresh consumers; VITE_STREAMS_URL is the convenience shorthand. |
| `STREAMS_SECRET / DURABLE_STREAMS_SECRET` | `auth` | Bearer secret for getStreamsAuth(); when set, every connect sends Authorization: Bearer . |

## Known limitations

Be deliberate about what the alpha producer does and does not guarantee.

> Writes are dropped after a connect failure (no reconnect)
>
> If the producer cannot reach the
>
> :4437
>
> durable-stream server at startup, it logs a
>
> console.warn
>
> and then
>
> silently skips every subsequent `upsert`/`delete`
>
> — there is no reconnect loop in the current alpha.
>
> flush()
>
> rethrows that connect error so a graceful shutdown surfaces the failure. (Writes issued
>
> before
>
> the connection completes are buffered and drained once it opens; the drop only applies after a connect
>
> error
>
> .) Treat a healthy
>
> :4437
>
> service as a hard precondition for durable delivery; do not assume buffered writes will be replayed once the server returns.

> No in-process consumer — read over HTTP/SSE
>
> There is no in-process
>
> subscribe()
>
> handle. Consumption happens over the durable-stream server's HTTP/SSE protocol, which Fresh clients read to materialize the latest value per key. Model your read side as an HTTP/SSE consumer of the
>
> :4437
>
> stream, not as an in-process callback.

> Local HTTP can limit concurrent stream consumers
>
> The local AppHost serves the generated app over
>
> http://
>
> . Under HTTP/1.1, browsers typically allow about six concurrent connections per origin, so several long-lived HTTP/SSE streams from one Fresh page can starve later requests or stream subscriptions. Use HTTPS for HTTP/2 when a local dashboard needs many simultaneous stream consumers.

> Operator visibility is console.warn (alpha)
>
> The producer reports skips and connect failures through
>
> console.warn
>
> today — tracked as
>
> AP-13
>
> architecture debt until the telemetry-integration wave supplies a structured reporter. Until then, scrape the
>
> [DurableStreamProducer]
>
> warn lines if you need to alert on dropped writes.

## Endpoints & manifest

The streams plugin is registered as a utility/infra plugin — note it requires **neither a database nor KV** (`requiresDb=false`, `requiresKv=false`), unlike workers, sagas, and triggers. Its durable-stream service listens on `:4437` and is wired into the Aspire resource graph so workers, sagas, and auth can publish through it. The port is overridable via `STREAMS_PORT` or `PORT`.

**Streams plugin — runtime facts**

| Property | Value |
| --- | --- |
| Plugin location | `plugins/streams/` |
| Producer package | `@netscript/plugin-streams-core` (`createDurableStream`, `createServiceStreamProducer`, `defineStreamSchema`) |
| Manifest import | `@netscript/plugin-streams` — topic helpers **throw** `StreamUnsupportedOperationError` |
| Transport client | `@durable-streams/client` (`IdempotentProducer`) |
| Dev service port | `:4437` (durable-stream Aspire service; override with `STREAMS_PORT`/`PORT`) |
| provider.kind | `stream` · category `plugin` · pluginType `utility` |
| Requires DB / KV | `false` / `false` |
| First-party producers | workers, sagas, triggers, auth (each `streams/producer.ts` → `createDurableStream`) |
| Consumer surface | HTTP/SSE from the `:4437` server (Fresh clients) — **no** in-process `subscribe()` |

The plugin is referenced from `netscript.config.ts` as `./plugins/streams/mod.ts`. Because workers, sagas, and triggers each list `streams` in their `dependencies`, it is installed first in the dependency graph and its `:4437` service comes up so dependent producers have somewhere to write.

## Production notes

> Footguns before you ship
>
> - **Build on the core package, not the manifest helpers.** `createDurableStream` / `defineStreamSchema` from `@netscript/plugin-streams-core` are real; the `defineStreamProducer`/`defineStreamConsumer` helpers in `@netscript/plugin-streams` fail loud with `StreamUnsupportedOperationError`.
> - **A healthy `:4437` server is a hard precondition.** A startup connect failure drops every later write with no reconnect — bring Aspire (or an explicit `DURABLE_STREAMS_URL`) up first, and treat a `flush()` rejection on shutdown as a real delivery failure, not noise.
> - **Keep `producerId` stable across restarts.** Idempotent delivery is keyed by it; a churning id defeats the duplicate-safety guarantee.
> - **Model the read side as HTTP/SSE.** There is no in-process `subscribe()`; resolve the base with `getStreamsUrl()` and consume the `:4437` stream path directly.
> - **Set the auth secret on both ends.** When the server expects a bearer token, export `STREAMS_SECRET` (or `DURABLE_STREAMS_SECRET`) wherever the producer runs so `getStreamsAuth()` can attach it.

## Kept in sync, compared

Convex is the reference point for live client state: sync there is a property of its hosted database — client queries are reactive subscriptions, and the platform re-runs them when the underlying data changes. A NetScript stream scopes the same promise differently: sync is a property of a **declared contract**, not of the database. You freeze a schema of collections, a producer writes latest-state per key to the `:4437` durable-stream service in your own Aspire graph, and any HTTP/SSE consumer materializes that view — independent of which store actually holds your data (the plugin itself requires neither a database nor KV). The practical consequence: you choose per-collection what becomes live state, and everything outside that schema stays on the request/response and persistence paths you already have.

## Reference

This hub is intentionally thin — the full generated API lives in the reference.

[streams](https://rickylabs.github.io/netscript/netscript/reference/streams/)

> Where the real surface comes from
>
> The producer you build on lives in
>
> @netscript/plugin-streams-core
>
> :
>
> createDurableStream
>
> , the Service-facing
>
> createServiceStreamProducer
>
> ,
>
> DurableStreamProducer
>
> ,
>
> defineStreamSchema
>
> , the
>
> buildStreamUrl
>
> /
>
> getStreamsUrl
>
> /
>
> getStreamsAuth
>
> resolvers,
>
> inspectStreamTopic
>
> , and the
>
> StreamProducerPort
>
> /
>
> DurableStreamProducerOptions
>
> types. The
>
> @netscript/plugin-streams
>
> manifest re-exports
>
> streamsPlugin
>
> plus the fail-loud topic helpers. See the
>
> full reference
>
> for every exported symbol and the
>
> cli
>
> /
>
> scaffolding
>
> /
>
> e2e
>
> /
>
> aspire
>
> sub-paths.

[Look up — @netscript/plugin-streams-core  The generated API for createDurableStream, defineStreamSchema, the URL/auth resolvers, inspectStreamTopic, and the StreamProducerPort type.](https://rickylabs.github.io/netscript/netscript/reference/streams/)

[Learn — stream a live dashboard  Track D 05: publish execution state and read it over HTTP/SSE into a live Fresh dashboard.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/05-live-stream/)

[Understand — the plugin system  How thread-isolated plugins like streams register contributions and wire into the Aspire resource graph.](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/)

[Related — durable sagas  Message-driven orchestration with compensation; sagas mirror their state through a streams producer.](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/)

[Triggers & ingress](https://rickylabs.github.io/netscript/netscript/durable-workflows/triggers/) [Database & Prisma](https://rickylabs.github.io/netscript/netscript/data-persistence/database/)

_Canonical: https://rickylabs.github.io/netscript/durable-workflows/streams/_

---

# Triggers & ingress

The **triggers** plugin is NetScript's front door for the outside world. It turns external events — inbound webhooks, files dropped on disk, and cron schedules — into durable background work. A trigger handler does one job: receive an event and return a list of *actions*. The canonical action is `enqueueJob(...)`, which hands the payload to the [workers](https://rickylabs.github.io/netscript/background-processing/workers/) plugin so the heavy lifting happens off the request path. The HTTP call returns immediately; the job runs durably behind it.

![Trigger ingress flow: a webhook POST is verified by an HMAC check, persisted as an event, and dispatched to the handler which returns an enqueueJob action; a file-watch event is debounced and stabilised before reaching the same handler path.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/trigger-ingress-flow.svg)

*Two ingress edges, one processor: webhook POST → HMAC verify → event store → handler → enqueueJob; file-watch → debounce + stability → handler. Both converge on the trigger processor, which retries and DLQs.*

This closes the continuous-app loop. A webhook lands on the triggers service, it `enqueueJob`s a workers job, that job publishes a saga message, and the [saga](https://rickylabs.github.io/netscript/durable-workflows/sagas/) advances a workflow — all from one inbound POST.

The failure modes ingress must absorb are mundane and expensive: a payment provider retries the same webhook five times because your handler took too long; a half-written CSV fires an import mid-copy on a network share; a cron host reboots through the 02:00 run. Each has a declared answer here — `idempotencyKey` collapses sender retries, `stabilityThreshold` waits out the half-written file, and `backfill` replays the missed fire. Because every trigger is a frozen definition rather than routing code, the registry surface can list what fires what — the same property that lets a coding agent enumerate an app's ingress edges before touching one.

> Typed oRPC contract, raw webhook ingress
>
> Like
>
> services
>
> ,
>
> workers
>
> , and
>
> sagas
>
> , the triggers API service serves a
>
> typed v1 oRPC contract
>
> for trigger and event introspection plus management — describing triggers, listing and fetching triggers and events, firing a trigger, testing a webhook, previewing a schedule, enabling/disabling a trigger, and subscribing to an SSE event stream. The one deliberate exception is the
>
> webhook ingress endpoint
>
> itself (
>
> POST /api/v1/webhooks/:triggerId
>
> , plus a legacy
>
> GET /api/v1/events
>
> ): it stays a
>
> raw, signature-verifying route
>
> , not an oRPC procedure, because it must verify an HMAC signature over the raw request bytes — incompatible with oRPC's Zod body parsing. That keeps it open to any third-party webhook sender, which has no NetScript typed client and just POSTs to the plain URL.

## What it is

A trigger is a **declarative event source** plus a handler. NetScript ships three authorable trigger builders from `@netscript/plugin-triggers-core/builders` — `defineWebhook` (inbound HTTP), `defineFileWatch` (filesystem events), and `defineScheduledTrigger` (cron). All three return a frozen *definition* the runtime walker discovers; all three share one handler contract — `(event, context) => Promise<TriggerActionResult[]>` — and one runtime processor that verifies, persists, retries, and dead-letters. Three more kinds (`queue`, `stream`, `manual`) are reserved in the type surface but not yet executable. The processing engine itself lives in [`@netscript/watchers`](https://rickylabs.github.io/netscript/reference/watchers/) (file watching) and the trigger processor/ingress runtime (`@netscript/plugin-triggers-core/runtime`).

## Learn / Do

[Learn — Ingest a webhook  Storefront Track A, rung 05: scaffold the triggers plugin, author a webhook, POST to :8093, and watch it enqueue a job — closing the continuous-app ladder.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/05-shipping-webhook/)

[Do — Add a plugin  The how-to recipe for public plugin package install and the local netscript-dev contributor path for source-backed trigger samples.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/)

## Minimal example — a verified payment webhook

The 80% case: a webhook that verifies an HMAC signature, then fans the inbound payment event out to a single durable job. The handler returns immediately; the real work runs on the [workers](https://rickylabs.github.io/netscript/background-processing/workers/) plugin.

```ts
// plugins/triggers/payment-status-webhook.ts
import { defineWebhook, enqueueJob } from '@netscript/plugin-triggers-core/builders';
import type { JobDefinition } from '@netscript/plugin-workers-core';

// The workers job this webhook will enqueue (authored in plugins/workers/jobs/).
const reconcilePaymentJob = {
  id: 'reconcile-payment' as JobDefinition<'reconcile-payment'>['id'],
  name: 'Reconcile Payment',
  topic: 'default',
} satisfies JobDefinition<'reconcile-payment'>;

// Inbound POST -> enqueue a workers job. Ingress verifies the HMAC signature
// (verifier: 'hmac-sha256' + secretEnv) BEFORE this handler ever runs, so by the
// time you see the event the sender is already proven.
export const paymentStatusWebhook = defineWebhook(
  (event) => Promise.resolve([
    enqueueJob(reconcilePaymentJob, {
      payload: { raw: event.payload.body },
      idempotencyKey: event.idempotencyKey, // de-dupe sender retries
      priority: 80,
    }),
  ]),
  {
    id: 'payment-status-webhook',
    path: 'payments/status',
    verifier: 'hmac-sha256',
    secretEnv: 'PAYMENT_WEBHOOK_SECRET',
    description: 'Verified payment-status webhook that enqueues reconciliation.',
    tags: ['webhook', 'payments', 'verified'],
  },
);

export default paymentStatusWebhook;
```

## Key types first — the webhook definition

`defineWebhook(handler, spec)` takes your handler and a static `WebhookSpec`. These are the **actual** fields the builder accepts (confirmed via `deno doc`), shown before any prose so you can read the contract at a glance.

**WebhookSpec — the second argument to defineWebhook(handler, spec)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string (required)` | Stable identifier for the webhook definition, e.g. 'payment-status-webhook'. Branded internally as a WebhookId. |
| `path` | `string (required)` | Ingress sub-path the webhook answers on, e.g. 'payments/status'. Resolved as the :triggerId route segment under /api/v1/webhooks/. |
| `verifier` | `'hmac-sha256' \| 'memory' \| string (required)` | Verification strategy selector (WebhookVerifierKind). 'hmac-sha256' performs a real signature check; 'memory' is open (dev only); a custom string selects a verifier you wire via selectVerifier. |
| `secretEnv` | `string?` | Name of the env var holding the signing secret. The runtime reads it (resolveSecret) and hands it to the verifier — the secret is never inlined in the definition. |
| `description` | `string?` | Human-readable summary surfaced by inspect/registry tooling. |
| `tags` | `readonly string[]?` | Free-form labels for discovery/filtering, e.g. ['webhook','payments','verified']. |
| `metadata` | `Readonly>?` | Arbitrary structured metadata attached to the definition. |

The handler receives a `TriggerEvent<'webhook', WebhookTriggerPayload>`. The payload carries the captured HTTP request: `body` (parsed/raw), `headers`, `method` (always `"POST"`), `path`, and an optional `remoteAddr`. The event envelope also surfaces `idempotencyKey`, `traceparent`/`tracestate`, and `requestHeaders` — so de-duplicating sender retries is a one-liner, as in the example above.

## HMAC verification — proving the sender

`verifier: 'hmac-sha256'` activates the `HmacSha256WebhookVerifier` adapter from `@netscript/plugin-triggers-core/adapters`. Ingress hashes the raw request body with the secret (resolved from `secretEnv`) and compares it against the signature header *before* persisting the event or running your handler — a bad signature is rejected at the edge. The `'memory'` verifier (`MemoryWebhookVerifier`) accepts everything and is for local iteration only.

**HmacSha256WebhookVerifier — constructor options (from @netscript/plugin-triggers-core/adapters)**

| Name | Type | Description |
| --- | --- | --- |
| `secret` | `string?` | Signing secret. Usually supplied by the runtime from the definition's secretEnv rather than hard-coded here. |
| `signatureHeader` | `string?` | Header carrying the sender's HMAC signature to compare against (e.g. 'x-signature'). |
| `idempotencyHeader` | `string?` | Header whose value is surfaced as the event idempotencyKey when present, so sender retries collapse. |

> How the verifier is wired
>
> You rarely construct the adapter yourself. The webhook spec declares
>
> verifier: 'hmac-sha256'
>
> and
>
> secretEnv
>
> , and the ingress runtime (
>
> createTriggerIngress
>
> ) resolves the secret and selects the verifier per definition (its
>
> verifier
>
> ,
>
> selectVerifier
>
> , and
>
> resolveSecret
>
> options). The verifier's
>
> verify(request)
>
> returns
>
> { ok, idempotencyKey?, reason? }
>
> —
>
> ok: false
>
> stops the event at the edge.

## File-watch triggers — react to dropped files

`defineFileWatch(handler, spec)` turns filesystem events into the same durable-work pipeline. The watching primitive lives in [`@netscript/watchers`](https://rickylabs.github.io/netscript/reference/watchers/); the trigger builder wraps it so a dropped file becomes a handler invocation that returns `enqueueJob` actions. Below: a CSV drop-folder that enqueues one import job per stable file.

```ts
// plugins/triggers/product-import.ts
import { defineFileWatch, enqueueJob } from '@netscript/plugin-triggers-core/builders';
import type { JobDefinition } from '@netscript/plugin-workers-core';

const importProductsJob = {
  id: 'import-products' as JobDefinition<'import-products'>['id'],
  name: 'Import Products',
  topic: 'default',
} satisfies JobDefinition<'import-products'>;

// Fires once a *.csv lands in ./incoming/products and stops growing. The
// stabilityThreshold guards against half-written files on a network share:
// the watcher waits for 3 unchanged checks 1s apart before yielding the event.
export const productImportWatch = defineFileWatch(
  (event) => Promise.resolve([
    enqueueJob(importProductsJob, {
      payload: { file: event.payload.path },
      idempotencyKey: event.payload.path, // one import per file path
      priority: 50,
    }),
  ]),
  {
    id: 'product-import-watch',
    paths: ['./incoming/products'],
    patterns: ['*.csv'],
    on: ['create', 'modify'],
    stabilityThreshold: { checkIntervalMs: 1000, stableChecks: 3 },
    description: 'Imports a product CSV the moment it lands and stabilises.',
    tags: ['file-watch', 'erp', 'import'],
  },
);

export default productImportWatch;
```

**FileWatchSpec — the second argument to defineFileWatch(handler, spec)**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string (required)` | Stable identifier for the file-watch definition. |
| `paths` | `readonly string[] (required)` | Directories to watch (at least one). Relative paths resolve against the process cwd. |
| `patterns` | `readonly string[] (required)` | Glob patterns selecting which filenames fire, e.g. ['*.csv','sales_*.xlsx']. |
| `on` | `readonly ('create'\|'modify'\|'remove')[] (required)` | Which filesystem lifecycle events yield to the handler (FileWatchLifecycle). |
| `ignored` | `readonly string[]?` | Glob patterns to exclude from the watch. |
| `debounceMs` | `number?` | Per-file debounce window collapsing rapid successive events for the same path. |
| `stabilityThreshold` | `{ checkIntervalMs, stableChecks }?` | Network-FS tolerant gate: waits for stableChecks unchanged polls (checkIntervalMs apart) so half-written files don't fire early. |
| `description` | `string?` | Human-readable summary for tooling. |
| `tags` | `readonly string[]?` | Free-form discovery labels. |
| `metadata` | `Readonly>?` | Arbitrary structured metadata. |

The handler receives a `TriggerEvent<'file-watch', FileWatchTriggerPayload>`; the payload carries `path`, `kind` (the lifecycle event), and — when the watcher could read them — `size`, `modifiedAt`, and `stableChecks`.

### The underlying watcher

For lower-level or standalone file watching (outside the trigger pipeline), call `createWatcher(options)` from `@netscript/watchers` directly. It returns a `FileWatcher` whose `watch()` is an async generator of `WatchEvent`s.

```ts
// scripts/watch-incoming.ts
import { createWatcher } from "@netscript/watchers";

const watcher = createWatcher({
  paths: ["./incoming"],
  patterns: ["*.csv"],
  events: ["create", "modify"],
  stabilityThreshold: { checkIntervalMs: 1000, stableChecks: 3 },
});

for await (const event of watcher.watch()) {
  console.log(`${event.kind}: ${event.path}`);
}
```

**createWatcher(options) — WatcherOptions (from @netscript/watchers)**

| Name | Type | Description |
| --- | --- | --- |
| `paths` | `readonly string[] (required)` | Directories to watch (at least one required). |
| `patterns` | `readonly string[]?` | Glob patterns for filtering files. Default ['*']. |
| `events` | `readonly EventKind[]?` | Which FS events to yield ('create'\|'modify'\|'remove'). Default ['create']. |
| `debounceMs` | `number?` | Per-file debounce in milliseconds. Default 2000. |
| `contentHash` | `boolean?` | Compute a SHA-256 content hash for de-duplication. Default true. |
| `processExisting` | `boolean?` | Scan existing files on startup and emit them as create events. Default false. |
| `forcePolling` | `boolean?` | Force the polling strategy instead of native FS notifications. Default false (use for network paths). |
| `pollIntervalMs` | `number?` | Polling interval for the polling strategy. Minimum 500. Default 5000. |
| `minFileSize` | `number?` | Skip files smaller than this many bytes. Default 0. |
| `maxFileAge` | `number?` | Skip files older than this (ms); only applies during the startup scan. |
| `stabilityThreshold` | `StabilityOptions?` | When set, waits for files to stop growing before yielding (network-FS tolerant). |
| `signal` | `AbortSignal?` | Abort signal for graceful shutdown of the watch loop. |

The watcher selects the strategy for you: native OS notifications for local paths, polling for network paths or when `forcePolling: true`, and a `HybridStrategy` that blends both. Events pass a filter pipeline before you see them — `GlobFilter` limits filenames, `StabilityFilter` waits for files to stop growing, and `DedupFilter` skips repeated content hashes within its window. The concrete `NativeStrategy`, `PollingStrategy`, and `HybridStrategy` classes are internal; construct watchers with `createWatcher` or `new FileWatcher(...)`.

## Scheduled triggers — cron without a daemon

`defineScheduledTrigger(handler, spec)` fires a handler on a cron schedule. The spec combines discovery metadata (`id`, `description`, `tags`, `metadata`) with the cron `ScheduledTriggerSpec`. The scheduler runs inside the trigger processor entrypoint, not the Hono API service.

```ts
// plugins/triggers/nightly-reconcile.ts
import { defineScheduledTrigger, enqueueJob } from '@netscript/plugin-triggers-core/builders';
import type { JobDefinition } from '@netscript/plugin-workers-core';

const nightlyReconcileJob = {
  id: 'nightly-reconcile' as JobDefinition<'nightly-reconcile'>['id'],
  name: 'Nightly Reconcile',
  topic: 'default',
} satisfies JobDefinition<'nightly-reconcile'>;

// Runs at 02:00 UTC. backfill replays fires the scheduler missed while down.
export const nightlyReconcile = defineScheduledTrigger(
  () => Promise.resolve([enqueueJob(nightlyReconcileJob, { payload: {} })]),
  {
    id: 'nightly-reconcile',
    description: 'Nightly reconciliation sweep.',
    cron: '0 2 * * *',
    timezone: 'UTC',
    persistent: true,
    backfill: { enabled: true, windowMs: 86_400_000, policy: 'fire-once' },
  },
);

export default nightlyReconcile;
```

**Scheduled trigger spec — DefineScheduledTriggerSpec + ScheduledTriggerSpec**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string (required)` | Stable identifier for the scheduled trigger definition. |
| `cron` | `CronExpression (required)` | Cron expression governing when the handler fires, e.g. '0 2 * * *'. |
| `timezone` | `string?` | IANA timezone the cron expression is evaluated in. Defaults to the runtime's zone. |
| `persistent` | `boolean?` | Whether the schedule state survives restarts so missed fires can be reasoned about. |
| `backfill` | `TriggerBackfillSpec?` | Quartz-style misfire handling: { enabled, windowMs, policy: 'fire-now'\|'fire-once'\|'do-nothing', maxMissedFires? } — replays fires the scheduler missed while down. |
| `description` | `string?` | Human-readable summary for tooling. |
| `tags` | `readonly string[]?` | Free-form discovery labels. |
| `metadata` | `Readonly>?` | Arbitrary structured metadata. |

## Supported trigger actions

Every trigger handler returns **actions** — declarative descriptions of what should happen after the event is accepted. The runtime processor reads each action and dispatches it. Exactly one action is wired end-to-end today; a second is *defined in the type surface* but not executable, and it now **fails loud** rather than silently dropping.

**Trigger actions — what the runtime processor actually does**

| Name | Type | Description |
| --- | --- | --- |
| `enqueueJob(job, opts)` | `✅ live` | Hands the payload to the workers plugin. The supported, end-to-end path — it closes the continuous-app loop (event → job → saga). opts: { payload?, idempotencyKey?, concurrencyKey?, priority? }. |
| `defer(...)` | `⛔ unsupported` | Defined in the action union (DeferAction) but NOT executable. The processor throws an unsupportedOperation error and routes the message to the dead-letter queue (DLQ). There is no deferred replay — do not author a trigger that relies on defer. |

> defer is defined-but-unsupported — it fails loud
>
> The
>
> defer
>
> action exists in the trigger action union, but the runtime processor does
>
> not
>
> implement deferred replay. When a handler emits a
>
> defer
>
> action, the processor throws an
>
> unsupportedOperation
>
> error and routes the message to the
>
> dead-letter queue (DLQ)
>
> — it does not silently swallow it. Build ingress flows on
>
> enqueueJob
>
> only; if you need delayed work, schedule it on the
>
> workers
>
> plugin from the enqueued job, or use a
>
> defineScheduledTrigger
>
> cron rather than deferring at the trigger edge.

## Runtime — ingress, processor, retry

The trigger runtime (`@netscript/plugin-triggers-core/runtime`) assembles the pieces the API service and background processor use. You configure these when wiring a custom host; the scaffold wires them for you.

**Trigger runtime entry points (from @netscript/plugin-triggers-core/runtime)**

| Name | Type | Description |
| --- | --- | --- |
| `createTriggerIngress(options)` | `→ TriggerIngressPort` | Builds the webhook ingress edge. Options: { definitions, eventStore, processor, verifier, selectVerifier?, resolveSecret?, logger?, now?, createEventId? }. Verifies + persists, then hands off to the processor; responds 202 Accepted. |
| `createTriggerProcessor(options)` | `→ TriggerProcessor` | Builds the processor that runs handlers and dispatches actions. Options: { idempotency, dlq, dispatchAction?, logger?, now?, random? }. Applies the retry policy and routes exhausted/unsupported events to the DLQ. |
| `defaultRetryPolicy()` | `→ TriggerRetryPolicy` | The default { maxAttempts, initialDelayMs, maxDelayMs, backoffMultiplier, jitter } policy applied before DLQ handoff. Override per definition via the trigger's retry field. |

> Where the background work runs
>
> The triggers API service (port
>
> 8093
>
> ) is the HTTP edge — it hosts
>
> createTriggerIngress
>
> behind a raw Hono router. The actual trigger processing — cron, file-watch, and DLQ handling — runs in a separate background processor entrypoint at
>
> plugins/triggers/src/runtime/trigger-processor.ts
>
> . Aspire wires both as resources (
>
> triggers-api
>
> and
>
> trigger-processor
>
> ) when you
>
> aspire start
>
> .

## Endpoints & port

The triggers API service runs on **`:8093`**. The webhook router resolves the inbound `:triggerId` segment against your registered `defineWebhook` definitions — so a definition with `path: 'payments/status'` is reachable at `POST :8093/api/v1/webhooks/payments/status`.

**Triggers API — runtime surface (port 8093, Hono)**

| Name | Type | Description |
| --- | --- | --- |
| `POST /api/v1/webhooks/:triggerId` | `Hono route` | Generic dispatch — :triggerId matches the path of any registered defineWebhook definition. Verifies, persists, responds 202 Accepted. |
| `POST /api/v1/webhooks/inbound/generic` | `Hono route` | The scaffold's generic inbound webhook. Posting JSON here resolves trigger id 'inbound/generic' and runs its actions. |
| `GET /api/v1/events?limit=10` | `Hono route` | Recent ingress events recorded by the event store. |
| `GET /health` | `Hono route` | Liveness check for the triggers API service. |

## Author + call a trigger

The simple case is one webhook that fans an inbound request out to a single job. The advanced case validates the payload first, then enqueues. The simple case is adapted from the scaffold's `plugins/triggers/generic-webhook.ts` sample and compiles as-is; the advanced tab is an illustrative pattern, not scaffold code — the real `plugins/triggers/webhook-validate-data.ts` is an accept-and-drop sample (`() => Promise.resolve([])`) that imports no zod and enqueues no job. Every handler returns an array of `enqueueJob` actions — the only supported trigger action.

> ns-workers is a shorthand you install once
>
> ns-workers
>
> is a name
>
> you
>
> give the workers plugin's CLI — the scaffold does not create it. Install it once, globally, and the
>
> ns-workers
>
> command below works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> ```
>
> Rather not install it?
>
> ns-workers <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-workers@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```ts
// plugins/triggers/generic-webhook.ts
import { defineWebhook, enqueueJob } from '@netscript/plugin-triggers-core/builders';
import type { JobDefinition } from '@netscript/plugin-workers-core';

// A reference to the workers job this webhook will enqueue.
const healthCheckJob = {
  id: 'workers-plugin-health-check' as JobDefinition<'workers-plugin-health-check'>['id'],
  name: 'Workers Health Check',
  topic: 'default',
} satisfies JobDefinition<'workers-plugin-health-check'>;

// Inbound POST -> enqueue a workers job. The HTTP call returns immediately;
// the job runs durably on the workers plugin (:8091).
export const genericInboundWebhook = defineWebhook(
  () => Promise.resolve([
    enqueueJob(healthCheckJob, { payload: { verbose: false }, priority: 50 }),
  ]),
  {
    id: 'generic-inbound-webhook',
    path: 'inbound/generic',
    verifier: 'memory',
    description: 'Open webhook that enqueues the workers plugin health-check job.',
    tags: ['webhook', 'runtime-task', 'health-check'],
  },
);

export default genericInboundWebhook;
```

```ts
// plugins/triggers/webhook-validate-data.ts (pattern)
import { defineWebhook, enqueueJob } from '@netscript/plugin-triggers-core/builders';
import type { JobDefinition } from '@netscript/plugin-workers-core';
import { z } from 'zod';

// Validate the inbound body before doing any work.
const InboundSchema = z.object({
  userId: z.string().min(1),
  source: z.string().default('webhook'),
});

const createUserSettingsJob = {
  id: 'create-user-settings' as JobDefinition<'create-user-settings'>['id'],
  name: 'Create User Settings',
  topic: 'default',
} satisfies JobDefinition<'create-user-settings'>;

export const validatedInboundWebhook = defineWebhook(
  (event) => {
    // Parse + validate. On a bad shape, accept-and-drop (return []),
    // or throw to reject the request.
    const parsed = InboundSchema.safeParse(event.payload.body ?? {});
    if (!parsed.success) return Promise.resolve([]);

    // Hand the validated payload to a workers job.
    return Promise.resolve([
      enqueueJob(createUserSettingsJob, {
        payload: { userId: parsed.data.userId },
        priority: 80,
      }),
    ]);
  },
  {
    id: 'validated-inbound-webhook',
    path: 'validate/data',
    verifier: 'memory',
    description: 'Validates the body with zod, then enqueues create-user-settings.',
    tags: ['webhook', 'validated'],
  },
);

export default validatedInboundWebhook;
```

```bash
# Triggers API runs on :8093. POST to the webhook's resolved path.
curl -X POST http://localhost:8093/api/v1/webhooks/inbound/generic \
  -H 'content-type: application/json' \
  -d '{"verbose": false}'

# Watch the resulting ingress events:
curl 'http://localhost:8093/api/v1/events?limit=10'

# The enqueued job lands on the workers plugin (:8091):
ns-workers executions --limit=10 --json
```

## How it wires to the rest of the app

This is the last rung of the continuous-app thread. The `generic-inbound-webhook` enqueues the workers health-check job; the `create-user-settings` job (authored in the [background jobs](https://rickylabs.github.io/netscript/background-processing/workers/) tutorial) publishes a `UserSettingsCreated` saga message; the saga from the [durable workflow](https://rickylabs.github.io/netscript/durable-workflows/sagas/) tutorial handles it. One inbound POST drives the whole chain — and every link is real scaffold code that compiles.

## Production notes

> Production pitfalls
>
> - **Never ship the `'memory'` verifier publicly.** It accepts any POST so you can iterate fast. Before exposing a webhook, set `verifier: 'hmac-sha256'` and a `secretEnv` so only a sender holding the secret can enqueue work.
> - **The signing secret lives in env, not the definition.** `secretEnv` names the env var; the runtime resolves it (`resolveSecret`) at ingress. Keep the secret out of source and out of the definition object.
> - **Return fast, work later.** A handler should verify, validate, and `enqueueJob` — not do the work inline. Webhook senders time out and retry; durable processing belongs on the workers plugin.
> - **De-dupe sender retries.** Pass `idempotencyKey` (the event's key, or a stable field) to `enqueueJob` so a retried POST collapses to one job.
> - **File watches need stability on network shares.** Set `stabilityThreshold` so a half-written CSV does not fire mid-copy; use `forcePolling` on the underlying watcher for network filesystems that miss native events.
> - **Do not reach for `defer`.** It is defined-but-unsupported, throws, and routes to the DLQ. Schedule delayed work from the enqueued workers job, or use a `defineScheduledTrigger` instead.

## Where ingress lives, compared

Inngest — the closest neighbor for this event-to-work shape — models ingress as events sent to its platform: your app or a webhook transform sends events to Inngest's event API, and Inngest invokes the matching functions over HTTP, owning the scheduling and retry loop. A NetScript trigger keeps the same shape inside your workspace: the definition is a TypeScript file the runtime walker discovers, ingress is your own `:8093` service verifying HMAC over the raw request bytes, and the retry policy, event store, and dead-letter queue run in your trigger processor under Aspire. The difference to weigh is operational locus, not capability count — with triggers, the pieces that decide whether an event becomes work are resources in your own Aspire graph, inspectable in your own telemetry, and yours to run.

## Reference

[triggers](https://rickylabs.github.io/netscript/netscript/reference/triggers/)

[Look up — triggers core reference  The full generated API surface for the triggers unit: builders (defineWebhook / defineFileWatch / defineScheduledTrigger), runtime (ingress + processor), adapters (HMAC verifier), and the Hono router types.](https://rickylabs.github.io/netscript/netscript/reference/triggers/)

[Look up — watchers reference  createWatcher, FileWatcher, strategies (native/polling/hybrid), and the GlobFilter / StabilityFilter / DedupFilter pipeline.](https://rickylabs.github.io/netscript/netscript/reference/watchers/)

[Do — Background jobs  Where the enqueued work runs: defineJobHandler, worker runtimes, and the enqueue path triggers hand off to.](https://rickylabs.github.io/netscript/netscript/background-processing/workers/)

[Understand — Durable sagas  The next link in the chain: how an enqueued job's saga message advances a durable workflow.](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/)

[Durable sagas](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/) [Durable streams](https://rickylabs.github.io/netscript/netscript/durable-workflows/streams/)

_Canonical: https://rickylabs.github.io/netscript/durable-workflows/triggers/_

---

# Identity & Access

**One env var and five endpoints separate a scaffolded workspace from a working OAuth sign-in — and the boundaries fail loud with typed errors instead of degrading to a silent anonymous session.**

Identity & Access covers the Principal model, authentication backends, sessions, roles, scopes, and claims. Use this pillar when you are adding sign-in, selecting a backend, or reasoning about how identity flows through services and pages.

Auth is where an agent-assembled backend most easily *looks* done without *being* done — the mis-wired flow compiles, demos, and ships. NetScript's answer is to keep the security conventions in the contract itself: `NETSCRIPT_AUTH_BACKEND` selects exactly one active backend, every backend normalizes to the same `Principal`, unsupported operations fail loud with typed errors, and the redacted audit surface refuses to run without a salt. The full story — including the concrete failure modes the contract closes off — is on the [Authentication](https://rickylabs.github.io/netscript/identity-access/auth/) page.

[Capability   Authentication  The auth plugin story: one active backend, five endpoints, fail-loud typed boundaries, and the salt-gated audit surface.](https://rickylabs.github.io/netscript/netscript/identity-access/auth/) [Overview & Concepts   Auth model  Principal, session, backend, and authorization vocabulary.](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) [Quickstart   Workspace auth  Add authentication in the Workspace tutorial.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/02-auth/) [How-To   Add authentication  Wire authentication into a generated workspace.](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/add-authentication/) [How-To   better-auth plugins  Mount better-auth plugins through a typed passthrough; bearer and jwt run as-is, table-backed and interactive plugins carry caveats.](https://rickylabs.github.io/netscript/netscript/identity-access/better-auth-plugins/) [API Reference   auth backends  Generated symbols for auth, better-auth, kv-oauth, and WorkOS packages.](https://rickylabs.github.io/netscript/netscript/reference/auth/) [API Reference   plugin auth  Generated plugin-auth package symbols.](https://rickylabs.github.io/netscript/netscript/reference/plugin-auth/)

## Learn, do, look up

[Learn  Workspace tutorial  Auth, workspace data, and route authorization in one track.](https://rickylabs.github.io/netscript/netscript/tutorials/workspace/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/) [Look up  `@netscript/auth` reference  Generated API reference. Related units: `auth-better-auth`, `auth-kv-oauth`, `auth-workos`, `plugin-auth`.](https://rickylabs.github.io/netscript/netscript/reference/auth/) [Understand  The auth model  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/)

_Canonical: https://rickylabs.github.io/netscript/identity-access/_

---

# Authentication

**One env var and five endpoints separate a scaffolded workspace from a working OAuth sign-in — and the boundaries fail loud with typed errors instead of degrading to a silent anonymous session.** Auth is the part of a backend where "compiles and demos fine" and "actually holds" diverge most easily, so NetScript puts the conventions in the contract rather than in notes an agent has to remember to apply.

NetScript ships authentication as a first-class official plugin: `netscript plugin install @netscript/plugin-auth` adds an `auth-api` oRPC service that boots on port **8094** alongside your workers, sagas, and triggers. The plugin is **pure-backend** — it owns the session lifecycle, OAuth/OIDC redirect flow, and a stable five-endpoint REST/RPC surface, but it does **not** ship UI. You compose exactly **one active backend** (single-active-backend), chosen by an environment variable, and the service exposes the same contract no matter which backend is wired in.

alpha

![A browser sign-in request enters the auth-api service, which resolves the single active backend from an env var; the kv-oauth backend redirects to the OAuth/OIDC provider, handles the callback, mints a normalized session in Deno KV, sets the __Host-ns_session cookie, and maps the session to a NetScript Principal that downstream services trust.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/auth-flow.svg)

*Auth flow: browser → auth-api → resolved backend → provider redirect/callback → session store → __Host-ns_session cookie → Principal.*

The design follows the framework's contracts-first doctrine: a core seam package (`@netscript/plugin-auth-core`) defines the `AuthBackendPort`, three interchangeable adapter packages implement it, and the `@netscript/plugin-auth` plugin composes the selected one into a running service. Of the three adapters, only the KV-OAuth backend implements the full **interactive** sign-in/callback flow today; the WorkOS and better-auth adapters are non-interactive by design.

> Use this when
>
> Reach for the auth plugin when you need
>
> session-based authentication backed by an OAuth or OIDC provider
>
> — a typed
>
> /api/v1/auth/*
>
> surface your services and Fresh UI can call to sign users in, resolve the current session, and sign out. The default
>
> kv-oauth
>
> backend gives you a complete interactive redirect flow with KV-stored sessions and an opaque HMAC-signed session token. To wire it into a workspace step by step, see
>
> Add authentication
>
> ; to understand the pure-backend port model and why only one backend is active, see
>
> The authentication model
>
> .

## Where agent-built auth goes wrong

Auth is a security-sensitive surface, and security-sensitive surfaces have a specific build-efficiency failure shape: the mistake does not stop the build. A missing job queue fails a request; a mis-wired sign-in flow ships. Supabase's published agent-skills guidance names the pattern for its own platform — agents building on it skip RLS policies, hallucinate CLI commands, and create views without `security_invoker = true` — and its remedy is a skill: reference material the agent loads so it applies the conventions at the right moment. NetScript takes the other route for the same problem: move the conventions out of the agent's working memory and into the shipped contract, so the common wrong turns either don't type-check, don't configure, or fail loud at runtime with a typed error.

Concretely, the contract closes off the classic failure modes:

- **The silent anonymous fallback.** An agent wiring auth by hand tends to catch the failure and degrade to an unauthenticated default. `backend.authenticate()` cannot express that: it returns a typed `AuthnResult` — `{ ok: true, principal }` or `{ ok: false, reason }` — never a silent anonymous principal.
- **Calling a capability the backend doesn't have.** Asking a non-interactive backend (WorkOS, better-auth) to run the interactive sign-in returns a typed `AUTH_PROVIDER_ERROR`, and direct session mutations throw `AuthBackendOperationUnsupportedError` — a capability boundary, not a no-op that looks like success.
- **Two half-wired providers.** There is nothing to reconcile: `NETSCRIPT_AUTH_BACKEND` selects exactly one active backend (single-active-backend), and every backend normalizes to the same `Principal`, so downstream authorization code is identical regardless of provider.
- **Hand-rolled session cookies.** The session cookie is `__Host-ns_session`; the `__Host-` prefix makes the browser itself refuse a cookie with a `Domain`, a non-root `Path`, or a plain-HTTP origin — the misconfiguration fails to set rather than silently weakening.
- **Logging raw subjects.** The audit surface (`createAuthTelemetry`) redacts by construction — subject hashes, stripped token-bearing claims — and runs as a no-op until a salt is configured, because an un-salted hash would be worse than nothing.

Each item above is the shipped behavior of the published packages, documented mechanism-by-mechanism in the sections below — start with

[the authentication model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) for why the seam is shaped this way.

## What it is

Auth is a **port-and-adapter seam, not a monolith**. The core package `@netscript/plugin-auth-core` is contract-only: it defines the `AuthBackendPort` (and the four sub-ports it composes — provider registry, session store, token crypto, and principal mapper), the normalized `AuthSession` and `Principal` shapes, the `AUTH_SESSION_STATES`, the auth oRPC contract, the config schemas, and the stream-event schemas. It contains **no provider SDK code**. Each backend adapter (`@netscript/auth-kv-oauth`, `@netscript/auth-workos`, `@netscript/auth-better-auth`) implements `AuthBackendPort` against a concrete identity provider, and the `@netscript/plugin-auth` plugin selects exactly one of them at boot via `NETSCRIPT_AUTH_BACKEND` and serves it as the `auth-api` service. Because every backend produces the same `Principal`, downstream services authorize identically regardless of which provider is wired in. The full rationale — why auth is pure-backend, what the single-active boundary buys you, and how `InteractiveFlowPort` gates the redirect flow — is in

[The authentication model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) .

## Learn → / Do →

[Do — Add authentication  Task recipe: add the auth plugin, set NETSCRIPT_AUTH_BACKEND, run the auth.prisma migration, and wire kv-oauth with a provider preset.](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/add-authentication/)

[Understand — The authentication model  Why auth is pure-backend: the AuthBackendPort seam, the single-active-backend boundary, InteractiveFlowPort, and the three adapters' capability matrices.](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/)

[Compose — Service authn / authz  Gate a service's own routes with the provider-agnostic /auth middleware seam — verify a credential or trust a header, complementary to this plugin.](https://rickylabs.github.io/netscript/netscript/services-sdk/services/)

## Add it in two shapes

The fastest path is the **provider preset**: add the plugin, set `NETSCRIPT_AUTH_BACKEND` (it already defaults to `kv-oauth`), and hand a preset like `providers.google({...})` to `createKvOAuthBackend`. The **advanced** shape uses the same factory but defines a custom OIDC provider explicitly with `defineOAuthProvider` when your identity provider is not one of the fourteen built-in presets.

```ts
// Add the plugin from the workspace root:
//   netscript plugin install @netscript/plugin-auth
// Default backend is already kv-oauth (NETSCRIPT_AUTH_BACKEND=kv-oauth).

import { createKvOAuthBackend, getRequiredEnv, providers } from '@netscript/auth-kv-oauth';

// One of 14 presets: github, google, gitlab, discord, slack, spotify,
// facebook, twitter, auth0, okta, awsCognito, azureAd, logto, clerk.
export const backend = await createKvOAuthBackend({
  provider: providers.google({
    clientId: getRequiredEnv('NETSCRIPT_AUTH_CLIENT_ID'),
    clientSecret: getRequiredEnv('NETSCRIPT_AUTH_CLIENT_SECRET'),
    redirectUri: getRequiredEnv('NETSCRIPT_AUTH_REDIRECT_URI'),
  }),
});

// backend.name === 'kv-oauth' — the only adapter with backend.interactive.
```

```ts
// Same factory, but define the OIDC provider yourself when your IdP
// is not one of the built-in presets.
import { createKvOAuthBackend, defineOAuthProvider, getRequiredEnv } from '@netscript/auth-kv-oauth';

const provider = defineOAuthProvider({
  id: 'my-idp',
  clientId: getRequiredEnv('NETSCRIPT_AUTH_CLIENT_ID'),
  clientSecret: getRequiredEnv('NETSCRIPT_AUTH_CLIENT_SECRET'),
  authorizationEndpoint: getRequiredEnv('NETSCRIPT_AUTH_AUTHORIZATION_ENDPOINT'),
  tokenEndpoint: getRequiredEnv('NETSCRIPT_AUTH_TOKEN_ENDPOINT'),
  userInfoEndpoint: getRequiredEnv('NETSCRIPT_AUTH_USERINFO_ENDPOINT'),
  redirectUri: getRequiredEnv('NETSCRIPT_AUTH_REDIRECT_URI'),
  scopes: ['openid', 'profile', 'email'],
});

export const backend = await createKvOAuthBackend({ provider });
```

> Alpha package pins
>
> The scaffold pins
>
> jsr:@netscript/plugin-auth-core@0.0.1-beta.11
>
> and siblings at the exact aligned NetScript version. Add auth through
>
> netscript plugin install @netscript/plugin-auth
>
> , which wires the workspace correctly for the alpha instead of hand-editing imports.

## Sign in, resolve the session, sign out

Once the plugin is wired, your front end or a typed client drives the five-endpoint surface. A sign-in begins the redirect, the provider returns to your callback, the service mints a session and sets the cookie, and every subsequent request resolves the current session from that cookie. The snippet below is a copy-ready client flow against the REST surface.

```ts
// app/sign-in.ts — drive the auth-api REST surface from the browser
const AUTH = 'http://localhost:8094/api/v1/auth';

// 1. Begin sign-in. The kv-oauth backend responds with a provider redirect;
//    follow it to authenticate with the IdP.
location.href = `${AUTH}/signin`;

// 2. The IdP redirects back to /api/v1/auth/callback, which mints the
//    session and sets the __Host-ns_session cookie automatically.

// 3. Resolve the current session on any later request (cookie is sent
//    automatically; the response is { authenticated, user, session }).
const me = await fetch(`${AUTH}/me`, { credentials: 'include' })
  .then((r) => r.json());
if (me.authenticated) {
  console.log('signed in as', me.user.subject, '— state', me.session.state);
}

// 4. Sign out — revokes the session and clears the cookie.
await fetch(`${AUTH}/signout`, { method: 'POST', credentials: 'include' });
```

```ts
// server/auth-guard.ts — use the resolved backend directly in app code
import { AuthBackendOperationUnsupportedError } from '@netscript/plugin-auth-core/ports';
import { backend } from './backend.ts';

// Resolve the current session from an incoming Request via the session store.
const session = await backend.sessions.getSession({ request: incoming });
if (session?.state === 'active') {
  // Map the normalized session to a NetScript Principal for authorization.
  const { principal } = backend.principalMapper.mapSessionToPrincipal(session);
  console.log(principal.subject, principal.scopes, principal.roles);
}

// Interactive sign-in is optional capability — guard before you call it.
if (!backend.interactive) {
  throw new AuthBackendOperationUnsupportedError(
    backend.name,
    'interactive.signIn',
    'The active backend authenticates sessions only.',
  );
}
const redirect = await backend.interactive.signIn(incoming);
```

## Key types first — the core auth contract

Every backend normalizes to the same two shapes the rest of NetScript depends on: an `AuthSession` (what the store persists) and a `Principal` (what services authorize against). The `AuthSession` is mapped to a `Principal` by the backend's `principalMapper`, and the `authenticate()` method on every backend returns an `AuthnResult`. These are the contract-only types from `@netscript/plugin-auth-core` — confirmed against the live export surface.

**Principal (@netscript/plugin-auth-core) — the identity services authorize against**

| Name | Type | Description |
| --- | --- | --- |
| `subject` | `string` | Stable subject identifier — a user id, service id, or API-key id. |
| `scopes` | `readonly string[]` | Granted scopes for per-operation RPC/REST permission checks. |
| `roles` | `readonly string[]` | Granted roles for role-based access checks. |
| `scheme` | `'api-key' \| 'bearer' \| 'trusted-header' \| 'custom'` | How the principal was established. Auth-plugin backends use 'custom' with the claim bag below. |
| `claims` | `Readonly>` | Opaque verified claims — organization/tenant id, session id, provider permissions, or normalized WorkOS/better-auth metadata. |

**AuthSession (@netscript/plugin-auth-core) — the normalized session the store persists**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable session id; the value an opaque session token resolves to. |
| `userId / subject` | `string` | User id and stable subject the session belongs to. |
| `state` | `AuthSessionState` | Lifecycle state: 'active' \| 'expired' \| 'revoked' (from AUTH_SESSION_STATES). |
| `scopes / roles` | `readonly string[]` | Scopes and roles carried into the mapped Principal. |
| `claims` | `Readonly>` | Verified provider claims preserved on the session. |
| `issuedAt / expiresAt` | `string (ISO)` | Issue and expiry timestamps; refreshedAt / revokedAt are set on those transitions. |
| `accountId / providerId` | `string?` | Optional linked provider account and provider id. |
| `traceparent / tracestate` | `string?` | Optional W3C trace context carried for audit correlation. |

**AuthnResult (@netscript/plugin-auth-core) — what backend.authenticate() returns**

| Name | Type | Description |
| --- | --- | --- |
| `{ ok: true, principal }` | `success` | A resolved Principal; optional responseHeaders and setCookies the service flushes to the client. |
| `{ ok: false, reason }` | `rejection` | A typed rejection reason — fail-loud, never a silent anonymous principal. |

## The service surface

The plugin's service is named `auth-api` and is built with `@netscript/service`'s oRPC builder (`createService(...).withRPC()`), not raw Hono. It mounts a public REST surface at `/api/v1/auth/*` and the equivalent oRPC surface at `/api/rpc/v1/auth/*`, plus standard `/health/live` and `/health/ready` probes.

**auth-api endpoints (REST at /api/v1/auth/*, oRPC at /api/rpc/v1/auth/*)**

| Name | Type | Description |
| --- | --- | --- |
| `signin` | `POST` | Begins the interactive sign-in. Requires backend.interactive; on WorkOS / better-auth it returns AUTH_PROVIDER_ERROR (502) because those backends are non-interactive. |
| `callback` | `POST` | Completes the OAuth/OIDC redirect, mints the session, sets the session cookie. Interactive-only — same non-interactive caveat as signin. |
| `signout` | `POST` | Revokes the current session and clears the cookie. |
| `session` | `GET` | Resolves the current AuthSession from the cookie (active \| expired \| revoked), refreshing on read when policy allows. |
| `me` | `GET` | Returns { authenticated: true, user, session } when a valid active session exists, or { authenticated: false } (HTTP 200) when there is none. |

> Backend selection is one env var
>
> The service picks
>
> one
>
> active backend from
>
> NETSCRIPT_AUTH_BACKEND
>
> (or appsettings
>
> auth.backend
>
> ): valid values are
>
> kv-oauth
>
> |
>
> workos
>
> |
>
> better-auth
>
> , defaulting to
>
> `kv-oauth`
>
> . This is the
>
> single-active-backend
>
> boundary — there is no multi-active routing, cross-backend account linking, or global logout across backends in v1. Switching providers means changing the env var and the backend's credentials, not running two backends at once.

## The three backends

All three implement the same `AuthBackendPort`, so the `auth-api` contract is identical across them. They differ in one decisive capability: whether they expose an interactive sign-in/callback flow. Each ships a single factory that returns an `AuthBackendPort`.

**Backend adapters: factory, capability, and what each one needs**

| Name | Type | Description |
| --- | --- | --- |
| `@netscript/auth-kv-oauth` | `createKvOAuthBackend(options)` | Interactive (default). Full OAuth/OIDC redirect flow, Deno KV session store, real createSession / refreshSession / revokeSession, refresh-on-read (refreshMode / refreshSkewMs), opaque session token, __Host-ns_session cookie, AES-256-GCM token-at-rest. Needs a provider preset or defineOAuthProvider config. |
| `@netscript/auth-workos` | `createWorkosBackend({ workos, cookiePassword })` | Non-interactive. WorkOS AuthKit sealed sessions, stateless verification. Needs a WorkOS SDK client and a cookie password. signin / callback return AUTH_PROVIDER_ERROR; session mutations throw AuthBackendOperationUnsupportedError. |
| `@netscript/auth-better-auth` | `createBetterAuthBackend({ auth, sessionTokenSecret })` | Non-interactive. Validates externally-issued sessions via auth.api.getSession over a Prisma store (createNetscriptBetterAuth wires the better-auth Prisma adapter). Needs a better-auth instance and a token secret. |

> Only kv-oauth is interactive
>
> The
>
> signin
>
> and
>
> callback
>
> endpoints require a backend that implements the optional
>
> InteractiveFlowPort
>
> (
>
> signIn
>
> /
>
> handleCallback
>
> /
>
> getSessionId
>
> /
>
> signOut
>
> ). Today that is
>
> only `kv-oauth`
>
> . On
>
> workos
>
> and
>
> better-auth
>
> those two endpoints return a typed
>
> AUTH_PROVIDER_ERROR
>
> ("does not expose an interactive flow"), and direct session mutations throw
>
> AuthBackendOperationUnsupportedError
>
> — a deliberate, fail-loud capability boundary rather than a silent no-op. Use those adapters when sign-in is handled by WorkOS or an external better-auth deployment and NetScript only verifies the resulting session.

## How auth integrates with services

The auth **plugin** (this page) signs human users in and resolves their sessions. A NetScript **service** gates its own routes with the separate, provider-agnostic `@netscript/service/auth` seam — `.withAuthn()` resolves a `Principal` and `.withAuthz()` makes an authorization decision from it. Both layers speak the same `Principal` type, so they compose: the auth plugin establishes identity, and a service's `.withAuthn({ authenticator })` can trust a backend's authenticator to turn a request into that `Principal`. By default a service protects `/api` and leaves `/health` anonymous. The full builder seam — `createStaticCredentialAuthenticator`, `createTrustedHeaderAuthenticator`, `createScopeAuthorizer`, and the preset `defineService(router, { auth: { authn, authz } })` form — is documented on the services hub.

> Plugin vs. service-auth seam
>
> The
>
> auth plugin
>
> owns interactive sign-in, OAuth callbacks, and session cookies. The
>
> [service-auth seam](https://rickylabs.github.io/netscript/services-sdk/services/)
>
> is for machine-to-machine and gateway-fronted gating — static credentials, trusted upstream headers, scope checks — without an interactive identity provider. They are complementary and can run together: sign users in with the plugin, then gate individual service routes with
>
> .withAuthn()
>
> /
>
> .withAuthz()
>
> . See
>
> [Services & contracts](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) .

## Database & runtime events

The plugin contributes a package-provided `auth.prisma` schema with four better-auth-shaped models — `User` → `auth_users`, `Session` → `auth_sessions`, `Account` → `auth_accounts`, `Verification` → `auth_verifications`. These tables back the better-auth adapter; `kv-oauth` keeps its sessions in Deno KV, and WorkOS is stateless. As with every plugin schema, you bring the tables to life by running the database workflow **after Aspire is up** — see [Database migrations](https://rickylabs.github.io/netscript/data-persistence/how-to/database-migration/).

The plugin also emits five durable `auth.*` runtime events through the durable-streams runtime — the `AUTH_STREAM_EVENT_TYPES`: `auth.signin.started`, `auth.signin.failed`, `auth.token.refreshed`, `auth.session.revoked`, and `auth.oidc.completed`. The session projection is described by the `authStreamSchema` entity stream. For the streams runtime itself see

[Durable streams](https://rickylabs.github.io/netscript/netscript/durable-workflows/streams/) .

> Scope: stream events are best-effort — the audit trail is separate
>
> The
>
> auth.*
>
> events are
>
> best-effort
>
> : they are no-ops unless the durable-streams service is wired (
>
> DURABLE_STREAMS_URL
>
> /
>
> services__streams__http__0
>
> set), so they are
>
> not
>
> a guaranteed audit trail. Only
>
> oidc.completed
>
> ,
>
> token.refreshed
>
> , and
>
> session.revoked
>
> write the session projection;
>
> signin.started
>
> /
>
> signin.failed
>
> are diagnostic-only. The dedicated audit surface is separate:
>
> createAuthTelemetry
>
> records structured, redacted audit spans when a
>
> subjectHashSalt
>
> is configured (see the production notes below and
>
> [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/) ) — the raw stream events complement it, they do not replace it. For general tracing and structured logs see [Telemetry & logging](https://rickylabs.github.io/netscript/observability/telemetry/).

## Endpoints & ports

**Authentication runtime surface**

| Name | Type | Description |
| --- | --- | --- |
| `:8094` | `port` | auth-api default port (AUTH_API_DEFAULT_PORT). Family: workers :8091, sagas :8092, triggers :8093, auth :8094. |
| `auth-api` | `service name` | AUTH_API_SERVICE_NAME — the service contribution the auth plugin (AUTH_PLUGIN_ID 'auth') adds. |
| `/api/v1/auth/*` | `REST` | Public REST surface: signin, callback, signout, session, me. |
| `/api/rpc/v1/auth/*` | `oRPC` | The oRPC surface for the same five operations, for typed NetScript clients. |
| `/health/live` | `HTTP` | Liveness probe; /health/ready for readiness. OpenAPI + docs served via .withOpenAPI()/.withDocs(). |
| `NETSCRIPT_AUTH_BACKEND` | `env` | Selects the single active backend: kv-oauth (default) \| workos \| better-auth. |

## Production notes

> Footguns before you ship
>
> - **Only `kv-oauth` signs users in.** If `NETSCRIPT_AUTH_BACKEND` is `workos` or `better-auth`, the `signin` / `callback` endpoints return `AUTH_PROVIDER_ERROR` by design — those adapters only verify externally-issued sessions. Pick the backend that matches who owns the sign-in.
> - **The session cookie is `__Host-ns_session`.** The `__Host-` prefix *requires* `Path=/`, **no Domain**, and **HTTPS** — a misconfigured domain or a plain-HTTP origin makes the cookie refuse to set. Use a real TLS origin in production.
> - **Switching providers is an env-var + credentials change, not a runtime toggle.** There is no multi-active routing, cross-backend account linking, or global logout across backends in v1 (single-active-backend).
> - Auth audit is opt-in, and not a compliance-grade ledger.
>
>   A real, structured, redacted auth audit surface ships via
>
>   createAuthTelemetry
>
>   , but it only records when a
>
>   subjectHashSalt
>
>   is configured (resolved from
>
>   NETSCRIPT_AUTH_AUDIT_SALT
>
>   ) — with no salt it runs as a no-op. The raw
>
>   auth.*
>
>   stream events are themselves best-effort and no-op until the durable-streams service is wired. Treat the audit surface as a strong, queryable trail for operational and security review, not a tamper-evident, write-once compliance log. See
>
>   [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/) .
> - **Run the `auth.prisma` migration after Aspire is up.** The better-auth backend's tables (and any DB-backed flow) need your database provisioned first (Postgres is the recommended engine; or `mysql` / `mssql` / `sqlite` via `--db` — better-auth persists through Prisma, so it is not Postgres-specific) — the same Aspire-first ordering every plugin schema follows.

## Reference

The auth runtime is a `@netscript/service`; the auth plugin, core contract package, and backend adapters now have dedicated generated reference pages.

[auth](https://rickylabs.github.io/netscript/netscript/reference/auth/)

[service](https://rickylabs.github.io/netscript/netscript/reference/service/)

[Do — Add authentication  Task recipe: add the auth plugin, set NETSCRIPT_AUTH_BACKEND, run the auth.prisma migration, and wire kv-oauth with a provider preset.](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/add-authentication/)

[Understand — The authentication model  Why auth is pure-backend: the AuthBackendPort seam, the single-active-backend boundary, InteractiveFlowPort, and the three adapters' capability matrices.](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/)

[Look up — @netscript/service reference  The oRPC service builder behind auth-api: createService().withRPC(), the contract surface, the /auth authn-authz seam, and the runtime that serves /api/v1/auth/*.](https://rickylabs.github.io/netscript/netscript/reference/service/)

[Fresh UI & design](https://rickylabs.github.io/netscript/netscript/web-layer/fresh-ui/)

_Canonical: https://rickylabs.github.io/netscript/identity-access/auth/_

---

# better-auth plugins

[better-auth](https://www.better-auth.com/) ships its feature set as plugins — organizations, two-factor, API keys, bearer and JWT tokens, magic links, passkeys, and more. NetScript's better-auth backend mounts them through a single typed passthrough on `createNetscriptBetterAuth`, so you enable a plugin the same way you would in a standalone better-auth app while NetScript keeps ownership of the Prisma-backed database adapter.

This page covers how to enable plugins, which ones run as-is, and the two prerequisites — database tables and interactive sign-in — that decide whether a given plugin is turnkey today.

## Enabling a plugin

`createNetscriptBetterAuth` accepts a `plugins` array typed as better-auth's own `BetterAuthOptions["plugins"]`. Pass plugin instances exactly as better-auth documents them; NetScript forwards them into the underlying better-auth server while supplying the Prisma adapter itself.

```ts
import { organization } from "better-auth/plugins";
import {
  createBetterAuthBackend,
  createNetscriptBetterAuth,
} from "@netscript/auth-better-auth";

const auth = createNetscriptBetterAuth({
  prisma,
  provider: "postgresql",
  secret: Deno.env.get("BETTER_AUTH_SECRET")!,
  plugins: [organization()],
});

const backend = createBetterAuthBackend({
  auth,
  sessionTokenSecret: Deno.env.get("BETTER_AUTH_SECRET")!,
});
```

For better-auth options that NetScript does not surface directly, use `betterAuthOptions` (typed as `Omit<BetterAuthOptions, "database" | "plugins">`). NetScript owns `database` through its Prisma adapter, and plugins use the dedicated `plugins` field, so both are excluded from that escape hatch.

When the `organization` plugin is enabled, the active-organization fields better-auth writes onto the session (`activeOrganizationId`, role, roles, and permissions) and the user's roles flow through NetScript's authenticator onto the `Principal` — its scopes, roles, and claims — so downstream services and pages can authorize on organization context without any extra wiring.

## What runs today, and what needs a prerequisite

A plugin enabled through the passthrough type-checks and is mounted at the better-auth layer. Whether it is *runnable* depends on what the plugin needs at runtime.

### Stateless plugins run as-is

`bearer` and `jwt` add no tables of their own. They run through the passthrough alone, with no further setup.

### Table-backed plugins need a schema migration

> Generate and migrate the plugin schema first
>
> `organization`, `twoFactor`, `admin`, and `apiKey` store state in their own better-auth tables. Enabling them through the passthrough mounts them at the better-auth layer, but they fail at runtime until their better-auth schema has been generated and migrated into your database. A turnkey schema-generation path is on the roadmap; until it lands, generate and apply the better-auth schema for these plugins before depending on them.

### Interactive plugins are driven by better-auth directly

> Interactive sign-in is owned by better-auth
>
> `magicLink` and `passkey` sign-in are interactive flows. NetScript's better-auth backend is non-interactive, so its `/signin` and `/callback` endpoints return `AUTH_PROVIDER_ERROR`. Drive those flows against better-auth's own handler and let NetScript verify the resulting session. An interactive-flow seam for the better-auth backend is tracked on the roadmap.

## Protect a route with the resolved session

`createBetterAuthBackend` returns an `AuthBackendPort`, and the piece a page or API route needs is `backend.sessions.getSession({ request })`: it validates the request's better-auth session cookie through `auth.api.getSession` and returns the normalized `AuthSession` (or `undefined`). Map that session to a `Principal` with `backend.principalMapper.mapSessionToPrincipal(session)` and you have the scopes and roles to authorize on. The example below gates a Fresh route on an **active** session and an `admin` role, failing closed on both.

```ts
// server/auth-backend.ts — one shared backend instance for the app
import { auth } from './better-auth.ts'; // your createNetscriptBetterAuth(...) instance
import { createBetterAuthBackend } from '@netscript/auth-better-auth';

export const backend = createBetterAuthBackend({
  auth,
  sessionTokenSecret: Deno.env.get('BETTER_AUTH_SECRET')!,
});
```

```tsx
// routes/admin/index.tsx — a page that only an authenticated admin can load
import { HttpError } from 'fresh';
import type { AuthnRequest } from '@netscript/service/auth';
import { define } from '@/utils/state.ts';
import { backend } from '../../server/auth-backend.ts';

// Adapt the Fresh Request into the AuthnRequest the backend port reads.
function toAuthnRequest(req: Request): AuthnRequest {
  const url = new URL(req.url);
  return {
    header: (name) => req.headers.get(name) ?? undefined,
    headers: () => req.headers,
    cookie: (name) =>
      req.headers.get('cookie')
        ?.split('; ')
        .find((c) => c.startsWith(`${name}=`))
        ?.slice(name.length + 1),
    method: req.method,
    path: url.pathname,
  };
}

export const handler = define.handlers(async (ctx) => {
  // Resolve the session from the request's better-auth cookie.
  const session = await backend.sessions.getSession({
    request: toAuthnRequest(ctx.req),
  });

  // Fail closed: no active session → redirect to sign-in, never render anonymously.
  if (!session || session.state !== 'active') {
    return ctx.redirect('/api/v1/auth/signin');
  }

  // Map to a NetScript Principal and authorize on its roles.
  const { principal } = backend.principalMapper.mapSessionToPrincipal(session);
  if (!principal.roles.includes('admin')) {
    throw new HttpError(403);
  }

  return { data: { subject: principal.subject, roles: principal.roles } };
});

export default define.page<typeof handler>(({ data }) => (
  <main>
    <h1>Admin dashboard</h1>
    <p>Signed in as {data.subject} — roles: {data.roles.join(', ')}</p>
  </main>
));
```

Because `getSession` returns a typed `AuthSession | undefined` and the state check is explicit, the route cannot silently degrade to an anonymous render — the same fail-loud discipline the [authentication](https://rickylabs.github.io/netscript/identity-access/auth/) page describes for the backend port. A machine-to-machine API route follows the identical shape: swap the redirect for `throw new HttpError(401)`.

## Where to go next

-

## [Auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) — how Principals, sessions, and backends fit together.

[Authentication](https://rickylabs.github.io/netscript/netscript/identity-access/auth/) — the authentication capability overview.

- [Reference: auth-better-auth](https://rickylabs.github.io/netscript/reference/auth-better-auth/) — generated symbols for every export shown here.

_Canonical: https://rickylabs.github.io/netscript/identity-access/better-auth-plugins/_

---

# Identity & Access — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/identity-access/how-to/_

---

# Add authentication

**Scope.** This recipe adds sign-in, sessions, and a `/me` identity endpoint to an existing NetScript workspace by installing the official **`auth`** plugin. You will choose an authentication backend, run the auth database migration, set the backend's environment, and verify a live session through the `auth-api` service on **`:8094`**. By the end you have a working OAuth/OIDC sign-in flow on the default backend (`kv-oauth`) and a clear picture of what the two non-interactive backends (`workos`, `better-auth`) do and do not provide.

This is the task-oriented companion to the [authentication capability hub](https://rickylabs.github.io/netscript/capabilities/auth/) (the headline API and endpoint map) and the [authentication model explanation](https://rickylabs.github.io/netscript/explanation/auth-model/) (why the backend is a pure adapter behind a port). If you want the *why*, read those; if you want the *how*, stay here.

> Aspire is the control plane — start it first
>
> The
>
> auth-api
>
> service and its database/KV dependencies run as resources in the Aspire graph (the database is Postgres, the recommended engine;
>
> mysql
>
> /
>
> mssql
>
> run as Aspire containers too, while
>
> sqlite
>
> is file-backed — pick one at scaffold with
>
> --db
>
> ). Bring orchestration up
>
> before
>
> you run any
>
> netscript db
>
> command or hit an auth endpoint: from the project root,
>
> cd aspire && aspire start
>
> (dashboard at
>
> https://localhost:18888
>
> ). DB commands require Aspire running first. See
>
> the Aspire explanation
>
> for the resource graph.

> Alpha package pins
>
> The CLI scaffold emits exact alpha specifiers such as
>
> jsr:@netscript/plugin-auth-core@0.0.1-beta.11
>
> . Add the plugin through
>
> netscript plugin install @netscript/plugin-auth
>
> so the workspace gets the matching auth dependency, generated glue, registry entries, and Aspire resources together.

## Before you start

You need an existing workspace with a database, because the `kv-oauth` and `better-auth` backends persist sessions and accounts. The `auth` plugin sets `requiresDb: true` and `requiresKv: true`, so both a database and KV (Redis) must be in the Aspire graph. The database is polyglot — Postgres is the recommended default, but `mysql`, `mssql`, or `sqlite` are first-class alternatives selected at scaffold time with `netscript init --db <engine>`. (Postgres/MySQL/SQL Server run as an Aspire container resource; SQLite is file-backed with no container.)

**Prerequisites**

| Name | Type | Description |
| --- | --- | --- |
| `Workspace` | `netscript init` | An existing project. If you have none, scaffold one first — see the tutorials. |
| `netscript CLI` | `on PATH` | Installed globally: deno install --global --allow-all --name netscript jsr:@netscript/cli. Confirm with netscript --help. |
| `Aspire` | `aspire start` | Postgres + Redis up via the AppHost before any db command or endpoint call (cd aspire && aspire start). |
| `OAuth credentials` | `client id / secret` | For the default kv-oauth backend you need a real OAuth/OIDC app (e.g. a Google client id + secret + redirect URI). Without provider env, signin/callback are non-functional stubs. |

Throughout, run commands from your workspace root.

## Step 1 — Add the `auth` plugin

The `auth` plugin is a first-class official plugin installed the same way as `workers`, `sagas`, `triggers`, and `streams`. Add it with `plugin install`:

```sh
netscript plugin install @netscript/plugin-auth
```

This installs the unified `@netscript/plugin-auth` dependency, emits the user-owned `auth/mod.ts` glue barrel, and registers it. The plugin package composes **one active backend** behind the `auth-api` oRPC service and contributes the Prisma schema (`auth.prisma`), service entry, and `/api/v1/auth/*` routes.

> One plugin, one active backend
>
> @netscript/plugin-auth
>
> is a thin composition layer. The real authentication logic lives in a
>
> backend adapter
>
> — one of
>
> @netscript/auth-kv-oauth
>
> ,
>
> @netscript/auth-workos
>
> , or
>
> @netscript/auth-better-auth
>
> . The plugin selects
>
> exactly one
>
> active backend at runtime; there is no multi-active routing or cross-backend account linking in v1. You pick the backend in Step 2.

## Step 2 — Choose a backend with the auth CLI

The active backend is selected by the `NETSCRIPT_AUTH_BACKEND` environment variable (or the `auth.backend` appsettings key). Three backends are valid; the default is **`kv-oauth`**.

**Auth backends — capability matrix (NETSCRIPT_AUTH_BACKEND)**

| Name | Type | Description |
| --- | --- | --- |
| `kv-oauth` | `interactive (default)` | Full OAuth/OIDC redirect flow. Real signin + callback, KV-backed sessions with refresh-on-read, signout. The only backend that implements InteractiveFlowPort. Package @netscript/auth-kv-oauth. |
| `workos` | `non-interactive` | WorkOS AuthKit sealed wos-session cookie. Validates an existing session; signin/callback return AUTH_PROVIDER_ERROR (no interactive flow). Package @netscript/auth-workos. |
| `better-auth` | `non-interactive` | better-auth over Prisma. Validates an existing session; signin/callback return AUTH_PROVIDER_ERROR. Package @netscript/auth-better-auth. |

> Only kv-oauth is interactive — choose accordingly
>
> The
>
> signin
>
> and
>
> callback
>
> endpoints require a backend that implements the optional
>
> InteractiveFlowPort
>
> .
>
> Only `kv-oauth` does.
>
> On
>
> workos
>
> and
>
> better-auth
>
> , calling
>
> POST /api/v1/auth/signin
>
> or
>
> POST /api/v1/auth/callback
>
> returns a typed
>
> AUTH_PROVIDER_ERROR
>
> (502) explaining the backend "does not expose an interactive flow." Those backends are for environments where sign-in already happened elsewhere and you only need NetScript to
>
> validate
>
> the session (
>
> session
>
> /
>
> me
>
> ). If you need NetScript to drive the login redirect, use
>
> kv-oauth
>
> .

For the rest of this recipe we use `kv-oauth`. Persist the choice in the workspace boot seam and confirm what the service will use:

```sh
netscript plugin auth backend set kv-oauth
netscript plugin auth backend show
netscript plugin doctor
```

The command reconciles `NETSCRIPT_AUTH_BACKEND` in the project `.env`, so scaffolded service tasks boot without a shell-specific export. Directly setting the environment variable or the `auth.backend` / `Auth.Backend` appsettings key remains an escape hatch for deployment systems that own configuration externally.

## Step 3 — Run the auth database migration

The `auth` plugin contributes a package-provided **`auth.prisma`** schema, which is aggregated into your project's database schema at `db generate` (Postgres is the recommended engine; or `mysql` / `mssql` / `sqlite` — the auth models persist through Prisma, so they follow whichever engine you scaffolded with `--db`). It defines four better-auth-shaped models mapped to these tables:

**auth.prisma models → your database tables**

| Name | Type | Description |
| --- | --- | --- |
| `User` | `auth_users` | Authenticated principals. Populated by backends that persist users (better-auth). |
| `Session` | `auth_sessions` | Server-side session records. kv-oauth keeps sessions in KV; this table backs the Prisma-persisting backend. |
| `Account` | `auth_accounts` | Linked provider accounts (the OAuth/OIDC identities behind a user). |
| `Verification` | `auth_verifications` | Verification / challenge records used during account flows. |

> Which backends actually use these tables
>
> auth.prisma
>
> is provisioned for every install so the schema is consistent, but storage differs by backend:
>
> kv-oauth
>
> stores sessions in Deno KV (not these tables),
>
> WorkOS
>
> is effectively stateless (sealed cookie), and
>
> better-auth
>
> is the backend that reads/writes
>
> auth_users
>
> /
>
> auth_sessions
>
> /
>
> auth_accounts
>
> /
>
> auth_verifications
>
> through Prisma. The migration runs regardless; it is the persistence path for the Prisma-backed backend.

With Aspire running (Step 0), generate and apply the migration the same way you do for any plugin schema:

```sh
netscript db init --name init    # first time only — create the migration
netscript db generate            # generate Prisma client + Zod schemas from the aggregated schema
netscript db seed                # optional seed data
netscript db status              # confirm the migration is applied
```

See [Run a database migration](https://rickylabs.github.io/netscript/data-persistence/how-to/database-migration/) for the full DB workflow and the Aspire-up dependency.

## Step 4 — Configure the provider and secrets

Each backend reads its own environment block. The auth CLI owns the normal setup path and writes the same project `.env` seam as Step 2. For GitHub on `kv-oauth`:

```sh
# Generate the boot key through the CLI and persist it with the provider config
KV_OAUTH_KEY="$(netscript plugin auth secret generate kv-oauth-key)"
netscript plugin auth provider set \
  --preset github \
  --client-id your-client-id \
  --client-secret your-client-secret \
  --redirect-uri http://localhost:8094/api/v1/auth/callback \
  --kv-oauth-key "$KV_OAUTH_KEY"
```

Tenant presets such as `okta`, `auth0`, `azure-ad`, `aws-cognito`, `logto`, and `clerk` additionally accept `--issuer`. The non-interactive variants use their boot-native credential names:

```sh
netscript plugin auth provider set --preset workos \
  --api-key sk_... --client-id client_... --cookie-password "$(netscript plugin auth secret generate workos-cookie)"

netscript plugin auth provider set --preset better-auth \
  --secret "$(netscript plugin auth secret generate better-auth)"
```

The explicit exports below are the escape hatch for CI/deployment systems that inject environment variables themselves; they are no longer required for ordinary workspace setup.

```sh
# Selects the interactive OAuth/OIDC backend
export NETSCRIPT_AUTH_BACKEND=kv-oauth

# Provider credentials (e.g. a Google OAuth app)
export NETSCRIPT_AUTH_CLIENT_ID=your-client-id
export NETSCRIPT_AUTH_CLIENT_SECRET=your-client-secret
export NETSCRIPT_AUTH_REDIRECT_URI=http://localhost:8094/api/v1/auth/callback

# OIDC discovery / endpoints (preset providers fill these for you)
export NETSCRIPT_AUTH_ISSUER=https://accounts.google.com
export NETSCRIPT_AUTH_AUTHORIZATION_ENDPOINT=https://accounts.google.com/o/oauth2/v2/auth
export NETSCRIPT_AUTH_TOKEN_ENDPOINT=https://oauth2.googleapis.com/token
export NETSCRIPT_AUTH_USERINFO_ENDPOINT=https://openidconnect.googleapis.com/v1/userinfo
export NETSCRIPT_AUTH_SCOPES=openid email profile

# Optional: cookie + KV tuning
export NETSCRIPT_AUTH_COOKIE_NAME=__Host-ns_session
export NETSCRIPT_AUTH_KV_OAUTH_KEY=<base64url-encoded-32-byte-secret>  # required for kv-oauth: missing key material is a startup error
# export NETSCRIPT_AUTH_ALLOW_INSECURE_REQUESTS=false

export PORT=8094
```

```sh
export NETSCRIPT_AUTH_BACKEND=workos

export WORKOS_API_KEY=sk_...
export WORKOS_CLIENT_ID=client_...
export WORKOS_COOKIE_PASSWORD=at-least-32-characters-of-entropy

# signin/callback return AUTH_PROVIDER_ERROR on this backend.
# It validates an existing WorkOS AuthKit session (session/me).
export PORT=8094
```

```sh
export NETSCRIPT_AUTH_BACKEND=better-auth

export BETTER_AUTH_SECRET=at-least-32-characters-of-entropy
export DB_PROVIDER=postgres

# Persists users/sessions/accounts via auth.prisma (Step 3).
# signin/callback return AUTH_PROVIDER_ERROR — validate-only.
export PORT=8094
```

> Provider presets fill the OIDC endpoints for you
>
> You rarely hand-type issuer/authorization/token/userinfo URLs. The
>
> kv-oauth
>
> package ships provider presets —
>
> github
>
> ,
>
> google
>
> ,
>
> gitlab
>
> ,
>
> discord
>
> ,
>
> slack
>
> ,
>
> spotify
>
> ,
>
> facebook
>
> ,
>
> twitter
>
> , plus tenant-based
>
> auth0
>
> ,
>
> okta
>
> ,
>
> awsCognito
>
> ,
>
> azureAd
>
> ,
>
> logto
>
> ,
>
> clerk
>
> — that encode the correct endpoints. Pass one to
>
> createKvOAuthBackend
>
> in Step 5, or call
>
> defineOAuthProvider(...)
>
> for a custom provider.

## Step 5 — The kv-oauth happy path (code)

When you compose the backend in code (for a custom service entry, a test, or a non-scaffold wiring), the interactive `kv-oauth` backend is one `await` call. Pass a provider preset from `providers.*`:

```ts
import { createKvOAuthBackend, providers } from "@netscript/auth-kv-oauth";

// providers.google(...) is a preset that fills the OIDC endpoints for you.
const backend = await createKvOAuthBackend({
  provider: providers.google({
    clientId: Deno.env.get("NETSCRIPT_AUTH_CLIENT_ID")!,
    clientSecret: Deno.env.get("NETSCRIPT_AUTH_CLIENT_SECRET")!,
    redirectUri: "http://localhost:8094/api/v1/auth/callback",
  }),
});

// backend implements AuthBackendPort AND the optional InteractiveFlowPort
// (signIn / handleCallback / getSessionId / signOut), so the auth-api
// signin + callback endpoints are live on this backend.
console.log(backend.name); // "kv-oauth"
```

```ts
import { createKvOAuthBackend, providers } from "@netscript/auth-kv-oauth";

// GitHub instead of Google — same shape, different preset.
const github = await createKvOAuthBackend({
  provider: providers.github({
    clientId: Deno.env.get("NETSCRIPT_AUTH_CLIENT_ID")!,
    clientSecret: Deno.env.get("NETSCRIPT_AUTH_CLIENT_SECRET")!,
    redirectUri: "http://localhost:8094/api/v1/auth/callback",
  }),
});

// Tenant providers (auth0, okta, azureAd, awsCognito, logto, clerk) take
// a tenant/domain in addition to the client credentials.
```

The returned `backend` satisfies the `AuthBackendPort` seam that `@netscript/plugin-auth-core` defines, and — because it is `kv-oauth` — also the optional `InteractiveFlowPort`. That is precisely what makes `signin` and `callback` work on this backend and fail loud on the other two. For the port architecture behind this, read [the authentication model](https://rickylabs.github.io/netscript/explanation/auth-model/).

## Step 6 — Start the service and the auth endpoints

With Aspire running, the `auth-api` service binds **port 8094** and mounts five endpoints under the public REST prefix **`/api/v1/auth/*`** (the oRPC surface is mirrored at `/api/rpc/v1/auth/*`):

**auth-api endpoints (:8094, /api/v1/auth/*)**

| Name | Type | Description |
| --- | --- | --- |
| `POST /api/v1/auth/signin` | `interactive only` | Begin the OAuth/OIDC redirect flow. Live on kv-oauth; returns AUTH_PROVIDER_ERROR on workos/better-auth. |
| `POST /api/v1/auth/callback` | `interactive only` | Complete the provider redirect, mint a session. Live on kv-oauth; AUTH_PROVIDER_ERROR on the others. |
| `POST /api/v1/auth/signout` | `session` | Revoke the current session and clear the session cookie. |
| `GET /api/v1/auth/session` | `session` | Return the current session if one is present and valid. Works on all backends. |
| `GET /api/v1/auth/me` | `identity` | Return the authenticated principal (the resolved user). Works on all backends. |

The service also exposes liveness/readiness probes at `/health/live` and `/health/ready`, plus OpenAPI docs, through the standard `@netscript/service` builder. Watch it come up in the Aspire dashboard at [https://localhost:18888](https://localhost:18888) under the `auth-api` resource.

## Step 7 — Verify a session

Confirm the service is up and the session endpoint responds. On a fresh, unauthenticated request, `session` reports no active session — which proves the endpoint is wired even before you complete a login:

```sh
# Service is alive
curl http://localhost:8094/health/ready

# No session yet — confirms the endpoint is mounted and reachable
curl http://localhost:8094/api/v1/auth/session
```

To exercise the full interactive flow on `kv-oauth`, drive the redirect from a browser: open `POST /api/v1/auth/signin` (the service issues the provider redirect), authenticate with your provider, let the provider call back to `/api/v1/auth/callback`, then re-check the session and identity with the cookie the flow set:

```sh
# After completing the browser sign-in, the session cookie is set.
# Re-checking now returns the active session and the resolved principal:
curl -b cookies.txt http://localhost:8094/api/v1/auth/session
curl -b cookies.txt http://localhost:8094/api/v1/auth/me
```

A successful `GET /api/v1/auth/session` after sign-in returns the active session; `GET /api/v1/auth/me` returns the authenticated principal. That round trip is the proof the backend is composed, the migration is applied, and the provider credentials are correct.

> Local smoke without real credentials
>
> If provider env is missing, the
>
> kv-oauth
>
> backend falls back to a non-functional local-default endpoint set so the service still boots and
>
> /health
>
> ,
>
> session
>
> , and
>
> me
>
> answer. The default is suitable for scaffold smoke tests. Real
>
> signin
>
> /
>
> callback
>
> require genuine provider credentials — the fallback is a stub path, not a working login.

## Production pitfalls

> Read before you ship authentication
>
> - **Wrong backend for the job** — `signin`/`callback` only work on `kv-oauth`. If those endpoints return `AUTH_PROVIDER_ERROR`, you are on `workos` or `better-auth`, which validate sessions but do not drive the login redirect. Set `NETSCRIPT_AUTH_BACKEND=kv-oauth` for an interactive flow.
> - **Single active backend** — there is exactly one backend at a time. No multi-active routing, cross-backend account linking, global logout, historical replay, or paged session mirror in v1. Plan your identity model around one provider path.
> - **No auth audit/telemetry surface yet** — there is **no** dedicated auth audit log or auth-specific telemetry API on main. Do not build dashboards against an auth audit stream that does not exist; the `defaultTelemetry` flag is generic OTLP plumbing, not an auth audit trail.
> - **Alpha package pins** — scaffolded `jsr:...` imports use exact `@0.0.1-beta.11` pins. Keep the generated workspace on one aligned NetScript version.
> - **Provider env is required for real login** — without `NETSCRIPT_AUTH_CLIENT_ID`/`SECRET`/`REDIRECT_URI` the `kv-oauth` backend boots into a stub fallback; `session`/`me` answer but no real sign-in is possible.
> - **Aspire down** — a 404 on `:8094` or a DB error during `netscript db` almost always means orchestration is not running. `cd aspire &&
>   aspire start` first.

## See also

[Authentication capability  The auth-api service, the five endpoints, and the three-backend capability matrix in one hub.](https://rickylabs.github.io/netscript/netscript/capabilities/auth/) [The authentication model  Why the backend is a pure adapter behind AuthBackendPort, and how the plugin composes one active backend.](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) [service reference  The @netscript/service builder that auth-api is built on — RPC mount, health, OpenAPI, service info.](https://rickylabs.github.io/netscript/netscript/reference/service/) [Run a database migration  The full db init / generate / seed / status workflow that applies auth.prisma.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/)

_Canonical: https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/_

---

# Observability

The most expensive turn in any change loop — whether the author is you or an AI agent — is the verification turn: *did the change actually work, across every process it touched?* This pillar is how NetScript answers it. The runtimes emit real OpenTelemetry spans, a single W3C `traceparent` groups a cross-process flow into one distributed trace, structured logs ride the same OTLP export, and both a dashboard and a **typed query port** read it all back — for you, or for an agent verifying its own change. Use this pillar when you need to add tracing, inspect runtime behavior, or connect package-level telemetry to the running system.

[Overview & Concepts   Telemetry model  Trace context and logging across services, workers, sagas, and orchestration.](https://rickylabs.github.io/netscript/netscript/explanation/observability/) [Quickstart   Turn on tracing  Run aspire start, trigger a job, and watch the runtime's automatic spans land in the dashboard — the lowest-effort path to a first trace.](https://rickylabs.github.io/netscript/netscript/observability/telemetry/) [How-To   Add OpenTelemetry  Wire OTel into a workspace.](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/) [API Reference   telemetry  Generated telemetry package symbols.](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) [API Reference   logger  Generated logger package symbols.](https://rickylabs.github.io/netscript/netscript/reference/logger/)

## Where to go next

Telemetry in NetScript is built-in, not bolted-on — the fastest route is to see a trace first, then learn the model:

- **Emit and view a trace:** [Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/)

  is the capability hub — automatic worker spans, the `@netscript/telemetry` helpers, browser logs, and the dashboard views, with [Add OpenTelemetry](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/)

  as the task recipe.
- **Understand the model:** [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

  maps what is framework-real versus a scaffold stub, and how trace context propagates across process boundaries.
- **See where telemetry is collected:** [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

  explains the dashboard and OTLP collector the AppHost provisions; trace context crosses service boundaries at the [services](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) seam.
- **Read a trace back in code:** the [Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/)

  hub's *Close the loop* section covers the typed `TelemetryQueryPort` read side — how a test or an agent asserts a span landed instead of eyeballing the dashboard.
- **Look up exact symbols:** [telemetry](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) and

[logger](https://rickylabs.github.io/netscript/netscript/reference/logger/) references, and the [telemetry convention](https://rickylabs.github.io/netscript/reference/telemetry/convention/) (span naming, SpanKind, the `netscript.*` attribute rules).

## Learn, do, look up

[Learn  Trace the request model  Follow one request through services, jobs, and streams in the core-concepts tour.](https://rickylabs.github.io/netscript/netscript/concepts/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/observability/how-to/) [Look up  `@netscript/telemetry` reference  Generated API reference. Related units: `logger`.](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) [Understand  Observability  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

_Canonical: https://rickylabs.github.io/netscript/observability/_

---

# Observability — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/observability/how-to/_

---

# Add OpenTelemetry

**Scope:** turn on, extend, and read distributed traces in an existing NetScript workspace. OpenTelemetry is not a bolt-on here — `@netscript/telemetry` wraps `@opentelemetry/api` and is wired into the services, the worker dispatcher, the scheduler, and the subprocess task runtime the scaffold generates. Aspire stands up the OTLP collector and the trace UI for you. This recipe shows where the instrumentation already lives, how to add your own spans and structured logs, how `traceparent` propagates across the oRPC/HTTP boundary and into job subprocesses, and how to watch it all land in the Aspire dashboard at [https://localhost:18888](https://localhost:18888).

This is a task recipe, not a deep-dive. For the mental model behind spans, structured logs, and the per-capability health endpoints, read [Observability](https://rickylabs.github.io/netscript/explanation/observability/). For the generated API surface, follow the [`telemetry`](https://rickylabs.github.io/netscript/reference/telemetry/) and [`logger`](https://rickylabs.github.io/netscript/reference/logger/) reference pages, and the [Telemetry capability](https://rickylabs.github.io/netscript/capabilities/telemetry/) hub for the Learn / Do / Reference triplet.

> What works today, and the one gap
>
> Worker tracing is built in and real.
>
> Job dispatch, job execution, the scheduler, and the task subprocess all emit real OpenTelemetry spans automatically — they appear in the Aspire dashboard with no code from you.
>
> task.execute
>
> spans are real too. The
>
> only
>
> gap is the scaffold's
>
> createJobTools(ctx)
>
> handler helpers:
>
> trace.addEvent
>
> ,
>
> trace.withChildSpan
>
> , and
>
> trace.recordProgress
>
> are currently
>
> no-op stubs
>
> in the generated
>
> job-tools.ts
>
> (a tracked debt with a fix planned). To emit custom spans from inside a handler today, call the
>
> @netscript/telemetry
>
> instrumentation helpers directly — shown in Step 3. Structured logging via
>
> log.*
>
> is real now.

## Prerequisites

**What this recipe assumes**

| Name | Type | Description |
| --- | --- | --- |
| `netscript workspace` | `netscript init` | An existing workspace. If you have none, scaffold one first — see the tutorials. |
| `Start Aspire` | `cd aspire && aspire start` | The AppHost provisions Postgres, Redis, the OTLP collector, and the dashboard. Start it BEFORE you expect traces. Dashboard at https://localhost:18888. |
| `@netscript/telemetry` | `OTel facade` | Wraps @opentelemetry/api and ships the worker/scheduler/queue/SSE instrumentation. Already wired into the generated handlers — no install step. |
| `A service or plugin to trace` | `services/users or plugins/workers` | The users service (:3001) and the workers/sagas/triggers/auth plugins all emit health + trace data once running. |

> Aspire first, always
>
> The OTLP endpoint and the trace UI are
>
> Aspire resources
>
> . Aspire is step 2 of the workflow:
>
> cd aspire && aspire start
>
> brings up Postgres, Redis, the collector, and the dashboard
>
> before
>
> any
>
> netscript db
>
> command or service. If
>
> aspire start
>
> is not up, there is nowhere for spans to go and nothing to view. Start orchestration from the
>
> aspire/
>
> folder before you run a service, trigger a job, or open the dashboard.

## How the telemetry is already wired

Three layers ship instrumented out of the box. Knowing which is which tells you where you get spans for free and where you add your own.

**Where instrumentation lives**

| Name | Type | Description |
| --- | --- | --- |
| `Service layer (real spans)` | `@netscript/service` | RPC trace context (header extraction into ctx.traceHeaders) is ON by default — traceContext defaults to true when withRPC() is called without arguments. The OTel TracingPlugin that creates real spans is also always active; it is independent of the traceContext option. |
| `Worker runtime (real spans)` | `job dispatcher + scheduler` | Job dispatch and execution, scheduler runs, and the task subprocess emit real OTel spans automatically via @netscript/telemetry — traceJobExecution, scheduler spans, task.execute. Traces show up in Aspire with no handler code. |
| `Scaffold job tools (stub spans today)` | `createJobTools(ctx)` | log / progress / trace handed to defineJobHandler bodies. log.* is REAL; trace.addEvent / withChildSpan / recordProgress are no-op stubs in the scaffold (tracked debt, fix planned). For custom handler spans, call @netscript/telemetry helpers directly. |
| `OTLP export + UI` | `http://localhost:4318 → :18888` | The Aspire profile points OTLP at http://localhost:4318; the dashboard renders the collected traces and correlated structured logs at :18888. |

> Two senses of "worker tracing"
>
> The framework/dispatcher layer emits real spans —
>
> traceJobExecution
>
> , scheduler spans, and subprocess
>
> traceparent
>
> propagation are all live, so you get job traces in Aspire automatically. The
>
> scaffold-facing
>
> createJobTools(ctx)
>
> helpers your handler calls are the only stubs. Never read "the job-tools helpers are stubs" as "worker tracing is a no-op" — the runtime around your handler is fully instrumented.

## Step 1 — Bring up Aspire and confirm the collector

From the workspace root, start orchestration. The AppHost registers the OTLP collector and the dashboard, then boots Postgres, Redis, and every service/plugin resource.

```bash
cd aspire
aspire start
# dashboard: https://localhost:18888  (login token printed in the console)
```

Open [https://localhost:18888](https://localhost:18888), authenticate with the token Aspire printed, and select the **Traces** tab. With nothing exercised yet it is empty — that is expected. Leave it open; it updates live.

> Resources you should see
>
> The Aspire resource graph lists
>
> postgres
>
> ,
>
> redis
>
> ,
>
> workers-api
>
> (
>
> :8091
>
> ),
>
> workers
>
> ,
>
> sagas-api
>
> (
>
> :8092
>
> ),
>
> sagas
>
> ,
>
> triggers-api
>
> (
>
> :8093
>
> ),
>
> triggers
>
> , the
>
> auth-api
>
> (
>
> :8094
>
> ), and the durable-streams service (
>
> :4437
>
> ). Each resource exports telemetry to the OTLP endpoint at
>
> http://localhost:4318
>
> ; the dashboard reads from there.

## Step 2 — Generate a trace without writing any code

Both service-layer and worker-runtime tracing are real and need no code from you. Exercise a running surface and a trace appears.

> ns-workers is a shorthand you install once
>
> ns-workers
>
> is a name
>
> you
>
> give the workers plugin's CLI — the scaffold does not create it. Install it once, globally, and every
>
> ns-workers
>
> command on this page works as written:
>
> ```bash
> deno install -gArf -n ns-workers jsr:@netscript/plugin-workers@0.0.1-beta.11/cli
> ```
>
> Rather not install it? Each
>
> ns-workers <verb …>
>
> is exactly
>
> deno x -A jsr:@netscript/plugin-workers@0.0.1-beta.11/cli <verb …>
>
> — run that full form instead.

```bash
# Workers API on :8091 — enqueue the sample health-check job by id.
# Dispatch + execution + scheduler spans are emitted automatically.
ns-workers trigger workers-plugin-health-check

# then list recent executions
ns-workers executions --limit=10 --json
```

```bash
# Users oRPC service on :3001 — the request is traced at the service layer.
# oRPC services are served under /api/rpc/* (not /rpc).
curl -s -X POST http://localhost:3001/api/v1/users/list \
  -H 'content-type: application/json' \
  -d '{}'
```

```bash
# Triggers API on :8093 (raw Hono routes, not oRPC) — resolves the inbound
# trigger, whose enqueueJob action enqueues the workers health-check job,
# producing a connected dispatch + execution trace.
curl -s -X POST http://localhost:8093/api/v1/webhooks/inbound/generic \
  -H 'content-type: application/json' \
  -d '{}'
```

Refresh the **Traces** tab in the dashboard. You will see a trace for the request, with the service or worker resource as the root span. Click it to expand the span tree, attributes, and the structured logs correlated to that trace. A webhook that enqueues a job shows the inbound request span and the resulting job-dispatch and job-execution spans — the dispatcher propagates `traceparent` into the worker subprocess, so they share one trace.

> Where the real job spans come from
>
> The worker dispatcher wraps each run in
>
> traceJobExecution
>
> and emits
>
> job.started
>
> /
>
> job.completed
>
> /
>
> job.failed
>
> events, a duration, and a status; the scheduler emits its own start and per-run spans; the multi-runtime task executor emits
>
> task.execute
>
> spans. All of that is automatic — you are seeing real instrumentation from
>
> @netscript/telemetry
>
> , not the scaffold helpers.

## Step 3 — Add your own spans in a job handler (the real way today)

The scaffold hands you `createJobTools(ctx)` so you can author against `log`, `progress`, and `trace`. `log.*` is real today. The `trace.*` helpers are **no-op stubs in the scaffold** — if you want a real custom span around a unit of work right now, call the `@netscript/telemetry` instrumentation helpers directly. Keep the `trace.*` calls if you like authoring against the forward-compatible shape, but do not rely on them for live spans yet.

```ts
import {
  createFailureResult,
  createSuccessResult,
  defineJobHandler,
} from '@netscript/plugin-workers-core';
// Call the instrumentation helpers directly for a REAL child span today.
import {
  recordJobProgress,
  withChildSpan,
} from '@netscript/telemetry/instrumentation';
import { createJobTools } from './job-tools.ts';

const handler = defineJobHandler(async (ctx) => {
  const { log } = createJobTools(ctx); // log.* is real today
  log.info('Starting workers plugin health check');

  // withChildSpan opens a real span as a child of the active job span
  // and gives you a handle to attach queryable attributes.
  const envOk = await withChildSpan('check.environment', async (span) => {
    span.setAttribute('check.name', 'environment');
    return Boolean(Deno.env.get('PORT'));
  });

  if (!envOk) return createFailureResult('environment check failed');

  // Emit a real job.progress event (current / total / percentage).
  recordJobProgress(1, 1);
  return createSuccessResult({ status: 'healthy' });
});

export default Object.assign(handler, {
  id: 'workers-plugin-health-check' as const,
});
```

```ts
import { defineJobHandler } from '@netscript/plugin-workers-core';
import { createJobTools } from './job-tools.ts';

// createJobTools(ctx) returns:
//   log          -> console.* wrappers: info/warn/error/debug (plain stdout today, NOT trace-correlated)
//   progress     -> progress(percent, message) (forwards to ctx.reportProgress)
//   trace        -> { addEvent, recordProgress, withChildSpan } (STUB spans today)
//   traceContext -> { traceparent, tracestate } for manual propagation
//
// Authoring against trace.* is fine — your code is ready for when the
// scaffold helpers are upgraded — but these calls emit NO real spans today.
// Prefer @netscript/telemetry helpers (other tab) for spans you need now.
const handler = defineJobHandler(async (ctx) => {
  const { log, trace, traceContext } = createJobTools(ctx);
  log.info('health check', { traceparent: traceContext.traceparent });
  trace.addEvent('health_check.started'); // no-op in the scaffold today
  return { ok: true } as const;
});

export default handler;
```

```ts
// @netscript/telemetry/instrumentation — the real worker helpers:
//   traceJobExecution(...)  wrap a whole job run in a span (dispatcher uses this)
//   withChildSpan(name, fn) open a child span under the active context
//   addJobStepEvent(...)    emit a job.step.* event
//   recordJobProgress(c, t) emit a job.progress event (current / total / %)
//   runTracedJob(...)       run a job body inside subprocess trace context
//   startWorkerSpan(...)    worker lifecycle span
//
// Companion subpaths:
//   @netscript/telemetry/context     active trace context + traceparent helpers
//   @netscript/telemetry/attributes  canonical OTel attribute keys
//   @netscript/telemetry/orpc        oRPC client/server trace interceptors
// Authoritative export map: /reference/telemetry/
```

> Where the scaffold log.* helpers actually go
>
> log.info
>
> /
>
> log.warn
>
> /
>
> log.error
>
> in the scaffold's
>
> createJobTools(ctx)
>
> forward to
>
> console.*
>
> — they appear in process stdout (surfaced in the Aspire dashboard's
>
> Console logs
>
> view per resource),
>
> not
>
> as OTel-correlated structured log records tied to the active trace. For trace-correlated structured logging from a handler, use
>
> @netscript/logger
>
> directly. Use real spans (the
>
> withChildSpan
>
> helper) when you want queryable attributes and durations on a unit of work.

## Step 4 — Extend service tracing and propagate `traceparent`

The services keep trace context across the oRPC/HTTP boundary. The workers service builds its app with the fluent builder and opts the RPC layer into trace context explicitly:

```ts
import { createService } from '@netscript/service';
import { router } from './router.ts';

// The plugin API services use the fluent builder. withRPC({ traceContext: true })
// threads the incoming traceparent through to handlers. oRPC is served under
// /api/rpc/* by default.
await createService(router, { name: 'workers', version: '1.0.0', port: 8091 })
  .withCors()
  .withLogger()
  .withOpenAPI({ title: 'Workers API' })
  .withDatabase(dbClient)
  .withRPC({ traceContext: true })
  .withHealth()
  .serve();
```

```ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';

// Local services use the one-call form. Tracing is enabled by the framework;
// debug: true surfaces verbose request/trace logs while you wire things up.
await defineService(router, {
  name: 'users',
  version: '1.0.0',
  port: parseInt(Deno.env.get('PORT') || '3001'),
  openapi: { title: 'Users API', description: 'users service' },
  debug: true,
});
```

```bash
# When one service calls another over HTTP, forward the W3C traceparent
# header so both spans land in ONE trace in the dashboard.
curl -s http://localhost:3001/api/v1/users/list \
  -X POST -H 'content-type: application/json' \
  -H 'traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01' \
  -d '{}'
```

Aspire injects `PORT` at runtime, so the entrypoint reads it from the environment; the typed source of truth is your `netscript.config.ts` `services.<name>.port` field, which the scaffold wires as the fallback default — set the port there rather than editing this line.

> traceparent is the join key
>
> NetScript follows the W3C Trace Context standard. When an inbound request carries a
>
> traceparent
>
> header, the service continues that trace instead of starting a new one — and the worker dispatcher propagates
>
> traceparent
>
> /
>
> tracestate
>
> into the job subprocess. So a webhook on
>
> :8093
>
> that enqueues a job and the worker subprocess that runs it appear as a
>
> single correlated trace
>
> , live, today. Always forward
>
> traceparent
>
> on service-to-service calls.

## Step 5 — Read the traces

Back in the dashboard at [https://localhost:18888](https://localhost:18888):

1. **Traces** — every request and job as a waterfall of spans. Click a root span to drill into children, durations, and attributes (the ones you set via `span.setAttribute(...)`). Job runs show `job.started` / `job.completed` events and, where you added them, `job.progress` and `job.step.*` events.
2. **Structured logs** — filter by resource (e.g. `workers-api`) or by trace id to see the `log.info`/`log.error` lines correlated to a span.
3. **Resources** — health and console output per resource; cross-reference a failing span with the resource that produced it.

Confirm liveness independently of the UI by hitting the per-capability health endpoints:

```bash
curl -s http://localhost:8091/health        # workers
curl -s http://localhost:8092/health/live   # sagas
curl -s http://localhost:8093/health        # triggers
curl -s http://localhost:8094/health        # auth
```

## Production pitfalls

> Custom handler spans: use the helpers, not the stubs
>
> The scaffold
>
> createJobTools(ctx)
>
> trace.addEvent
>
> ,
>
> trace.withChildSpan
>
> , and
>
> trace.recordProgress
>
> are
>
> no-op stubs
>
> today (tracked debt, fix planned). The dispatcher, scheduler, and task subprocess spans around your handler are real and need nothing from you — but for a
>
> custom
>
> span inside the handler, call
>
> @netscript/telemetry/instrumentation
>
> helpers (
>
> withChildSpan
>
> ,
>
> recordJobProgress
>
> ,
>
> addJobStepEvent
>
> ) directly so the span actually emits.

> No collector, no traces
>
> Spans are only collected while Aspire is running and the OTLP endpoint (
>
> http://localhost:4318
>
> ) is reachable. Running a service standalone with
>
> --no-aspire
>
> means tracing has nowhere to export to. If the Traces tab is empty, check that
>
> aspire start
>
> is up first — Aspire provisions the collector and dashboard used by the examples.

> Set attributes, not log lines, for span data
>
> Data you want to filter or aggregate on (ids, counts, statuses) belongs on the span via
>
> span.setAttribute(...)
>
> , not buried in a log string. Attributes are queryable in the dashboard; freeform log text is not. Reserve
>
> log.*
>
> for human-readable narrative and errors.

## See also

[Telemetry capability  The OTel-in-handlers capability hub — headline API, ports, and the Learn / Do / Reference triplet.](https://rickylabs.github.io/netscript/netscript/capabilities/telemetry/)

[Observability (explanation)  The mental model: spans, structured logs, health endpoints, and how Aspire renders distributed traces across services and jobs.](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

[telemetry reference  The generated @netscript/telemetry API surface — the full, authoritative export map (instrumentation, context, attributes, orpc).](https://rickylabs.github.io/netscript/netscript/reference/telemetry/)

[logger reference  The structured logger used by log.info / log.warn / log.error inside handlers and jobs.](https://rickylabs.github.io/netscript/netscript/reference/logger/)

_Canonical: https://rickylabs.github.io/netscript/observability/how-to/add-opentelemetry/_

---

# Telemetry & logging

The most expensive turn in any change loop — whether the author is you or an AI agent — is the verification turn: *did the change actually work, across every process it touched?* NetScript closes that loop inside the framework. The runtimes emit real OpenTelemetry spans on their own, a single W3C `traceparent` groups a cross-process flow into **one distributed trace**, and a typed query surface reads the resulting spans back — so "did it work" is a trace you open (or query programmatically), not four console logs you correlate by eye.

Concretely, observability is a built-in, not a bolt-on. Every service and plugin runtime is wired for **OpenTelemetry** — services serve their RPC handlers with trace-context propagation (first-party oRPC and Hono instrumentation), the worker runtime wraps job dispatch, execution, scheduling, subprocess hand-off, and task execution in real OTel spans, and structured logs flow through the framework `logger`. The viewing surface is the **Aspire dashboard at `https://localhost:18888`**, which collects OTLP traces, metrics, and structured logs from every resource in the app graph (services, plugin APIs, background processors) the moment you run `aspire start`. You do not stand up Jaeger, Grafana, or a log shipper to get started — the AppHost provisions the OTLP collector and the dashboard for you.

![A W3C traceparent header propagates from a service request through the worker runtime into a subprocess and across a saga boundary, keeping every span under one trace id.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/otel-traceparent.svg)

*Trace-context propagation: a single traceparent (W3C) flows service → worker → subprocess → saga, so spans from every runtime join one distributed trace in Aspire.*

This page is the capability hub: what telemetry exists, how to emit it, where to view it, and the one place that is still a scaffold stub. For the full generated API of each unit, follow the reference links: the telemetry primitives live at [`/reference/telemetry/`](https://rickylabs.github.io/netscript/reference/telemetry/) and the structured logger at [`/reference/logger/`](https://rickylabs.github.io/netscript/reference/logger/).

> Aspire first, then telemetry
>
> The dashboard, the OTLP collector, and the per-resource trace/log views all come up with the orchestrator — they are not separate processes you start by hand. Run
>
> cd aspire && aspire start
>
> before
>
> any
>
> netscript db
>
> command (Aspire provisions Postgres and Redis first), then open the dashboard URL printed in the console (
>
> https://localhost:18888
>
> , with a one-time auth token). Until Aspire is running there is no
>
> :18888
>
> surface to view traces or logs on. See
>
> Database & migration
>
> for the full startup order.

## The story: one grouped trace, end to end

Picture the failure mode that eats an afternoon. A trigger fires, the scheduler dispatches, a queue hands the job to a worker, the job reports success — and the downstream callback never lands. With per-process logs you tail one console per resource and correlate timestamps by eye; an AI agent in the same position burns its turns asking you to check logs it cannot see.

In NetScript that whole flow is **one grouped trace**: trigger → scheduler dispatch → queue enqueue/dequeue → `job.execute` → the SDK's `rpc.client` callback span, all under a single trace id, because the runtimes propagate W3C trace context across every process boundary for you. Where many producers feed one consumer — a fan-in into a durable-streams processor — `createFanInLinks` attaches **span links** from each producer trace instead of re-parenting, so the consumer span shows exactly which upstream flows fed it. And this shape is not aspirational: the grouped cross-process trace is exercised by a non-mocked merge gate in the framework's own CI, which scaffolds a real project, runs the flow under Aspire, and reads the live spans back before a change can land.

The same spine covers AI workloads. Spans follow the upstream `gen_ai.*` semantic conventions (via `createGenAiAttributes` in `@netscript/telemetry/attributes`), so a traced agent turn shows the model call, the tool calls, and the durable write it produced — step by step, on one tree.

## What it is

Telemetry in NetScript is three OpenTelemetry signals — **traces**, **metrics**, and **logs** — wired through one package, `@netscript/telemetry`, and one viewing surface, the Aspire dashboard. Traces are the headline: a request enters a service, the worker runtime dispatches and executes a job, a subprocess runs a polyglot task, and a saga advances — and because a single **W3C `traceparent`** header propagates across every one of those process boundaries, the whole fan-out collapses into one trace tree. Metrics (worker counts, SSE connection stats) and structured logs ride the same OTLP export. The framework owns transport (OTLP/HTTP to the collector) and viewing (the dashboard); it now owns most of emission too — the worker, scheduler, queue, saga, and SSE runtimes are instrumented for you. The full mental model — what is framework-real versus a scaffold stub — is in [Observability](https://rickylabs.github.io/netscript/explanation/observability/).

Under the hood, `@netscript/telemetry` is structured as **telemetry ports and adapters**: application and runtime code programs against port contracts (`TracerProviderPort`, `MeterPort`, `PropagatorPort`, `SpanLinkPort`, `TelemetryQueryPort` — the `@netscript/telemetry/otel` subpath), with a zero-dependency default adapter (`OtelDenoTracerProvider`, bound to Deno's built-in OTLP exporter via `OTEL_DENO=true`) and an opt-in OpenTelemetry-SDK adapter (`OtelSdkTracerProvider`) for apps that bring the JS SDK — which also unlocks attribute-preserving span links. Attribute names follow one convention: upstream semconv keys (`rpc.*`, `messaging.*`, `gen_ai.*`, `server.*`) wherever OpenTelemetry defines them, and NetScript-owned keys under the single proprietary root `netscript.*` — correlated spans share `netscript.correlation.id`. The full rule set (span naming, SpanKind, status, propagation) is the [telemetry convention](https://rickylabs.github.io/netscript/reference/telemetry/convention/).

## Learn → / Do →

[Do — Add OpenTelemetry  Task-oriented recipe: lean on the automatic job spans, add custom spans via @netscript/telemetry withChildSpan, propagate traceparent across services and subprocesses, and point the OTLP export (:4318) at the dashboard.](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/)

[Understand — Observability  The mental model: how spans, structured logs, health endpoints, and Aspire traces fit together — and the precise framework-vs-scaffold map of what is real (traceJobExecution, task.execute) versus the tracked createJobTools(ctx) stub.](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

[Look up — telemetry reference  The full generated deno doc API for @netscript/telemetry — tracer facade, context/traceparent helpers, the NetScript instrumentation helpers, and the oRPC tracing plugin.](https://rickylabs.github.io/netscript/netscript/reference/telemetry/)

## What you get out of the box

Telemetry in NetScript spans three layers — emission (in framework runtimes and your handler code), transport (OTLP over HTTP to the collector), and viewing (the Aspire dashboard). The framework owns transport and viewing, and it now owns most of emission too: the worker runtime traces the entire job lifecycle automatically. The only thing you still wire by hand is custom spans *inside* a job handler — and even there the `@netscript/telemetry` helpers do the work.

Structured logging

The @netscript/logger unit gives every service and plugin a level-aware, structured logger. Config is declared in netscript.config.ts (logging: { level: 'info', format: 'text' }) and threaded through the runtime — text or JSON, filterable in the dashboard.

OpenTelemetry traces (real)

Service request paths propagate W3C trace context, and the worker runtime emits real spans for job dispatch, execution, scheduling, subprocess hand-off, and task.execute. @opentelemetry/api (^1.9) is in the catalog and wired into the request and job paths so spans flow to the collector.

OTLP → Aspire dashboard

The generated AppHost configures an OTLP endpoint (http://localhost:4318) and the Aspire dashboard (https://localhost:18888) so traces, metrics, and logs from every resource land in one place — no collector to deploy.

Browser console logs (default)

Generated app resources call withBrowserLogs() automatically (the AppHost pins Aspire.Hosting.Browsers), so a Fresh/Vite app's browser console output — including a client-side error an island throws — is forwarded into the dashboard next to server logs and traces. No opt-in, nothing to wire.

Per-resource health

Each plugin API exposes a liveness probe — workers :8091 GET /health, sagas :8092 GET /health/live, triggers :8093 GET /health, auth :8094 — surfaced as resource state in the dashboard.

> Browser logs land in the dashboard too
>
> Because generated app resources emit
>
> withBrowserLogs()
>
> by default, the class of failure that is otherwise invisible from the server — a client-side
>
> TypeError
>
> a durable-streams island throws in the browser, say — shows up in the Aspire dashboard's
>
> Console logs
>
> for that app resource, correlated with the server-side spans of the same request. You do not start a separate browser-log collector; the AppHost wires it when it scaffolds the app.

## Enable tracing & see a span

Tracing turns on from the **environment** — `@netscript/telemetry/config` resolves a `TelemetryConfig` from the standard `OTEL_*` variables, and the Aspire AppHost already sets them for you. The fastest path is to run `aspire start`, trigger any job, and the runtime's automatic spans show up in the dashboard with no code change. The tab below adds a **custom** span on top of that automatic trace.

> Local vs deployed: same instrumentation, different collector
>
> Locally
>
> , Aspire provisions the OTLP collector and the dashboard and injects the
>
> OTEL_*
>
> variables into every resource, so telemetry works the moment you run
>
> aspire start
>
> — nothing to configure. Note the dashboard and OTLP endpoints bind to
>
> ephemeral ports
>
> (the generated profile uses
>
> localhost:0
>
> ), so use the URL
>
> aspire start
>
> prints rather than assuming
>
> :18888
>
> /
>
> :4318
>
> . Running
>
> aspire start --isolated
>
> (an upstream Aspire CLI flag) also randomizes the dashboard, OTLP, and resource-service ports and isolates secrets, so several apphosts can boot in parallel without colliding.
>
> Deployed
>
> , there is no Aspire and no dashboard: you point
>
> OTEL_EXPORTER_OTLP_ENDPOINT
>
> at your own collector or a hosted backend (Grafana Tempo, Honeycomb, Jaeger, …). The instrumentation code is identical — only the endpoint/protocol env and the sampler change. That single OTLP seam is the whole porting story; see
>
> Production notes
>
> below.

```ts
// netscript.config.ts — declare the structured-logging contract for the workspace.
// Tracing itself is enabled by OTEL_* env vars (the Aspire AppHost sets these); the
// config package reads them — there is no defineTelemetry() call to make.
import { defineConfig } from '@netscript/config';

export default defineConfig({
  name: 'my-app',
  version: '1.0.0',
  logging: { level: 'info', format: 'text' }, // level: debug|info|warn|error
  plugins: ['./plugins/workers/mod.ts'],
});

// Anywhere in app code you can inspect what telemetry resolved (log-safe, redacted):
import { describeTelemetryConfig, isTelemetryEnabled } from '@netscript/telemetry/config';
if (isTelemetryEnabled()) console.log(describeTelemetryConfig());
// → { enabled: true, endpoint: 'http://localhost:4318', protocol, serviceName, sampler }
```

```ts
// plugins/workers/jobs/health-check.ts — a real child span inside a handler.
// The dispatcher already wraps this job in traceJobExecution automatically;
// withChildSpan opens a child span under that parent. recordJobProgress's 3rd arg
// is a UNIT label (e.g. 'steps'), not a free-text message.
import { createSuccessResult, defineJobHandler } from '@netscript/plugin-workers-core';
import { withChildSpan, recordJobProgress } from '@netscript/telemetry/instrumentation';

const handler = defineJobHandler(async (ctx) => {
  recordJobProgress(1, 2, 'steps'); // → job.progress event on the trace

  const envCheck = await withChildSpan('check.environment', async (span) => {
    span.setAttribute('check.name', 'environment');
    return { ok: true };
  });

  recordJobProgress(2, 2, 'steps');
  return createSuccessResult({ healthy: envCheck.ok });
});

export default Object.assign(handler, { id: 'workers-plugin-health-check' as const });
```

> Lowest-effort observability path
>
> Run
>
> aspire start
>
> , trigger a job, and open
>
> :18888
>
> →
>
> Traces
>
> . You will see the dispatch span, the execution span, progress and step events, and — for subprocess or polyglot tasks — a continued trace across the process boundary. None of that requires editing the scaffold. Reach for custom instrumentation only when you want spans
>
> inside your own handler logic
>
> .

## Key types: the telemetry init/config surface

Configuration is **read from the environment**, not constructed — `@netscript/telemetry/config` resolves and caches a `TelemetryConfig` from the `OTEL_*` variables. These are the confirmed fields and the helpers that read them.

**TelemetryConfig (@netscript/telemetry/config — resolved from OTEL_* env vars)**

| Name | Type | Description |
| --- | --- | --- |
| `enabled` | `boolean` | Whether OpenTelemetry instrumentation is active (driven by OTEL_DENO / endpoint presence). Mirror it with isTelemetryEnabled(). |
| `endpoint` | `string \| undefined` | OTLP exporter endpoint URL (e.g. http://localhost:4318). Read directly via getOtlpEndpoint(). |
| `protocol` | `string` | OTLP exporter protocol (e.g. http/protobuf), from OTEL_EXPORTER_OTLP_PROTOCOL. |
| `serviceName` | `string` | Service name reported to backends, from OTEL_SERVICE_NAME (or the default). Read via getServiceName(). |
| `serviceVersion` | `string` | Service version reported to backends. |
| `resourceAttributes` | `Record` | Resource attributes parsed from OTEL_RESOURCE_ATTRIBUTES. |
| `sampler` | `string` | Trace sampler name, from OTEL_TRACES_SAMPLER (e.g. parentbased_always_on, traceidratio). |
| `debug` | `boolean` | Whether debug-level telemetry logging is on (OTEL_LOG_LEVEL). |

**Config helpers (@netscript/telemetry/config)**

| Name | Type | Description |
| --- | --- | --- |
| `getTelemetryConfig()` | `→ TelemetryConfig` | Resolve telemetry config from the OTEL_* environment variables. |
| `getConfig()` | `→ TelemetryConfig` | Return the process-cached config (resetConfig() clears the cache, mainly for tests). |
| `isTelemetryEnabled()` | `→ boolean` | Whether instrumentation is enabled for this process. |
| `getOtlpEndpoint()` | `→ string \| undefined` | The configured OTLP endpoint, when present. |
| `getServiceName()` | `→ string` | The configured service name, or the default. |
| `describeTelemetryConfig()` | `→ TelemetryConfigDescription` | A redacted, log-safe summary of the resolved config — safe to print in diagnostics. |
| `OTEL_ENV_VARS` | `const record` | The OTEL_* variable NAMES NetScript reads: OTEL_DENO, OTEL_EXPORTER_OTLP_ENDPOINT/_PROTOCOL, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES, OTEL_TRACES_SAMPLER, OTEL_LOG_LEVEL, the BSP/BLRP schedule delays, and OTEL_METRIC_EXPORT_INTERVAL. |

## Span & instrumentation helpers

Two subpaths cover hand-written instrumentation. `@netscript/telemetry/tracer` is the low-level facade over `@opentelemetry/api` — get a tracer, open a span, run a callback inside one. `@netscript/telemetry/instrumentation` is the NetScript-domain layer the runtimes themselves use — job, scheduler, queue, and SSE spans with the right attributes baked in. The `/context` subpath holds the **`traceparent`** propagation helpers that make the cross-boundary trace in the diagram above possible.

**Tracer facade (@netscript/telemetry/tracer)**

| Name | Type | Description |
| --- | --- | --- |
| `getTracer(name, version)` | `→ Tracer` | Cached tracer for an instrumentation name/version. Domain shortcuts exist: getJobTracer/getQueueTracer/getWorkerTracer/getSchedulerTracer/getSagaTracer/getSSETracer/getKVTracer. |
| `withSpan(tracer, name, fn, options)` | `→ Promise` | Run an async callback inside a span and close it on completion. withSpanSync is the synchronous form. |
| `createSpan(tracer, name, options)` | `→ Span` | Create a span from a tracer + CreateSpanOptions (kind, attributes, parentContext, links). You end() it yourself. |
| `setSpanAttributes / setSpanError / setSpanOk` | `(span, …) → void` | Bulk-set attributes, mark a span failed (with an optional Error), or mark it OK. addSpanEvent(span, name, attrs?) adds an event. |
| `getActiveSpan() / getActiveContext()` | `→ Span? / Context` | Read the span / OTel context active on the current async path. isTracingEnabled() gates work. |
| `SpanKind / SpanStatusCode / TracerNames` | `const` | Span-kind (INTERNAL/SERVER/CLIENT/PRODUCER/CONSUMER), status (UNSET/OK/ERROR), and the standard domain tracer-name strings. |

**NetScript instrumentation helpers (@netscript/telemetry/instrumentation)**

| Name | Type | Description |
| --- | --- | --- |
| `traceJobExecution(options, fn)` | `→ Promise` | Wrap a job run in a span with job.started/completed/failed events. Emitted automatically by the dispatcher; the supported entry point for tracing a job by hand. |
| `withChildSpan(name, fn, attributes?)` | `→ Promise` | Open a child span under the active span and run fn inside it. The go-to for custom spans in a handler. |
| `recordJobProgress(current, total, unit)` | `→ void` | Emit a job.progress event. The 3rd arg is a UNIT label (e.g. 'steps'), NOT a description. addJobStepEvent(stepName, attrs?) records job.step.* events. |
| `startJobDispatchSpan / traceJobDispatch` | `span / → Promise` | Open the dispatch span and return PropagationHeaders to carry traceparent to the executor. createJobSubprocessEnv injects traceparent/tracestate into a subprocess env. |
| `scheduler & cron spans` | `span / event` | createSchedulerStartSpan, createScheduleJobSpan, startSchedulerTickSpan, traceSchedulerTick, recordCronJobRun — cron/schedule dispatch traced end to end. |
| `traceQueue(queue, options) / TracedQueue` | `→ TracedQueue` | Wrap a MessageQueue so enqueue/consume carry trace context. SSE helpers (startSSEConnection, createSSEEventSpan, traceSSEEvent) trace Server-Sent-Event streams. |

**Traceparent / context propagation (@netscript/telemetry/context)**

| Name | Type | Description |
| --- | --- | --- |
| `formatTraceparent(spanContext)` | `→ string` | Serialize a span context to a W3C traceparent header value. parseTraceparent(value) parses one back to a ParsedTraceparent \| null. |
| `injectContext(headers, ctx?) / extractContext(headers)` | `→ headers / → Context` | Inject the active trace context into outbound PropagationHeaders, or extract a remote one from inbound headers — the core of cross-service propagation. |
| `withContext(ctx, fn) / withContextAsync(ctx, fn)` | `→ T / → Promise` | Run a callback with a given OTel context active so spans created inside attach to the right parent. |
| `createMessageHeaders / resolveParentContextFromHeaders` | `→ headers / → Context` | Build propagation headers for a queue message, and resolve the parent context back out on the consumer side. |
| `getTraceId(ctx?) / getSpanId(ctx?)` | `→ string?` | Read the current trace/span ids — handy for correlating structured log lines with a trace. |

## Service, RPC & HTTP tracing

Services opt into trace propagation through **first-party instrumentation** rather than by hand — NetScript wraps the upstream OTel packages instead of reinventing them. The `@netscript/telemetry/orpc` subpath ships an oRPC **tracing plugin** (backed by the upstream `@orpc/otel` instrumentation) that opens a SERVER span per RPC and continues any inbound `traceparent`, plus an error-handling plugin that classifies failures. The `@netscript/telemetry/hono` subpath does the same for plain HTTP: `createHonoTracingMiddleware` wraps Hono's first-party `@hono/otel` middleware and layers NetScript service naming and W3C propagation on top — the service builder registers it outermost for you. On the service builder the RPC side is the `.withRPC({ traceContext: true })` toggle (see [Services](https://rickylabs.github.io/netscript/services-sdk/services/)); the factories below are the underlying surface if you mount oRPC or Hono yourself.

**oRPC + Hono tracing surface (@netscript/telemetry/orpc, @netscript/telemetry/hono)**

| Name | Type | Description |
| --- | --- | --- |
| `createTracingPlugin(options?)` | `→ TracingPlugin` | oRPC plugin that opens a SERVER span per call and continues an inbound traceparent, following upstream rpc.* semconv. Options are TracingPluginOptions. |
| `registerORPCInstrumentation(config?)` | `→ void` | Registers the upstream @orpc/otel ORPCInstrumentation the tracing plugin is backed by — wrap-don't-reinvent, applied to oRPC. |
| `createErrorHandlingPlugin(options?)` | `→ ErrorHandlingPlugin` | Classifies errors as client \| server \| transient and records them on the span; takes an optional ErrorClassifier and ErrorLogger. |
| `createTraceContext()` | `→ TraceContext` | Build the per-call trace context the plugin threads through. addEvent / setAttributes / getTraceId / getSpanId operate on the active span. |
| `createHonoTracingMiddleware(options)` | `→ HonoTracingMiddleware` | Hono middleware wrapping @hono/otel's httpInstrumentationMiddleware with NetScript service naming + W3C propagation. app.use('*', createHonoTracingMiddleware({ serviceName: 'users' })). |

> Database & worker tracing toggles live next door
>
> The Prisma query-tracing and worker-runtime tracing toggles are documented on their own hubs to avoid duplication. Database query spans are wired through the
>
> database
>
> client; the worker runtime's automatic job spans are described in
>
> background jobs
>
> . This hub owns the
>
> cross-cutting
>
> telemetry surface — config, the tracer facade, traceparent propagation, and the oRPC plugin — that those runtimes build on. See
>
> [Database & Prisma](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) for the per-query toggle.

## What is traced automatically

Before you write a single instrumentation call, the worker runtime already produces a usable trace tree in Aspire. The `@netscript/telemetry` instrumentation is wired into the dispatcher, the executor, and the scheduler, so the moment a job runs you get spans with attributes, durations, status, and lifecycle events — no scaffold changes required.

**Automatic worker traces (emitted by the runtime — see /reference/telemetry/)**

| Name | Type | Description |
| --- | --- | --- |
| `traceJobExecution` | `span` | Wraps each job's execution with attributes, duration, status, and job.started / job.completed / job.failed / job.exception events. Emitted by the dispatcher. |
| `recordJobProgress` | `event` | job.progress events carrying current / total / unit — the runtime records real progress as the job advances. |
| `addJobStepEvent` | `event` | job.step.* events for each step the runtime walks through. |
| `scheduler spans` | `span` | createSchedulerStartSpan / createScheduleJobSpan / startSchedulerTickSpan / recordCronJobRun — cron and schedule dispatch are traced end to end. |
| `subprocess traceparent` | `context` | The dispatcher injects W3C traceparent / tracestate into the subprocess env so out-of-process job runs continue the same trace (initJobTracing / runTracedJob / createJobSubprocessEnv). |
| `task.execute` | `span` | The multi-runtime task executor wraps each task run in a task.execute span — polyglot and TS tasks alike show up in the trace tree. |

## Instrument a handler

The two tabs below show the two emission paths a developer touches: structured logging through the framework logger, and **custom** spans inside a job handler. For custom spans, call the `@netscript/telemetry` helpers (`traceJobExecution`, `withChildSpan`, `recordJobProgress`) directly — they are the real, supported surface. Read the callout under the tabs to understand why you reach for the telemetry package rather than the scaffold's `createJobTools(ctx)` trace helpers.

```ts
// netscript.config.ts — declare the logging contract for the whole workspace.
import { defineConfig } from '@netscript/config';

export default defineConfig({
  name: 'my-app',
  version: '1.0.0',
  // level: 'debug' | 'info' | 'warn' | 'error'; format: 'text' | 'json'
  logging: { level: 'info', format: 'text' },
  plugins: ['./plugins/workers/mod.ts', './plugins/sagas/mod.ts'],
});

// Inside a job handler, the logger comes from the job tools (console-backed today,
// and surfaced under the resource's Console logs view in the Aspire dashboard).
// import { createJobTools } from './job-tools.ts';
const emit = (log) => {
  log.info('user provisioned', { userId: 'u_123', source: 'scaffold' });
  log.warn('rate limit approaching', { remaining: 4 });
};
```

```ts
// plugins/workers/jobs/health-check.ts — real custom spans inside a handler.
// The dispatcher already wraps this job in traceJobExecution automatically;
// withChildSpan + recordJobProgress let you add detail under that parent span.
import { createSuccessResult, createFailureResult, defineJobHandler } from '@netscript/plugin-workers-core';
import { withChildSpan, recordJobProgress } from '@netscript/telemetry/instrumentation';

const handler = defineJobHandler(async (ctx) => {
  const { log } = ctx;
  log.info('Starting workers plugin health check');

  // Real progress event — 3rd arg is a UNIT label, not a message.
  recordJobProgress(1, 2, 'steps');

  // withChildSpan opens a real child span under the job-execution span.
  const envCheck = await withChildSpan('check.environment', async (span) => {
    span.setAttribute('check.name', 'environment');
    return { ok: true };
  });

  recordJobProgress(2, 2, 'steps');
  if (!envCheck.ok) return createFailureResult('environment check failed');
  return createSuccessResult({ status: 'healthy' });
});

export default Object.assign(handler, { id: 'workers-plugin-health-check' as const });
```

> Known gap: the scaffold createJobTools(ctx) trace/progress helpers are no-op stubs
>
> Job dispatch and execution are instrumented with
>
> real OTel spans
>
> — traces show up in Aspire automatically (
>
> traceJobExecution
>
> ,
>
> recordJobProgress
>
> , scheduler spans, and subprocess traceparent propagation are all live in the runtime). The one remaining gap is narrow and specific: the
>
> trace.{addEvent,withChildSpan,recordProgress}
>
> and
>
> progress(...)
>
> helpers returned by the scaffold's
>
> createJobTools(ctx)
>
> are currently
>
> no-op stubs
>
> in the generated copy.
>
> log
>
> writes to the console; those particular trace/progress helpers do nothing. This is a
>
> known, tracked limitation with a fix planned
>
> (debt
>
> workers-scaffold-job-tools-noop
>
> ), not a permanent design choice.
>
> Workaround:
>
> for custom spans and progress, call the
>
> @netscript/telemetry
>
> helpers directly (as in the tab above) rather than the scaffold
>
> createJobTools
>
> trace surface — those are real today. See
>
> Observability
>
> for the full framework-vs-scaffold map.

## Endpoints & ports

Telemetry has no single service of its own — it is emitted by every runtime and aggregated by Aspire. These are the real addresses you interact with, validated by the CLI E2E suite.

**Observability surfaces (link to /reference/telemetry/ and /reference/logger/ for the generated APIs)**

| Name | Type | Description |
| --- | --- | --- |
| `https://localhost:18888` | `dashboard` | Aspire dashboard — traces, structured logs, metrics, and resource state for the whole app graph. Auth token printed by `aspire start`. |
| `http://localhost:4318` | `OTLP/HTTP` | OTLP ingest endpoint the AppHost configures (aspire.config.json https profile). Runtimes export spans and logs here; the dashboard reads them back. This is the seam you point at a hosted backend. |
| `GET :8091/health` | `liveness` | Workers API health probe — reported as resource health in the dashboard. |
| `GET :8092/health/live` | `liveness` | Sagas API liveness route. |
| `GET :8093/health` | `liveness` | Triggers API health probe (Hono service). |
| `:8094` | `service` | Auth API (auth-api) — its request spans propagate trace context like any other service. |

## View it in Aspire

With `aspire start` up, the dashboard at `https://localhost:18888` gives you four views over the same telemetry stream — there is no separate tool to configure.

**Aspire dashboard views (https://localhost:18888)**

| Name | Type | Description |
| --- | --- | --- |
| `Resources` | `graph` | Live state of every app-graph resource: postgres, redis, workers-api, workers, sagas-api, sagas, triggers-api, triggers, auth-api. Health probes drive the status colour. |
| `Console logs` | `stream` | Per-resource stdout/stderr — the framework logger's text/JSON output lands here in real time. |
| `Structured logs` | `OTLP` | Structured log records exported over OTLP, filterable by resource, level, and attributes. |
| `Traces` | `OTLP` | Distributed traces collected from the OTLP endpoint (http://localhost:4318) — job dispatch/execution/scheduler/task spans and cross-service request spans as trace context propagates. |

> Use this when…
>
> Reach for the dashboard whenever you need to answer
>
> "what happened and where"
>
> : which resource is unhealthy, what a service logged for a given request, why a job failed, or how a call fanned out across services and subprocesses. Because Aspire wires OTLP for you, the lowest-effort observability path is to run
>
> aspire start
>
> and open
>
> :18888
>
> — no extra dependency, no collector to deploy. When you outgrow the local dashboard, the same OTLP export (
>
> http://localhost:4318
>
> ) is the seam you point at a hosted backend.

## Close the loop: read the trace back in code

The dashboard answers *"what happened and where"* for a human. The same telemetry has a **typed, in-language read side** for programs — and for an AI agent verifying its own change without a browser. `@netscript/telemetry/query` publishes a `TelemetryQueryPort` contract with an Aspire-backed reader: `createAspireTelemetryQuery(...)` (or `createTelemetryQuery(...)` for the port type) reads the Aspire `/api/telemetry/*` surface into package-owned read models — `TelemetryTrace`, `TelemetrySpan` (with its `events` and `links`), `TelemetryLog`, `TelemetryResource`, `TelemetryMetric`. So the verification turn becomes an assertion: fetch the trace by id, check that the span you expected is present with the status you expected — no console to tail, no screenshot to read.

**Telemetry query read side (@netscript/telemetry/query)**

| Name | Type | Description |
| --- | --- | --- |
| `createAspireTelemetryQuery(options) / createTelemetryQuery(options)` | `→ AspireTelemetryQuery / TelemetryQueryPort` | Build the Aspire-backed reader over the dashboard's /api/telemetry/* surface. The first returns the concrete adapter; the second returns it typed as the port contract. |
| `queryTraces(filter?) / getTrace(traceId)` | `→ Promise / Promise` | List traces matching a TraceQueryFilter, or fetch a single trace by id — the assertion primitive for 'did my flow produce the span I expected'. |
| `querySpans / queryLogs / queryMetrics / queryResources` | `→ Promise` | Read spans, structured logs, metrics, and resource records back as package-owned models (TelemetrySpan / TelemetryLog / TelemetryMetric / TelemetryResource). |
| `validateTraceQueryFilter / validateMetricQueryFilter / validateResourceQueryFilter` | `(filter) → filter` | Standard Schema validators for the query filters — a malformed query fails in-process rather than returning silently-wrong rows. |

> One comparison: reading traces back to verify a change
>
> Encore ships an MCP server that exposes its local traces to an AI agent, so the agent can read back what its change did. NetScript closes the same loop from the other side: instead of a separate protocol server, the trace read side is a **typed in-language port** (
>
> TelemetryQueryPort
>
> ) the app — or a test, or an agent's own tool — calls directly, returning the same package-owned read models the runtimes emit. Same goal — let the author verify a change *from the trace*, not by eye — kept inside the language and the type system.

## Production notes

> Footguns before you ship telemetry
>
> **❌ Trace 100% of traffic in production.** The local Aspire default samples everything — fine for dev, ruinous at scale.
>  **✅ Set a ratio sampler via env.** Sampling is an env decision, not a code one: set `OTEL_TRACES_SAMPLER` (surfaced as `TelemetryConfig.sampler`) to `traceidratio` with a rate. *Exception:* keep always-on sampling for low-volume services or a targeted debugging window.
>
> **❌ Fork the runtime to change telemetry backends.** Editing instrumentation to point at Grafana/Honeycomb is churn you will re-do every upgrade.
>  **✅ Point the exporter.** The OTLP export (`OTEL_EXPORTER_OTLP_ENDPOINT`, default `http://localhost:4318`) is the single seam — swap endpoint/protocol via env and the instrumentation code does not change.
>
> **❌ Put unbounded values in span attributes.** User ids, raw URLs, or full payloads in `span.setAttribute` explode index cardinality on the backend.
>  **✅ Use stable, low-cardinality keys.** Correlate to a specific record with `getTraceId()` in a structured log line instead of widening the span.
>
> **❌ Pass a message as `recordJobProgress`'s 3rd argument.** Free text there inflates cardinality and misreads the API.
>  **✅ Pass a stable unit label.** `'steps'` / `'items'` — the argument is a unit, not a description.
>
> **❌ Ship code that relies on the scaffold `createJobTools(ctx)` trace/progress helpers.** Those are no-op stubs today (debt `workers-scaffold-job-tools-noop`).
>  **✅ Call the `@netscript/telemetry` helpers directly** for real spans and progress, as in the handler tab above.

## Reference

This hub is intentionally thin — the full generated API lives in the reference.

[telemetry](https://rickylabs.github.io/netscript/netscript/reference/telemetry/)

[Do — Add OpenTelemetry  Task-oriented recipe: lean on the automatic job spans, add custom spans via @netscript/telemetry withChildSpan, propagate traceparent across services and subprocesses, and point the OTLP export (:4318) at the dashboard.](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/)

[Understand — Observability  The mental model: how spans, structured logs, health endpoints, and Aspire traces fit together — and the precise framework-vs-scaffold map of what is real (traceJobExecution, task.execute) versus the tracked createJobTools(ctx) stub.](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

[Look up — telemetry reference  The full generated deno doc API for @netscript/telemetry — tracer facade, context/traceparent helpers, the instrumentation helpers, scheduler spans, and the oRPC tracing plugin. The authority for signatures.](https://rickylabs.github.io/netscript/netscript/reference/telemetry/)

[Look up — logger reference  The full generated deno doc API for @netscript/logger — log levels, formats, and the structured-logging surface declared in netscript.config.ts.](https://rickylabs.github.io/netscript/netscript/reference/logger/)

[KV, queues & cron](https://rickylabs.github.io/netscript/netscript/data-persistence/kv-queues-cron/) [Fresh UI & design](https://rickylabs.github.io/netscript/netscript/web-layer/fresh-ui/)

_Canonical: https://rickylabs.github.io/netscript/observability/telemetry/_

---

# Orchestration & Runtime

A NetScript app is never one process — it is services, plugin APIs, background processors, a database, and a cache, wired together. This pillar is about the machinery that makes that fleet **derived rather than hand-maintained**: one `netscript init` scaffolds the workspace, plugin contributions become Aspire resources through generated registries, and a single `aspire start` stands the whole graph up with its wiring resolved. Encore markets its generated local development dashboard hard, and for good reason — a live, auto-provisioned map of the system is the artifact that proves the wiring is derived. NetScript's equivalent is the Aspire dashboard at `:18888`: every resource on it comes from your declared services and plugin contributions, not from a hand-edited process list.

Orchestration & Runtime covers the Aspire AppHost, generated plugin registry, runtime configuration, resource graph, deployment flow, and process lifecycle. Start here when you need to bring the whole workspace up, change runtime overrides, or understand how plugin contributions become resources.

[Overview & Concepts   Aspire resource graph  How the AppHost materializes services, plugins, stores, and the dashboard.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) [Story   CLI & scaffold  One command to a complete workspace — and why generated conventions save agent turns.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/cli-scaffold/) [Story   Runtime configuration  Typed project config plus hot-reloadable operator overrides.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/runtime-config/) [Quickstart   Run the workspace  Scaffold and start a workspace from the quickstart.](https://rickylabs.github.io/netscript/netscript/quickstart/) [How-To   Deploy locally with Aspire  Use Aspire to bring up local resources.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-local-aspire/) [How-To   Runtime overrides  Roll out configuration overrides across resources.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/roll-out-runtime-overrides/) [How-To   Plugins  Add or author a plugin contribution.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/) [API Reference   aspire and runtime config  Generated symbols for AppHost, config, runtime-config, plugin, and CLI units.](https://rickylabs.github.io/netscript/netscript/reference/aspire/)

## Where to go next

New here, start with the concept, then the practical wiring, then the reference:

- **Start from the CLI:** [CLI & scaffold](https://rickylabs.github.io/netscript/orchestration-runtime/cli-scaffold/) is the story of how one command lays the workspace down and why the generated conventions are the part that saves turns — for you and for a coding agent.
- **Understand the model:** [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

  explains why a NetScript app is a resource graph, how plugin contributions become resources, and when to change vs. regenerate vs. hand-edit the generated AppHost.
- **Wire resources together:** [Discover services](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/discover-services/)

  covers the two-pass reference resolution — including how a service now declares `pluginReferences`/`dependsOn` — and [Roll out runtime overrides](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/roll-out-runtime-overrides/)

  covers configuration across resources.
- **See it observed:** [Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/) is the dashboard side of the same graph — the spans and logs `aspire start` collects.
- **Look up exact symbols:** [the Aspire reference](https://rickylabs.github.io/netscript/netscript/reference/aspire/) and the [CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) .

## Learn, do, look up

[Learn  Quickstart  From `netscript init` to a running, orchestrated workspace.](https://rickylabs.github.io/netscript/netscript/quickstart/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/) [Look up  `@netscript/aspire` reference  Generated API reference. Related units: `cli`, `config`, `runtime-config`, `plugin`.](https://rickylabs.github.io/netscript/netscript/reference/aspire/) [Understand  Orchestration with Aspire  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/_

---

# CLI & scaffold

One command — `netscript init` — lays down a complete, running backend workspace: shared oRPC contracts, an example service, a Fresh frontend, the plugin registry, a default cache, and the Aspire orchestration layer. Everything after that is the same CLI extending the same workspace: `netscript plugin install` to add a capability, `netscript generate plugins` to rewire the registry, `netscript db` for the database workflow. The point is not typing speed. It is that every structural decision a backend needs — where contracts live, how a service registers, how a plugin contributes, how processes find each other — has already been made, once, in one conventional shape that both you and a coding agent can read back out of the workspace itself.

## The problem the scaffold solves

Ask a coding agent to "add a backend feature" in an unstructured TypeScript repo and watch where its turns go. Before it writes the feature, it has to *decide* things: a validation library, a database access pattern, a folder layout, a way to register the new route, a way to start the new process. Each decision is a turn, each turn is a chance to pick differently than last time, and the resulting drift is what you spend review cycles undoing.

A scaffolded NetScript workspace removes that entire class of turns. The layout is generated, so there is exactly one place a contract goes (`contracts/versions/v1/`), one way a service declares itself, one registry through which plugins are discovered — and the registry is **generated from the workspace, not hand-imported**, so the convention is enforced by regeneration rather than by review. When configuration changes, `netscript service generate` regenerates the Aspire helper files that wire services, health checks, ports, and cross-service discovery from your declarative config — the local topology is derived, not hand-maintained. An agent (or a new teammate) reads the existing conventions and follows them; the turns go into the feature.

> One comparison, stated plainly
>
> Encore's NestJS comparison makes the file-count argument for conventions — a CRUD endpoint "shouldn't require five files and a module registration" — and AdonisJS positions itself as batteries-included, "for teams who want to ship products, not assemble frameworks." NetScript applies both arguments one level up, to the whole workspace: run
>
> netscript init my-app --dry-run
>
> and it prints every file the scaffold would create — the contracts workspace, the example service, the frontend, the plugin registry, and the orchestration layer you would otherwise assemble by hand, one decision at a time — without writing anything to disk.

## The everyday flow

Four steps, in a fixed order — Aspire must be up before any `db` command. The

[CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) covers each group in depth; the

[Quickstart](https://rickylabs.github.io/netscript/netscript/quickstart/) walks the same path end to end in about five minutes.

1 · Scaffold

netscript init my-app --db postgres --service — a workspace with contracts, an example service, the Fresh app, the plugin registry, and the Aspire layer. With a database and a service it generates a real Prisma-backed CRUD contract and an oRPC playground at GET /.

2 · Orchestrate

cd aspire && aspire start brings up the database and cache and opens the dashboard at :18888 — the generated resource graph, live.

3 · Database

netscript db init / generate / seed — the Prisma-on-Deno workflow, including every plugin's contributed schema, only after Aspire is up.

4 · Extend

netscript plugin install workers, then netscript generate plugins so the registry picks the contribution up.

```bash
# Preview the whole scaffold plan without writing a file
netscript init my-app --dry-run

# The fully specified, non-interactive form
netscript init my-app --db postgres --service --service-name users --yes

# Extend the workspace, then regenerate the registry
netscript plugin install workers --name workers
netscript generate plugins
```

> Fresh NetScript releases and Deno's 24-hour window
>
> Deno 2.9 applies a 24-hour minimum dependency age to newly published registry versions. A generated JSR-mode workspace preserves that policy for third-party dependencies and exempts only exact `jsr:@netscript/*` versions from its matching NetScript release train. First-party plugin commands load the workspace policy explicitly, so scaffolding and plugin verbs work immediately after a NetScript release. Third-party plugins and explicitly different NetScript versions keep the normal age check; local-source workspaces do not add registry policy.

This page is the story; the mechanism lives elsewhere and is linked, not duplicated: the curated command tour is the [CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) , the exhaustive generated surface is [the @netscript/cli reference](https://rickylabs.github.io/netscript/netscript/reference/cli/) , and the database order-of-operations is the

[database & migration how-to](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/) .

## Installing a plugin is installing a capability

Plugins are how the scaffold grows: background workers, durable sagas, webhook triggers, durable streams, and authentication are all installed the same way. `netscript plugin install <kind-or-package>` adds the plugin package dependency, emits **workspace-owned glue** that imports it (such as `workers/mod.ts`), and registers its contributions — the host application never changes. The plugin's service, runtime, contract, and schema internals stay in the installed dependency; what lands in your repo is the thin, typed seam you own. After installing, one `netscript generate plugins` regenerates the registry so the host discovers the new contribution statically.

Medusa's Agent Skills docs collapse "install a plugin" and "give an agent a capability" into the same action — skills are installable units an agent uses directly. A NetScript plugin carries the same dual reading, one artifact with two framings: `netscript plugin install workers` adds a runtime capability (a jobs API and its isolated background processors, run as separate Aspire resources), and the typed glue plus generated registry it emits *is* the convention surface a coding agent reads to use that capability correctly — no separate integration guide to keep in sync.

The lifecycle is symmetric and inspectable: `netscript plugin list` shows what is registered, `netscript plugin doctor` sanity-checks the wiring, `netscript plugin info <name>` runs a plugin's published info command, and `netscript plugin remove` unregisters it. Authoring your own follows the same two-tier shape the official plugins use — `netscript plugin new billing` scaffolds a JSR-publishable core engine package and a thin connector that re-exports its contract.

- **Add one:** [Add a plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/) — the install flow step by step.
- **Author one:** [Author a plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/author-a-plugin/) — the two-tier core + connector pattern.
- **Understand the model:** [the plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) — manifest, contributions, generated registries, and why one plugin runs as several processes.

## Generated, then owned

Two generation modes coexist in a scaffolded workspace, and knowing which is which tells you what is safe to edit:

- **Regenerated artifacts** — the plugin registries (`netscript generate plugins`), runtime configuration schemas (`netscript generate runtime-schemas`), and the Aspire helper files (`netscript service generate`). These are derived from your configuration and re-derived when it changes; treat them as outputs.
- **Emitted-then-owned code** — the glue a `plugin install` writes and the Fresh UI components `netscript ui:add` copies into your repo. These are yours from the moment they land: edit them freely, they are never overwritten behind your back.

That split is the scaffold's contract with you: conventions are enforced where regeneration is cheap, and ownership is handed over where your edits are the point. How generated runtime schemas feed the operator-facing override layer is the

[runtime configuration](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/runtime-config/) story.

## Where to go next

[Look up — CLI reference  The curated, task-grouped tour of every netscript command group: scaffold, plugins, services, database, generate, deploy.](https://rickylabs.github.io/netscript/netscript/cli-reference/)

[Learn — Quickstart  Install → init → aspire start → db → hit an endpoint, in about five minutes.](https://rickylabs.github.io/netscript/netscript/quickstart/)

[Understand — Orchestration with Aspire  Why the workspace is a resource graph and what a single aspire start actually stands up.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

[Understand — The plugin system  Manifest, contributions, generated registries — the mental model behind plugin install.](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/)

[Orchestration & Runtime](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/) [Runtime configuration](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/runtime-config/)

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/cli-scaffold/_

---

# Orchestration & Runtime — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/_

---

# Add a plugin

**Goal:** add one of NetScript's official plugins — **workers**, **sagas**, **triggers**, **streams**, or **auth** — to an existing workspace, register it with the runtime, and confirm it is wired up and healthy.

This is a task-oriented recipe. It assumes you already have a NetScript workspace (created with `netscript init`) and that the `netscript` command is on your path. Each step is a single command you run from your workspace root; the [Verify](#step-4--verify-the-plugin-is-registered) step proves the plugin landed before you write a line of application code. For the exact APIs each plugin exposes, follow the [reference links](#reference) at the end — this guide adds the plugin; the reference documents its surface.

> Plugins compose; they do not replace your service
>
> A plugin is an
>
> installable capability
>
> — a background-job runtime, a saga orchestrator, an auth service — that scaffolds its own workspace folder, registers itself in your runtime, and (where applicable) runs as its own Aspire service on a dedicated port. Your application service and your plugins run side by side. See
>
> Plugin architecture
>
> for the design behind the model.

## Before you start

You need:

- **An existing NetScript workspace.** If you do not have one yet, create it first with `netscript init` — walk through the [Quickstart](https://rickylabs.github.io/netscript/quickstart/) or the [tutorials index](https://rickylabs.github.io/netscript/tutorials/).
- **The `netscript` command on your path.** Run `netscript --help` to confirm it resolves, and `netscript plugin --help` for the exact option spelling in your installed version. If the command is missing, install it:

```bash
deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11
```

```bash
netscript --help
netscript plugin --help
```

- **Aspire up if you plan to run the plugin.** Adding and registering a plugin is offline, but several plugins (workers, sagas, auth) need a database and Redis to actually run. The database is Postgres, the recommended engine (or `mysql` / `mssql` / `sqlite`, chosen at scaffold time with `--db`). Bring the local stack up first — `cd aspire && aspire start` — exactly as in [Run the stack with Aspire](https://rickylabs.github.io/netscript/explanation/aspire/). You do **not** need it up just to scaffold and register.

> Run commands from the workspace root
>
> Every command below runs from your workspace root. To target a different project, pass
>
> --project-root <path>
>
> — it defaults to the current directory. Run
>
> netscript plugin install --help
>
> for the version-accurate option list before you rely on any flag.

## Step 1 — Choose the plugin kind

Each official plugin has a *kind* you pass to the command and a conventional installed *name*. Use the conventional name unless you have a specific reason to differ — generated registries, ports, and docs all assume it.

**Official plugins**

| Kind | Conventional name | JSR package | Default port | Reference |
| --- | --- | --- | --- | --- |
| `worker` | `workers` | `@netscript/plugin-workers` | 8091 | [workers](https://rickylabs.github.io/netscript/reference/workers/) |
| `saga` | `sagas` | `@netscript/plugin-sagas` | 8092 | [sagas](https://rickylabs.github.io/netscript/reference/sagas/) |
| `trigger` | `triggers` | `@netscript/plugin-triggers` | 8093 | [triggers](https://rickylabs.github.io/netscript/reference/triggers/) |
| `auth` | `auth` | `@netscript/plugin-auth` | 8094 | [auth](https://rickylabs.github.io/netscript/capabilities/auth/) |
| `stream` | `streams` | `@netscript/plugin-streams` | 4437 | [streams](https://rickylabs.github.io/netscript/reference/streams/) |

Pick the kind for the capability you need:

- **workers** — background job scheduling, task execution, and worker API endpoints. Fully traced through Aspire (scheduler → queue → worker → subprocess). See [Background jobs](https://rickylabs.github.io/netscript/capabilities/background-jobs/).
- **sagas** — durable saga orchestration and long-running workflow APIs, with a selectable durable store (`kv` or `prisma`). See [Durable sagas](https://rickylabs.github.io/netscript/capabilities/durable-sagas/).
- **triggers** — trigger ingress, scheduling, and file watching over raw Hono routes. See [Triggers](https://rickylabs.github.io/netscript/capabilities/triggers/).
- **auth** — an oRPC auth service (sign-in, callback, sign-out, session, me) backed by a single selectable backend (kv-oauth, WorkOS, or better-auth). See [Authentication](https://rickylabs.github.io/netscript/capabilities/auth/).
- **streams** — durable, change-data stream producers served as their own Aspire service. See [Streams](https://rickylabs.github.io/netscript/capabilities/streams/).

> auth is a first-class official plugin
>
> Auth is now added the same way as workers, sagas, triggers, and streams — through
>
> netscript plugin install auth
>
> . It installs the
>
> @netscript/plugin-auth
>
> dependency, emits a user-owned
>
> auth/mod.ts
>
> glue barrel, registers the
>
> auth-api
>
> service on port
>
> 8094
>
> , and contributes its package-provided Prisma models. The active backend is selected at runtime with
>
> NETSCRIPT_AUTH_BACKEND
>
> (default
>
> kv-oauth
>
> ). See
>
> Configure authentication
>
> for the backend setup.

## Step 2 — Add the plugin

In the public `netscript` CLI, `plugin install` accepts either an official bare alias (`workers`, `sagas`, `triggers`, `auth`, `streams`) or a published plugin package specifier such as `@netscript/plugin-workers`. Add an official plugin by alias:

```bash
netscript plugin install workers --name workers
```

Repeat with the matching alias for the other plugins: `sagas`, `triggers`, `auth`, and `streams`. The package-spec forms also work, for example `netscript plugin install @netscript/plugin-workers --name workers` or an explicit `jsr:` specifier. Run `netscript plugin install --help` for the version-accurate surface.

### Useful options

Run `netscript plugin install --help` for the full, version-accurate list. The public `netscript plugin install` command takes the plugin alias or package specifier and applies the workspace-level install flags before invoking the plugin-owned scaffolder:

**netscript plugin install — options**

| Option | What it does |
| --- | --- |
| `--name <name>` | Plugin workspace and config key, for example `workers`. |
| `--project-root <path>` | Target a workspace other than the current directory. |
| `--port <port>` | Override the plugin service port. |
| `--db <engine>` / `--no-db` | Provision or target a database engine, or skip database wiring. |
| `--samples` / `--no-samples` | Include or skip user-owned sample stubs. |
| `--jsr-url <specifier>` / `--local-path <path>` | Use an explicit JSR package or local plugin package directory. |
| `--force` | Overwrite generated files if they already exist. |

> Contributor CLI uses local sources
>
> The local contributor command
>
> deno run -A packages/cli/bin/netscript-dev.ts plugin install <kind>
>
> accepts the same framework-level install flags, but resolves against the monorepo checkout instead of the globally installed public CLI. Always run
>
> netscript plugin install --help
>
> for the option list your installed version actually exposes.

> auth needs a database and KV
>
> The auth plugin sets
>
> requiresDb
>
> and
>
> requiresKv
>
> , and contributes its own Prisma models (
>
> auth_users
>
> ,
>
> auth_sessions
>
> ,
>
> auth_accounts
>
> ,
>
> auth_verifications
>
> ). Keep DB wiring on (do not pass
>
> --no-db
>
> ) and run the database steps in
>
> Step 3
>
> so its tables exist before the service starts.

## Step 3 — Generate registries and wire the database

After adding plugins, regenerate the plugin registries so the runtime can discover them:

```bash
netscript generate plugins
```

If a plugin contributes runtime configuration schemas, also run:

```bash
netscript generate runtime-schemas
```

Plugins that contribute Prisma models (workers, sagas, and **auth**) need their tables created. With Aspire already running (`cd aspire && aspire start`), apply migrations and generate the client:

```bash
netscript db init --name add-plugin
```

```bash
netscript db generate
```

```bash
netscript db seed
```

> Aspire is step 2, the database is step 3
>
> netscript db
>
> talks to the database that Aspire provisions — Postgres by default, or
>
> mysql
>
> /
>
> mssql
>
> /
>
> sqlite
>
> if you chose a different engine with
>
> --db
>
> at scaffold time (sqlite is file-backed, so it has no Aspire container resource). Always
>
> cd aspire && aspire start
>
> before
>
> any
>
> db
>
> command — see
>
> Run the stack with Aspire
>
> . Skip these database steps only when every plugin you added is stateless.

## Step 4 — Verify the plugin is registered

List the registered plugins to confirm your new plugin appears:

```bash
netscript plugin list
```

You should see your plugin in the inventory — for example, `workers`, `sagas`, `triggers`, `auth`, and `streams` if you added all five. Then run the health check:

```bash
netscript plugin doctor
```

`plugin doctor` checks installed NetScript plugin health and reports wiring problems (missing registration, port collisions, absent database tables). A clean run means the plugin is registered, wired, and ready to use.

```bash
# Detailed info for a single installed plugin
netscript plugin info @netscript/plugin-auth
```

```bash
# Bring the whole stack up and exercise the plugin's service
cd aspire && aspire start
# Aspire dashboard: https://localhost:18888
# auth-api:         http://localhost:8094
```

> Confirm in the Aspire dashboard
>
> Service-bearing plugins appear as resources in the Aspire dashboard at
>
> `https://localhost:18888`
>
> once
>
> aspire start
>
> is up. A green resource on the plugin's port (workers
>
> :8091
>
> , sagas
>
> :8092
>
> , triggers
>
> :8093
>
> , auth
>
> :8094
>
> , streams
>
> :4437
>
> ) confirms the plugin is live end to end.

## Manage plugins later

Once a plugin is installed you can inspect, update, and remove it without re-scaffolding:

**Plugin lifecycle commands**

| Command | Purpose |
| --- | --- |
| `netscript plugin list` | List installed plugins in the current workspace. |
| `netscript plugin info <name>` | Show detailed metadata for one installed plugin. |
| `netscript plugin doctor` | Health-check installed plugins and report wiring problems. |
| `netscript plugin update <pkg>` | Dispatches the `update` verb to the plugin's own published CLI (e.g. `netscript plugin update @netscript/plugin-workers`). The argument is a JSR package specifier, not an installed plugin name. |
| `netscript plugin remove <name>` | Remove an installed plugin from the workspace. |

Run `netscript plugin --help` for the complete, version-accurate command set.

## Reference

[workers  Background jobs, scheduling, task execution.](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[sagas  Durable saga orchestration (kv | prisma store).](https://rickylabs.github.io/netscript/netscript/reference/sagas/)

[triggers  Trigger ingress, scheduling, file watching.](https://rickylabs.github.io/netscript/netscript/reference/triggers/)

[auth  oRPC auth service with a selectable backend.](https://rickylabs.github.io/netscript/netscript/capabilities/auth/)

[streams  Durable change-data stream producers.](https://rickylabs.github.io/netscript/netscript/reference/streams/)

[All packages  Browse the full package and plugin index.](https://rickylabs.github.io/netscript/netscript/reference/)

### Where to go next

- **Build on the plugin you just added.** Next up: [Add a service](https://rickylabs.github.io/netscript/services-sdk/how-to/add-a-service/) to give the plugin something to call, or [Configure authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/) if you added the auth plugin.
- **Understand the model.** Read [Plugin architecture](https://rickylabs.github.io/netscript/explanation/plugin-system/) for the design behind installable capabilities, ports, and runtime registration.
- **Browse capabilities.** The [capabilities](https://rickylabs.github.io/netscript/capabilities/) section maps each plugin to the problem it solves, with runnable examples.

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/add-a-plugin/_

---

# Author a plugin

**Scope.** This recipe shows how to author a *new* custom plugin from scratch — its canonical location, the manifest it exports through `definePlugin(...)`, the contribution shape the kernel reads, and the generated registry that makes those contributions discoverable at runtime. It is the advanced companion to [Add a first-party plugin](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/add-a-plugin/), which only *installs* one of the four official plugins (`workers`, `sagas`, `triggers`, `streams`). If you just want a worker or a saga, install it there. Come here when you need a capability NetScript does not ship.

A NetScript plugin is **two packages**: a JSR-publishable **core engine** under `packages/plugin-<name>-core/` that owns the behavior (domain, ports, application, contract), and a thin **connector** under `plugins/<name>/` whose `mod.ts` exports a plugin **manifest** built with `definePlugin`. The framework discovers the connector because `netscript.config.ts` lists `./plugins/<name>/mod.ts`, and it discovers the plugin's *contributions* (jobs, services, stream topics, DB schemas, e2e gates) through a generated **registry**. Scaffold both tiers with `netscript plugin new <name>`, get location, manifest, and registry right, and the kernel wires the rest. The conceptual model behind that split lives in [The plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/); the generated manifest and contribution types live in the [plugin reference](https://rickylabs.github.io/netscript/reference/plugin/).

> Aspire is the control plane — start it first
>
> If your plugin contributes an API service or a background processor, those run as resources in the Aspire graph alongside Postgres and Redis. Bring orchestration up
>
> before
>
> you run any
>
> netscript db
>
> command or exercise your plugin's endpoints: from the project root,
>
> cd aspire && aspire start
>
> (dashboard at
>
> https://localhost:18888
>
> ). DB commands require Aspire running first. See
>
> the Aspire explanation
>
> for the resource graph.

## Before you start

You need an existing workspace and a clear idea of what your plugin *contributes*. The official plugins are the reference implementations — read one that resembles your goal before you write a line. The richest real-world exemplar is the **auth plugin**: a multi-package plugin (`plugins/auth/` plus `@netscript/plugin-auth-core` and three backend adapters) that composes a core seam, swappable adapters, and a single oRPC service. Study it when your plugin spans more than one package.

**Prerequisites**

| Name | Type | Description |
| --- | --- | --- |
| `Workspace` | `netscript init` | An existing project. If you have none, scaffold one first — see the tutorials. |
| `netscript CLI` | `on PATH` | Installed globally: deno install --global --allow-all --name netscript jsr:@netscript/cli. Confirm with netscript --help. |
| `A starting skeleton` | `netscript plugin new ` | Scaffold the two-tier core + connector pair, then adapt it. Read a first-party plugin's mod.ts + scaffold.plugin.json alongside it; the auth plugin is the best multi-package exemplar. |
| `Provider kind` | `worker \| saga \| trigger \| stream \| plugin` | Decide which archetype your plugin is. Utility/infra plugins use kind 'stream' or the generic 'plugin'. |

Throughout, run commands from your workspace root.

## Step 1 — Scaffold the two-tier skeleton

Every NetScript plugin is **two packages, not one**: a JSR-publishable **core engine package** under `packages/plugin-<name>-core/` that owns the behavior, and a **thin connector** under `plugins/<name>/` that wires that behavior into a host. The fastest — and doctrine-true — way to get both trees correct is the greenfield generator:

```sh
netscript plugin new notifier
```

`netscript plugin new <name>` emits the whole pair in one pass. It scaffolds a **proxy** connector by default; pass `--feature` to generate a route-backed feature connector instead. Its other options are `--force` (overwrite existing files instead of skipping them) and `--project-root <path>` (target a project root other than the current directory). The connector under `plugins/<name>/` is the workspace member `netscript.config.ts` references; the core package under `packages/plugin-<name>-core/` is where the domain, ports, application logic, and contract live and is independently publishable to JSR.

The **core engine package** owns the capability. Its `deno.json` is strict and exports `. ./contracts/v1 ./domain ./ports ./testing`:

```
packages/plugin-notifier-core/
├── deno.json                          # strict; exports . ./contracts/v1 ./domain ./ports ./testing
├── mod.ts                             # curated builders + domain type re-exports
├── README.md
├── src/domain/mod.ts                  # domain entities and ids
├── src/ports/mod.ts                   # the engine's ports (the seam adapters implement)
├── src/application/mod.ts             # application orchestration (define<Name>)
├── src/contracts/v1/notifier.contract.ts  # the v1 oRPC contract, extends the base plugin contract
├── src/contracts/v1/mod.ts            # contract barrel
├── src/testing/mod.ts                 # in-memory port doubles for tests
└── tests/contracts/notifier-contract-soundness_test.ts
```

The **thin connector** carries only integration. Its `deno.json` exports `. ./contracts ./services ./aspire ./cli ./scaffold`, and its `contracts/v1.ts` re-exports the core's `contracts/v1`:

```
plugins/notifier/
├── deno.json                 # exports . ./contracts ./services ./aspire ./cli ./scaffold
├── package.json
├── mod.ts                    # ← public manifest: definePlugin(...).build() + an inspect fn
├── README.md
├── contracts/v1.ts           # re-exports @netscript/plugin-notifier-core/contracts/v1
├── adapter.ts                # NetScriptPlugin adapter (install/doctor/info/update/remove)
├── aspire.ts                 # Aspire contribution
├── cli.ts                    # CLI adapter entrypoint
├── scaffold.ts               # scaffold adapter entrypoint
├── verify-plugin.ts          # manifest self-verification
├── scaffold.plugin.json      # manifest descriptor read by the CLI/kernel (kind, capabilities…)
├── scaffold.runtime.json
├── database/notifier.prisma  # (optional) plugin's Prisma models, aggregated at db generate
├── scaffolding/              # item scaffolder + stub the connector emits into userland
├── services/src/             # the plugin's service: context.ts, handlers.ts, main.ts
└── tests/public/manifest_test.ts
```

> Two tiers: behavior in core, integration in the connector
>
> The pair the generator emits mirrors the core/connector split every official plugin uses:
>
> packages/plugin-notifier-core/
>
> holds the domain, ports, application logic, and the versioned contract — the parts you would publish and reuse — while
>
> plugins/notifier/
>
> holds only the manifest, adapters, and service wiring, re-exporting the core's contract through
>
> contracts/v1.ts
>
> .
>
> netscript.config.ts
>
> references
>
> `./plugins/notifier/mod.ts`
>
> , so the connector is the workspace member you register; author capability changes in the core package and integration changes in the connector.

## Step 2 — Write the manifest descriptor (`scaffold.plugin.json`)

`scaffold.plugin.json` is the static descriptor the CLI and kernel read to understand your plugin's *archetype* and runtime needs. The single most important field is **`provider.kind`** — it tells the framework what category of contributions to expect. The official plugins set it as follows, and your plugin should pick the closest match:

**provider.kind by archetype (from the official scaffold.plugin.json files)**

| Name | Type | Description |
| --- | --- | --- |
| `worker` | `background-processor` | Job handlers run by a worker processor. defaultEntrypoint bin/combined.ts, concurrencyEnvVar WORKER_CONCURRENCY (default 2) in current Aspire metadata; runtime entrypoints read WORKERS_CONCURRENCY, servicePort 8091. |
| `saga` | `background-processor` | Durable message-driven sagas. defaultPermissions ['--unstable-kv','--allow-all'], concurrencyEnvVar SAGA_CONCURRENCY, servicePort 8092. |
| `trigger` | `ingress` | Webhooks / schedules / file-watchers. defaultEntrypoint src/runtime/trigger-processor.ts, concurrencyEnvVar TRIGGER_CONCURRENCY (default 10), servicePort 8093. |
| `stream` | `utility / plugin` | Infra/utility plugin. requiresDb=false, requiresKv=false, portRangeKey PLUGIN_API, servicePort 4437. |

A worker-archetype descriptor looks like this — copy the shape and change the names. The `officialSource` block is what the official plugins carry; for a custom plugin you set `canonicalName`, `servicePort`, and any `dependencies` your plugin needs wired ahead of it:

```json
{
  "provider": {
    "kind": "worker",
    "category": "background-processor",
    "defaultEntrypoint": "bin/combined.ts",
    "defaultServiceEntrypoint": "services/src/main.ts",
    "defaultRequiresDb": true,
    "defaultRequiresKv": true,
    "concurrencyEnvVar": "WORKER_CONCURRENCY"
  },
  "officialSource": {
    "canonicalName": "notifier",
    "servicePort": 8095,
    "dependencies": ["streams"]
  }
}
```

```ts
// provider.kind          -> which contribution category to scan for
// defaultEntrypoint       -> the background processor aspire starts
// defaultServiceEntrypoint-> the API service aspire starts (if any)
// defaultRequiresDb / Kv  -> whether to provision Postgres / Redis for it
// concurrencyEnvVar       -> env var that caps processor concurrency
// officialSource.servicePort -> the HTTP port the service binds
// officialSource.dependencies -> plugins wired BEFORE this one in the graph
```

> Pick a free port
>
> The official plugins claim
>
> :8091
>
> (workers),
>
> :8092
>
> (sagas),
>
> :8093
>
> (triggers),
>
> :8094
>
> (
>
> auth
>
> ), and
>
> :4437
>
> (streams). Choose a
>
> different
>
> port for your custom plugin's service (for example
>
> :8095
>
> ) so it does not collide in the Aspire graph.

## Step 3 — Export the manifest from `mod.ts`

`mod.ts` is the plugin's public surface. It exports the **manifest** — built with the `definePlugin(name, version)` fluent builder from `@netscript/plugin` — plus an `inspect*` helper, mirroring the official plugins. The builder is the doctrine-true way to assemble a manifest: each `withX(...)` method adds one contribution axis, and `.build()` validates the result against the manifest schema and freezes it. Follow the same convention the scaffold emits:

```ts
// Public manifest for the notifier plugin.
// Mirrors the official plugins: build the manifest with definePlugin(...),
// then export it alongside an inspect helper.
import { definePlugin } from '@netscript/plugin';

export const NOTIFIER_PLUGIN_ID = 'notifier' as const;
export const NOTIFIER_API_DEFAULT_PORT = 8095 as const;

export const notifierPlugin = definePlugin('@notifier/plugin', '0.1.0')
  .withDescription('Delivers user notifications via worker jobs.')
  .withLicense('MIT')
  .withAuthor('Acme Platform Team')
  .withDependencies({ streams: true })
  .withE2e([{ name: 'notifier.smoke', command: 'deno test --allow-all tests/' }])
  .build();

export const inspectNotifier = () => ({
  id: NOTIFIER_PLUGIN_ID,
  version: notifierPlugin.version,
  port: NOTIFIER_API_DEFAULT_PORT,
});

export default notifierPlugin;
```

```ts
// definePlugin(name, version) returns a PluginBuilder. Each axis is one
// withX(...) call; .build() validates + freezes the manifest.
//
//   .withService(...)             -> an oRPC/API service contribution
//   .withBackgroundProcessor(...) -> a worker/saga processor entrypoint
//   .withStreamTopics([...])      -> durable stream topic schemas
//   .withDbSchemas([...])         -> Prisma models aggregated at db generate
//   .withContractVersions([...])  -> versioned oRPC contracts
//   .withRuntimeConfigTopics([...]) -> runtime-config schemas
//   .withMigrations([...])        -> DB migration contributions
//   .withE2e([...])               -> merge-readiness gates
//   .withDependencies({...})      -> plugins wired ahead of this one
//   .withAspire(modulePath)       -> the Aspire contribution module
//   .build()                      -> immutable, schema-validated manifest
```

```json
{
  "name": "@notifier/plugin",
  "version": "0.1.0",
  "exports": {
    ".": "./mod.ts",
    "./contracts": "./contracts/v1/mod.ts"
  },
  "imports": {
    "@netscript/plugin": "jsr:@netscript/plugin",
    "@netscript/plugin-workers-core": "jsr:@netscript/plugin-workers-core",
    "zod": "jsr:@zod/zod@4.4.3"
  }
}
```

The manifest is data, not behavior: it declares *what* the plugin is (name, version, dependencies) and *which contribution axes* it owns. The actual capability lives in the contribution modules you write next, which the registry binds to the kernel. See the [plugin reference](https://rickylabs.github.io/netscript/reference/plugin/) for the full builder surface and the manifest type it produces.

## Step 4 — Author a contribution

A contribution is a typed module the registry scans and exposes to the runtime. The shape depends on your `provider.kind`:

**Contribution authoring API by kind**

| Name | Type | Description |
| --- | --- | --- |
| `worker` | `defineJobHandler` | A job: defineJobHandler(async (ctx) => …) + createSuccessResult/createFailureResult; id via Object.assign(handler, { id }). Lives in jobs/. |
| `saga` | `defineSaga(id)…build()` | Fluent builder: .durability('t1').state({…}).on(type, fn).build(); effects via sagaComplete({…}). Durable store is kv \| prisma. |
| `trigger` | `defineWebhook` | defineWebhook(handler, { id, path, verifier, tags }); handler returns enqueueJob(jobRef, { payload, priority })[]. The service speaks a typed v1 oRPC contract for trigger/event introspection and management; the webhook ingress endpoint stays a raw signature-verifying route by design. enqueueJob is live; defer throws + routes to DLQ. |
| `stream` | `createDurableStream / defineStreamSchema` | Real producer runtime via @netscript/plugin-streams-core. The @netscript/plugin-streams manifest helpers (defineStreamProducer/Consumer) fail loud — they throw StreamUnsupportedOperationError. |

For a worker-archetype plugin, a contribution is an ordinary job handler. This is the exact authoring API the official workers plugin uses — drop the file in `plugins/notifier/jobs/`:

```ts
import {
  createSuccessResult,
  defineJobHandler,
} from '@netscript/plugin-workers-core';
import { z } from 'zod';

const PayloadSchema = z.object({ userId: z.string().min(1) });

const handler = defineJobHandler(async (ctx) => {
  const { userId } = PayloadSchema.parse(ctx.payload ?? {});
  // …deliver the notification here…
  return createSuccessResult({ userId, delivered: true });
});

export default Object.assign(handler, { id: 'send-notification' });
```

```ts
import { defineWebhook, enqueueJob } from '@netscript/plugin-triggers-core/builders';

// A webhook contribution: returns an array of enqueueJob effects that
// bind inbound HTTP to worker jobs. The triggers service serves a typed
// v1 oRPC contract for trigger/event introspection and management; the
// webhook ingress route (POST /api/v1/webhooks/:triggerId) stays a raw
// signature-verifying endpoint by design. enqueueJob is the only live
// action; a defer action throws and routes to the DLQ.
export const inbound = defineWebhook(
  () => Promise.resolve([
    enqueueJob(jobRef, { payload: { verbose: false }, priority: 50 }),
  ]),
  { id: 'notifier-inbound', path: 'inbound/notify', verifier: 'memory', tags: ['webhook'] },
);
export default inbound;
```

```ts
import { createDurableStream, defineStreamSchema } from '@netscript/plugin-streams-core';

// The producer runtime is REAL. createDurableStream serves a durable
// stream (an Aspire service on :4437) you can upsert/delete/flush against.
const schema = defineStreamSchema({ /* topic entity schema */ });
const producer = createDurableStream({
  streamPath: '/notifier/events',
  schema,
  producerId: 'notifier-service',
});
producer.upsert('event', { id: 'evt-1', status: 'sent' });
```

> Edges: trigger ingress is a raw route, stream helpers fail loud
>
> Two reality checks the official plugins make explicit.
>
> Triggers
>
> serve a
>
> typed v1 oRPC contract
>
> for trigger/event introspection and management, but the
>
> webhook ingress endpoint
>
> (
>
> POST /api/v1/webhooks/:triggerId
>
> ) stays a
>
> raw signature-verifying route
>
> by design — it verifies an HMAC signature over the raw request bytes, which oRPC's schema parsing cannot do, so third-party senders (with no NetScript client) POST to that plain URL; the supported action is
>
> enqueueJob
>
> (live), while
>
> defer
>
> is defined-but-unsupported (it
>
> throws
>
> and routes to the DLQ — no deferred replay).
>
> Streams
>
> are split: the
>
> producer runtime is real
>
> via
>
> @netscript/plugin-streams-core
>
> 's
>
> createDurableStream
>
> (served as an Aspire service on
>
> :4437
>
> and used by the workers, auth, and sagas plugins). Only the
>
> @netscript/plugin-streams
>
> manifest helpers (
>
> defineStreamProducer
>
> /
>
> defineStreamConsumer
>
> ) are unsupported — they
>
> fail loud
>
> , throwing
>
> StreamUnsupportedOperationError
>
> , and redirect you to the core package. There is no in-process consumer
>
> subscribe()
>
> ; consume over HTTP/SSE. See
>
> Streams
>
> for the producer-vs-helper split.

## Step 5 — Register the plugin in `netscript.config.ts`

The kernel only loads plugins listed in the config, so the generated connector's `mod.ts` has to appear in the `plugins` array. **If you scaffolded through the CLI, this already happened.** Both wiring commands run a workspace mutator that adds the connector to `netscript.config.ts` for you:

- `netscript plugin new <name>` — the greenfield generator from [Step 1](#step-1-scaffold-the-two-tier-skeleton) — registers the connector it emits; the `--register` flag defaults to on.
- `netscript plugin install <kind> --name <name> --local-path <path>` — installs a plugin workspace from a local package directory and registers it as part of the same install.

After either command, open `netscript.config.ts` and confirm the entry is present — the entries are **`./plugins/<name>/mod.ts`**, confirming `plugins/<name>/` as the canonical location.

Only reach for the manual edit below if you are hand-authoring the connector without the CLI: add the `mod.ts` path to the `plugins` array yourself.

```ts
import { defineConfig } from '@netscript/config';

export default defineConfig({
  name: 'my-app',
  version: '1.0.0',
  paths: { services: 'services', apps: 'apps', contracts: 'contracts', plugins: 'plugins' },
  plugins: [
    './plugins/streams/mod.ts',
    './plugins/workers/mod.ts',
    './plugins/sagas/mod.ts',
    './plugins/triggers/mod.ts',
    './plugins/notifier/mod.ts', // ← your custom plugin
  ],
});
```

## Step 6 — Generate the registry

Listing the plugin is not enough — the runtime addresses contributions through a **generated registry**. For a worker-archetype plugin, the generator scans `plugins/<name>/jobs/` and writes a jobs registry (e.g. `.netscript/generated/plugin-<name>/job-registry.ts`) keyed by each handler's `id`. Generate it:

```sh
netscript generate plugins
```

If your plugin contributes runtime configuration schemas, also generate those:

```sh
netscript generate runtime-schemas
```

After generation, your contribution is discoverable by its `id` (a job at `POST /api/v1/<name>/jobs/{id}/trigger`, a webhook at `POST /api/v1/webhooks/<path>`, and so on).

> Regenerate after every contribution change
>
> The registry is a build artifact, not a live scan. Any time you add, rename, or remove a contribution module, re-run
>
> netscript generate
>
> and restart
>
> aspire start
>
> (or let it hot-reload) so the service and its background processor pick up the new registry.

## Step 7 — Verify it is wired up

List the registry and run the health check to confirm the kernel sees your plugin:

```sh
netscript plugin list      # your plugin should appear in the registry
netscript plugin doctor    # checks plugin health and reports wiring problems
```

With Aspire running, your plugin's service is live on the port you chose. Confirm it and exercise a contribution — for the `notifier` worker example on `:8095`:

```sh
curl http://localhost:8095/health
curl http://localhost:8095/api/v1/notifier/jobs

curl -X POST http://localhost:8095/api/v1/notifier/jobs/send-notification/trigger \
  -H 'content-type: application/json' \
  -d '{ "payload": { "userId": "user-42" } }'
```

You should see the contribution registered in the jobs list and an execution recorded after you trigger it. Watch it live in the Aspire dashboard at [https://localhost:18888](https://localhost:18888) under your plugin's resource.

## A real multi-package exemplar: the auth plugin

When your plugin grows beyond a single package — a core seam plus swappable adapters plus one service — the **auth plugin** is the production reference to copy. It is built from five units:

**Auth plugin topology (a multi-package plugin)**

| Name | Type | Description |
| --- | --- | --- |
| `@netscript/plugin-auth-core` | `core seam` | Defines AuthBackendPort, domain types, contracts/v1, and stream events. Adapters depend on it; it depends on no adapter. |
| `@netscript/auth-kv-oauth` | `backend adapter` | Interactive OAuth/OIDC backend (the only backend with an interactive sign-in flow). Default backend. |
| `@netscript/auth-workos` | `backend adapter` | Non-interactive WorkOS AuthKit backend; signin/callback return unsupported on this backend. |
| `@netscript/auth-better-auth` | `backend adapter` | Non-interactive better-auth backend; signin/callback return unsupported on this backend. |
| `@netscript/plugin-auth (plugins/auth/)` | `unifying plugin` | Composes ONE active backend (NETSCRIPT_AUTH_BACKEND, default kv-oauth) into one oRPC service (auth-api on :8094). |

The pattern to copy: a **core package owns the port** (`AuthBackendPort`), each **adapter is pure** (implements the port, declares no service), and the **plugin under `plugins/<name>/`** composes one active adapter into a single service and registry. That keeps adapters swappable and the kernel-facing manifest small. Build the full thing in [Add authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/) — that page is the concrete walkthrough for the auth plugin specifically.

> Alpha package pins
>
> CLI scaffolds pin
>
> jsr:@netscript/plugin-auth-core@0.0.1-beta.11
>
> and siblings at the exact aligned alpha version. Keep generated plugin workspaces on one NetScript release train.

## Production pitfalls

> Read before you ship a custom plugin
>
> - **Aspire not running** — a plugin's API service and background processor are Aspire resources. If endpoints 404 or jobs never execute, `aspire start` from `aspire/` is almost always the cause. DB-backed plugins also need it up before `netscript db`.
> - **Stale registry** — the runtime reads a generated registry, not your source tree. Forgetting `netscript generate` after adding a contribution is the most common "my job isn't registered" bug. Regenerate, then restart Aspire.
> - **Port collision** — do not reuse `:8091`/`:8092`/`:8093`/`:8094`/`:4437`. Set a free `servicePort` in both `scaffold.plugin.json` and `mod.ts`.
> - **Wrong canonical directory** — author in `plugins/<name>/`, the directory `netscript.config.ts` references. Edits to a top-level staging copy are not the source of truth.
> - **Mismatched archetype expectations** — a `trigger` plugin serves a typed v1 oRPC contract for introspection/management while keeping the webhook ingress endpoint a raw signature-verifying route, and only the `enqueueJob` action is live; a `stream` plugin's real runtime is the *producer* in `@netscript/plugin-streams-core`, while the `@netscript/plugin-streams` manifest helpers throw `StreamUnsupportedOperationError`. Match your plugin's behavior to its declared `provider.kind`.
> - **Unstated dependencies** — if your plugin needs another plugin wired ahead of it, declare it with `.withDependencies({...})` on the manifest and in `officialSource.dependencies` so the Aspire graph orders them correctly.

## See also

[Add a first-party plugin  Install one of the four official plugins instead of writing your own.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/) [Add authentication  Build the multi-package auth plugin — the production exemplar for a core seam plus swappable backends.](https://rickylabs.github.io/netscript/netscript/identity-access/how-to/add-authentication/) [The plugin system  Why plugins are thread-isolated background processors, and how the kernel loads them.](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) [plugin reference  The generated @netscript/plugin API — definePlugin builder, manifest type, contribution shapes.](https://rickylabs.github.io/netscript/netscript/reference/plugin/) [Aspire orchestration  The AppHost resource graph that runs your plugin's service and background processor.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/author-a-plugin/_

---

# Deno LSP code intelligence in Claude Code

**Goal:** give every Claude Code session the same Deno language-server features for NetScript apps: go-to-definition, find-references, hover, document symbols, and live diagnostics across the CLI, VS Code, and Zed.

This is the blessed setup for NetScript app work. It uses the Claude Code LSP tool, the Deno LSP, and a skills-dir plugin install so every new session loads the same `.lsp.json` configuration.

## Prerequisites

**What each device needs**

| Name | Type | Description |
| --- | --- | --- |
| `Deno` | `2.9+` | `deno` must be on PATH for terminal and GUI launches. Check with `deno --version`. |
| `Claude Code` | `CLI / VS Code / Zed` | All surfaces should launch the same `claude` binary and read the same `~/.claude` directory. |
| `LSP tool flag` | `ENABLE_LSP_TOOL=1` | Set globally in Claude settings and as a real user environment variable. |

## Step 1 - Install the Deno LSP plugin

Install the plugin into the Claude skills directory so it auto-loads in every session:

```bash
git clone https://github.com/wyattjoh/deno-lsp-claude-plugin ~/.claude/skills/deno-lsp
```

Claude Code auto-loads plugins installed under `~/.claude/skills/<name>/` as `<name>@skills-dir`, so this install appears as `deno-lsp@skills-dir` across harnesses and devices. The cloned plugin ships:

- `.claude-plugin/plugin.json` with the plugin name `claude-deno-lsp`.
- `.lsp.json` that starts `deno lsp`, maps the Deno/JavaScript extensions, and enables unstable language-server support.

The bundled `.lsp.json` content is the shape NetScript expects. Keep it in the skills-dir plugin; do not check a live `.lsp.json` into a NetScript app just to make Claude Code work:

```json
{
  "command": "deno",
  "args": ["lsp"],
  "extensions": {
    ".ts": "typescript",
    ".tsx": "typescriptreact",
    ".js": "javascript",
    ".jsx": "javascriptreact",
    ".mts": "typescript",
    ".cts": "typescript",
    ".mjs": "javascript",
    ".cjs": "javascript"
  },
  "unstable": true
}
```

## Step 2 - Enable the Claude Code LSP tool globally

Add the LSP tool flag to `~/.claude/settings.json`. If the file already has an `env` object, merge the key rather than replacing the rest of your settings:

```json
{
  "env": {
    "ENABLE_LSP_TOOL": "1"
  }
}
```

Also set the same value as a real user environment variable so terminal and GUI-launched Claude Code processes inherit it.

On Windows:

```powershell
[Environment]::SetEnvironmentVariable('ENABLE_LSP_TOOL','1','User')
```

On macOS and Linux, put this in your shell profile:

```bash
export ENABLE_LSP_TOOL=1
```

## Step 3 - Confirm Deno is on PATH

The plugin runs `deno lsp`, so the `deno` executable must resolve from the environment that launches Claude Code:

```bash
deno --version
```

Use Deno 2.9 or newer for NetScript app work.

## Step 4 - Restart Claude Code completely

Close and reopen Claude Code after installing the plugin or changing the environment. `/reload-plugins` is not enough for the LSP process; the language server and environment need a full process restart.

After restart, open a NetScript app file and use the language features directly:

- Go to definition on a NetScript import or local symbol.
- Find references for a handler, component, or builder.
- Hover a `@netscript/fresh` or Preact symbol.
- Open document symbols for a route, island, service, or task file.
- Read live Deno diagnostics before running the slower project check.

## CLI, VS Code, and Zed notes

The global skills-dir install is the portable path.

**Claude Code surface behavior**

| Name | Type | Description |
| --- | --- | --- |
| `CLI` | `global or one-off` | The global `~/.claude/skills/deno-lsp` install is enough. `claude --plugin-dir <path>` also works for one CLI launch. |
| `VS Code` | `global only` | VS Code launches the same `claude` binary and reads `~/.claude`. CLI-only `--plugin-dir` does not apply here. |
| `Zed` | `ACP over PATH` | Zed 0.202.5 and newer run Claude Code through ACP over the `$PATH` binary. Set `CLAUDE_CODE_EXECUTABLE` if Zed cannot find it, such as when the binary lives inside WSL. |

For VS Code and Zed, prefer the skills-dir install over a one-off CLI flag. That keeps editor sessions, terminal sessions, and harness sessions on the same plugin and Deno LSP settings.

> Root Claude where the code lives
>
> Claude's LSP config discovery is scoped to the workspace root it starts with, which becomes the language server's cwd/rootUri. Files opened from a sibling git worktree outside that root are treated as detached files: the Deno LSP does not see the app's
>
> deno.json
>
> , so Fresh and Preact files can show false positives such as
>
> document
>
> or
>
> useState
>
> inferred as
>
> any
>
> , or
>
> This JSX tag requires 'React' to be in scope
>
> .
>
> That is expected LSP behavior. Launch Claude Code with the repository or worktree as the root, or add the worktree directory to the session:
>
> ```
> claude --continue --add-dir "<worktree-abs-path>"
> ```
>
> For Fresh and Preact apps, the app-level `deno.json` must be inside the discovered scope so the LSP sees `jsx: "precompile"`, `jsxImportSource: "preact"`, and the DOM libraries. When LSP diagnostics look wrong inside a worktree, trust `deno task check`; it is the project source of truth.

## Quick verification

Run these checks after the restart:

```bash
which deno
deno --version
echo "$ENABLE_LSP_TOOL"
```

Then open a file under the NetScript app root and confirm hover, definition lookup, document symbols, and live diagnostics work from the same Claude Code session. If the diagnostics disagree with the project check, root the session at the app or worktree and run:

```bash
deno task check
```

Use that command as the final verdict for the workspace.

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deno-lsp-code-intelligence/_

---

# Deploy to Deno Deploy

**Goal:** push a NetScript workspace to [Deno Deploy](https://deno.com/deploy) with a single first-class command — `netscript deploy deno-deploy <op>` — preflighting it for the hosted platform, pushing a preview, promoting to production, and reading status and logs, without hand-rolling a `deno deploy` invocation.

This is the one **runnable managed-platform** path in NetScript today. It is a thin router over the native `deno deploy` CLI: NetScript resolves your `deploy.targets['deno-deploy']` config, layers any flags on top, runs an unstable-API guard, and shells out to `deno deploy`. Authentication, upload, and the platform itself are all owned by the `deno deploy` CLI — NetScript adds the preflight and the config-to-argv wiring, nothing more.

> This is the managed-platform path; the container/VM path is still manual
>
> netscript deploy deno-deploy
>
> is fully wired and runnable. The Docker, Compose, and Linux/systemd targets are
>
> config schema only
>
> — there is no runnable
>
> netscript deploy docker|compose|linux
>
> verb yet. For those targets you assemble the deployment yourself from the primitives in the
>
> Deploy
>
> recipe.

## Before you start

**What you need before your first push**

| Name | Type | Description |
| --- | --- | --- |
| `A healthy workspace` | `netscript init` | A workspace that passes `deno task check`. If you have not built one, start with [Quickstart](https://rickylabs.github.io/netscript/quickstart/). |
| `The deno deploy CLI on PATH` | `external CLI` | NetScript shells out to `deno deploy …`. The `deploy` subcommand ships with a current Deno; confirm `deno deploy --help` resolves before you start. |
| `A Deno Deploy account + auth` | `deno deploy login` | Authentication is delegated entirely to the `deno deploy` CLI — its own token/login flow. NetScript issues no credentials and stores no token. Log in with the CLI (or supply its auth env vars) first. |
| `An organization + app name` | `org / app` | The Deno Deploy organization slug and the application/project name to deploy into. Provide them as config or flags (below). |

> Where the command lives (and where it does not)
>
> The surface is the CLI subcommand
>
> netscript deploy deno-deploy
>
> , wired inside
>
> packages/cli
>
> . There is
>
> no
>
> @netscript/deploy
>
> package and no rollback, secrets, or health-gating command — those are described in the deployment doctrine as a future wave, not shipped. Document and rely on only the five operations below.

## Configure the target (`deploy.targets['deno-deploy']`)

Set defaults once in `netscript.config.ts` under `deploy.targets['deno-deploy']`. Every field is optional — you can pass everything as flags instead — but config keeps a repeatable push to one line.

```ts
// netscript.config.ts
export default {
  deploy: {
    targets: {
      "deno-deploy": {
        org: "my-org",          // Deno Deploy organization slug  → deno deploy --org
        app: "my-app",          // application / project name      → deno deploy --app
        entrypoint: "main.ts",  // default "main.ts"               → positional arg to deno deploy
        prod: false,            // default false; true adds --prod
        envFile: ".env.production", // passed as `--env-file <path>` to deno deploy
      },
    },
  },
};
```

**deploy.targets['deno-deploy'] fields (all optional)**

| Name | Type | Description |
| --- | --- | --- |
| `org` | `string` | Deno Deploy organization slug. Forwarded as `--org`. |
| `app` | `string` | Application / project name. Forwarded as `--app`. |
| `entrypoint` | `string` | Module the platform runs. Defaults to `main.ts`. Passed as the positional argument to `deno deploy`. |
| `prod` | `boolean` | Defaults to `false` (preview). When `true`, the push adds `--prod`. |
| `envFile` | `string (path)` | Environment file path. Passed straight through as `--env-file <path>` to `deno deploy` (see the callout below). |

> envFile is `--env-file`, not `deno deploy env load`
>
> Some older docstrings describe
>
> envFile
>
> as being "loaded via
>
> deno deploy env load
>
> ". The shipped adapter does
>
> not
>
> call
>
> env load
>
> ; it appends
>
> --env-file <path>
>
> to the
>
> deno deploy
>
> invocation. Treat the value as a path to a
>
> .env
>
> -style file that
>
> deno deploy
>
> reads directly.

> Flags win over config
>
> Config is the default layer; command-line flags override it per run. Nothing in config is required — a fully flag-driven push (
>
> --org … --app … --entrypoint …
>
> ) works with no
>
> deploy
>
> block at all. This is what lets one workspace target several orgs/apps from different pipelines without editing
>
> netscript.config.ts
>
> .

## The workflow: plan → preview → production

The command exposes five operations. All five share the same resolution flags; `up` adds two more.

**netscript deploy deno-deploy**

| Name | Type | Description |
| --- | --- | --- |
| `plan` | `preflight` | Runs the unstable-API guard only. Never touches the platform. Reports whether the project is Deploy-ready or lists violations. |
| `up` | `push` | Runs the guard, then shells `deno deploy [--prod] …`. Adds `--prod` (promote to production) and `--dry-run` (equivalent to `plan`; does not push). |
| `status` | `read` | Maps to `deno deploy show` to read deployment state. Live-account behavior is pending verification. |
| `logs` | `read` | Shows deployment logs (`deno deploy logs`). |
| `down` | `delete` | Maps to `deno deploy delete` to remove the deployment. Live-account behavior is pending verification. |

**Shared flags (all subcommands) + up-only flags**

| Name | Type | Description |
| --- | --- | --- |
| `--org ` | `shared` | Organization slug. Overrides `org` from config. |
| `--app ` | `shared` | Application / project name. Overrides `app`. |
| `--entrypoint ` | `shared` | Entrypoint module. Overrides `entrypoint` (default `main.ts`). |
| `--env-file ` | `shared` | Env file forwarded as `--env-file` to `deno deploy`. Overrides `envFile`. |
| `--project-root ` | `shared` | Workspace root to resolve config + the guard against. Defaults to the discovered root or the current directory. |
| `--prod` | `up only` | Promote this push to production. Without it, `up` pushes a preview. |
| `--dry-run` | `up only` | Run the preflight without pushing — the same effect as `plan`. |

A typical first deployment walks these steps:

```bash
# Guard-only. No push, no platform mutation. Safe to run any time.
netscript deploy deno-deploy plan --org my-org --app my-app

# Equivalent, via up:
netscript deploy deno-deploy up --dry-run --org my-org --app my-app
```

```bash
# Push a preview deployment (no --prod). If the guard finds unstable-API
# usage it warns but still proceeds for a preview.
netscript deploy deno-deploy up --org my-org --app my-app
```

```bash
# Promote to production. If the guard finds unstable-API usage, this
# REFUSES to push (see the guard callout).
netscript deploy deno-deploy up --prod --org my-org --app my-app
```

```bash
# Read state and logs, or delete the deployment.
netscript deploy deno-deploy status --org my-org --app my-app
netscript deploy deno-deploy logs   --org my-org --app my-app
netscript deploy deno-deploy down   --org my-org --app my-app
```

If your `netscript.config.ts` already carries the `org`/`app`/`entrypoint`, every line above shortens to just `netscript deploy deno-deploy <op>` — the config supplies the rest, and any flag you add wins for that run.

## The unstable-API guard

Before any push, NetScript runs a best-effort **unstable-API guard**. Deno Deploy rejects `--unstable-*` flags, so a project that depends on an unstable API cannot run there — the guard catches this before you upload rather than after the platform rejects it.

**Signatures the guard scans for**

| Name | Type | Description |
| --- | --- | --- |
| `Deno.openKv` | `--unstable-kv` | Deno KV usage. |
| `Deno.cron` | `--unstable-cron` | Deno cron scheduling. |
| `new BroadcastChannel` | `--unstable-broadcast-channel` | Cross-isolate broadcast channels. |
| `Temporal.` | `--unstable-temporal` | The Temporal API. |

> up --prod refuses when the guard finds a violation
>
> The guard reads
>
> deno.json#unstable
>
> plus the entrypoint source (
>
> <root>/<entrypoint>
>
> and
>
> <root>/src/<entrypoint>
>
> —
>
> not
>
> the full module graph). Behavior on a match:
>
> - **`up --prod`** — **refuses** and throws. Deno Deploy would reject the required `--unstable-*` flag, so a KV/cron/broadcast/Temporal project is blocked from production until you remove the dependency or move it off the entrypoint path.
> - **`up` (preview)** — **warns but proceeds**.
> - **`plan` / `up --dry-run`** — reports the violations and exits without pushing.
>
> Because the scan is entrypoint-scoped and best-effort, a clean
>
> plan
>
> is a strong signal, not a proof: an unstable API reached only through a deep import may not be flagged.

Many NetScript runtime plugins (workers, sagas, triggers) require Deno KV and therefore `--unstable-kv`. Those background processors are not a fit for a single Deno Deploy isolate — deploy a KV-free entrypoint (for example a Fresh app or a stateless oRPC service) here, and run the KV-backed processors on infrastructure that permits `--unstable-kv`, as covered in the [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/) recipe.

## Troubleshooting

**Common failures and what they mean**

| Name | Type | Description |
| --- | --- | --- |
| `deno deploy: command not found` | `PATH` | The native `deno deploy` CLI is not resolvable. NetScript only shells out to it. Confirm `deno deploy --help` works in the same shell. |
| `Auth / 401 on push` | `auth` | Authentication is the `deno deploy` CLI's own flow — NetScript stores no token. Log in with the CLI (or provide its auth env vars) and retry. |
| `up --prod throws about unstable APIs` | `guard` | The guard found `Deno.openKv`/`Deno.cron`/`BroadcastChannel`/`Temporal`. Deploy a KV-free entrypoint, or move the unstable usage off the entrypoint path. |
| `Wrong org/app targeted` | `precedence` | Flags override config. Check for a stale `deploy.targets['deno-deploy']` default, or pass `--org`/`--app` explicitly. |
| `env vars not applied` | `env-file` | The value is passed as `--env-file <path>` to `deno deploy`, not `deno deploy env load`. Confirm the path exists and is a `.env`-style file. |
| `down / status behaves unexpectedly` | `platform` | The `deno deploy show`/`delete` subcommands `status`/`down` map to are not yet verified against a live Deno Deploy account, so their exact argv and behavior are pending live-account verification. NetScript isolates the argv in one adapter, so any upstream change is a framework-side fix, not a config error. |

## Where to go next

[Deploy (containers & bare metal)  The manual path: deployable units from appsettings.json, backing services, per-process deno run commands, and the --no-aspire escape hatch.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy/)

[Deploy locally with Aspire  Run the whole graph on one machine under the Aspire AppHost before you ship anything remote.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-local-aspire/)

[Add OpenTelemetry  Wire spans and traceparent propagation to your OTLP collector so a deployed process is observable.](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/)

For every CLI command grouped by workflow, see the [CLI reference](https://rickylabs.github.io/netscript/cli-reference/).

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy-deno-deploy/_

---

# Deploy locally with Aspire

**Goal:** run your whole NetScript workspace on one machine under .NET Aspire — scaffold the AppHost, bring up the resource graph (Postgres, Redis, every service and background processor), and watch it from the Aspire dashboard. This is the **local** orchestration companion to the [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/) recipe (which covers shipping to a remote target); for *why* the AppHost works the way it does, read [Orchestration with Aspire](https://rickylabs.github.io/netscript/explanation/aspire/).

> The order is: scaffold → orchestrate → database
>
> Aspire is
>
> step 2
>
> , before any database command.
>
> netscript init
>
> writes the
>
> aspire/
>
> AppHost;
>
> aspire start
>
> provisions Postgres and Redis and starts every process;
>
> only then
>
> do
>
> netscript db init/generate/seed
>
> work, because those commands migrate the database
>
> through
>
> the running AppHost. Run a db command with no Aspire up and it fails — there is no Postgres for it to reach. See
>
> [Database](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) .

## Prerequisites

**What you need before you start**

| Name | Type | Description |
| --- | --- | --- |
| `A scaffolded workspace` | `netscript init` | Created WITHOUT --no-aspire, so the aspire/ AppHost folder exists. See the CLI reference for init flags. |
| `Docker daemon running` | `container engine` | Aspire provisions Postgres and Redis as local Docker containers. No daemon = the default workflow does not start. |
| `The Aspire CLI` | `aspire (external)` | The aspire restore / aspire start commands are the external .NET Aspire CLI, run from inside aspire/ — not netscript subcommands. |
| `A reachable port range` | `ports` | Dashboard :18888 (HTTPS) / :18889 (HTTP), OTLP :4318, services from :3000, plugin APIs :8091–8099, the Fresh app :8010. |

> No --no-aspire
>
> This recipe assumes the orchestration layer was scaffolded. If you ran
>
> netscript init my-app --no-aspire
>
> there is
>
> no
>
> aspire/
>
> folder and no
>
> aspire start
>
> — you start the Deno processes yourself and supply your own infrastructure. That path is covered in the
>
> Deploy
>
> recipe and the [Aspire explanation](https://rickylabs.github.io/netscript/explanation/aspire/).

## Step 1 — Confirm the AppHost was scaffolded

The AppHost is a small **TypeScript/Node** program (not C#) at `aspire/apphost.mts`, configured by `aspire/aspire.config.json`. `netscript init` generates it; you do not hand-write it. Verify it is on disk before going further:

```bash
# From the workspace root — these two files are the orchestration entry point.
ls aspire/apphost.mts aspire/aspire.config.json
```

`aspire.config.json` pins `language: "typescript/nodejs"`, `appHost.path: "apphost.mts"`, and the Aspire SDK version `13.4.6`. The graph inside the AppHost is **derived from your installed plugins** at boot via `composeAppHost` (from `@netscript/aspire/application`) — add a plugin and its API plus background processor appear in the graph; remove it and they vanish, no edit to `apphost.mts` required. The mechanics are in [Orchestration with Aspire](https://rickylabs.github.io/netscript/explanation/aspire/).

> Regenerate without re-scaffolding
>
> After changing the resource graph, run
>
> netscript generate aspire
>
> from the workspace root. It re-reads
>
> appsettings.json
>
> and regenerates the TypeScript AppHost helpers; it does not replace the rest of the scaffold. Service mutation verbs regenerate those helpers in the same operation:
>
> ```
> netscript service ref add api users
> netscript service ref remove api users
> netscript service set api --port 3010 --enabled true
> ```

## Step 2 — Restore the AppHost SDK (once)

The AppHost runs on its own isolated Node runtime inside `aspire/` so its dependency graph never leaks into your Deno workspace. Restore that runtime once per machine (and after an SDK bump):

```bash
# Run from inside the aspire/ folder. One-time SDK restore.
cd aspire
aspire restore
```

## Step 3 — Start the resource graph

A single `aspire start` translates `appsettings.json` plus the plugin contributions into a coherent resource graph and boots all of it — infrastructure first, then services, plugin APIs, and background processors, with cross-references resolved into injected environment variables:

```bash
# Still inside aspire/. Boots the whole graph; prints the dashboard URL + a login token.
aspire start
```

When boot finishes, `aspire start` prints the dashboard address and a one-time login token. The graph a single run stands up:

**What `aspire start` brings up (the local resource graph)**

| Name | Type | Description |
| --- | --- | --- |
| `aspire (dashboard)` | `https://localhost:18888 / http://localhost:18889` | The Aspire dashboard. Live resource list, console logs, structured logs and traces. A login token is printed on start. |
| `OTLP collector` | `http://localhost:4318` | OpenTelemetry endpoint (http/protobuf) the dashboard runs; framework spans and structured logs land here automatically. |
| `postgres` | `Container` | Provisioned via Docker. The database `netscript db` commands target — reachable only once Aspire is up. Postgres is the recommended engine — pass `--db postgres` at init; `--db mysql` or `--db mssql` select those engines (each also an Aspire container), or `--db sqlite` for a file-backed database with no container. |
| `redis` | `Container (cache)` | Redis cache — the default `--cache-backend`; Redis-compatible. Backs KV/queue workloads for the runtime plugins. Swap it for `garnet` (also a container) or app-level `deno-kv` via `--cache-backend`. |
| `users (example service)` | `:3000+ (SERVICE range, OS-allocated from 3000)` | The scaffolded oRPC service, when you init with --service. OpenAPI at /api/v1/users/* and RPC at /api/rpc/*. |
| `plugin APIs` | `:8091–8099 (PLUGIN_API range)` | Each installed runtime plugin's HTTP API (workers, sagas, triggers, auth). Ports are allocated from the plugin range, not hardcoded. |
| `background processors` | `executables (no port)` | Each plugin's isolated runners (workers, sagas, triggers) — separate processes, not threads inside the API. |
| `dashboard (Fresh app)` | `:8010` | The scaffolded Fresh frontend, when present (the app range start 8000 + 10). |

> Plugin API ports are range-allocated, not fixed
>
> The runtime plugins publish their APIs from the
>
> :8091–8099
>
> PLUGIN_API
>
> range, and services from the
>
> :3000–3099
>
> SERVICE
>
> range. The conventional assignments (workers
>
> :8091
>
> , sagas
>
> :8092
>
> , triggers
>
> :8093
>
> , auth
>
> :8094
>
> ) are what a default four-plugin workspace lands on — but the dashboard's resource list is the authority for the exact port each resource bound, not a memorized number. Read it from there.

## Step 4 — Initialize the database (through the running AppHost)

With Aspire up, your database engine is live and the `netscript db` commands can reach it. The resource graph above shows Postgres — the recommended engine and the one these recipes use; if you scaffolded with `--db mysql` / `--db mssql` you get that container instead, and `--db sqlite` gives a file-backed database with no Aspire container. Run the commands from the **workspace root** (a second terminal — leave `aspire start` running in the first):

```bash
# From the workspace root, with `aspire start` still up in another terminal.
netscript db init --name init   # create + apply the first migration
netscript db generate           # generate the Prisma client
netscript db seed               # optional: seed development data
```

These talk to the Postgres container Aspire provisioned. Outside Aspire (an isolated CI container, say), point them at your own database via `POSTGRES_URI` / `DATABASE_URL` instead — covered in

[Database & migration](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/) .

## Step 5 — Use the dashboard

Open `https://localhost:18888`, paste the login token `aspire start` printed, and you have a single pane over the running graph:

**Aspire dashboard surfaces**

| Name | Type | Description |
| --- | --- | --- |
| `Resources` | `tab` | Every container and executable above with status, endpoints, and the resolved environment. The authority for which port each resource bound. |
| `Console logs` | `tab` | stdout/stderr per resource — a failing background processor is one click away, not buried in a terminal. |
| `Structured logs + Traces` | `tab` | Spans and structured logs your handlers emit, correlated by traceparent across services. Aspire collects them via the OTLP endpoint at :4318. |

Because Aspire starts each resource with its `OTEL_SERVICE_NAME` and an OTLP endpoint pointed at `http://localhost:4318`, framework-level spans (job dispatch, job execution, scheduler runs) surface here with no extra wiring. See [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

for the framework-vs-scaffold span boundary.

## In-production pitfalls

> Aspire is the LOCAL story — not a production deployer
>
> aspire start
>
> exists to make
>
> git clone
>
> → one command produce a complete, observable, correctly-wired stack on
>
> one machine
>
> . The Postgres and Redis it starts are throwaway Docker containers for dev convenience —
>
> not
>
> your production database or cache. For a remote target you point processes at managed infrastructure and let your platform own lifecycle; that is the
>
> Deploy
>
> recipe.

> Footguns when `aspire start` will not boot
>
> - **Docker not running.** Aspire provisions Postgres + Redis through Docker; no daemon means the default local workflow cannot start. Start Docker, or use the `--no-aspire` path with your own infrastructure.
> - **Wrong directory.** `aspire restore` and `aspire start` run from inside `aspire/`. `netscript db` commands run from the **workspace root**. Mixing them up is the most common first-run error.
> - **db command before `aspire start`.** Every `netscript db` command needs a live Postgres. Run it with no Aspire up and it fails fast — bring the graph up first.
> - **Ports in use.** The dashboard wants `:18888`/`:18889` and OTLP `:4318`; services and plugin APIs claim the `:3000+` and `:8091–8099` ranges. A stale prior run holding a port blocks boot — check the dashboard resource list (or your process table) and free it.
> - **The AppHost is Node, your app is Deno.** The two runtimes are isolated on purpose; an `aspire restore` failure is a Node/SDK problem in `aspire/`, not a Deno workspace problem.

## See also

- **Why it works this way:** [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

  — the AppHost, plugin contributions, two-pass reference resolution, and the dashboard.
- **Ship it remotely:** [Deploy](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy/) — the production companion: deployable units, backing services, and the `--no-aspire` path.
- **The database sequence:** [Database](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) and

[Database & migration](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/) .

- **Exact symbols + full port map:** [the Aspire reference](https://rickylabs.github.io/netscript/netscript/reference/aspire/)

  and the [CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) .

[Graceful shutdown](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/graceful-shutdown/) [How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/)

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy-local-aspire/_

---

# Deploy a NetScript workspace

**Goal:** take the workspace you scaffolded with `netscript init` and run it somewhere other than your laptop — a container host, a VM, or a managed platform — with clear expectations about what the scaffold wires for you and what you still own.

This is a task recipe, not a one-click button. NetScript is in alpha, and the scaffold is deliberately minimal about deployment: it gives you a single declarative description of every process (`appsettings.json`), runnable Deno entrypoints with explicit permissions, the Aspire AppHost that orchestrates them locally and can publish deployment artifacts for targets you configure in it, and starter GitHub Actions workflows for the shipped deployment targets. The CLI has thin deploy routers for Deno Deploy, Docker/Compose, Kubernetes, Azure, and Cloud Run, but it does **not** generate a `Dockerfile`, a `docker-compose.yml`, or a finished cloud infrastructure stack for you — target-specific infrastructure still lives in Aspire and your cloud account, assembled from the verified facts below.

> What is wired vs. what is manual
>
> Wired:
>
> a declarative resource graph in
>
> appsettings.json
>
> (ports, entrypoints, permissions, env vars, dependencies), runnable per-process Deno entrypoints, and the Aspire AppHost (
>
> aspire/apphost.mts
>
> ) for local orchestration.
>
> Generated CI starters:
>
> .github/workflows/deploy-compose-ghcr.yml
>
> ,
>
> .github/workflows/deploy-deno-deploy.yml
>
> , and
>
> .github/workflows/deploy-bare-metal.yml
>
> .
>
> Delegated:
>
> Docker/Compose, Kubernetes, and Azure target commands call
>
> aspire publish
>
> ,
>
> aspire deploy
>
> , and
>
> aspire destroy
>
> against the generated AppHost code. Aspire emits the manifests and provisions supported resources; your cloud account, cluster credentials, registry access, and RBAC remain yours. Cloud Run follows the Docker-image provider lane: Docker builds and pushes the image, then
>
> gcloud run deploy
>
> applies it.
>
> Manual:
>
> there is
>
> no
>
> generated container image, compose file, or finished cloud infrastructure stack.
>
> netscript.config.ts
>
> ships an empty
>
> deploy: {}
>
> block unless you configure a target. You assemble the production target yourself from the primitives below — every one of which is a verified fact you can copy verbatim.
>
> Migration (#337):
>
> Windows deploy settings now live under
>
> deploy.targets.windows
>
> (previously
>
> deploy.windows
>
> ).

> Generated CI follows the shipped targets
>
> The scaffolded workflows cover the deploy surfaces that ship today:
>
> Deno Deploy
>
> (
>
> netscript deploy deno-deploy up
>
> ),
>
> Compose/GHCR
>
> (
>
> netscript deploy compose plan
>
> +
>
> netscript deploy docker up
>
> ), and
>
> bare metal
>
> (
>
> netscript deploy build
>
> ). They are intentionally starter pipelines: fill in repository secrets, GitHub environment protection, host credentials, and target-specific configuration before you treat them as production release jobs. See
>
> Deploy to Deno Deploy
>
> for the managed-platform command reference.

> Managed deployment commands
>
> There is now a first-class, runnable managed-platform path:
>
> `netscript deploy deno-deploy <op>`
>
> (
>
> plan
>
> /
>
> up
>
> /
>
> status
>
> /
>
> logs
>
> /
>
> down
>
> ) pushes a workspace to
>
> Deno Deploy
>
> over the native
>
> deno deploy
>
> CLI, with a preflight guard and
>
> deploy.targets['deno-deploy']
>
> config. Aspire-backed targets are also routed:
>
> netscript deploy docker|compose|kubernetes|azure-aca|azure-app-service|azure-aks|cloud-run <op>
>
> delegates to the target adapter. See
>
> Deploy to Deno Deploy
>
> for Deno Deploy details.

## Before you start

You need a working, type-checked workspace and a clear idea of where it is going. If you have not built one yet, start with [Quickstart](https://rickylabs.github.io/netscript/quickstart/) and the [Storefront tutorial](https://rickylabs.github.io/netscript/tutorials/storefront/). Then confirm the workspace is healthy locally before you try to move it:

```bash
deno task check    # type-check apps, services, contracts
deno task lint
deno task test
```

For the orchestration model that underpins everything below — why the AppHost lives in its own `aspire/` folder, and how it provisions Postgres and Redis — read the [Aspire explanation](https://rickylabs.github.io/netscript/explanation/aspire/) alongside this recipe.

## The mental model: three layers

A NetScript deployment is three layers, and you choose how much of each you keep in production:

1. Backing services

Postgres (the recommended database; `mysql`, `mssql`, or `sqlite` are first-class alternatives via `--db`) and Redis (KV/cache — the default `--cache-backend`; `garnet` and `deno-kv` are alternatives). In dev, Aspire provisions Postgres/MySQL/SQL Server as containers (`sqlite` is file-backed, no container) and Redis as a container. In production you bring your own — managed database, managed Redis-compatible cache.

2. NetScript processes

Each API service, plugin service, background processor, and the Fresh app is one Deno process with an entrypoint, a port, and an explicit permission set — all declared in appsettings.json.

3. Orchestration

Aspire's AppHost wires the graph together locally. In production you can keep Aspire (it can publish a deployment manifest) or drop it and run each process yourself with your own supervisor.

## Step 1 — Know your deployable units (`appsettings.json`)

`appsettings.json` is the single source of truth for *what runs*. The CLI writes it during `netscript init` and updates it as you `netscript plugin install`. Every Aspire resource — and every process you would deploy by hand — is described there. From a workspace with the four first-party plugins installed, the graph looks like this:

**Resources declared in appsettings.json (verified from a scaffolded workspace)**

| Name | Type | Description |
| --- | --- | --- |
| `users` | `service · :3000 (the scaffold default; the exact port is OS-allocated from the SERVICE range starting at 3000)` | Example oRPC service. Entrypoint `src/main.ts`, runtime `deno`. RPC mounts under `/api/rpc/*`. |
| `streams` | `plugin · :4437` | durable-streams runtime service. `RequiresDb=false`, `RequiresKv=false`. Real producer runtime — see Step 6. |
| `workers-api` | `plugin · :8091` | Workers API. Requires DB + KV. References `streams`. |
| `sagas-api` | `plugin · :8092` | Sagas API. Requires DB + KV. References `workers-api`, `streams`. |
| `triggers-api` | `plugin · :8093` | Triggers API. Typed v1 oRPC contract for trigger/event introspection + management; the webhook ingress endpoint `POST /api/v1/webhooks/:triggerId` stays a raw HMAC-verifying route by design. Requires DB + KV. References `workers-api`, `streams`. |
| `workers / sagas` | `background processor` | Entrypoint `bin/combined.ts`. Watch mode + telemetry on. Workers runtime pool via `WORKERS_CONCURRENCY`; sagas via `SAGA_CONCURRENCY`. |
| `triggers` | `background processor` | Entrypoint `src/runtime/trigger-processor.ts`. Concurrency 10 via `TRIGGER_CONCURRENCY`. |
| `dashboard` | `app · :8010` | Fresh frontend. References service `users`. |
| `postgres / redis` | `infrastructure` | `Mode=Container` in dev. `PrimaryDatabase=postgres`, `PrimaryCache=redis` (the default; `garnet` via `--cache-backend garnet`). |

> Auth service is opt-in (port :8094)
>
> If you add the auth plugin, a fifth API service —
>
> auth-api
>
> on
>
> :8094
>
> — joins the graph. It is an oRPC service exposing five endpoints under
>
> /api/v1/auth/{signin,callback,signout,session,me}
>
> , backed by one active backend selected via
>
> NETSCRIPT_AUTH_BACKEND
>
> (default
>
> kv-oauth
>
> ). Treat it as just another deployable unit: it has an entrypoint, a port, and a permission set in
>
> appsettings.json
>
> like every other process.

Each entry carries the exact information a deploy needs: `Runtime`, `Port`, `Entrypoint`, `Workdir`, `RequiresDb`/`RequiresKv`, the Deno `Permissions` array, the concurrency env var, and `PluginReferences` (the wiring order). When you containerize or write systemd units, copy these values verbatim — do not guess them.

> Permissions are deployment-critical
>
> The
>
> Permissions
>
> array on each resource is the exact Deno permission set that process needs — for example
>
> workers-api
>
> runs with
>
> --unstable-kv --allow-net --allow-env --allow-read --allow-write --allow-run
>
> , while
>
> sagas-api
>
> and
>
> triggers-api
>
> use
>
> --unstable-kv --allow-all
>
> . Reproduce these flags exactly in your run command; a missing
>
> --unstable-kv
>
> will crash any DB/KV-backed process at startup.

## Step 2 — Build and validate a release artifact

There is no opinionated build step that produces a single bundle — each Deno process runs from source. Your "build" is therefore: cache dependencies, type-check, and (optionally) pre-generate the database client and plugin registries so the container does not do it at boot.

```bash
# From the workspace root — prove the graph is healthy before you ship it.
deno task check
deno task lint
deno task test
```

```bash
# Warm the module cache so production start-up does no network fetch.
# Cache each deployable entrypoint you intend to run.
deno cache services/users/src/main.ts
deno cache plugins/workers/services/src/main.ts
deno cache plugins/sagas/services/src/main.ts
deno cache plugins/triggers/services/src/main.ts
```

```bash
# Requires Aspire (and therefore Postgres) up first — see the DB callout below.
# Bake the Prisma client + plugin registries into the artifact so boot is deterministic.
netscript db generate
netscript generate plugins
```

> Aspire is step 2: Postgres comes up before any db command
>
> Every
>
> netscript db <cmd>
>
> talks to a live Postgres. In the scaffold that Postgres is provisioned
>
> by Aspire
>
> . So the order is always:
>
> cd aspire && aspire start
>
> (which brings Postgres and Redis up)
>
> before
>
> any
>
> netscript db init
>
> /
>
> db generate
>
> /
>
> db seed
>
> . Running a DB command with no Postgres reachable — for example in an isolated CI container — fails fast. In production, point the same commands at your managed Postgres via
>
> POSTGRES_URI
>
> or
>
> DATABASE_URL
>
> instead of relying on Aspire. See
>
> Database migration
>
> for the full sequence.

## Step 3 — Provision backing services

In production you do **not** run Postgres and Redis as throwaway Aspire containers. You provision them as durable, managed resources and hand their connection details to NetScript through environment variables. NetScript reads the database URL from `POSTGRES_URI` (falling back to `DATABASE_URL`) and normalizes engine-specific connection strings to a URL — this is handled in `database/postgres/prisma.config.ts`.

**Production environment a NetScript deployment expects**

| Name | Type | Description |
| --- | --- | --- |
| `POSTGRES_URI` | `string (url)` | Primary Postgres connection. `DATABASE_URL` is the accepted fallback. Read by Prisma config. |
| `REDIS_URI / cache url` | `string` | Redis-compatible cache endpoint for the `redis` KV/cache resource (the default backend). With `--cache-backend garnet` the key is `GARNET_URI` for the `garnet` resource (managed Redis or Garnet in prod). |
| `PORT` | `number` | Per-process listen port. Each service reads it (e.g. `Deno.env.get('PORT') ?? '8091'`) and falls back to its default. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `string (url)` | OTLP collector. Dev defaults to `http://localhost:4318` (http/protobuf) via the Aspire dashboard. |
| `NETSCRIPT_SAGA_STORE` | `kv \| prisma` | Durable saga store backend (mandatory when sagas run). Also settable via appsettings `sagas.store.backend`. |
| `NETSCRIPT_AUTH_BACKEND` | `string` | Active auth backend if the auth plugin is installed. Default `kv-oauth`. |
| `WORKERS_CONCURRENCY` | `number` | Workers runtime process pool size. Current Aspire metadata also emits `WORKER_CONCURRENCY`, but the runtime honors `WORKERS_CONCURRENCY`; set the runtime var. |
| `SAGA_CONCURRENCY` | `number` | Sagas background processor concurrency (default 2). |
| `TRIGGER_CONCURRENCY` | `number` | Triggers background processor concurrency (default 10). |

> appsettings.json is your config map
>
> The
>
> Otel.HttpEndpoint
>
> ,
>
> Databases.postgres
>
> ,
>
> Cache.redis
>
> (or
>
> Cache.garnet
>
> when scaffolded with
>
> --cache-backend garnet
>
> ), and per-process
>
> ConcurrencyEnvVar
>
> values in
>
> appsettings.json
>
> tell you every knob to externalize. Treat that file as the contract between your infrastructure and the NetScript processes.

> Queue and saga durability backends are deploy-time choices
>
> Two stateful subsystems pick a backend at deploy time, so decide before you ship:
>
> - **Queue** has four backends — Deno KV, Redis, RabbitMQ, and PostgreSQL. Auto-discovery probes RabbitMQ → Redis → Deno KV only; **PostgreSQL is explicit-provider only** (`provider: 'postgres'` with `connection.postgres.{url, tableName}`).
> - **Sagas** persist durable runtime state to `kv` or `prisma`, selected by `NETSCRIPT_SAGA_STORE` (or appsettings). The selection is mandatory — the runtime throws if it is unset. The Prisma path writes the `saga_runtime_*` tables.
>
> See
>
> Queues & cron
>
> and
>
> Durable sagas
>
> for the full backend matrices.

## Step 4 — Choose an orchestration path

This is the real fork in the road. Pick based on whether your target understands Aspire.

```bash
# The AppHost is a TypeScript/Node project under aspire/ (apphost.mts).
# Locally it provisions Postgres + Redis and wires every process.
cd aspire
aspire restore   # one-time: restore the TS AppHost SDK
aspire start       # boots the full graph; dashboard at https://localhost:18888

# Aspire 13.x can publish/deploy target artifacts from the same AppHost.
netscript deploy kubernetes plan --project-root .
netscript deploy kubernetes up --project-root .
```

```bash
# Scaffold without the orchestration layer, then run processes yourself.
netscript init my-app --no-aspire

# You now own provisioning Postgres + a cache, and starting each process.
# Bring-your-own-supervisor: systemd, a container per process, or a PaaS.
# Start the Fresh app directly during dev:
deno task --cwd apps/dashboard dev
```

> The AppHost is Node/TypeScript, not dotnet
>
> aspire/apphost.mts
>
> is a generated
>
> TypeScript/Node
>
> AppHost (language
>
> typescript/nodejs
>
> , Aspire SDK 13.x, package
>
> Aspire.Hosting.PostgreSQL
>
> ). It is intentionally isolated in
>
> aspire/
>
> so its Node dependency graph never leaks into the Deno root.
>
> netscript.config.ts
>
> records this same path under
>
> aspire.appHost
>
> (
>
> 'aspire/apphost.mts'
>
> ), so the config metadata and the artifact you actually run agree. The dashboard binds
>
> :18888
>
> and the OTLP collector listens on
>
> :4318
>
> .

### Aspire cloud targets

The Aspire-backed target routers all share the same shape:

```bash
# Generate artifacts without applying them.
netscript deploy kubernetes plan --project-root . --output-dir .deploy/kubernetes

# Apply/provision through the validated AppHost platform integration.
netscript deploy azure-aks up --project-root . --output-dir .deploy/azure-aks

# Tear down the previously deployed target.
netscript deploy azure-aks down --project-root . --output-dir .deploy/azure-aks
```

For Kubernetes, add the Aspire Kubernetes integration to the TypeScript AppHost (`aspire add kubernetes`, then `builder.addKubernetesEnvironment('k8s')`). Use `publishAsKubernetesService(...)` in `aspire/apphost.mts` for per-service manifest customization such as replicas, labels, annotations, or extra manifests. `plan` runs `aspire publish --apphost <path> --output-path .deploy/kubernetes`; Aspire emits a Helm chart with `Chart.yaml`, `values.yaml`, and `templates/`.

Apply the published chart with your normal cluster workflow:

```bash
kubectl config current-context
helm upgrade --install my-netscript-app .deploy/kubernetes

# Or inspect/apply rendered manifests if your release process requires kubectl.
helm template my-netscript-app .deploy/kubernetes > .deploy/kubernetes/rendered.yaml
kubectl apply -f .deploy/kubernetes/rendered.yaml
```

For Azure, configure the matching AppHost hosting integration before using the router. The CLI validates the AppHost source contains an Azure Container Apps, Azure App Service, or Azure Kubernetes marker before it shells `aspire publish|deploy --apphost <path>`. Azure CLI login, subscription/location parameters, provider feature registration, and RBAC are operator prerequisites.

For Cloud Run, configure the Docker-image provider fields:

```ts
export default defineConfig({
  // ...
  deploy: {
    targets: {
      'cloud-run': {
        registry: 'us-docker.pkg.dev/acme/prod',
        imageName: 'orders-api:latest',
      },
    },
  },
});
```

`netscript deploy cloud-run up` runs `docker build -t <registry>/<imageName> .`, `docker push <registry>/<imageName>`, then `gcloud run deploy <service> --image <registry>/<imageName> --quiet`.

## Step 5 — Wire generated CI and promotion

New Aspire-backed workspaces include three GitHub Actions starter workflows under `.github/workflows/`:

**Generated deployment workflows**

| Name | Type | Description |
| --- | --- | --- |
| `deploy-compose-ghcr.yml` | `Compose + GHCR` | Restores the Aspire AppHost, emits Compose output with `netscript deploy compose plan`, builds/pushes images to GHCR, then runs `netscript deploy docker up` with `--clear-cache`. |
| `deploy-deno-deploy.yml` | `Deno Deploy` | Runs workspace checks, then calls `netscript deploy deno-deploy up` using GitHub secrets and variables for the Deno Deploy token, organization, and app. |
| `deploy-bare-metal.yml` | `Bare metal` | Compiles service artifacts with `netscript deploy build` on Linux and Windows runners, then uploads the output as workflow artifacts for host-specific installation. |

Treat the workflow `environment` input as the promotion ladder: `development` first, then `staging`, then `production`. In GitHub, map those names to protected environments and keep secrets environment-scoped so a staging run cannot accidentally read production credentials. Promote the same reviewed commit through each environment; do not rebuild from a different branch between staging and production.

> Do not persist Aspire deployment state in CI
>
> Aspire deployment state is cached under
>
> ~/.aspire/deployments/{AppHostSha}/{environment}.json
>
> and may contain plaintext values entered during deployment prompts. The generated Compose/GHCR workflow does not cache
>
> ~/.aspire/deployments
>
> and passes
>
> --clear-cache
>
> to
>
> netscript deploy docker up
>
> , which forwards it to
>
> aspire deploy --clear-cache
>
> . Keep that behavior in CI. If you need durable values, store them in GitHub environment secrets or your platform's secret manager, not in the Aspire deployment cache.

## Step 6 — Run a process by hand (the bare-metal primitive)

Under every option above, the atomic unit is the same: one Deno process started from an entrypoint with the exact permission set from `appsettings.json`. This is what a container `CMD`, a systemd `ExecStart`, or a PaaS start command ultimately becomes. For the workers API (`:8091`), it is:

```bash
# Run from the workspace root. Flags and entrypoint come straight from appsettings.json.
PORT=8091 \
deno run \
  --unstable-kv --allow-net --allow-env --allow-read --allow-write --allow-run \
  plugins/workers/services/src/main.ts
```

The corresponding background processor (which actually executes jobs) runs its own entrypoint:

```bash
# Workers + sagas background processors share bin/combined.ts; triggers uses its own.
WORKERS_CONCURRENCY=2 \
deno run \
  --unstable-kv --allow-net --allow-env --allow-read --allow-write --allow-run \
  workers/bin/combined.ts
```

Map this pattern across every enabled resource and you have a complete, container-free deployment. To containerize, each process becomes one image whose `CMD` is the matching `deno run` line; orchestrate them with compose or your platform of choice, honoring the `PluginReferences` start order (streams → workers → sagas/triggers, plus auth-api when present).

> Limits of the alpha scaffold
>
> - The CLI scaffold does not hand-author a `Dockerfile`, `docker-compose.yml`, or Kubernetes manifest. Docker/Compose, Kubernetes, and Azure artifacts are generated by Aspire from the AppHost code you configure; you write anything Aspire does not emit from the `appsettings.json` facts above.
> - Cloud Run uses the Docker-image provider lane (`docker build`, `docker push`, `gcloud run deploy`) and requires `registry` plus `imageName` in config.
> - `netscript.config.ts` ships an empty `deploy: {}` block unless you configure a target. Generated workflows are starter CI definitions; you still provide registry, host, cloud, and secret-manager configuration before they are production release jobs.
> - Cluster/cloud auth, registry access, RBAC, subscriptions, regions, and provider quotas are operator prerequisites. The CLI shells to Aspire, Docker, or gcloud; it does not create credentials.
> - The `streams` service runs a **real producer runtime** (durable-streams over `@netscript/plugin-streams-core`, served on :4437) — deploy it as a first-class service. What is *not* production-ready is the manifest-helper layer: `@netscript/plugin-streams`'s `defineStreamProducer`/`defineStreamConsumer` **throw `StreamUnsupportedOperationError`** by design (use `@netscript/plugin-streams-core` directly), and there is no in-process consumer `subscribe()` — consumption is HTTP/SSE.
> - The scaffold worker `createJobTools(ctx)` handler helpers (`trace.addEvent`, `withChildSpan`, `progress`) are still no-op stubs (tracked debt, fix planned). Job dispatch/execution traces still appear in Aspire automatically; for custom handler spans call `@netscript/telemetry` helpers directly.
> - DB commands assume a reachable Postgres — in CI/containers without Aspire, inject `POSTGRES_URI` yourself or the command fails fast.

## Step 7 — Verify the deployment

Once your processes are up against real backing services, hit the health endpoints to confirm the graph is wired. These are the exact routes the local runtime exposes (substitute your production host):

**Health and liveness endpoints (verified live)**

| Name | Type | Description |
| --- | --- | --- |
| `GET /health` | `:8091` | Workers API health. |
| `GET /health/live` | `:8092` | Sagas API liveness. |
| `GET /health` | `:8093` | Triggers API health (Hono). |
| `GET /api/v1/workers/jobs` | `:8091` | Lists registered worker jobs — proves the jobs registry generated. |
| `GET /api/v1/sagas/sagas` | `:8092` | Lists registered sagas — proves saga metadata is in KV. |
| `POST /api/v1/webhooks/inbound/generic` | `:8093` | Inbound webhook → enqueues the workers health-check job (end-to-end proof). |
| `GET /api/v1/events?limit=10` | `:8093` | Recent trigger events. |
| `GET /api/v1/auth/session` | `:8094` | Auth session probe (only if the auth plugin is installed). |
| `(dashboard)` | `https://localhost:18888` | Aspire dashboard: every resource, health, logs, distributed traces (Aspire path only). |

```bash
# Smoke a deployed graph (replace localhost with your host).
curl -fsS http://localhost:8091/health
curl -fsS http://localhost:8092/health/live
curl -fsS http://localhost:8093/health
curl -fsS "http://localhost:8091/api/v1/workers/jobs"
```

If every health endpoint returns and `/api/v1/workers/jobs` lists your jobs, the processes are running with their permissions, reaching Postgres/KV, and discovering their registries — the deployment is live.

## Where to go next

[Deploy to Deno Deploy  The one runnable managed-platform path: netscript deploy deno-deploy plan/up/status/logs/down, the unstable-API guard, and deploy.targets['deno-deploy'] config.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-deno-deploy/)

[How Aspire orchestrates it  The AppHost graph, two-pass resource wiring, and why orchestration is a layer you can keep or drop.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

[Database migration  Run db init → generate → seed → status against Postgres — and why aspire start comes first.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/)

[Add OpenTelemetry  Wire spans and traceparent propagation to your OTLP collector in production.](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/)

For the full generated API of each deployable unit, see the reference: [workers](https://rickylabs.github.io/netscript/reference/workers/), [sagas](https://rickylabs.github.io/netscript/reference/sagas/), [triggers](https://rickylabs.github.io/netscript/reference/triggers/), and [streams](https://rickylabs.github.io/netscript/reference/streams/). For every CLI command grouped by workflow, see the [CLI reference](https://rickylabs.github.io/netscript/cli-reference/).

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/_

---

# Graceful shutdown

Drain in-flight requests and jobs, run teardown hooks, and close DB/queue connections when your app receives `SIGINT`/`SIGTERM` — so a deploy or `Ctrl+C` never drops work mid-flight.

## Prerequisites

**What you need**

| Name | Type | Description |
| --- | --- | --- |
| `@netscript/service` | `package` | Provides createService().onShutdown().serve() — signal handling and request draining live here. |
| `@netscript/plugin-workers-core/shutdown` | `subpath export` | ShutdownManager for draining worker/scheduler resources; the worker runtime also exposes a runtime.shutdown handle. |
| `@netscript/queue` | `package (if you consume a queue)` | MessageQueue.listen(handler, { signal }) + stop() let an AbortSignal stop consumption gracefully. |
| `A long-running entrypoint` | `main.ts` | A service or worker process you start with deno run / aspire start that needs to stop cleanly. |

> Signals are wired for you (services)
>
> You do
>
> not
>
> call
>
> Deno.addSignalListener
>
> yourself for a service.
>
> serve()
>
> installs
>
> SIGINT
>
> /
>
> SIGTERM
>
> (or
>
> SIGINT
>
> /
>
> SIGBREAK
>
> on Windows) automatically and drains the HTTP listener before the process exits. You only register
>
> what to tear down
>
> via
>
> .onShutdown()
>
> .

## Step 1 — Drain a service with `.onShutdown()`

`serve()` already drains in-flight HTTP requests. Add `.onShutdown(hook)` to close the things the framework does not own — your database client, an external connection, a flush buffer. Each `ShutdownHook` receives a `ShutdownContext` (`reason`, optional `signal`) and runs during the drain, in LIFO order (last registered, first to run).

```ts
// services/users/src/main.ts
import { createService } from '@netscript/service';
import { router } from './router.ts';
import { db } from '@database';

const running = await createService(router, { name: 'users', version: '1.0.0' })
  .withRPC()
  .withHealth()
  .onShutdown(async ({ reason, signal }) => {
    // reason: 'signal' | 'manual' | 'startup-failure'
    audit.record({ event: 'shutdown', reason, signal });
    await db.$disconnect();
  })
  .serve({
    port: 3001,
    drainTimeoutMs: 10_000, // wait up to 10s for in-flight work
    handleSignals: true,    // SIGINT/SIGTERM (SIGBREAK on Windows) — the default
  });

// In tests or a supervisor, trigger the same drain manually:
await running.stop();
```

The drain is bounded by `drainTimeoutMs` (default `30_000`). When it elapses the service stops anyway and the returned `ShutdownReport` records `timedOut: true` plus a per-hook `ShutdownHookOutcome`. `running.stop()` runs the identical drain with reason `'manual'`; both paths are idempotent, so a double `Ctrl+C` will not double-run hooks.

**Shutdown contract (@netscript/service)**

| Name | Type | Description |
| --- | --- | --- |
| `.onShutdown(hook)` | `ServiceBuilder method` | Registers an async teardown ShutdownHook. Hooks run LIFO during the drain. |
| `ShutdownHook` | `(context: ShutdownContext) => Promise \| void` | Your teardown callback. Throwing is captured, not fatal — it lands in the report as a failed hook. |
| `ShutdownContext` | `{ reason: ShutdownReason; signal?: Deno.Signal }` | signal is set only when reason is 'signal'. |
| `ShutdownReason` | `'signal' \| 'manual' \| 'startup-failure'` | An OS signal, a manual stop() call, or a failed startup hook. |
| `ShutdownReport` | `{ reason; timedOut: boolean; hooks: readonly ShutdownHookOutcome[] }` | Returned by stop(); timedOut is true when the drain budget elapsed first. |

## Step 2 — Configure the drain budget via `serve()`

The drain budget and signal behavior are `ServeOptions` keys. Pass an external `AbortSignal` to stop the listener from anywhere — a parent controller, a test harness, or a higher-level orchestrator — without an OS signal.

**ServeOptions — shutdown-relevant keys**

| Name | Type | Description |
| --- | --- | --- |
| `drainTimeoutMs` | `number?` | Max time to wait for in-flight requests and shutdown hooks before forcing exit. Defaults to 30_000. |
| `handleSignals` | `boolean?` | Install SIGINT/SIGTERM (or SIGBREAK) handlers. Defaults to true — set false only if a parent process owns signals. |
| `signal` | `AbortSignal?` | External signal that stops the listener (and runs the drain) when aborted. Reason is reported as 'manual'. |
| `port` | `number?` | Preferred listener port; 0 for an ephemeral port. |

```ts
// supervisor.ts — stop a service from a parent AbortController
const controller = new AbortController();

const running = await createService(router, { name: 'users' })
  .withRPC()
  .serve({ port: 3001, signal: controller.signal, drainTimeoutMs: 15_000 });

// Anywhere in the parent: triggers the same bounded drain.
controller.abort();
```

## Step 3 — Drain a worker runtime

The worker runtime carries its own `ShutdownManager` and exposes it as `runtime.shutdown`. The runtime pre-registers its worker (priority `20`) and, when present, its scheduler (priority `30`); higher-priority resources stop first. Register your own long-lived resources — a queue consumer, a connection pool — and call `runtime.shutdown.shutdown(reason)` to stop them all under one bounded budget.

```ts
// workers/src/main.ts — drain workers + a queue consumer on signal
import { ShutdownManager } from '@netscript/plugin-workers-core/shutdown';

// runtime.shutdown is a RuntimeShutdownManager: { register, shutdown }
runtime.shutdown.register({
  id: 'queue-consumer',
  priority: 10, // stops after worker (20) and scheduler (30)
  stop: async () => {
    await queue.stop(); // let in-flight messages ack before exiting
  },
});

// Workers do NOT auto-install signal handlers — wire them yourself:
for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  Deno.addSignalListener(signal, () => {
    void runtime.shutdown.shutdown(signal);
  });
}
```

> Workers need their own signal wiring
>
> Unlike a service's
>
> serve()
>
> , the worker runtime does
>
> not
>
> register OS signal handlers for you. Add
>
> Deno.addSignalListener
>
> in your worker entrypoint and route the signal into
>
> runtime.shutdown.shutdown()
>
> . On Windows, listen for
>
> SIGBREAK
>
> instead of
>
> SIGTERM
>
> (the service listener already does this internally for its own signals).

You can also build a standalone `ShutdownManager` directly. Its `createAbortController()` returns an `AbortController` that aborts the moment shutdown starts — feed that signal into `queue.listen(handler, { signal })` so consumption stops cleanly, and `register()` each resource you want stopped (higher `priority` stops first).

**ShutdownManager (@netscript/plugin-workers-core/shutdown)**

| Name | Type | Description |
| --- | --- | --- |
| `register(resource)` | `(ShutdownResource) => void` | Adds a resource: { id, priority?, stop(reason?) }. Higher priority stops first; default 0. |
| `shutdown(reason?, options?)` | `=> Promise` | Stops all registered resources concurrently under timeoutMs (default 30_000); idempotent — returns the same report on repeat calls. |
| `createAbortController()` | `=> AbortController` | An AbortController that aborts when shutdown begins. Pass its .signal to queue.listen({ signal }). |
| `waitForShutdown()` | `=> Promise` | Resolves once shutdown has started — await it to gate your own cleanup. |
| `state` | `'running' \| 'shutting-down' \| 'stopped'` | Current lifecycle state. |

## Step 4 — Stop a queue consumer cleanly

A `MessageQueue` consumer is a long-running `listen()` loop. Two ways to stop it without dropping a message mid-process: pass an `AbortSignal` to `listen()`, or call `queue.stop()` (which lets in-flight messages finish before shutting down). Wiring the `AbortSignal` from a `ShutdownManager` ties consumption directly to your drain.

```ts
// workers/src/consumer.ts — stop consuming when shutdown begins
import { ShutdownManager } from '@netscript/plugin-workers-core/shutdown';

const manager = new ShutdownManager({ timeoutMs: 15_000 });
const { signal } = manager.createAbortController();

// listen() returns when the signal aborts; in-flight messages ack/nack first.
await queue.listen(
  async (message, ctx) => {
    await handle(message);
    await ctx.ack();
  },
  { signal, concurrency: 5 },
);
```

```ts
// workers/src/consumer.ts — drain via stop()
// stop() halts the listen loop and lets in-flight messages complete.
await queue.stop();
```

## In-production pitfalls

> Footguns before you ship
>
> - **Set `drainTimeoutMs` below your platform's kill grace.** The drain defaults to `30_000`. If your orchestrator sends `SIGKILL` sooner (Kubernetes `terminationGracePeriodSeconds` defaults to 30s), in-flight work is cut off — pick a budget comfortably under the grace period.
> - **Workers do not auto-handle signals.** Only a service's `serve()` installs `SIGINT`/`SIGTERM`. A standalone worker entrypoint that omits `Deno.addSignalListener` will be killed ungracefully — register the listener and route it into `runtime.shutdown.shutdown()`.
> - **Use `SIGBREAK`, not `SIGTERM`, on Windows.** Deno does not deliver `SIGTERM` on Windows; the service listener already uses `SIGBREAK` internally, but your own worker signal wiring must too.
> - **A throwing hook does not abort the drain.** A `ShutdownHook` that rejects is captured as a failed `ShutdownHookOutcome` in the report, not re-thrown — inspect the returned `ShutdownReport` (or the logged warning) to catch teardown failures.
> - **Close the DB in a hook, not at module scope.** Call `db.$disconnect()` inside `.onShutdown()` so it runs *after* in-flight requests drain — disconnecting earlier breaks requests still being served.

> No single app-wide shutdown orchestrator yet
>
> Planned The framework drains **each runtime independently**: `serve()` drains a service, `ShutdownManager` drains workers, `queue.stop()` drains a consumer. There is **no** single top-level `host.shutdown()` that orchestrates a service + its workers + its queue + its DB together under one budget. Until that lands, *you* compose them: register every long-lived resource with the worker runtime's `runtime.shutdown`, and put service-owned teardown in `.onShutdown()`. Co-locating a service and workers in one process means wiring both drains in the same entrypoint by hand.

## See also

[service](https://rickylabs.github.io/netscript/netscript/reference/service/)

[Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/)

[Look up — @netscript/service  The full shutdown contract: onShutdown, ServeOptions (drainTimeoutMs, handleSignals, signal), ShutdownReport, and the running.stop() drain.](https://rickylabs.github.io/netscript/netscript/reference/service/)

[Look up — @netscript/workers  ShutdownManager, the runtime.shutdown handle, and the worker/scheduler resources it pre-registers.](https://rickylabs.github.io/netscript/netscript/reference/workers/)

[Do — Tune the worker runtime  Recipe: concurrency, retry, and the runtime knobs that decide how much in-flight work a drain has to wait on.](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/tune-worker-runtime/)

[Understand — The durability model  Why queue messages and saga steps survive a restart — the guarantees a clean drain protects.](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/)

[Run a polyglot task](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/run-a-polyglot-task/) [Deploy locally with Aspire](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-local-aspire/)

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/graceful-shutdown/_

---

# Roll out runtime overrides

Use runtime overrides when operations need to change a deployed behavior without rebuilding the workspace. `watchRuntimeConfig(onChange, options)` watches the runtime config directory, reloads after file changes settle, and passes the current `RuntimeConfig` to your callback.

## Prerequisites

- A writable runtime config directory.
- `NETSCRIPT_RUNTIME_CONFIG_DIR` set for the process that reads overrides.
- The `netscript` CLI with write access to that directory. The CLI creates and atomically replaces the `current` pointer.
- A service or worker process that can call `watchRuntimeConfig(...)` during startup.

## Create an override topic

Runtime config files are versioned behind the `current` pointer. Author the topic payload locally, then publish it; the CLI writes `runtime/<topic>/v<version>.json` before atomically replacing `current`, so readers see either the previous version or the next one.

```bash
export NETSCRIPT_RUNTIME_CONFIG_DIR=/etc/netscript/runtime-config
cat > ./features-v2026-06-22.json <<'JSON'
{
  "flags": [
    { "id": "workers.high-throughput", "enabled": true }
  ]
}
JSON

netscript config override publish features ./features-v2026-06-22.json \
  --version 2026-06-22
```

For a single dashboard-style feature change, the CLI can create and activate the next snapshot directly:

```bash
netscript config override set flags.checkout-v2 --rollout 30
```

## Watch and apply changes

`watchRuntimeConfig(onChange, options)` returns `void`; use an `AbortController` to stop watching during process shutdown.

```ts
import {
  isFeatureEnabled,
  summarizeRuntimeConfig,
  watchRuntimeConfig,
} from '@netscript/runtime-config';

const controller = new AbortController();

watchRuntimeConfig(
  async (config) => {
    const enabled = isFeatureEnabled(config, 'workers.high-throughput', false);
    const summary = summarizeRuntimeConfig(config);

    await publishRuntimeStatus({
      enabled,
      messages: summary.messages,
    });
  },
  {
    signal: controller.signal,
    prefix: 'runtime-config',
  },
);

addEventListener('unload', () => controller.abort());
```

The watcher debounces file churn before reloading. Keep rollout writes atomic anyway: write a new version file first, then replace `current` in a single rename.

## Roll back

Rollback validates that the requested topic version exists, preserves the other active topic pointers, and atomically replaces `current`:

```bash
netscript config override rollback features 2026-06-21
```

The next watcher reload sees the previous version and calls `onChange` again.

## Failure modes

- Missing directory or missing files load as empty defaults so the process can start.
- A malformed pointed-to file is surfaced in the runtime config summary; publish that summary to logs or health output.
- Hand-editing `current` can produce a partial read. Use `config override publish|rollback`, which stage a complete pointer and replace it with one rename.
- A long-running `onChange` callback can lag later updates. Keep the callback bounded and hand off heavier work to a queue.

## Next steps

- Tune worker behavior with [Tune the worker runtime](https://rickylabs.github.io/netscript/background-processing/how-to/tune-worker-runtime/).
- Deploy the process with [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/).
- Look up the package surface in [runtime-config reference](https://rickylabs.github.io/netscript/reference/runtime-config/).

[Deploy locally with Aspire](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/deploy-local-aspire/) [Add a task runtime adapter](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/add-a-task-runtime-adapter/)

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/how-to/roll-out-runtime-overrides/_

---

# Runtime configuration

NetScript splits configuration into two layers: a **typed project config** you author once in `netscript.config.ts` and load at startup (`@netscript/config`), and a **hot-reloadable runtime override layer** that operators roll out without redeploying (`@netscript/runtime-config`). Together they give you one validated, type-safe view of how the app is wired — defaults baked into the schema, values pulled from a config file and the environment, and last-mile operational overrides applied at runtime.

![Configuration resolution chain: schema defaults flow into the loaded config file, environment variables override typed values via resolveEnv, and hot-reloadable runtime override files apply last to produce a frozen resolved config.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/runtime-config-resolution.svg)

*Resolution chain — schema defaults → config file (defineConfig / loadConfig) → environment (resolveEnv / getEnv) → runtime override files (loadRuntimeConfig) → the validated config the framework reads.*

> Use this when
>
> Reach for
>
> project config
>
> (
>
> @netscript/config
>
> ) when you need to declare
>
> how the app is built and wired
>
> — services, ports, databases, plugins, paths — once, with full TypeScript inference and Zod validation. Reach for
>
> runtime overrides
>
> (
>
> @netscript/runtime-config
>
> ) when an
>
> operator
>
> needs to toggle a feature flag, disable a job/saga/trigger, or add a task
>
> without a redeploy
>
> . For one-off typed reads of a single environment variable, use
>
> `getEnv`
>
> . See also
>
> architecture
>
> .

## What it is

Project config is the **static, schema-validated topology** of a NetScript app. You author it with `defineConfig` (or `defineConfigAsync` when the shape depends on mode/command), NetScript validates it against a Zod schema, and `loadConfig` / `initConfig` resolve the authored file into a fully typed `NetScriptConfig`. Environment variables feed into this layer through `resolveEnv` / `getEnv`, which coerce and default typed values per call.

Runtime config is a **separate, dynamic override layer**. It lives under a `runtime/` directory of versioned JSON files (jobs, sagas, triggers, features, tasks) selected by a `current` version pointer. `loadRuntimeConfig` reads it into a `RuntimeConfig` snapshot; `watchRuntimeConfig` reloads on change. Missing files produce **empty defaults** so startup never blocks on overrides that have not been rolled out yet. The two packages are deliberately distinct: `@netscript/config` owns the build-time contract, and `@netscript/runtime-config` owns the hot-reloadable operational layer.

## Learn → / Do →

[Learn — Architecture  How project config, the workspace layout, and the plugin system fit together at startup.](https://rickylabs.github.io/netscript/netscript/explanation/architecture/)

[Do — Choose a queue provider  A config-driven decision recipe: pick and wire a queue backend through project config.](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/choose-a-queue-provider/)

## Minimal example

Author the project config once, then load and inspect it at startup. The `runtimeConfig` section of the project config controls where the **generated** runtime schema/output lives — `netscript generate runtime-schemas` derives those schemas from registered plugin metadata (see [CLI & scaffold](https://rickylabs.github.io/netscript/orchestration-runtime/cli-scaffold/)); the live overrides are read separately by `@netscript/runtime-config`.

```ts
// netscript.config.ts
import { defineConfig } from '@netscript/config';

export default defineConfig({
  name: 'orders',
  version: '1.0.0',
  databases: {
    active: 'postgres',
    config: [{ provider: 'postgres', schema: 'database/postgres/schema' }],
  },
  services: {
    api: { port: 3000 },
  },
  plugins: ['@netscript/plugin-workers'],
});
```

```ts
// src/bootstrap.ts — load project config + apply runtime overrides
import { initConfig, getConfig } from '@netscript/config';
import { isFeatureEnabled, loadRuntimeConfig } from '@netscript/runtime-config';

// 1. Project config: validated once, then read synchronously anywhere via getConfig().
await initConfig();
const config = getConfig();

// 2. Runtime overrides: hot-reloadable JSON the operator controls (empty if unset).
const runtime = await loadRuntimeConfig();
const rolloutOn = isFeatureEnabled(runtime, 'worker-rollout', false);

console.log(config.name, config.services?.api?.port, rolloutOn);
```

## Key types first

The project config you author is `NetScriptConfigInput`; what `loadConfig` / `initConfig` return is the fully validated `NetScriptConfig`. These are the load-bearing fields.

**NetScriptConfig — the validated project config (returned by loadConfig / initConfig / getConfig)**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string (required)` | Project name. |
| `version` | `string (required)` | Project version. |
| `paths` | `PathsConfig (required)` | Workspace path conventions (services, packages, apps, workers, sagas, triggers, plugins, contracts, database, tasks, deploy). |
| `databases` | `DatabasesConfig (required)` | { active?: provider, config: DatabaseConfig[] } — configured databases and the active selector. |
| `plugins` | `string[] (required)` | Enabled plugin package names or specifiers. |
| `services` | `Record?` | Service configuration by service name. |
| `apps` | `Record?` | Frontend application configuration by app name. |
| `logging` | `LoggingConfig?` | { level, format, timestamps, colors? } logging behavior. |
| `aspire` | `AspireConfig?` | { appHost, dashboardPort } Aspire orchestration settings. |
| `sagas / triggers / gateway / sdk / deploy` | `section objects?` | Optional per-capability config sections. |
| `runtimeConfig` | `RuntimeConfigSection?` | Runtime schema/config OUTPUT settings (where generated runtime schema is written) — not the live overrides. |

The runtime override snapshot is a separate type — `RuntimeConfig` — returned by `loadRuntimeConfig()`. Each field is an array loaded from one topic directory.

**RuntimeConfig — the hot-reloadable override snapshot (returned by loadRuntimeConfig)**

| Name | Type | Description |
| --- | --- | --- |
| `jobs` | `JobOverride[]` | Job overrides from runtime/jobs/*.json (enabled, schedule, timeout, maxRetries, timezone, concurrency). |
| `sagas` | `SagaOverride[]` | Saga overrides from runtime/sagas/*.json (enabled, timeout, maxRetries, compensationTimeout). |
| `triggers` | `TriggerOverride[]` | Trigger overrides from runtime/triggers/*.json (enabled, paths). |
| `features` | `FeatureFlag[]` | Feature flags from runtime/features/*.json (id, enabled, description?, rolloutPercentage?). |
| `tasks` | `RuntimeTask[]` | Runtime task definitions from runtime/tasks/*.json (id, name, runtime, entrypoint, enabled?, timeout?, schedule?). |

## Resolution & precedence

There is no single monolithic merge function — resolution happens across the two packages, each with its own precedence. The order below is the conceptual chain the diagram depicts.

**How a value is resolved (lowest precedence first)**

| Name | Type | Description |
| --- | --- | --- |
| `1. Schema defaults` | `@netscript/config` | Zod schema fills omitted fields when defineConfig validates the authored input into NetScriptConfig. |
| `2. Config file` | `loadConfig / initConfig` | File search order: options.configFile → netscript.config.ts → .js → .mjs. cwd resolves from options.cwd → NETSCRIPT_PROJECT_ROOT → Deno.cwd(). |
| `3. Environment` | `resolveEnv / getEnv` | Per-variable: read the env var (def.env overrides the name) and coerce by type (string\|number\|boolean\|json); if absent, use default; if required and absent with no default, throw. |
| `4. Runtime overrides` | `loadRuntimeConfig` | Hot-reloadable JSON under the runtime dir, keyed by the 'current' version pointer; applied per-id (job/saga/trigger/feature/task). Missing files → empty defaults. |

**@netscript/config — primary functions**

| Name | Type | Description |
| --- | --- | --- |
| `defineConfig(input)` | `(NetScriptConfigInput) => NetScriptConfig` | Type-safe, validated config definition for netscript.config.ts. The 80% path. |
| `defineConfigAsync(fn)` | `((env: ConfigEnv) => …) => () => Promise` | Async/env-aware config when the shape depends on { mode, command }. |
| `loadConfig(options?)` | `(LoadConfigOptions?) => Promise` | Find, import, and validate the config file. Options: { cwd?, configFile? }. |
| `initConfig(options?)` | `(LoadConfigOptions?) => Promise` | Load once and cache; call at startup. Then read synchronously via getConfig(). |
| `getConfig()` | `() => NetScriptConfig` | Synchronous access to the cached config; throws if initConfig() has not run. |
| `isConfigLoaded() / clearConfigCache()` | `() => boolean / () => void` | Inspect or reset the config cache (clearConfigCache is for tests/reload). |
| `resolveEnv(schema) / getEnv(name, opts?)` | `typed env readers` | Coerce env vars (string\|number\|boolean\|json) with defaults; getEnv reads one variable. |
| `getMode() / isDev() / isProd() / isTest() / hasEnv(name)` | `env helpers` | Current mode (DENO_ENV/NODE_ENV) and presence checks. |
| `discoverWorkspace(root?) / findWorkspaceRoot(dir) / findMember(ws, name)` | `workspace` | Classify and locate Deno workspace members. |
| `inspectConfig(target)` | `(Partial \| string) => InspectionReport` | JSON-stable diagnostic report for CLI rendering. |

**@netscript/runtime-config — primary functions**

| Name | Type | Description |
| --- | --- | --- |
| `loadRuntimeConfig()` | `() => Promise` | Load overrides from the runtime dir via the 'current' pointer; empty defaults when files are missing. |
| `watchRuntimeConfig(onChange, opts?)` | `(cb, { signal?, prefix? }) => void` | Watch the runtime config files and invoke onChange after debounced reloads. |
| `isFeatureEnabled(config, flagId, defaultValue)` | `(RuntimeConfig, string, boolean) => boolean` | Read a feature flag, falling back when the flag is absent. |
| `getJobOverride / getSagaOverride / getTriggerOverride` | `(RuntimeConfig, id) => …Override \| undefined` | Look up a single override by id. |
| `getRuntimeTask(config, taskId)` | `(RuntimeConfig, string) => RuntimeTask \| undefined` | Get a runtime task definition by id. |
| `summarizeRuntimeConfig(config, prefix?)` | `(RuntimeConfig, string?) => RuntimeConfigSummary` | Structured summary of active overrides (disabled jobs/sagas/triggers/features, message lines) for caller-owned presentation. |
| `RUNTIME_CONFIG_TOPICS` | `('jobs'\|'sagas'\|'triggers'\|'features'\|'tasks')[]` | The topic names backed by versioned JSON files. |

## Runtime override layout

The runtime override directory is resolved from the environment, then read through the `current` pointer that names the active version of each topic file.

```ts
// src/feature-gate.ts
import { isFeatureEnabled, loadRuntimeConfig } from '@netscript/runtime-config';

const runtime = await loadRuntimeConfig();

// Third arg is the fallback when the flag file/entry is absent.
if (isFeatureEnabled(runtime, 'worker-rollout', false)) {
  // run the gated path
}
```

```ts
// src/runtime-watch.ts
import { summarizeRuntimeConfig, watchRuntimeConfig } from '@netscript/runtime-config';

const controller = new AbortController();

watchRuntimeConfig(async (config) => {
  const summary = summarizeRuntimeConfig(config);
  // re-apply overrides; summary.messages is presentation-ready
  console.log(summary.messages.join('\n'));
}, { signal: controller.signal });
```

```ts
// src/env.ts
import { getEnv, resolveEnv } from '@netscript/config';

const port = getEnv('PORT', { type: 'number', default: 3000 });

const env = resolveEnv({
  DATABASE_URL: { env: 'DB_URL', required: true },
  DEBUG: { type: 'boolean', default: false },
});
```

## Production notes

> Two packages, two precedence rules — not one merge
>
> There is
>
> no single function
>
> that merges defaults, file, env, and runtime overrides into one object.
>
> @netscript/config
>
> validates and loads the
>
> project
>
> config; per-variable env coercion is explicit via
>
> resolveEnv
>
> /
>
> getEnv
>
> ; and
>
> @netscript/runtime-config
>
> is a
>
> separate
>
> hot-reloadable layer your code reads with
>
> loadRuntimeConfig
>
> and applies per id. Don't expect a runtime override file to silently change your
>
> NetScriptConfig
>
> — you read and apply the override explicitly.

> Runtime dir resolution & missing files
>
> The runtime override directory is resolved as
>
> NETSCRIPT_RUNTIME_CONFIG_DIR
>
> → else the parent of
>
> NETSCRIPT_TASKS_DIR
>
> → else
>
> ./runtime
>
> . A missing directory, pointer, or topic file is
>
> not an error
>
> —
>
> loadRuntimeConfig
>
> returns empty defaults so startup proceeds while operators roll overrides out independently. Make sure your deployment sets the env var (or the working directory) you expect, or you may silently read empty overrides.

> getConfig() must follow initConfig()
>
> getConfig()
>
> returns the cached config and
>
> throws
>
> if
>
> initConfig()
>
> has not run. Call
>
> initConfig()
>
> once at startup, then read synchronously anywhere. In tests, use
>
> clearConfigCache()
>
> to force a reload between cases.

## Reference →

This hub is intentionally thin — the full generated API surface for both packages lives in the reference.

[runtime-config](https://rickylabs.github.io/netscript/netscript/reference/runtime-config/)

[Look up — @netscript/runtime-config  loadRuntimeConfig, watchRuntimeConfig, the override types, and the topic helpers.](https://rickylabs.github.io/netscript/netscript/reference/runtime-config/)

[Look up — @netscript/config  defineConfig, loadConfig/initConfig, resolveEnv/getEnv, the NetScriptConfig schema, and workspace helpers.](https://rickylabs.github.io/netscript/netscript/reference/config/)

[Understand — Architecture  Where project config, the workspace, and the plugin system sit in the framework.](https://rickylabs.github.io/netscript/netscript/explanation/architecture/)

[Browse — Capabilities  All NetScript capabilities: services, jobs, sagas, triggers, database, and more.](https://rickylabs.github.io/netscript/netscript/capabilities/)

[Polyglot tasks](https://rickylabs.github.io/netscript/netscript/background-processing/polyglot-tasks/) [Capabilities](https://rickylabs.github.io/netscript/netscript/capabilities/)

_Canonical: https://rickylabs.github.io/netscript/orchestration-runtime/runtime-config/_

---

# Services & SDK

**Declare the API once — as a versioned contract — and the server handler, the typed client, the OpenAPI spec, and the query layer all derive from that one object.** That is this pillar in a sentence. A [service](https://rickylabs.github.io/netscript/services-sdk/services/) implements the contract; the [SDK](https://rickylabs.github.io/netscript/services-sdk/sdk/) consumes it. Because both sides import the *same* contract object, a renamed field or a changed response shape is a compile error on both ends before it can ship — there is no hand-written client wrapper to keep in sync, and no separate "update the API docs" step.

That property is not hypothetical. In a production chat application built on NetScript, every dashboard data call goes through a typed client built directly off the contract type: adding a route to the channel contract makes it appear, fully typed, on the browser client with no extra wiring turn. The same discipline pays off whether the code is written by a teammate or an AI agent: one declared shape to read, one place to change it.

Use this pillar when you are defining a service, exposing OpenAPI or Scalar, or connecting a front end to a service without duplicating request and response types. Start with [Services & contracts](https://rickylabs.github.io/netscript/services-sdk/services/) for the server side, then [Typed SDK & client](https://rickylabs.github.io/netscript/services-sdk/sdk/) for the caller side; the type-flow theory lives in [Contracts](https://rickylabs.github.io/netscript/explanation/contracts/).

> TLS & HTTP/2 are opt-in
>
> A service listens over plain HTTP by default. Pass a
>
> tls
>
> option (
>
> ServiceTlsOptions { cert, key }
>
> as PEM strings) to
>
> defineService
>
> or the builder's
>
> .serve()
>
> — or set both
>
> NETSCRIPT_TLS_CERT_FILE
>
> and
>
> NETSCRIPT_TLS_KEY_FILE
>
> (file paths) — and the listener serves HTTPS and negotiates HTTP/2 via ALPN automatically. See
>
> Services → TLS & HTTP/2
>
> .

[Overview & Concepts   Contracts to service to client  The shared model for service handlers, OpenAPI, RPC, and typed clients.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/) [Quickstart   Catalog service  Create the first service in the Storefront tutorial.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/) [How-To   Add a service  Add a new service to a workspace.](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/add-a-service/) [How-To   Discover services  Resolve service URLs and clients from the generated workspace.](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/discover-services/) [How-To   OpenAPI and Scalar  Expose the generated OpenAPI document and Scalar UI.](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/expose-openapi-scalar/) [API Reference   service and sdk  Generated service, SDK, and contract package symbols.](https://rickylabs.github.io/netscript/netscript/reference/service/)

## Learn, do, look up

[Learn  Storefront tutorial  Define contracts and services, then consume them through the typed SDK.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/) [Look up  `@netscript/service` reference  Generated API reference. Related units: `sdk`, `contracts`.](https://rickylabs.github.io/netscript/netscript/reference/service/) [Understand  Contracts & type flow  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)

_Canonical: https://rickylabs.github.io/netscript/services-sdk/_

---

# Services & SDK — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/services-sdk/how-to/_

---

# Add a service

**Goal:** add a new typed oRPC service to an existing NetScript workspace — define its contract, implement the handlers, serve it with `defineService`, and confirm it answers on its own port over both its OpenAPI surface and the `/api/rpc/*` RPC endpoint that typed clients call.

This is a task-oriented recipe. It assumes you already have a NetScript workspace (created with `netscript init`) and that the `netscript` command is on your path. If you want the guided, build-up-from-scratch version that explains *why* each piece exists — contract to typed client to a Fresh island — follow the [Build a service tutorial](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/) instead. For the full generated API of the service runtime, see the [`@netscript/service` reference](https://rickylabs.github.io/netscript/reference/service/); for the concept behind contract-first wiring, read [Contracts, explained](https://rickylabs.github.io/netscript/explanation/contracts/).

A NetScript service is contract-first: a service is the runtime that *implements* an `@orpc/contract` definition. You author the contract once (route + zod input/output), `implement()` it, bind `.handler()`s, then hand the resulting router to `defineService(...)`. The same contract object is what a typed client imports, so the service and its callers cannot drift.

> Two ways to construct a service
>
> Workspace services use
>
> defineService(router, options)
>
> — one call, an options object, the right default for the 80% case. NetScript
>
> plugin
>
> API services (workers, sagas, triggers, auth) instead use the fluent
>
> createService(router, options).withCors().withDatabase(db).withRPC().serve({ port })
>
> builder when they need to layer CORS, OpenAPI, a database client, authn/authz, or custom context step by step. Both stand up the same Hono + oRPC runtime and advertise the identical
>
> /api/rpc/*
>
> endpoint; this recipe uses
>
> defineService
>
> .

## Before you start

**Prerequisites**

| Name | Type | Description |
| --- | --- | --- |
| `A NetScript workspace` | `netscript init` | An existing project on disk. If you do not have one, scaffold it first — see the tutorials. Run commands from the workspace root. |
| `The netscript CLI` | `on your PATH` | Install globally with: deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11 — then confirm with netscript --help. |
| `A contracts workspace` | `contracts/` | The init scaffold ships a shared contracts/ workspace exposed as the @/contracts import alias. New services add their contract here so clients can import it. |
| `A free port` | `:3001 by default` | The example users service listens on :3001. Pick an unused port per service; it is read from the PORT env var with a literal fallback. Plugin API ports are already claimed (workers :8091, sagas :8092, triggers :8093, auth :8094). |

This recipe adds a service named `users` on port `3001`, mirroring the example the scaffold ships, so every path and code shape below matches a real generated workspace. Substitute your own name and port where you see them.

## Step 1 — Scaffold the service (or add one at init time)

The fastest path is to let the CLI scaffold a service workspace for you. If you are creating a brand-new project, pass the service flags straight to `netscript init`:

```bash
netscript init my-app --db postgres --service --service-name users --service-port 3001 --yes
```

`--db postgres` is the recommended default; swap it for `mysql`, `mssql`, or `sqlite` to scaffold a different Prisma-backed engine (`sqlite` is file-backed and runs without an Aspire container).

To add a service to a workspace that already exists, use the `netscript service add` subcommand with the `--name` and `--port` flags (the `service` group also has `list` and `generate` subcommands; `service generate` only regenerates Aspire helper files):

```bash
# from the workspace root
netscript service add --name users --port 3001
```

Either path lays down a `services/users/` workspace member with this shape:

```text
services/users/
├── deno.json              # workspace member; exports ./src/main.ts
└── src/
    ├── main.ts            # defineService(router, { name, version, port, openapi })
    ├── router.ts          # version-namespaced router aggregation
    └── routers/
        ├── v1.ts          # binds the contract: v1.users.list.handler(...)
        └── health.ts      # health.check handler
```

> Naming and the import alias
>
> The service name (
>
> users
>
> ) becomes the workspace folder under
>
> services/
>
> and the service's reported
>
> name
>
> . Its contract lives in the shared
>
> contracts/
>
> workspace and is imported through the
>
> @<project>/contracts
>
> alias (for the example project that is
>
> @my-app/contracts
>
> ) — never via a relative
>
> ../../contracts
>
> path.

## Step 2 — Define the contract

A service implements a contract; define it first. `service add` creates the initial versioned contract and aggregate. Add each procedure through the CLI so it updates the existing contract without hand-editing the aggregate:

```bash
netscript contract add-route users findByEmail \
  --method POST \
  --path /users/by-email \
  --input "z.object({ email: z.string().email() })" \
  --output "UsersListItemSchemaV1.optional()"

netscript contract inspect users
netscript contract inspect users --json
```

The command appends an `@orpc/contract` + Zod route to `contracts/versions/v1/users.contract.ts`. The generated module calls `implement()` so the result is ready for `.handler()` binding. The equivalent source shape is shown below so you know what to customize:

```ts
// contracts/versions/v1/users.contract.ts
import { z } from 'zod';
import { oc } from '@orpc/contract';
import { implement } from '@orpc/server';

export const UsersListItemSchemaV1 = z.object({
  id: z.number().int().positive(),
  name: z.string().min(1),
  summary: z.string().min(1),
  status: z.enum(['active', 'suspended']),
  createdAt: z.string().datetime(),
});

export const UsersContractV1 = {
  health: {
    check: oc.route({ method: 'GET' })
      .input(z.object({}).optional())
      .output(z.object({ status: z.literal('healthy'), service: z.string() })),
  },
  list: oc.route({ method: 'POST' })
    .input(z.object({ limit: z.number().int().positive().optional() }))
    .output(z.object({ items: z.array(UsersListItemSchemaV1) })),
};

// implement() turns the contract object into a .handler()-bindable surface.
export const UsersV1 = implement(UsersContractV1);
```

The CLI maintains this aggregate so callers and the service share one type source:

```ts
// contracts/versions/v1/mod.ts
export { UsersContractV1, UsersV1 } from './users.contract.ts';
export const v1 = { users: UsersV1 };
```

> Contract is the source of truth
>
> Each route is
>
> oc.route({ method }).input(zod).output(zod)
>
> . Calling
>
> implement(UsersContractV1)
>
> produces the object whose
>
> .handler()
>
> the service binds — and the very same contract is what a typed client imports. Change the schema in one place and both the service handler and every caller fail to type-check until they agree.

For a breaking schema change, promote the contract instead of editing v1 in place. This creates the v2 aggregate and updates the root contract exports:

```bash
netscript contract version add users --from v1 --to v2
netscript contract list
```

## Step 3 — Implement the handlers

Create the binding stub with the paired service verb, then replace its intentional `Not implemented` error with your business logic:

```bash
netscript service add-handler users findByEmail
```

The command verifies that `findByEmail` exists in the users contract, then appends a compiling `.handler()` binding to `services/users/src/routers/v1.ts`. Import the contract through the project alias, not a relative path. At this scaffold stage handlers can return seeded in-memory records — no database is wired yet, which keeps the contract↔client proof isolated.

```ts
// services/users/src/routers/v1.ts
import { v1 } from '@my-app/contracts';

const seeded = [
  { id: 1, name: 'Ada Lovelace', summary: 'first programmer', status: 'active' as const, createdAt: new Date().toISOString() },
];

export const UsersV1 = {
  list: v1.users.list.handler(async ({ input }) => ({
    items: seeded.slice(0, input.limit ?? seeded.length),
  })),
};
```

```ts
// services/users/src/routers/health.ts
import { v1 } from '@my-app/contracts';

export const health = {
  check: v1.users.health.check.handler(async () => ({
    status: 'healthy' as const,
    service: 'users',
  })),
};
```

Aggregate the handlers into a version-namespaced router:

```ts
// services/users/src/router.ts
import { UsersV1 } from './routers/v1.ts';
import { health } from './routers/health.ts';

export const v1 = { users: { ...UsersV1, health } };
export const router = { v1 };
```

## Step 4 — Serve it with `defineService`

`netscript service add` already creates this entry point and registers it in appsettings and the Deno workspace; `netscript service generate` can regenerate Aspire helpers after later config edits. The service entry point passes the router to `defineService(...)`. The port reads from the `PORT` env var with a literal fallback so the same code runs locally and under Aspire.

```ts
// services/users/src/main.ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';

await defineService(router, {
  name: 'users',
  version: '1.0.0',
  port: parseInt(Deno.env.get('PORT') || '3001'),
  openapi: { title: 'Users API', description: 'users service' },
  debug: true,
});
```

Aspire injects `PORT` at runtime, so the entrypoint reads it from the environment; the typed source of truth is your `netscript.config.ts` `services.<name>.port` field, which the scaffold wires as the fallback default — set the port there rather than editing this line.

`defineService` stands up the Hono + oRPC runtime, mounting your router under both an OpenAPI surface (`/api/v1/users/*`) and the RPC surface (`/api/rpc/v1/...`). The default RPC mount point is `/api/rpc` and the OpenAPI mount point is `/api`; both are overridable via the builder's `rpcPath` / `apiPath` options if you reach for `createService`.

To reverse this lifecycle, `netscript service remove users` removes the service workspace, appsettings/workspace registrations, paired contracts, and regenerated helpers. Pass `--keep-contract` when the API definition must remain published after the runtime is retired.

> Need CORS, a database, or auth? Use createService
>
> When a service must layer cross-cutting concerns, swap
>
> defineService
>
> for the fluent builder. Each step returns the builder, so you compose only what you need before
>
> .serve({ port })
>
> :
>
> ```
> const app = createService(router, { name: 'users', version: '1.0.0' })
>   .withCors()
>   .withDatabase(db)
>   .withAuthn({ authenticator })
>   .withAuthz({ authorizer })
>   .withRPC();
> await app.serve({ port: 3001 });
> ```
>
> The authn/authz seam (
>
> @netscript/service/auth
>
> ) is provider-agnostic — static-credential and trusted-header authenticators plus a scope authorizer ship built in. It is distinct from the auth
>
> plugin
>
> backends; see
>
> Authentication
>
> .

## Step 5 — Run and verify

Start just this service workspace directly, or let `aspire start` orchestrate it alongside the rest of your resources:

```bash
# run only the users service
deno task --cwd services/users dev
```

You should see it bind on `:3001`. Confirm the runtime answers — the health route over HTTP, and the RPC surface that typed clients call:

```bash
# OpenAPI / HTTP surface
curl http://localhost:3001/api/v1/users/health

# RPC surface (what the generated typed client uses)
curl -X POST http://localhost:3001/api/rpc/v1/users/list \
  -H 'content-type: application/json' -d '{"limit":10}'
```

A healthy service returns `{"status":"healthy","service":"users"}` from the health route and the seeded `items` array from `list`. A typed client imports `UsersContractV1` from `@my-app/contracts` and calls `.list(...)` with full input/output inference — no codegen, no drift.

> Production pitfalls
>
> Port collisions.
>
> Every service needs a distinct port; the workers (
>
> :8091
>
> ), sagas (
>
> :8092
>
> ), triggers (
>
> :8093
>
> ), and auth (
>
> :8094
>
> ) plugins already claim theirs. Read the port from
>
> PORT
>
> and let Aspire assign it in orchestrated runs rather than hard-coding.
>
> RPC lives under `/api/rpc/*`.
>
> The typed-client surface is
>
> /api/rpc/<version>/<router>/<procedure>
>
> , not a bare
>
> /rpc
>
> . The REST/OpenAPI surface is
>
> /api/*
>
> . Point clients and smoke tests at the right one.
>
> Contracts before handlers.
>
> Edit the contract first, then the handler — never the reverse. The contract is the shared truth; a handler that out-runs its contract silently breaks every client.
>
> Use the import alias.
>
> Import contracts via
>
> @<project>/contracts
>
> , not a relative path, so the service and its clients resolve the identical type.
>
> No DB yet at this step.
>
> The scaffold handlers return seeded in-memory records. Wire persistence with the database recipe before you depend on durability.

## See also

[Tutorial: Build a service  The guided, learning-oriented version — contract to typed client to a Fresh island, explained step by step.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[Service API reference  The full generated surface of defineService and createService — every option, builder method, and return type.](https://rickylabs.github.io/netscript/netscript/reference/service/)

[Contracts, explained  How an oRPC contract flows from service to typed client to UI without a codegen step.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)

[Database & migration  Replace the seeded in-memory records with real Prisma-backed persistence — Postgres is the recommended engine, or mysql / mssql / sqlite via --db — init, generate, seed (Aspire up first).](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/database-migration/)

Manage the service over its lifetime by editing its contract under `contracts/versions/` and re-running your workspace gates (`deno task check`). For the concepts behind contract-first services, read the [contracts explanation](https://rickylabs.github.io/netscript/explanation/contracts/); for the capability overview, see [Services](https://rickylabs.github.io/netscript/capabilities/services/).

_Canonical: https://rickylabs.github.io/netscript/services-sdk/how-to/add-a-service/_

---

# Discover services

**Goal:** call another plugin's (or another workspace member's) oRPC service from your app, end to end — declare the dependency so Aspire injects the callee's URL, then obtain a fully typed client from `@netscript/sdk` that resolves that URL at request time. No registry, no hardcoded `localhost:<port>`, no codegen.

alpha

There is **no service-registry API** in NetScript. "Discovery" is two cooperating mechanics: Aspire injects each referenced service's resolved endpoint as an environment variable (`services__<name>__http__0`), and the SDK's typed client reads that variable lazily via `@netscript/sdk/discovery` when it builds the request URL. Declare the reference, import the contract, construct the client — that is the whole recipe.

![The shared contract object feeds the generated typed client; the client resolves the callee's URL from an Aspire-injected services__ env var and issues a cache-first oRPC query that the same contract's service implements.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/sdk-data-flow.svg)

*Discovery flow: shared contract → typed client → URL resolved from the Aspire services__ env var → oRPC call to the service that implements the same contract.*

## Before you start

**Prerequisites**

| Name | Type | Description |
| --- | --- | --- |
| `A NetScript workspace` | `netscript init` | An existing project with at least the caller (an app, plugin, or service) and the callee service already present. Run commands from the workspace root. |
| `The callee service` | `services//` | A target service that answers on its own port over /api/rpc/* — e.g. the example users service on :3001. See the Add a service recipe to create one. |
| `@netscript/sdk` | `import alias` | The SDK provides the typed client (createServiceClient / defineServices) and the discovery readers (@netscript/sdk/discovery). It is a workspace dependency of apps and consuming services. |
| `The shared contract` | `@/contracts` | Both the service and the caller import the SAME oRPC contract object through the project alias, so the client's input/output types are inferred — never duplicated. |
| `Aspire (for resolved URLs)` | `aspire start` | Aspire injects the services____http__ env vars that discovery reads. Without it you must set those vars yourself (see pitfalls). |

This recipe assumes the callee is the example `users` service (port `3001`) and the caller is an app or another service. Substitute your own service name throughout.

## Step 1 — Declare the service reference

The caller declares which services it depends on by name in its resource entry under `ServiceReferences`. The init scaffold already writes this into the Aspire `appsettings.json` when you scaffold an app against a service; to add a dependency to an existing resource, add the callee's name to that resource's `ServiceReferences` array.

```jsonc
// aspire/appsettings.json — the caller (an app here) depends on the users service
{
  "NetScript": {
    "Apps": {
      "web": {
        "Runtime": "deno",
        "Type": "app",
        "Port": 3000,
        "ServiceReferences": ["users"]
      }
    }
  }
}
```

`ServiceReferences` is the live field. The names you list here must match the service resource keys under `NetScript.Services`.

> What the reference actually wires
>
> At generate time the Aspire helper does a two-pass registration: pass 1 creates every service resource, pass 2 walks each resource's
>
> ServiceReferences
>
> and, for each referenced name, calls
>
> getEndpoint('http')
>
> on the target and injects it into the caller as
>
> services__<name>__http__0
>
> via
>
> withEnvironment(...)
>
> . That env var is exactly what the SDK's discovery layer reads at request time — so declaring the reference is what makes
>
> getServiceUrl('users')
>
> resolve.

## Step 2 — Regenerate the Aspire helpers

The `register-services` helper that performs the two-pass wiring is generated from `appsettings.json`. After editing `ServiceReferences`, regenerate so the new dependency is emitted into the AppHost helpers:

```bash
# from the workspace root — regenerates the Aspire helper files only
netscript service generate
```

`service generate` only rewrites the Aspire helper files (it does not touch your service code). The next `aspire start` will inject the `services__users__http__0` variable into the caller's environment.

## Step 3 — Construct the typed client

In the caller, import the **same contract object** the service implements and hand it to `createServiceClient`. The `serviceName` you pass is the discovery key — it must match the name you referenced in Step 1. The client is fully typed from the contract; there is no generated client file to import.

```ts
// web/src/clients/users.ts — a typed client for the discovered users service
import { createServiceClient } from '@netscript/sdk/client';
import { UsersContractV1 } from '@my-app/contracts';

// serviceName is the discovery key — it resolves services__users__http__0 at call time.
export const usersClient = createServiceClient({
  contract: UsersContractV1,
  serviceName: 'users',
});

// Fully inferred input/output — a renamed contract field is a compile error here.
const { items } = await usersClient.list({ limit: 20 });
```

The URL is resolved **lazily**, on the first call, by the internal HTTP link — so the client can be constructed at import time (even in a browser bundle) without touching Deno APIs. By default it targets `<resolved-url>/api/rpc/v1/<service>` over HTTP.

**CreateServiceClientOptions (createServiceClient) — confirmed surface**

| Name | Type | Description |
| --- | --- | --- |
| `contract` | `TContract (required)` | The shared oRPC contract object. Drives both client typing and HTTP method inference — import the same object the service implements. |
| `serviceName` | `string (required)` | The discovery key. Resolved as services____http__ on the server (and the VITE_ form in the browser). Must match the ServiceReferences entry. |
| `routerName` | `string?` | Overrides the URL path segment for the router; defaults to serviceName. Use when the mounted router path differs from the service name. |
| `protocol` | `'http' \| 'https'?` | Discovery protocol. Defaults to 'http' (resolves the __http__ endpoint). |
| `apiPath` | `string?` | Base RPC path the runtime mounts. Defaults to '/api/rpc' — match what the service serves. |
| `apiVersion` | `string?` | API version segment in the URL. Defaults to 'v1'. |
| `propagateTraceContext` | `boolean?` | Attach W3C traceparent/tracestate headers automatically from the active trace context. Defaults to true. |

## Step 4 — Call it (and handle typed errors)

The client methods mirror the contract's procedure tree. Wrap calls in the SDK's `safe()` helper to get a tuple instead of a throw, and narrow defined errors with `isDefinedError`:

```ts
// web/src/routes/users.ts — typed call with safe-style error handling
import { isDefinedError, safe } from '@netscript/sdk/client';
import { usersClient } from '../clients/users.ts';

const [error, result] = await safe(usersClient.list({ limit: 20 }));

if (error && isDefinedError(error)) {
  // error.code and error.data are typed from the contract
  console.error('users.list failed:', error.code, error.data);
} else {
  // result.items is the contract's output type
  return result.items;
}
```

## Many services at once — `defineServices`

When the caller talks to several services, `defineServices` builds the clients (plus cache-aware query factories and TanStack Query utils) from one map. The map key is the discovery key unless you override `serviceName`.

```ts
// web/src/clients/users.ts — one service, direct calls only
import { createServiceClient } from '@netscript/sdk/client';
import { UsersContractV1 } from '@my-app/contracts';

export const usersClient = createServiceClient({
  contract: UsersContractV1,
  serviceName: 'users',
});

const page = await usersClient.list({ limit: 20 });
void page;
```

```ts
// web/src/sdk.ts — clients + query factories + query utils for several services
import { defineServices } from '@netscript/sdk';
import { OrdersContractV1, UsersContractV1 } from '@my-app/contracts';

export const sdk = defineServices({
  // map key is the discovery key (services__users__http__0, services__orders__http__0)
  users: { contract: UsersContractV1 },
  orders: { contract: OrdersContractV1, options: { staleTime: 60_000 } },
});

const people = await sdk.clients.users.list({ limit: 20 });
const orderPage = await sdk.queries.orders.list({ limit: 20, offset: 0 });
void people;
void orderPage;
```

`defineServices` returns `{ clients, queries, queryUtils }`. The `serviceName` per entry defaults to the map key, so `users` resolves `services__users__http__0` automatically — override it only when the registered service name differs from your local map key.

## Manual / non-Aspire resolution

The discovery readers are usable on their own when you are not running under Aspire — for a smoke test, a one-off script, or a custom transport. `getServiceUrl(name)` throws a clear error naming the missing env var; `isServiceAvailable(name)` is the non-throwing probe; `getAllServices()` lists every `services__*` name in the environment.

```ts
// scripts/check-users.ts — resolve a discovered URL by hand
import { getAllServices, getServiceUrl, isServiceAvailable } from '@netscript/sdk/discovery';

if (isServiceAvailable('users')) {
  const baseUrl = getServiceUrl('users', 'http'); // reads services__users__http__0
  console.log('users at', baseUrl, '| all:', getAllServices());
}
```

The server-side lookup key is `services__<name>__http__<index>`; the browser path checks the `VITE_`-prefixed forms first (Aspire injects those for Vite apps). Set the env var yourself to point a client at a fixed URL with no orchestrator:

```bash
# point the users client at a locally-running service, no Aspire
services__users__http__0=http://localhost:3001 deno task --cwd web dev
```

## End to end in one pass

The four steps above, run start to finish against the example `users` service. Copy the file, then run the command sequence from the workspace root:

```ts
// web/src/clients/users.ts — the resulting file (contract in, typed client out)
import { createServiceClient, isDefinedError, safe } from '@netscript/sdk/client';
import { UsersContractV1 } from '@my-app/contracts';

// serviceName is the discovery key — resolves services__users__http__0 at call time.
export const usersClient = createServiceClient({
  contract: UsersContractV1,
  serviceName: 'users',
});

// A typed call with safe-style error handling — no hardcoded URL anywhere.
export async function firstUsers() {
  const [error, result] = await safe(usersClient.list({ limit: 20 }));
  if (error && isDefinedError(error)) {
    throw new Error(`users.list failed: ${error.code}`);
  }
  return result.items;
}
```

```bash
# From the workspace root, in order:

# 1. Declare the dependency — add "users" to the caller's ServiceReferences
#    array in aspire/appsettings.json (see Step 1 above).

# 2. Regenerate the Aspire helpers so the reference is wired into the AppHost.
netscript service generate

# 3. Bring the graph up — Aspire injects services__users__http__0 into the caller.
cd aspire && aspire start && cd ..

# 4. Run the caller; the typed client resolves the URL lazily on the first call.
deno task --cwd web dev
```

With `aspire start` up, `usersClient.list({ limit: 20 })` resolves `services__users__http__0`, issues the oRPC call to `<resolved-url>/api/rpc/v1/users`, and returns the contract's typed `items`. No registry, no `localhost:<port>`, no generated client file.

## Production pitfalls

> Footguns before you ship
>
> - **Alpha surface.** NetScript packages share the aligned `0.0.1-beta.11` version; the discovery env-var convention and client option names are stable in the scaffold but may shift before `1.0`. Pin the version you build on.
> - **The reference must be declared, then generated.** Adding a `ServiceReferences` entry does nothing until you re-run `netscript service
>   generate` and restart `aspire start`. A missing reference means `getServiceUrl` throws *"Service URL not found … Expected environment variable: services__<name>__http__0"*.
> - **The discovery key must match.** `serviceName` (and the `defineServices` map key) must equal the service's registered name, or discovery resolves a variable that was never injected.
> - **The served path is `/api/rpc/*`.** The client defaults to `apiPath: '/api/rpc'` and `apiVersion: 'v1'`; if your service mounts a different path, set them explicitly or calls 404. It is *not* a bare `/rpc`.
> - **Aspire injects the URL; outside Aspire you must.** Without an orchestrator the `services__<name>__http__0` variable is unset — provide it yourself (env var) or the client cannot find the service.

## See also

[Do — Add a service  Create the callee first: contract → defineService → an oRPC service answering on its own port.](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/add-a-service/)

[Capability — Services & contracts  Why the shared contract object is the single source of truth, and how a typed client cannot drift from the service.](https://rickylabs.github.io/netscript/netscript/capabilities/services/)

[Look up — @netscript/sdk  The full SDK surface: createServiceClient, defineServices, the discovery readers, query factories, and TanStack utils.](https://rickylabs.github.io/netscript/netscript/reference/sdk/)

[Understand — Orchestration with Aspire  How Aspire wires resources, resolves endpoints, and injects the services__ env vars discovery reads.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

For the concepts behind the typed-client surface see [Typed SDK & client](https://rickylabs.github.io/netscript/netscript/services-sdk/sdk/) ; the sibling recipe that builds the callee is [Add a service](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/add-a-service/) ; and the orchestration that injects the URLs is explained in [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) .

[How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/) [Expose OpenAPI & Scalar](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/expose-openapi-scalar/)

_Canonical: https://rickylabs.github.io/netscript/services-sdk/how-to/discover-services/_

---

# Expose OpenAPI & Scalar

Turn on the generated **OpenAPI** document and the interactive **Scalar** API reference UI for an existing oRPC service — as a one-line `defineService` option or by mounting the Layer-1 primitives onto any Hono app yourself.

## Prerequisites

**What you need before you start**

| Name | Type | Description |
| --- | --- | --- |
| `An oRPC service` | `router` | An existing service with an oRPC router whose contract inputs/outputs are zod schemas. See the Services hub or the Build-a-service tutorial. |
| `@netscript/service` | `package` | Already a dependency of every generated service. Exposes defineService, the createService builder, and the createOpenAPISpec / createScalarDocs / createScalarJs primitives. |
| `zod schemas` | `contract` | Spec generation reads your contract's zod schemas via the ZodToJsonSchemaConverter; routes without zod input/output produce an empty schema for that operation. |

> Already on by default in the scaffold
>
> Generated service entrypoints call
>
> defineService(router, { openapi: { … } })
>
> , so a freshly scaffolded service
>
> already
>
> serves the spec at
>
> /api/openapi.json
>
> and the Scalar UI at
>
> /api/docs
>
> . This recipe is for adding the surface to a service that does not have it yet, or for hand-wiring the primitives into a custom Hono host.

## Steps

### 1. Turn it on with `defineService` (the one-line path)

Pass an `openapi` block to the preset. That single option enables the generated OpenAPI JSON spec, the Scalar docs page, and the bundled Scalar JS — no extra imports.

```ts
// services/users/src/main.ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';

await defineService(router, {
  name: 'users',
  version: '1.0.0',
  port: parseInt(Deno.env.get('PORT') || '3001'),
  openapi: {
    title: 'Users API',
    description: 'User management service',
  },
});
```

Aspire injects `PORT` at runtime, so the entrypoint reads it from the environment; the typed source of truth is your `netscript.config.ts` `services.<name>.port` field, which the scaffold wires as the fallback default — set the port there rather than editing this line.

This wires three routes onto the service:

**Routes added by the openapi option**

| Name | Type | Description |
| --- | --- | --- |
| `/api/openapi.json` | `GET → JSON` | The machine-readable OpenAPI document, generated from your contract's zod schemas. |
| `/api/docs` | `GET → HTML` | The Scalar interactive API reference UI; it fetches the spec above and renders try-it docs. |
| `/api/docs/scalar.js` | `GET → JS` | The locally bundled Scalar runtime, so the docs UI works offline with no CDN dependency. |

### 2. Hit the endpoints

With the service running (directly via `deno task --cwd services/users dev`, or under `aspire start` for DB-backed services), open the docs UI and fetch the raw spec:

```sh
# from a shell — confirm both surfaces answer
curl http://localhost:3001/api/openapi.json   # raw OpenAPI document
open http://localhost:3001/api/docs           # Scalar reference UI in a browser
```

The REST surface generated from the same contract is served under `/api/*`, and the typed oRPC endpoint stays at `/api/rpc/*` — the spec describes the former.

### 3. (Optional) Hand-wire the primitives onto a host app

When you need finer control — a custom path, a different theme, or mounting onto an existing Hono app that is not a `defineService` runtime — drop down to the three Layer-1 primitives. `createOpenAPISpec` serves the spec JSON, `createScalarDocs` serves the Scalar HTML, and `createScalarJs` serves the bundled runtime so the UI loads offline.

```ts
// services/users/src/main.ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';

// One option turns on the spec, the Scalar UI, and the bundled JS.
await defineService(router, {
  name: 'users',
  version: '1.0.0',
  port: 3001,
  openapi: {
    title: 'Users API',
    description: 'User management service',
  },
});
```

```ts
// services/users/src/main.ts — step-by-step, with a custom spec URL
import { createService } from '@netscript/service';
import { router } from './router.ts';

await createService(router, { name: 'users', version: '1.0.0', port: 3001 })
  .withCors()
  .withLogger()
  .withOpenAPI({ title: 'Users API', description: 'User management service' })
  .withDocs() // optional: .withDocs({ specUrl: '/api/openapi.json' })
  .withRPC()
  .withHealth()
  .serve();
```

```ts
// host/openapi-routes.ts — wire the primitives onto an existing Hono app
import {
  createOpenAPISpec,
  createScalarDocs,
  createScalarJs,
} from '@netscript/service';
import { router } from './router.ts';

// 1. Serve the OpenAPI JSON document.
app.get('/api/openapi.json', createOpenAPISpec(router, {
  title: 'Users API',
  version: '1.0.0',
  description: 'User management service',
  servers: [{ url: '/api', description: 'local' }],
}));

// 2. Serve the Scalar UI that loads that spec.
app.get('/api/docs', createScalarDocs({
  specUrl: '/api/openapi.json',
  title: 'Users API',
  theme: 'kepler',
}));

// 3. Serve the bundled Scalar runtime (offline, no CDN).
app.get('/api/docs/scalar.js', createScalarJs());
```

## Option keys

The primitives accept these confirmed option shapes (`@netscript/service`):

**OpenAPIConfig (createOpenAPISpec)**

| Name | Type | Description |
| --- | --- | --- |
| `title` | `string (required)` | API title shown in the spec and the Scalar UI. |
| `version` | `string (required)` | API version string, e.g. '1.0.0'. |
| `description` | `string?` | Longer API description rendered in the docs. |
| `servers` | `Array<{ url; description? }>?` | Server URLs advertised in the spec; defaults to a single entry { url: '/api' }. |

**ScalarDocsOptions (createScalarDocs)**

| Name | Type | Description |
| --- | --- | --- |
| `specUrl` | `string (required)` | URL the Scalar UI fetches the OpenAPI document from, e.g. '/api/openapi.json'. |
| `title` | `string?` | Docs page title; defaults to 'API Documentation'. |
| `theme` | `'default' \| 'kepler' \| 'moon' \| 'purple' \| 'saturn'` | Scalar UI theme; defaults to 'kepler'. |

> Spec quality comes from your contract
>
> The OpenAPI document is generated by oRPC's
>
> OpenAPIGenerator
>
> from your router, with a
>
> ZodToJsonSchemaConverter
>
> turning each route's zod schemas into JSON Schema. Richer schemas —
>
> .describe()
>
> , explicit
>
> .method()
>
> on each contract route, named output shapes — produce a richer, more accurate reference. The spec is only as good as the contract behind it.

## In-production pitfalls

> Before you ship the docs UI
>
> - **The Scalar JS is served from your origin, not a CDN.** `/api/docs/scalar.js` streams the bundled runtime from the package's `assets/`. That keeps the UI working offline, but it also means the `/api/docs` page is *three* routes — if you hand-wire the primitives, mount all three (`createOpenAPISpec`, `createScalarDocs`, `createScalarJs`) or the page loads blank.
> - **The docs and spec are public by default.** With the service-auth seam installed, `.withAuthn()` protects `/api` — which includes `/api/openapi.json` and `/api/docs`. If you do *not* want your API surface publicly enumerable, gate it or set `allowAnonymous` deliberately; do not assume the docs are hidden.
> - **The REST surface is `/api/*`; the typed RPC endpoint is `/api/rpc/*`.** The OpenAPI document describes the REST routes — point human/integration consumers at those, and keep generated typed clients on the RPC path.
> - **Routes without zod schemas under-document.** A contract route with no zod input/output yields an empty operation schema in the spec. Add schemas (and `.describe()`) to get useful request/response docs.

## See also

[Services & contracts](https://rickylabs.github.io/netscript/netscript/services-sdk/services/)

[Understand — Services & contracts  The capability hub: how defineService, the fluent builder, and the OpenAPI/Scalar primitives fit together.](https://rickylabs.github.io/netscript/netscript/capabilities/services/)

[Do — Discover services  Recipe: enumerate the services in a workspace and the endpoints each one exposes.](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/discover-services/)

[Do — Graceful shutdown  Recipe: drain in-flight requests and run teardown hooks before the service process exits.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/graceful-shutdown/)

[Look up — @netscript/service  The full generated API: the OpenAPI/Scalar primitives, the builder, and every option key.](https://rickylabs.github.io/netscript/netscript/reference/service/)

[Discover services](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/discover-services/) [Use a second database](https://rickylabs.github.io/netscript/netscript/data-persistence/how-to/use-a-second-database/)

_Canonical: https://rickylabs.github.io/netscript/services-sdk/how-to/expose-openapi-scalar/_

---

# Typed SDK & client

**Declare a contract action once and everything the caller needs — the typed method, the query key, the cache entry, the TanStack options — is derived from it, in one import.**

The `@netscript/sdk` is the **typed client and data layer** for NetScript: it turns an [`@orpc/contract`](https://rickylabs.github.io/netscript/explanation/contracts/) into a discovered, type-safe service client, wraps each contract action in a **cache-first query factory** (KV-backed SWR), and bridges those into [TanStack Query](https://tanstack.com/query) for islands. The contract object is the single source of truth — the *same* object the [service](https://rickylabs.github.io/netscript/services-sdk/services/) implements is the one the client imports, so caller and server **cannot drift**.

beta

![A contract object flows into a generated typed client, then a cache-first query factory backed by Deno KV, then into a Fresh island; the same contract object is imported by the oRPC service so the two ends cannot drift.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/sdk-data-flow.svg)

*One contract → typed client → KV cache-first query → island. The service imports the same contract, so a renamed field is a compile error on both sides.*

## What it is

The SDK is layered. **L1** is the typed client: `createServiceClient<Contract>()` resolves a service URL from [Aspire service discovery](https://rickylabs.github.io/netscript/explanation/aspire/) and returns a callable object whose method signatures are inferred from the contract. **L2** wraps each contract action in a query factory (`createQueryFactories`) that runs through a shared KV-backed cache provider and exposes `queryOptions`/`mutationOptions`/`clientKey`/`key`/`getCachedEntry` per action. **L3** is the `defineServices()` preset that builds clients, server query factories, and frontend query utils from one contract map. You consume the layer you need and can drop down without rewiring. See [Contracts](https://rickylabs.github.io/netscript/explanation/contracts/) for the type-flow theory.

> Use this when
>
> Reach for the SDK when an app or a service needs to
>
> call a typed oRPC service
>
> and render its data with
>
> cache-first, server-hydrated queries
>
> . Use the bare
>
> `createServiceClient`
>
> for service-to-service RPC; add
>
> createQueryFactories
>
> when you want KV-backed SWR and TanStack option helpers; reach for
>
> Fresh
>
> when an island must hydrate that same query key on the client.

## Declare once, derived everywhere

The classic data-layer tax is the [hand-rolled fetch wrapper](https://rickylabs.github.io/netscript/web-layer/query/): a `lib/api.ts` full of `fetch()` calls whose request and response types are re-typed by hand from whatever the server currently returns. Every server change costs a second edit in the wrapper, a third in the query keys, and whichever one is forgotten becomes a runtime bug. For an AI agent working the codebase the tax is worse — each of those copies is a separate turn, and a stale one is a wrong answer the agent cannot see until runtime.

The SDK collapses those copies into one declaration. tRPC made this move famous for TypeScript APIs — declare a procedure on the server and the client's types follow, "end-to-end typesafe." NetScript keeps that declare-once property and shifts *where* the declaration lives: not inside server code, but in a standalone, versioned contract package that the server, the client, **and** the OpenAPI/Scalar surface all import. And the derivation goes further than method types — from one contract action the factory derives the server KV cache key (`key()`), the client TanStack key (`clientKey()`), the `queryOptions`/`mutationOptions` helpers, and the SWR cache reads. One edit to the contract updates the client, the docs surface, and the query layer together — there is no separate turn to keep them in sync.

This is how a production chat application built on NetScript wires its dashboard: the typed client is built straight off the contract type, so a route added to the contract shows up on the client already typed. The mechanics of each layer are below; the type-flow theory is in [Contracts](https://rickylabs.github.io/netscript/explanation/contracts/).

## Learn → / Do →

[Learn — Build a service + client  Track D walks contract → typed client → query factory → definePage layer → island, end to end.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[Do — Discover a service  Task recipe: resolve a service URL from Aspire env and stand up a typed client for it.](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/discover-services/)

## Minimal example

A single `lib/api-clients.ts` is the spine of the data layer: build the typed client from a contract, then derive a query factory from `{ contract, client }`. Every consumer — server loader or island — imports from here.

```ts
// apps/playground/lib/api-clients.ts
import { createServiceClient } from '@netscript/sdk/client';
import { createQueryFactories } from '@netscript/sdk/query';
import { ordersContract } from '@contracts';

// L1 — typed client. `serviceName` resolves a URL via Aspire discovery.
export const ordersClient = createServiceClient<typeof ordersContract>({
  contract: ordersContract,
  serviceName: 'orders',
});

// L2 — cache-first query factory bound to that client (KV-backed SWR).
export const api = createQueryFactories({
  orders: { contract: ordersContract, client: ordersClient },
});

// Direct typed call: `.list()` is fully inferred from the contract.
const recent = await ordersClient.list({ limit: 10 });
```

> Plugin services add a routerName
>
> A first-party plugin API (workers, sagas, triggers) mounts its router under a named segment, so its client needs
>
> routerName
>
> in addition to
>
> serviceName
>
> :
>
> createServiceClient<typeof workersContract>({ contract, serviceName: 'workers-api', routerName: 'workers' })
>
> . Plain workspace services omit it.

## Key types first

The query factory is the heart of the data layer. Each contract action becomes an **`ActionMethod`** carrying the full cache-first surface — keys, prefetch, cached reads, and TanStack option helpers. These are the methods you call from a `definePage` loader and an island; reading them first explains the rest of the page.

**ActionMethod — per-action query helpers (api.orders.list.*)**

| Name | Type | Description |
| --- | --- | --- |
| `queryOptions(props, options?)` | `(input, ActionQueryOptions?) => QueryOptions` | TanStack queryOptions with a typed queryKey and queryFn derived from the contract. The primary helper a loader/island passes to useQuery. |
| `mutationOptions(options?)` | `(ActionMutationOptions?) => MutationOptions` | TanStack mutationOptions with a typed mutationKey and mutationFn for writes (e.g. updateStatus). |
| `key(props)` | `(input) => readonly [string, action, string]` | Canonical SERVER cache key [resource, action, serializedInput] used by the KV cache. |
| `clientKey(props?)` | `(input?) => readonly unknown[]` | CLIENT-side TanStack query key, prefix-matchable for invalidateQueries. clientKey() vs key() is the server↔client split. |
| `getCachedEntry(props)` | `(input) => Promise \| null>` | Read cached data WITH its cache timestamp (cachedAt) — the SWR primitive a layer loader uses to decide stale-reload. |
| `getCachedData(props)` | `(input) => Promise` | Read cached data only, without fetching. |
| `prefetch(props, options?)` | `(input, QueryParams?) => void` | Warm the cache in the background (fire-and-forget). |
| `invalidate()` | `() => Promise` | Invalidate all cached queries for this action. |

## Constructing the client & factory

The two L1/L2 constructors and their options. `createServiceClient` is the only call that touches discovery; `createQueryFactories` is pure wiring over `{ contract, client }`.

**createServiceClient(options) — CreateServiceClientOptions**

| Name | Type | Description |
| --- | --- | --- |
| `contract` | `TContract — required` | The @orpc/contract object. Drives both client typing AND HTTP method inference. |
| `serviceName` | `string — required` | Service name registered in Aspire / NetScript config. Resolved to a URL via discovery (services__{name}__{protocol}__{index}; browser uses the VITE_ mirror). |
| `routerName` | `string?` | Router-name segment for URL path construction. Required for plugin API services, omitted for plain services. |
| `protocol` | `'http' \| 'https'?` | Resolved protocol for service discovery. |
| `apiPath / apiVersion` | `string?` | Base RPC path and API version segment overrides. |
| `propagateTraceContext` | `boolean?` | Auto-propagate W3C traceparent/tracestate headers on each call. |

The L3 alternative builds all three layers from one map: `defineServices({ orders: { contract, serviceName: 'orders' } })` returns `{ clients, queryFactories, queryUtils }` — the same L2 values, just composed in one call.

## Service discovery & query client

`serviceName` is resolved at call time from Aspire-injected environment variables. The `@netscript/sdk/discovery` subpath exposes the resolvers directly when you need a raw URL, and `@netscript/sdk/query-client` provides the browser-side TanStack glue.

**Discovery & query-client helpers**

| Name | Type | Description |
| --- | --- | --- |
| `getServiceUrl(name, protocol, index)` | `@netscript/sdk/discovery` | Resolve a service URL from Aspire browser-VITE or server services__* env. This is how serviceName resolves. |
| `getServiceInfo(name) / isServiceAvailable(name) / getAllServices()` | `@netscript/sdk/discovery` | Inspect a service's endpoints, check availability, or list all server-side Aspire service names (topology). |
| `createNetScriptQueryClient(options)` | `@netscript/sdk/query-client` | A TanStack QueryClient with server-first defaults: staleTime 30s, gcTime 300s, refetchOnWindowFocus false, retry 1. |
| `createServiceQueryUtils()` | `@netscript/sdk/query-client` | Bridge a typed SDK client into oRPC/TanStack frontend query utilities. |
| `bridgeInvalidation(resource, action?)` | `@netscript/sdk/query-client` | Build a client-side invalidation filter ({ queryKey }) for queryClient.invalidateQueries(). |
| `toClientKeyPrefix(resource, action?)` | `@netscript/sdk/query-client` | Map a server resource/action to a prefix-matchable client query key, e.g. ['orders','list']. |
| `cacheQuery.setCachedData(key, data, ttl)` | `@netscript/sdk/cache` | Server-only: fire-and-forget pre-warm of an entity into the KV cache. Importing /cache auto-registers the shared provider. |

```ts
// routes/(dashboard)/orders/(_loaders)/orders-list.ts
import { api } from '@/lib/api-clients.ts';

// Cache-first: read the KV entry (with cachedAt) for SWR; fall back to a fetch.
export const loadOrders = async () => {
  const entry = await api.orders.list.getCachedEntry({ limit: 20 });
  if (entry) return entry; // serve cached; SDK reloads stale in the background
  return { data: await api.orders.list.queryOptions({ limit: 20 }).queryFn(), cachedAt: Date.now() };
};
```

```tsx
// orders/(_islands)/OrdersQueryIsland.tsx
import { useQuery, useQueryClient } from '@netscript/fresh/query';
import { api } from '@/lib/api-clients.ts';

// Same contract action → same query key as the server loader, so the island
// hydrates from server state instead of refetching on mount.
const OrdersList = () => {
  const qc = useQueryClient();
  const orders = useQuery(api.orders.list.queryOptions({ limit: 20 }));
  // invalidate by prefix after a write:
  const refresh = () => qc.invalidateQueries({ queryKey: api.orders.list.clientKey() });
  return null; // render orders.data
};
```

```ts
// services/orders/src/routers/v1.ts — service-to-service call
import { safe, isDefinedError } from '@netscript/sdk/client';
import { usersClient } from '@/lib/api-clients.ts';

const [error, user, isDefined] = await safe(usersClient.getById({ id }));
if (error) {
  // narrow to a typed, contract-declared error
  if (isDefinedError(error)) return { code: error.code, status: error.status };
  throw error;
}
```

## Production notes

> /cache and /discovery are server-only
>
> @netscript/sdk/cache
>
> touches Deno KV and
>
> @netscript/sdk/discovery
>
> reads
>
> services__*
>
> env on the server — never import them into island/browser code. Browsers resolve service URLs through the
>
> `VITE_`-mirrored
>
> keys that Aspire injects, and the query factory's cache reads happen on the server loader; the island receives hydrated state and a
>
> clientKey()
>
> for invalidation only.

> clientKey() vs key() — don't cross the streams
>
> key(props)
>
> is the
>
> server
>
> KV cache key (
>
> [resource, action, serializedInput]
>
> );
>
> clientKey(props?)
>
> is the
>
> client
>
> TanStack key (prefix-matchable). Invalidate on the client with
>
> clientKey()
>
> /
>
> toClientKeyPrefix(...)
>
> — passing a server
>
> key()
>
> to
>
> invalidateQueries
>
> will silently match nothing. NetScript is in beta; subpath barrels are stable but signatures may still move.

## Reference →

This hub is intentionally thin — the full generated API (client, query, query-client, cache, collections, discovery, streams, telemetry, ports) lives in the reference.

[sdk](https://rickylabs.github.io/netscript/netscript/reference/sdk/)

[Look up — @netscript/sdk reference  Generated API for every subpath: createServiceClient, createQueryFactories, defineServices, discovery, and the cache engine.](https://rickylabs.github.io/netscript/netscript/reference/sdk/)

[Understand — Contracts  The oRPC contract → implement → handler → typed client → query → island type flow that makes drift a compile error.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)

[Build — Services & contracts  The server side of the contract: defineService, the fluent builder, OpenAPI/Scalar, and the auth seam.](https://rickylabs.github.io/netscript/netscript/services-sdk/services/)

[Render — Fresh meta-framework  How a definePage layer + island consume these query factories with cache-first hydration.](https://rickylabs.github.io/netscript/netscript/web-layer/)

[Fresh meta-framework](https://rickylabs.github.io/netscript/netscript/web-layer/) [Polyglot tasks](https://rickylabs.github.io/netscript/netscript/background-processing/polyglot-tasks/)

_Canonical: https://rickylabs.github.io/netscript/services-sdk/sdk/_

---

# Services & contracts

**Write the contract once; the handler, the typed client, and the OpenAPI surface are all derived from it — so an agent (or a teammate) never spends a turn keeping them in sync.**

A NetScript **service** is a typed HTTP runtime that *implements* an [`@orpc/contract`](https://rickylabs.github.io/netscript/explanation/contracts/) definition. You author the contract once (route + zod input/output), `implement()` it, bind `.handler()`s, and serve the resulting router on a Hono + oRPC runtime. The contract object is the single source of truth: the same object a typed client imports is the one the server implements, so caller and server **cannot drift**. The example `users` service answers on port **3001** with both an OpenAPI surface (`/api/v1/users/*`) and a typed oRPC endpoint (`/api/rpc/*`).

![A browser request flows into the service router, through middleware to the matched contract handler, optionally to the database, and back as a typed response.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/request-lifecycle.svg)

*Request lifecycle: browser → service router → middleware → contract handler → database → typed response.*

> Use this when
>
> Reach for a service when you need a
>
> synchronous, request/response API
>
> with a versioned, type-locked contract shared between front end and back end — a CRUD surface, an internal RPC boundary, or a public REST/OpenAPI endpoint. For
>
> fire-and-forget
>
> work use a
>
> background job
>
> ; for
>
> message-driven, long-running
>
> orchestration use a
>
> durable saga
>
> ; for
>
> inbound HTTP that kicks off work
>
> use a
>
> trigger
>
> ; for
>
> signed-in identity and sessions
>
> compose the
>
> auth plugin
>
> .

## Why contract-first: the drift you never debug

Every hand-synced API dies the same way. A field gets renamed on the server; the client wrapper, the API docs, and the front-end types each get updated in separate steps — and one of them gets missed. The bug ships silently and surfaces later as a runtime `undefined`, and the fix costs a round of archaeology to find which of the three copies drifted.

A NetScript service removes the copies. The contract — plain `@orpc/contract` routes with zod input/output schemas, versioned in its own package — is the only declaration of the wire shape. The handler binds to it via `implement()`, the client imports it, and the OpenAPI spec is generated from it. Rename a field and the build fails in the handler *and* the caller before anything ships. In a production chat application built on NetScript, this is how the whole API surface works: `implement(ChannelContractV1)` on the service side, a typed dashboard client built off the same contract type on the other — a new contract route is automatically typed on the client, with no "keep the API docs in sync" step in between.

The same property is why contract-first services suit AI-agent codebases. Encore's [NestJS-alternatives article](https://encore.dev/articles/nestjs-alternatives) names the failure mode: TypeScript's backend ecosystem has many valid ways to structure validation, data access, and project layout, so coding agents pick a different combination on every prompt. Encore's answer is to fix the conventions in application code; NetScript locks the convention at the **contract layer** — one way to declare a route (contract + zod schemas + `implement()`), and everything downstream derived from it. An agent working in the codebase reads one declared shape and follows it, instead of inventing a new client wrapper per session.

## What it is

A service is the **Layer 3 preset** (`defineService`) over a three-layer package. Layer 1 is small primitives — health, error, RPC, OpenAPI, and Scalar docs handlers you can mount in any Hono app. Layer 2 is `createService()`, a fluent builder that materializes a mountable `ServiceApp` (via `build()`) or starts a Deno listener (via `serve()`). Layer 3 is `defineService()`, the curated one-call preset used by generated service entrypoints. Every layer takes the oRPC router as its input, and the same contract the router implements is the one a typed client imports — so a renamed field is a compile error on both sides. The full type story is in [Contracts](https://rickylabs.github.io/netscript/explanation/contracts/).

## Learn → / Do →

[Learn — Build a service  Track A 02: author a contract, stand up the users service on :3001, call it from a typed client.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[Do — Expose OpenAPI & Scalar  Recipe: turn on the generated OpenAPI spec and the Scalar docs UI for an existing service.](https://rickylabs.github.io/netscript/netscript/services-sdk/how-to/expose-openapi-scalar/)

[Do — Graceful shutdown  Recipe: drain in-flight requests and run teardown hooks on SIGINT/SIGTERM before the process exits.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/graceful-shutdown/)

## The contract is the source of truth

Before there is a service there is a contract. A contract is plain `@orpc/contract` routes whose inputs and outputs are zod schemas, collected into an object and passed to `implement()` from `@orpc/server`. `implement()` returns a `.handler()`-bindable object the service router consumes. The example workspace versions its contracts under `contracts/versions/v1/` and re-exports them as `@<project>/contracts` — so a contract bump is an explicit, reviewable version directory, never an accidental break.

```ts
// contracts/versions/v1/users.contract.ts
import { z } from 'zod';
import { oc } from '@orpc/contract';
import { implement } from '@orpc/server';

export const UsersContractV1 = {
  health: oc.route({ method: 'GET' }).input(z.object({}).optional()).output(UsersHealthSchemaV1),
  list: oc.route({ method: 'POST' }).input(UsersListInputSchemaV1).output(UsersListResponseSchemaV1),
  updateStatus: oc.route({ method: 'POST' }).input(UsersUpdateStatusInputSchemaV1).output(UsersUpdateStatusResponseSchemaV1),
};

// `implement()` produces the .handler()-bindable object the service router consumes.
export const UsersV1 = implement(UsersContractV1);
```

The chain end-to-end — contract → `implement()` → `.handler()` → typed client → query → island — is laid out in [Contracts](https://rickylabs.github.io/netscript/explanation/contracts/). The key property: the client imports the *same* contract object, so a renamed field or a changed output shape is a **compile error in both the handler and the caller** before it can ship.

## Headline API: two ways to construct a service

NetScript ships **two** service-construction APIs, and the example project uses both. Workspace services use the one-call `defineService(router, options)` — the right default for the 80% case. Plugin API services (workers, sagas, auth) use the fluent `createService(router, options).with*().serve()` builder when they need to add CORS, OpenAPI, a database client, auth middleware, or custom context step by step. Both stand up the same Hono + oRPC runtime; `defineService` is a curated preset over the same builder.

```ts
// services/users/src/main.ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';

// One call wires CORS, request logging, OpenAPI, RPC, and health endpoints.
await defineService(router, {
  name: 'users',
  version: '1.0.0',
  port: parseInt(Deno.env.get('PORT') || '3001'),
  openapi: { title: 'Users API', description: 'users service' },
  debug: true,
});
```

```ts
// plugins/workers/services/src/main.ts — step-by-step composition
import { createService } from '@netscript/service';
import { router } from './router.ts';

await createService(router, { name: 'workers', version: '1.0.0', port: 8091 })
  .withCors()
  .withLogger()
  .withOpenAPI({ title: 'Workers API' })
  .withDocs()
  .withDatabase(dbClient)
  .withContext(() => ({ workers: runtime }))
  .withRPC({ traceContext: true })
  .withHealth()
  .withServiceInfo()
  .onStartup(async () => {/* seed, warm caches */})
  .serve();
```

Aspire injects `PORT` at runtime, so the entrypoint reads it from the environment; the typed source of truth is your `netscript.config.ts` `services.<name>.port` field, which the scaffold wires as the fallback default — set the port there rather than editing this line.

### `defineService(router, options)` — the preset options

`DefineServiceOptions` extends the base `ServiceConfig` (`name`, `version`, `port`) and adds the preset-only keys below. These are the **complete** option keys confirmed against the package surface — nothing is omitted.

**DefineServiceOptions (extends ServiceConfig)**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string (required)` | Service name used for logging, telemetry, and health-check labels. |
| `version` | `string?` | Service version (e.g. '1.0.0'); surfaced on /health and the OpenAPI spec. |
| `port` | `number?` | Default listener port if serve() is not passed an explicit port. The generated entrypoint reads Deno.env.get('PORT') \|\| '3001'. |
| `db` | `DbContext?` | Database context injected as context.db. Accepts a single Prisma client (with $queryRaw) or a multi-db record like { netscript, mdb, prosco, prev }; the first value exposing $queryRaw is auto-wired as the /health and /health/ready probe client. |
| `openapi` | `{ title?; description? }?` | Turns on the generated OpenAPI spec endpoint and the Scalar docs UI with this title/description. |
| `debug` | `boolean?` | Enables verbose oRPC logging. Defaults to the NETSCRIPT_DEBUG env var. |
| `auth` | `{ authn: AuthnOptions; authz?: AuthzOptions }?` | Installs the authentication (and optional authorization) gate on guarded paths — the preset form of .withAuthn()/.withAuthz(). |
| `tls` | `ServiceTlsOptions?` | Opt-in TLS: { cert, key } as PEM strings. When set, the listener serves HTTPS and negotiates HTTP/2 via ALPN automatically. Forwarded to serve() as .serve({ tls }). See TLS & HTTP/2 below. |

> Handlers bind to the contract
>
> A router aggregates versioned handlers —
>
> export const router = { v1: { users: { ...UsersV1, health } } }
>
> — and each handler is bound from the implemented contract:
>
> v1.users.list.handler(async ({ input }) => { /* return records */ })
>
> . In the scaffold's
>
> Step 5
>
> the
>
> users
>
> handlers return seeded
>
> in-memory records
>
> (no database yet) — the front-end ↔ contract proof. Wiring Prisma comes later; see
>
> Database
>
> .

## Endpoints & ports

A `defineService` runtime exposes its OpenAPI routes, a typed oRPC endpoint mounted under `/api/rpc/*`, and a health check. The example `users` service is reachable once `aspire start` is up (Aspire provisions Postgres/Redis first) or when you run it directly with `deno task --cwd services/users dev`.

**Users service surface (port 3001)**

| Name | Type | Description |
| --- | --- | --- |
| `/api/v1/users/*` | `HTTP/OpenAPI` | REST surface generated from the contract (list, updateStatus, health). |
| `/api/rpc/*` | `oRPC` | Typed RPC endpoint a generated client calls — same contract object, no drift. This is the served default path (not /rpc). |
| `/health` | `HTTP` | Liveness/readiness check; anonymous by default (excluded from authn). |
| `:3001` | `port` | Default service port; read from Deno.env.get('PORT') \|\| '3001'. |

> Aspire first, then hit the endpoint
>
> Services that touch the database need orchestration up first:
>
> cd aspire && aspire start
>
> brings up Postgres and Redis (dashboard at
>
> https://localhost:18888
>
> )
>
> before
>
> any
>
> netscript db
>
> command. The seeded-records example service runs without the DB, but the real workflow expects Aspire running. See
>
> Aspire
>
> .

## OpenAPI spec & Scalar docs

Passing `openapi` to `defineService` (or calling `.withOpenAPI().withDocs()` on the builder) turns on a REST surface generated from the same contract, a machine-readable OpenAPI JSON spec, and the **Scalar** interactive docs UI. Under the hood three Layer-1 primitives do the work, and you can mount them directly in any host Hono app when you need finer control: `createOpenAPISpec` serves the spec JSON, `createScalarDocs` serves the Scalar HTML page, and `createOpenAPIHandler` serves the REST routes themselves (it adds the `ZodSmartCoercionPlugin` so query-string values coerce to their schema types automatically).

**OpenAPI / Scalar primitives (@netscript/service)**

| Name | Type | Description |
| --- | --- | --- |
| `createOpenAPISpec(router, config)` | `→ ServiceHandler` | Serves the OpenAPI JSON spec. config is OpenAPIConfig (see below). Mount at e.g. /api/openapi.json. |
| `createScalarDocs(options)` | `→ ServiceHandler` | Serves the Scalar docs UI HTML that loads the spec. options is ScalarDocsOptions (specUrl, title?, theme?). |
| `createScalarJs()` | `→ ServiceHandler` | Serves the bundled Scalar JS so the docs UI works offline without CDN access. |
| `createOpenAPIHandler(router, config?)` | `→ FetchHandler` | The OpenAPI REST request handler (with ZodSmartCoercionPlugin). config is RPCHandlerConfig; mount under /api/*. |

**OpenAPIConfig (createOpenAPISpec)**

| Name | Type | Description |
| --- | --- | --- |
| `title` | `string (required)` | API title shown in the spec and docs. |
| `version` | `string (required)` | API version, e.g. '1.0.0'. |
| `description` | `string?` | Longer API description. |
| `servers` | `Array<{ url; description? }>?` | Server URLs advertised in the spec (e.g. staging vs. production base URLs). |

**ScalarDocsOptions (createScalarDocs)**

| Name | Type | Description |
| --- | --- | --- |
| `specUrl` | `string (required)` | URL the docs UI fetches the OpenAPI spec from, e.g. '/api/openapi.json'. |
| `title` | `string?` | Docs page title. |
| `theme` | `'default' \| 'kepler' \| 'moon' \| 'purple' \| 'saturn'` | Scalar UI theme. |

```ts
// services/users/src/main.ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';

// Turns on the OpenAPI spec + Scalar docs UI in one option.
await defineService(router, {
  name: 'users',
  version: '1.0.0',
  port: 3001,
  openapi: {
    title: 'Users API',
    description: 'User management service',
  },
});
```

```ts
// host/openapi-routes.ts — wire the primitives onto an existing Hono app
import {
  createOpenAPISpec,
  createScalarDocs,
  createScalarJs,
} from '@netscript/service';
import { router } from './router.ts';

app.get('/api/openapi.json', createOpenAPISpec(router, {
  title: 'Users API',
  version: '1.0.0',
  description: 'User management service',
}));

app.get('/api/docs', createScalarDocs({
  specUrl: '/api/openapi.json',
  title: 'Users API',
  theme: 'kepler',
}));

// Serve Scalar offline (no CDN dependency)
app.get('/api/docs/scalar.js', createScalarJs());
```

## Health, readiness & liveness

The preset wires `/health` automatically; the underlying primitives let you compose probes by hand or mount them in a host app. `createHealthHandler` runs every registered `HealthCheck` in parallel and returns an aggregate `HealthResponse` (`status` ∈ `healthy | degraded | unhealthy`). `createReadinessHandler` takes an array of async boolean checks and is the one to point an orchestrator's *readiness* probe at — it fails until dependencies (DB, caches) are reachable. `createLivenessHandler` is a bare "is the process up" probe that returns 200 with no dependency checks, for an orchestrator's *liveness* probe. The `healthChecks` namespace ships pre-built checks for the common dependencies so you don't hand-roll them.

**Health primitives & checks (@netscript/service)**

| Name | Type | Description |
| --- | --- | --- |
| `createHealthHandler(options?)` | `→ ServiceHandler` | Runs all checks in parallel, returns an aggregate HealthResponse. options: HealthHandlerOptions { checks?, version?, includeDetails? (default true) }. |
| `createReadinessHandler(checks)` | `→ ServiceHandler` | Readiness probe: checks is Array<() => Promise>; reports not-ready until every check resolves true. Mount at /health/ready. |
| `createLivenessHandler()` | `→ ServiceHandler` | Liveness probe: 200 OK while the process runs, no dependency checks. Mount at /health/live. |
| `healthChecks.database(db)` | `→ HealthCheck` | Pre-built DB probe; runs a $queryRaw `SELECT 1`-style ping against the Prisma client. |
| `healthChecks.kv()` | `→ HealthCheck` | Pre-built check for the KV store. |
| `healthChecks.service(name, baseUrl)` | `→ HealthCheck` | Probes another service's health endpoint by name + base URL. |
| `healthChecks.custom(name, fn)` | `→ HealthCheck` | Wraps your own async () => Promise as a named check. |

```ts
// host/health-routes.ts — readiness + liveness + aggregate health
import {
  createHealthHandler,
  createLivenessHandler,
  createReadinessHandler,
  healthChecks,
} from '@netscript/service';
import { db } from '@database';

// Aggregate health (parallel checks + details)
app.get('/health', createHealthHandler({
  version: '1.0.0',
  checks: [healthChecks.database(db)],
}));

// Liveness: is the process up?
app.get('/health/live', createLivenessHandler());

// Readiness: are dependencies reachable?
app.get('/health/ready', createReadinessHandler([
  async () => { await db.$queryRaw`SELECT 1`; return true; },
]));
```

> Liveness vs. readiness
>
> Point an orchestrator's
>
> liveness
>
> probe at
>
> /health/live
>
> (restart the container only when the process is wedged) and its
>
> readiness
>
> probe at
>
> /health/ready
>
> (stop routing traffic until the DB and caches answer). Wiring both to the same dependency-checking endpoint is the classic footgun: a transient DB blip then triggers a
>
> restart
>
> instead of a brief traffic pause.

## Graceful shutdown

`serve()` installs SIGINT/SIGTERM (or SIGBREAK on Windows) handlers and drains in-flight requests before exiting. Register teardown work with `.onShutdown(hook)` on the builder — a `ShutdownHook` receives a `ShutdownContext` (`reason`, optional `signal`) and runs during the drain. The drain is bounded by `drainTimeoutMs` (default `30_000`); when it elapses the service stops anyway and the resulting `ShutdownReport` records `timedOut: true` plus a per-hook `ShutdownHookOutcome` for each registered hook. Calling `running.stop()` triggers the same drain manually (reason `'manual'`).

**Shutdown types (@netscript/service)**

| Name | Type | Description |
| --- | --- | --- |
| `ShutdownHook` | `(context: ShutdownContext) => Promise \| void` | Async teardown callback registered via .onShutdown(). Run in registration order during the drain. |
| `ShutdownContext` | `{ reason: ShutdownReason; signal?: Deno.Signal }` | Passed to each hook. signal is set only when reason is 'signal'. |
| `ShutdownReason` | `'signal' \| 'manual' \| 'startup-failure'` | Why the drain started: an OS signal, a manual stop() call, or a failed startup hook. |
| `ShutdownHookOutcome` | `{ ok: boolean; error?: string }` | Per-hook result; error holds a normalized message when a hook throws or rejects. |
| `ShutdownReport` | `{ reason; timedOut: boolean; hooks: readonly ShutdownHookOutcome[] }` | Final result of a completed shutdown — the reason, whether the timeout elapsed, and every hook outcome in execution order. |

**ServeOptions (serve()) — shutdown-relevant keys**

| Name | Type | Description |
| --- | --- | --- |
| `port` | `number?` | Preferred listener port; use 0 for an ephemeral port. |
| `signal` | `AbortSignal?` | External signal that stops the listener when aborted (drives the drain). |
| `drainTimeoutMs` | `number?` | Max time to wait for in-flight requests and shutdown hooks before forcing exit. Defaults to 30_000. |
| `handleSignals` | `boolean?` | Install SIGINT/SIGTERM (or SIGBREAK) handlers. Defaults to true. |
| `tls` | `ServiceTlsOptions?` | Opt-in TLS ({ cert, key } PEM strings). Present → HTTPS + HTTP/2 via ALPN; absent → plain HTTP/1.1. See TLS & HTTP/2 below. |

```ts
// services/users/src/main.ts — drain + teardown on signal or manual stop
import { createService } from '@netscript/service';
import { router } from './router.ts';
import { db } from '@database';

const running = await createService(router, { name: 'users', version: '1.0.0' })
  .withRPC()
  .withHealth()
  .onShutdown(async ({ reason, signal }) => {
    // reason: 'signal' | 'manual' | 'startup-failure'
    audit.record({ event: 'shutdown', reason, signal });
    await db.$disconnect();
  })
  .serve({
    port: 3001,
    drainTimeoutMs: 10_000, // wait up to 10s for in-flight work
    handleSignals: true,    // SIGINT/SIGTERM/SIGBREAK
  });

// Later, in tests or a supervisor: trigger the same drain manually.
await running.stop();
```

## TLS & HTTP/2 (opt-in)

By default a service listens over plain HTTP. Pass a `tls` option and the *same* listener serves HTTPS and negotiates **HTTP/2 automatically via ALPN** — HTTP/1.1 stays available as a fallback, and there is no separate `http2` flag. TLS is purely additive: a service that omits `tls` is unchanged.

`tls` is a `ServiceTlsOptions` object whose `cert` and `key` are **PEM-encoded strings** — the certificate chain and the private key as *contents*, not file paths. It is accepted by both `defineService(router, { …, tls })` and the fluent builder's `.serve({ tls })`.

```ts
// services/users/src/main.ts — serve HTTPS + HTTP/2 with an inline cert/key
import { defineService } from '@netscript/service';
import { router } from './router.ts';

await defineService(router, {
  name: 'users',
  port: 3000,
  tls: {
    cert: await Deno.readTextFile('cert.pem'), // PEM contents
    key: await Deno.readTextFile('key.pem'),   // PEM contents
  },
});
// Fluent equivalent: createService(router, { name }).withHealth().serve({ tls: { cert, key } })
```

If you omit `tls`, the listener falls back to environment configuration: set **both** `NETSCRIPT_TLS_CERT_FILE` and `NETSCRIPT_TLS_KEY_FILE` and the service serves HTTPS from those files. Unlike the inline `cert`/`key` (PEM contents), these env vars are **file paths** — and both are required; one alone is ignored.

**ServiceTlsOptions (@netscript/service) + env fallback**

| Name | Type | Description |
| --- | --- | --- |
| `cert` | `string (required)` | PEM-encoded certificate chain — the contents, not a path. |
| `key` | `string (required)` | PEM-encoded private key — the contents, not a path. |
| `NETSCRIPT_TLS_CERT_FILE` | `env (path)` | Fallback when tls is omitted: file path to the PEM certificate chain. Both env vars must be set together. |
| `NETSCRIPT_TLS_KEY_FILE` | `env (path)` | Fallback when tls is omitted: file path to the PEM private key. Both env vars must be set together. |

## Service-layer authn / authz middleware

The service builder ships a **provider-agnostic** authentication and authorization seam in `@netscript/service/auth`. It is a thin Hono-middleware layer over the request pipeline — deliberately **distinct from the [auth plugin](https://rickylabs.github.io/netscript/identity-access/auth/)**, which composes a sign-in/session backend (kv-oauth, WorkOS, better-auth). Use this seam when a service needs to gate its own routes — verify a credential, trust an upstream identity header, or check a scope — without taking on an interactive identity provider.

Two stages wrap the request: `.withAuthn()` resolves a `Principal` (authentication) via an `AuthenticatorPort`, and `.withAuthz()` makes an `AuthzDecision` from that principal (authorization) via an `AuthorizerPort`. By default the `/api` surface is protected and `/health` is anonymous — both configurable through `AuthnOptions.protect` / `AuthnOptions.allowAnonymous`. The preset form is `defineService(router, { auth: { authn, authz } })`.

**@netscript/service/auth surface**

| Name | Type | Description |
| --- | --- | --- |
| `createStaticCredentialAuthenticator` | `authenticator` | Matches a configured static credential (e.g. API key / shared secret) → Principal. |
| `createTrustedHeaderAuthenticator` | `authenticator` | Trusts an identity asserted by an upstream proxy header (e.g. behind a gateway). |
| `createScopeAuthorizer` | `authorizer` | Allows/denies a request by checking the Principal's scopes against required scopes. |
| `.withAuthn({ authenticator, protect?, allowAnonymous? })` | `builder method` | Installs the authentication gate (AuthnOptions). protect defaults to ['/api']; allowAnonymous defaults to ['/health']. |
| `.withAuthz({ authorizer, denyByDefault? })` | `builder method` | Installs the authorization gate (AuthzOptions) from the Principal. denyByDefault fails closed and defaults to true. |

```ts
// Gate a service with a static credential + scope check
import { createService } from '@netscript/service';
import {
  createStaticCredentialAuthenticator,
  createScopeAuthorizer,
} from '@netscript/service/auth';
import { router } from './router.ts';

const authenticator = createStaticCredentialAuthenticator({
  credentials: {
    [Deno.env.get('SERVICE_API_KEY') ?? '']: {
      subject: 'service:ci',
      scopes: ['users:write'],
    },
  },
});
const authorizer = createScopeAuthorizer({
  rules: [{ match: () => true, requireScopes: ['users:write'] }],
  denyByDefault: true,
});

await createService(router, { name: 'users', version: '1.0.0', port: 3001 })
  .withRPC()
  .withAuthn({ authenticator })
  .withAuthz({ authorizer })
  .withHealth() // /health stays anonymous
  .serve();
```

```ts
// Trust identity asserted by an upstream proxy/gateway
import { createTrustedHeaderAuthenticator } from '@netscript/service/auth';

// The Principal is assembled internally from these header NAMES — point at the
// headers your gateway sets; you do not map values yourself.
const authenticator = createTrustedHeaderAuthenticator({
  subjectHeader: 'x-forwarded-user',
  scopesHeader: 'x-forwarded-scopes', // optional; space/comma-separated
});

// then: .withAuthn({ authenticator })
```

> Service-auth seam vs. the auth plugin
>
> This middleware is for
>
> machine-to-machine and gateway-fronted
>
> gating: static credentials, trusted upstream headers, scope checks. It does
>
> not
>
> do interactive sign-in, OAuth callbacks, or session cookies. For
>
> signed-in human users
>
> (sign-in / callback / session / me), compose the
>
> `auth` plugin
>
> backend instead — the two layers are complementary and can run together.

## Production notes

> Footguns before you ship
>
> - **Don't wire liveness to dependency checks.** `/health/live` must stay dependency-free; only `/health/ready` should fail on an unreachable DB. Crossing them turns a transient DB blip into a container restart loop.
> - **Set `drainTimeoutMs` below your platform's kill grace.** The drain defaults to `30_000`; if your orchestrator sends SIGKILL sooner, in-flight requests are cut off — pick a timeout under the platform's termination grace period.
> - **The served RPC path is `/api/rpc/*`, not `/rpc`.** Point generated clients at the same path the runtime mounts.
> - **`denyByDefault` is `true`.** With `.withAuthz()` installed, any request that reaches no matching rule is rejected — add an explicit allow rule for public-but-authenticated routes rather than relaxing the default.
> - **Aspire first for DB-backed services.** `aspire start` must bring up Postgres/Redis before any `netscript db` command or the readiness probe will fail.

## Reference

This hub is intentionally thin — the full generated API lives in the reference.

[service](https://rickylabs.github.io/netscript/netscript/reference/service/)

[Look up — @netscript/service  The full generated API: defineService, createService, the fluent builder, the OpenAPI/Scalar and health primitives, the shutdown types, and the /auth middleware seam.](https://rickylabs.github.io/netscript/netscript/reference/service/)

[Look up — @netscript/contracts  Contract primitives plus the /crud, /query, and /transform helpers that generate CRUD contracts, paginated queries, and response transformers.](https://rickylabs.github.io/netscript/netscript/reference/contracts/)

[Understand — Contracts  The oRPC contract → implement → handler → typed client → query → island type flow, explained.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)

[Learn — Build a service  Guided tutorial: contract → users service on :3001 → typed client → island, built from scratch.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[Capabilities](https://rickylabs.github.io/netscript/netscript/capabilities/) [Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/)

_Canonical: https://rickylabs.github.io/netscript/services-sdk/services/_

---

# Web Layer

The web layer is where API drift surfaces last and costs the most turns to fix. NetScript's answer is `@netscript/fresh`: a server-first meta-framework, built on [Fresh](https://fresh.deno.dev/) 2.x and Preact, that renders pages from the **same contract object your services implement**. The page loader, the typed browser client, and the server handler share one type — so when a contract changes, the page that depends on it fails `deno check`, not production.

## The failure this layer removes

Picture the usual sequence in a UI built on hand-rolled `fetch` calls. A service endpoint gains a required filter and reshapes its response. The API compiles, its tests pass, and the dashboard — which encoded the old response shape in an untyped `fetch` — keeps rendering until a user (or an agent's browser check) finds the broken page. Whoever fixes it now spends turns rediscovering what the endpoint actually returns, because nothing in the UI's code says so.

In a NetScript workspace that sequence stops at the type checker. The scaffolded dashboard builds its client from the contract itself — `apps/dashboard/lib/example-service.ts` imports `UsersContractV1` and derives a typed client plus TanStack-Query factories from it — and that is the same contract object the `users` service implements. Reshape the endpoint and every page loader, island, and form that consumes it becomes a compile error with a file and line number: the response shape lives in the type system, where an agent can read it, instead of in someone's memory.

## How a page is put together

You author a page with `definePage()` — binding a typed **route contract**, server **resources** and **layers** (each with its own loader, cache window, and partial-refresh endpoint), and **forms** — then build it into Fresh route wiring. Rendering is server-first: handlers run in Deno and return HTML, and only components under `islands/` ship JavaScript to the browser, where they hydrate against the same query cache the server dehydrated.

![Request flow: browser hits a Fresh route built by definePage; the server handler runs resource and layer loaders that call the typed SDK client, which calls an oRPC service backed by the database; the rendered HTML ships to the browser where an island hydrates against the same query key.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/fresh-page-model.svg)

*The Fresh page model: definePage binds a route, runs server loaders through the typed SDK to a service, renders HTML, and hydrates islands against a shared query cache — one contract end to end.*

Each piece of that model has its own leaf page — link into the one you need rather than reading in order:

- **[The Fresh page model](https://rickylabs.github.io/netscript/web-layer/server/)** — server-first rendering, the islands boundary, and `defineFreshApp()` (`@netscript/fresh/server`), the bootstrap every NetScript Fresh app starts from.
- **[The define-page builder](https://rickylabs.github.io/netscript/web-layer/builders/)** — `definePage()` and `definePartial()` (`@netscript/fresh/builders`): typed layers, defer policies, and per-layer partial refresh.
- **[Route contracts](https://rickylabs.github.io/netscript/web-layer/route/)** — `defineRouteContract()`, schema helpers such as `paginationSearchSchema()`, and `createRouteReference()` for typed links.
- **[Data loading & the query cache](https://rickylabs.github.io/netscript/web-layer/query/)** — `QueryIsland`, `useQuery`, `useMutation`, and `useLiveQuery`: the TanStack-Query bridge that shares one cache between server render and island hydration.
- **[Server-validated forms](https://rickylabs.github.io/netscript/web-layer/form/)** — typed, contract-aware form handling declared as a page layer.
- **[Deferred & streaming UI](https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/)** — stream a fallback now, swap in real content when a slower layer resolves.
- **[Interactivity](https://rickylabs.github.io/netscript/web-layer/interactive/)** and **[durable-stream consumption](https://rickylabs.github.io/netscript/durable-workflows/streams/)** — island runtime helpers and the browser-side client for durable HTTP/SSE streams.
- **[Vite integration](https://rickylabs.github.io/netscript/web-layer/vite/)**, **[testing](https://rickylabs.github.io/netscript/web-layer/testing/)**, **[diagnostics](https://rickylabs.github.io/netscript/web-layer/error/)**, and **[worked examples](https://rickylabs.github.io/netscript/web-layer/examples/)**.

The visual layer on top of all of this — the copy-source component registry, design tokens, and the scaffolded dashboard app — is [Fresh UI & design](https://rickylabs.github.io/netscript/web-layer/fresh-ui/), which has its own story.

## Start here

[Overview & Concepts   Fresh page model  Server rendering, islands, route contracts, layers, partials, and shared query cache.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Overview & Concepts   Fresh UI & design  The copy-source component registry, design tokens, and the scaffolded dashboard app.](https://rickylabs.github.io/netscript/netscript/web-layer/fresh-ui/) [Quickstart   Live dashboard  Build a Fresh page backed by a typed SDK client and a cache-first QueryIsland.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/) [How-To   Customize Fresh UI  Adjust the generated UI layer and design-system surface.](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/customize-fresh-ui/) [How-To   Server-validated form  Build a form that validates and mutates on the server.](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/build-a-server-validated-form/) [API Reference   @netscript/fresh  Generated symbols for the Fresh framework package.](https://rickylabs.github.io/netscript/netscript/reference/fresh/) [API Reference   @netscript/fresh-ui  Generated symbols for the companion UI package.](https://rickylabs.github.io/netscript/netscript/reference/fresh-ui/)

## Learn, do, look up

[Learn  Live dashboard tutorial  Contract to page to live stream — the web layer end to end.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/) [Do  Recipes  Task-oriented recipes for this area, one problem each.](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/) [Look up  `@netscript/fresh` reference  Generated API reference. Related units: `fresh-ui`.](https://rickylabs.github.io/netscript/netscript/reference/fresh/) [Understand  Contracts & type flow  The design rationale behind this pillar.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)

_Canonical: https://rickylabs.github.io/netscript/web-layer/_

---

# Pages and the define-page builder

`@netscript/fresh` exposes a fluent builder for declaring pages. You start a chain with `definePage()`, layer on resources, params, render layers, handlers, and metadata, and finish with `build()` to produce a Fresh-compatible page definition. The same module also defines framework-owned partial routes through `definePartial()` and `defineStatsPartial()`. Reach for this surface whenever you author a route module and want a typed pipeline rather than hand-wired loaders and handlers.

Route contracts themselves — the generated route references passed to `withRoute()` — live on `@netscript/fresh/route`; see [Routing and route contracts](https://rickylabs.github.io/netscript/web-layer/route/).

## The builder chain

`definePage<TState>()` returns a `PageRootBuilder<TState>`, the root of a typed fluent chain. `PageRootBuilder` extends `PageBuilder`, the public fluent page builder surface. Each method returns a new `PageBuilder` whose type parameters carry forward the accumulated state, resources, path/search schemas, layer data, and a `THasRoute` flag. Because every step is typed, downstream loaders, handlers, layouts, and metadata resolvers see the exact shapes you declared earlier in the chain.

The chain ends with `build()`. When the page was bound to a route with `withRoute()` (setting `THasRoute` to `true`), `build()` returns a `RoutedPageDefinition`; otherwise it returns a `PageDefinition`. A `PageDefinition` exposes a `page` renderer and a `default` export-compatible renderer — both `(ctx: PageRequestContext<TState>) => Promise<PageRenderable>` — plus an optional `handler` built from the handlers you registered.

> `build()` is overloaded. Calling `build()` with no argument, `build(routePattern: string)`, or `build(options)` selects the routed or unrouted return type based on the arguments and the `THasRoute` flag. A page bound with `withRoute()` always builds a `RoutedPageDefinition`.

## Building a page

The example below composes documented builder methods only: it declares a resource, applies a search schema, registers a render layer, sets a status code, and builds an unrouted page definition. `definePage` infers each generic from the calls you make.

```ts
import { definePage } from "@netscript/fresh";

const page = definePage()
  .withResource("metrics", async () => {
    return await loadMetrics();
  })
  .withStatus(200)
  .withMeta((ctx) => ({ title: "Dashboard" }))
  .build();

export default page.default;
```

Inside a loader, handler, layout, or metadata resolver, the runtime hands you a `PageContext`. It extends `PageRequestContext` and adds the parsed `path` and `search` state, already-resolved `layerData`, the `routePattern`, a typed `nav` href builder, the `resources` record, and a `resource(key)` accessor that resolves a single named resource with full typing.

## Builder methods

The methods on `PageBuilder` group into resources, params, routing, render layers, handlers, and response shaping. Each returns a `PageBuilder` for continued chaining.

| Method | Purpose |
| --- | --- |
| `withResource(key, factory)` | Add a single named resource to the page pipeline. |
| `withResources(factories)` | Add multiple named resources to the page pipeline. |
| `withParams({ path?, search? })` | Apply both path and search schemas in one step. |
| `withPathParams(schema)` | Apply a typed path schema to the page. |
| `withSearchParams(schema)` | Apply a typed search schema to the page. |
| `withRoute(route)` | Bind the page to a generated route reference. |
| `withRouteContract({ $route?, pathSchema?, searchSchema? })` | Bind the page to a route via an inline contract; the Vite plugin inserts `$route` from the page path. |
| `withPolicy(policy)` | Configure defer policy defaults for the page. |
| `withTelemetry(telemetry)` | Configure telemetry metadata for the page. |
| `withLayer(id, component, config?)` | Register a render layer for the page. |
| `withForm(id, component, config)` | Register a route-bound form as a typed layer. |
| `withHandler(method, handler)` | Register a page method handler. |
| `withLayout(layout)` | Register the page layout. |
| `withMeta(resolver)` | Register the page metadata resolver. |
| `withHeader(...)` | Append a static header, header map, or computed headers. |
| `withStatus(status)` | Set the default HTTP status code for Fresh `GET` rendering. |
| `withStreaming()` | Enable builder-owned HTML streaming for `delivery: 'stream'` layers. |
| `createNav(routePattern?)` | Create typed route navigation for the page. |
| `build(...)` | Build the `PageDefinition` or `RoutedPageDefinition`. |

`withHeader` is overloaded: it accepts a single `name`/`value` pair, a `HeadersInit` map, or a `PageHeaderResolver` that computes headers per request.

### Params and route state

`withPathParams`, `withSearchParams`, and the combined `withParams` apply typed schemas to the page. After they run, `PageContext.path` and `PageContext.search` carry the parsed, typed state. `withRoute` binds the page to a `PageRouteReference`, which exposes a typed `nav`, an `href(...)` builder, a route-bound `Link` component, and `parsePath` / `parseSearch` helpers (plus `safeParsePath` / `safeParseSearch` returning a `PageSchemaParseResult`). Data loading details are covered in [Data loading and the query cache](https://rickylabs.github.io/netscript/web-layer/query/).

#### Codegen-owned route binding

With the NetScript Vite plugin enabled, the binding call itself is generated from the page module's path under `routes/`, so you author only the contract body. Three forms converge on the same generated `routes.<key>` tree:

- **Form A — inline.** `withRouteContract({ pathSchema?, searchSchema? })` keeps the contract body in the page module. The generator inserts `$route: routePatterns.<key>.$route` as the first field and the `routePatterns` import. The inline schemas drive the same `path` / `search` type-state promotion as `withRoute`.
- **Form B — sidecar.** A sibling `<page>.route.ts` owns the contract. The generator inserts `.withRoute(routes.<key>.$route)` and the `routes` import.
- **Form C — no contract.** The generator inserts a default `.withRoute(routes.<key>.$route)` backed by `createRouteReference(routePattern)`.

Both inline and sidecar in the same page is a build warning (inline wins, the sidecar is left in place). `.withRoute` and `.withRouteContract` in the same page is a build error. Set `pageModuleRouteBinding: false` on the Vite plugin to disable page-module rewriting and keep hand-written `.withRoute(...)` lines.

### Defer policy and streaming

`withPolicy` accepts a `PageDeferPolicyInput` or a `PageDeferPolicyProfile`. The profile is one of `"balanced"`, `"aggressive-first-paint"`, `"background-refresh"`, or `"low-bandwidth"`. A `PageDeferPolicyInput` overrides individual fields such as `staleTimeMs`, `prewarmOnMiss`, and `prewarmOnStale`. `withStreaming()` enables builder-owned HTML streaming for layers declared with `delivery: 'stream'`. See [Deferred and streaming UI](https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/) for the policy model.

### Handlers and methods

`withHandler(method, handler)` registers a method handler. `method` is a `PageMethod`, one of `"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`, `"OPTIONS"`, or `"HEAD"`. `withForm` registers a route-bound form as a typed layer, wiring a layer, method handler, CSRF headers, and form metadata; its component receives `RuntimeFormState` props. Forms are covered in [Server-validated forms](https://rickylabs.github.io/netscript/web-layer/form/).

## Partials

`definePartial()` defines a framework-owned partial route backed by an async loader, and `defineStatsPartial()` defines a stats-only partial backed by a context-free query function. Both return a `DefinedPartialRoute`, which carries a Fresh `config`, an optional `handler`, a `page` renderer, and a `default` export-compatible renderer.

`DefinePartialOptions` requires a stable `name`, a `loader` `(ctx) => Promise<TProps>`, and a `component`. It also accepts an optional `errorComponent`, `errorTitle`, `handler`, and Fresh `config`. `DefineStatsPartialOptions` omits `loader` and instead requires a `query` `() => Promise<TProps>`.

```ts
import { definePartial } from "@netscript/fresh";

export const liveCount = definePartial({
  name: "live-count",
  loader: async (ctx) => {
    return { total: await countActive(ctx) };
  },
  component: CountView,
});
```

## API summary

| Symbol | Description |
| --- | --- |
| `definePage<TState>()` | Start a new typed page builder chain. |
| `PageRootBuilder<TState>` | Root page builder returned by `definePage()`. |
| `PageBuilder<...>` | Public fluent page builder surface. |
| `PageDefinition<...>` | Unrouted page definition returned by `build()` without a route. |
| `RoutedPageDefinition<...>` | Page definition built with an explicit route. |
| `PageContext<...>` | Runtime context shared by loaders, handlers, layouts, and metadata resolvers. |
| `PageRequestContext<TState>` | Typed request context exposed to page builders. |
| `PageRenderContext<TState>` | Request context variant that can call `ctx.render()`. |
| `definePartial(options)` | Define a framework-owned partial route backed by an async loader. |
| `defineStatsPartial(options)` | Define a stats-only partial route backed by a context-free query. |
| `DefinePartialOptions<...>` | Options for creating a framework-owned partial route. |
| `DefineStatsPartialOptions<...>` | Options for creating a stats-only partial route. |
| `DefinedPartialRoute<...>` | Materialized partial route contract returned by `definePartial()`. |
| `PageMethod` | Page handler HTTP method union. |
| `PageDeferPolicyProfile` | Named defer policy profile union. |
| `PageRenderable` | Renderable value returned by page and partial renderers. |

## Related

[The Fresh page model  How a NetScript Fresh page is structured.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Routing and route contracts  Generated route references for withRoute().](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Data loading and the query cache  Resolve resources and cache data.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Server-validated forms  withForm and RuntimeFormState.](https://rickylabs.github.io/netscript/netscript/web-layer/form/) [Deferred and streaming UI  withPolicy, withStreaming, and defer profiles.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Live dashboard tutorial  Build a page end to end.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/)

See the [Web Layer overview](https://rickylabs.github.io/netscript/web-layer/) for the full pillar map.

_Canonical: https://rickylabs.github.io/netscript/web-layer/builders/_

---

# Deferred and streaming UI

A page often has one region that is slower than the rest — a dashboard panel that aggregates data, a detail view that reads from cache, or a feed that updates as events arrive. `@netscript/fresh` gives you two complementary tools for these regions: **deferred rendering**, which paints a fallback immediately and fills the region in once data is ready, and the **streams client SDK**, which keeps a region reactive against durable streams over the wire. Reach for deferral when a region is slow on the server; reach for streams when a region needs to stay live after the first paint.

## Deferred rendering

Deferred rendering lets a page respond with stable content while a slower region resolves separately. The `defer` surface ships two layers: a low-level Suspense-style boundary (`Deferred`) for a single promise, and a higher-level page wrapper (`DeferPage`) that coordinates a cached region, a fallback, and a refresh policy.

### Deferring a single region

`Deferred` is a promise-prop consumer for RFC-style deferred data. It takes a `promise`, an optional `fallback` shown while the promise is pending, an optional `errorFallback` invoked when the promise rejects, and `children` — either renderable content or a render function that turns the resolved value into content.

```tsx
import { Deferred } from "@netscript/fresh";

export function Panel({ slowData }: { slowData: Promise<readonly string[]> }) {
  return (
    <Deferred
      promise={slowData}
      fallback={<p>Loading…</p>}
      errorFallback={(error) => <p>Could not load: {error.message}</p>}
    >
      {(rows) => (
        <ul>
          {rows.map((row) => <li>{row}</li>)}
        </ul>
      )}
    </Deferred>
  );
}
```

The render function signature is captured by `DeferredRenderFunction<T>`, and both the fallback and the resolved output are typed as `DeferredRenderable` — the set of values Fresh accepts in a deferred slot.

> **Progressive delivery is staged.** In the current non-streaming Fresh runtime, `Deferred` behaves like a Suspense-ready boundary and becomes fully progressive once streaming delivery lands. Code written against it today keeps working as that delivery path is enabled.

### Deferring a page region with a policy

`DeferPage` renders a deferred region with optional server prewarm and telemetry hooks. Where `Deferred` wraps a promise, `DeferPage` coordinates the full lifecycle of a cached region: it renders `component` when cached data exists, `fallback` until the region resolves, and uses a Fresh partial (`name`, `partial`, `action`) to refresh the region on the client.

The props are described by `DeferPageProps`:

```tsx
import { DeferPage } from "@netscript/fresh";

export function OrdersRegion(
  { ctx, cachedOrders, cachedAt }: {
    ctx: { url: URL; req: Request; isPartial?: boolean };
    cachedOrders?: unknown;
    cachedAt?: number;
  },
) {
  return (
    <DeferPage
      name="orders"
      action="/orders"
      partial="/orders/partial"
      component={cachedOrders}
      fallback={<p>Loading orders…</p>}
      cachedAt={cachedAt}
      staleTime={30_000}
      policy={ { profile: "background-refresh" } }
      staleStrategy="server-prewarm"
      ctx={ctx}
    />
  );
}
```

The `policy` prop accepts either a named `DeferPagePolicyProfile` or a `DeferPagePolicyInput` object. The `ctx` prop is a `DeferPageRequestContextLike` — just the `url`, `req`, and optional `isPartial` fields `DeferPage` needs to detect partial and prewarm rendering, so you do not have to pass your full app context type.

### Refresh policy

A policy controls when a deferred region revalidates. `DeferPolicyInput` exposes the tunable knobs:

- `staleTimeMs` — freshness window before cached data is considered stale.
- `prewarmOnMiss` / `prewarmOnStale` — whether a cache miss or stale hit starts a server-side prewarm request.
- `clientRefreshOnFreshCache` — whether fresh cache hits still trigger a client refresh.
- `skipClientWhenServerPrewarm` — whether client refresh is skipped while a server prewarm is active (avoids duplicate requests).

Instead of setting every field, you can name a `DeferPolicyProfile`: `"balanced"`, `"aggressive-first-paint"`, `"background-refresh"`, or `"low-bandwidth"`. `resolveDeferPolicy` merges a profile, a stale override, and any legacy strategy into a fully populated `DeferPolicyResolved` used by both the server and the island renderers:

```ts
import { resolveDeferPolicy } from "@netscript/fresh";

const resolved = resolveDeferPolicy(
  { profile: "balanced" },
  30_000,
  "server-prewarm",
);
// resolved.staleTimeMs, resolved.prewarmOnStale, …
```

The package also ships conventional presets used by generated pages: `DEFER_POLICY` (profiles keyed by `header` and `detail`), `DEFER_STALE_MS` (stale windows for `crud` and `forceRefresh`), and `DETAIL_FORCE_REFRESH_POLICY` (a detail-page policy that preserves immediate consistency after navigation).

The `staleStrategy` prop on `DeferPage` is a `LegacyStaleStrategy` — `"none"` (the default; let the island decide) or `"server-prewarm"` (fire-and-forget server revalidation when stale).

## Streaming UI with durable streams

The `@netscript/fresh/streams` subpath is the client SDK for end-to-end durable streams. It connects a Preact island to the durable streams server and keeps TanStack DB collections updating reactively as events arrive.

`createNetScriptStreamDB()` is the entry point: a generic, TanStack DB-backed StreamDB factory that wraps `@durable-streams/state` with NetScript URL resolution. It returns a `NetScriptStreamDB` whose `.collections` are typed TanStack DB collections that update as events arrive from the server.

```ts
import {
  createNetScriptStreamDB,
  useLiveQuery,
} from "@netscript/fresh/streams";
import { myStreamSchema } from "../schemas.ts";

const db = createNetScriptStreamDB({
  streamPath: "/my-service/my-stream",
  schema: myStreamSchema,
});

// In a Preact island:
const { data: items } = useLiveQuery((q) =>
  q.from({ i: db.collections.myEntity })
);
```

### Factory options

`NetScriptStreamDBOptions` configures the stream database:

- `streamPath` — stream path relative to the streams server root (e.g. `/workers/executions`).
- `schema` — the `NetScriptStateSchema` for the durable stream database.
- `baseUrl` — optional override for the base stream server URL; defaults to the env-resolved `getStreamsUrl()`.
- `createStreamDB` — optional factory port for tests or alternate stream DB adapters.

The returned `NetScriptStreamDB` exposes `collections` plus optional `stop` and `dispose` hooks for adapters that support tearing the connection down.

### Live queries in islands

Two hooks run a TanStack DB live query through the NetScript streams surface, both working via `preact/compat` inside Fresh islands:

- `useLiveQuery` — run a live query and read its current result.
- `useLiveSuspenseQuery` — the suspense variant of the same query.

Both accept a query factory (`NetScriptLiveQueryFactory`) and optional `deps`, and return a `NetScriptLiveQueryResult<TData>` with `data`, `status`, `error`, and a `details` record carrying any additional upstream fields.

## API summary

### Deferred rendering (`@netscript/fresh`)

| Symbol | Kind | Description |
| --- | --- | --- |
| `Deferred` | function | Promise-prop consumer for RFC-style deferred data; a Suspense-ready boundary. |
| `DeferredProps<T>` | interface | Props for `Deferred`: `promise`, `fallback`, `children`, `errorFallback`. |
| `DeferredRenderable` | type | Renderable content accepted by deferred Suspense slots. |
| `DeferredRenderFunction<T>` | type | Render function turning resolved deferred data into content. |
| `DeferPage` | function | Render a deferred region with optional server prewarm and telemetry hooks. |
| `DeferPageProps` | interface | Props for the `DeferPage` server wrapper. |
| `DeferPagePolicyInput` | interface | Policy overrides accepted by the page wrapper. |
| `DeferPagePolicyProfile` | type | Named page policy profiles. |
| `DeferPolicyInput` | interface | Policy overrides that tune when deferred regions refresh. |
| `DeferPolicyResolved` | interface | Fully resolved defer policy used by server and island renderers. |
| `DeferPolicyProfile` | type | `"balanced"` \| `"aggressive-first-paint"` \| `"background-refresh"` \| `"low-bandwidth"`. |
| `resolveDeferPolicy` | function | Resolve policy input, stale override, and legacy strategy into a complete policy. |
| `DEFER_POLICY` | const | Conventional defer policy profiles used by generated pages. |
| `DEFER_STALE_MS` | const | Conventional stale windows used by generated CRUD pages. |
| `DETAIL_FORCE_REFRESH_POLICY` | const | Detail-page policy preserving immediate consistency after navigation. |

### Streams client SDK (`@netscript/fresh/streams`)

| Symbol | Kind | Description |
| --- | --- | --- |
| `createNetScriptStreamDB` | function | Create a NetScript-configured TanStack DB-backed StreamDB. |
| `NetScriptStreamDBOptions<TDef>` | interface | Options for `createNetScriptStreamDB`. |
| `NetScriptStreamDB<TDef>` | interface | Stream database handle with reactive `collections` plus optional `stop`/`dispose`. |
| `useLiveQuery` | function | Run a TanStack DB live query through the streams surface. |
| `useLiveSuspenseQuery` | function | Suspense variant of the live query. |
| `NetScriptLiveQueryResult<TData>` | interface | Result with `data`, `status`, `error`, and `details`. |
| `NetScriptLiveQueryFactory` | type | Function that builds a live query from the upstream query builder. |
| `NetScriptStateSchema<TDef>` | type | NetScript-owned state schema accepted by the factory. |

## Related

[The Fresh page model  How a Fresh page is assembled on the server.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Data loading and the query cache  Load data and read it from the query cache that deferred regions build on.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Interactive islands  Hydrate islands where live-query hooks run.](https://rickylabs.github.io/netscript/netscript/web-layer/interactive/)

For an end-to-end walkthrough that combines deferred regions and streaming updates, follow the flagship tutorial: [Live dashboard](https://rickylabs.github.io/netscript/tutorials/live-dashboard/).

_Canonical: https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/_

---

# Error handling and diagnostics

`@netscript/fresh` ships an explicit error-handling surface for the Web Layer. Instead of letting a thrown loader propagate into a blank screen, it normalizes any failure into a single `ErrorData` payload, classifies it by HTTP status, and renders it with a default display that you can override. Reach for this surface whenever a page loads data that can fail and you want a predictable shape to branch on — and a presentation you control.

## The model

The surface is built around three ideas: a normalized payload, a wrapped loader, and a renderable display.

- **`ErrorData`** is the normalized payload. Every failure is reduced to a stable object — `message`, `status`, optional `code`, a classified `type`, a `retry` flag, and a `timestamp`. Loaders, handlers, and error displays all speak this shape.
- **`errorHandler()`** wraps a loader so a thrown value never escapes raw. It returns a `LoaderResult<T>` — either your success data or a normalized error envelope.
- **`ErrorDisplay`** renders an `ErrorData` payload, with an overridable presentation slot for custom views.

### Error classification

Errors are categorized by HTTP status into the `ErrorType` taxonomy:

| `ErrorType` | Meaning |
| --- | --- |
| `"client"` | Client-side failure (4xx-range status). |
| `"server"` | Server-side failure (5xx-range status). |
| `"unknown"` | Status that does not map cleanly to either category. |

`classifyErrorType(status)` performs this mapping, `getDefaultMessage(status)` returns the default user-facing message for a known status code, and `isRetryable(status, type)` decides whether retry affordances should be offered for a given status-and-type combination.

### The normalized payload

`extractErrorData(error)` takes any thrown value and produces a normalized `ErrorData`:

```ts
interface ErrorData {
  message: string;    // User-facing message derived from the source error.
  status: number;     // HTTP status associated with the error.
  code?: string;      // Optional machine-readable code.
  type: ErrorType;    // HTTP-derived error classification.
  retry: boolean;     // Whether retry affordances should be shown.
  timestamp: number;  // Unix epoch timestamp in milliseconds.
}
```

## Wrapping a loader

`errorHandler()` wraps a loader with Fresh error normalization. It has two forms, distinguished by whether you supply a fallback:

- `errorHandler(loader, fallback)` returns a loader producing `LoaderResult<T, true>` — on failure the result carries both normalized `error` data and your `fallback` value as `data`.
- `errorHandler(loader)` returns a loader producing `LoaderResult<T, false>` — on failure the result carries only normalized `error` data.

`LoaderResult<T, HasFallback>` is a union of either the success value `T` or an error envelope. The result is narrowed with `hasError()` and unpacked with the matching extract/parse helper.

```ts
import {
  errorHandler,
  hasError,
  extractData,
  extractErrorWithFallback,
} from "@netscript/fresh";

// No-fallback form: errored result carries only normalized error data.
const loadOrders = errorHandler(async () => {
  return await fetchOrders();
});

const result = await loadOrders();

if (hasError(result)) {
  // result is { error: ErrorData }
  console.error(result.error.message, result.error.status);
} else {
  // Narrowed to success data.
  const orders = extractData(result);
  renderOrders(orders);
}
```

With a fallback, the errored result still hands you usable data:

```ts
import { errorHandler, hasError, extractErrorWithFallback } from "@netscript/fresh";

const loadStats = errorHandler(
  async () => await fetchStats(),
  { total: 0, pending: 0 }, // fallback
);

const result = await loadStats();

if (hasError(result)) {
  // result is { error: ErrorData; data: typeof fallback }
  const { error, data } = extractErrorWithFallback(result);
  reportError(error);
  renderStats(data); // render the fallback rather than crashing
}
```

### Choosing an extraction helper

The helpers below unpack a `LoaderResult` after you have classified it. Pick the one that matches whether your loader was wrapped with a fallback and how strict you want to be:

| Helper | Result form | Returns |
| --- | --- | --- |
| `extractData(result)` | `LoaderResult<T, false>` | Success data, after a `hasError()` check. |
| `extractDataWithFallback(result)` | `LoaderResult<T, true>` | Fallback data from an errored result. |
| `extractErrorWithFallback(result)` | `LoaderResult<T, true>` | `{ error, data }` — both normalized error and fallback. |
| `safeParseData(result)` | `LoaderResult<T, false>` | Success data, or `null` when the result contains an error. |
| `safeParseDataWithFallback(result)` | `LoaderResult<T, true>` | Success data, or the fallback when errored. |

## Rendering the error

`ErrorDisplay` renders normalized error data with an overridable presentation slot. It accepts `ErrorDisplayProps`:

- `error: ErrorData` — the normalized payload to render.
- `title?: string` — optional title shown above the message.
- `showRetry?: boolean` — whether retry affordances appear for retryable errors.
- `children?` — a render prop or replacement node for custom presentation.

```tsx
import { ErrorDisplay, hasError, extractData } from "@netscript/fresh";

export default function Page({ result }) {
  if (hasError(result)) {
    return (
      <ErrorDisplay
        error={result.error}
        title="We could not load this page"
        showRetry
      />
    );
  }

  const data = extractData(result);
  return <Dashboard data={data} />;
}
```

For compact, in-flow surfaces — a failed widget inside an otherwise healthy page — use `InlineError`, which renders the same normalized `ErrorData` in a tighter layout:

```tsx
import { InlineError } from "@netscript/fresh";

<InlineError error={result.error} />;
```

### Custom presentation with primitives

The `children` prop of `ErrorDisplay` accepts a render prop that receives `ErrorPrimitives` — a precomputed view payload shared by package-owned and app-owned error views. It exposes the resolved `errorTitle`, `errorMessage`, `errorCode`, `errorType`, `errorStatus`, `errorTimestamp`, `errorIcon`, `isRetryable`, and the default renderer's utility classes (`bgColor`, `borderColor`, `textColor`), alongside the raw `error`. This lets you replace the markup while keeping the framework's classification and message resolution.

```tsx
import { ErrorDisplay } from "@netscript/fresh";

<ErrorDisplay error={result.error}>
  {(p) => (
    <section class={`${p.bgColor} ${p.borderColor} ${p.textColor}`}>
      <h2>{p.errorIcon} {p.errorTitle}</h2>
      <p>{p.errorMessage}</p>
      {p.errorCode ? <code>{p.errorCode}</code> : null}
    </section>
  )}
</ErrorDisplay>;
```

> The `children` render prop and `ErrorDisplay` return values are typed as `ErrorDisplayContent` — the renderable content accepted and returned by the error display helpers.

## API summary

| Symbol | Description |
| --- | --- |
| `ErrorData` | Normalized error payload for loaders, handlers, and error displays. |
| `ErrorType` | HTTP-derived error category: `"client"`, `"server"`, or `"unknown"`. |
| `LoaderResult<T, HasFallback>` | Loader result returned by `errorHandler()` — success value or an error envelope. |
| `errorHandler(loader, fallback?)` | Wrap a loader with Fresh error normalization; the fallback form also returns fallback data. |
| `extractErrorData(error)` | Extract a normalized `ErrorData` payload from any thrown value. |
| `classifyErrorType(status)` | Classify an HTTP status code into the `ErrorType` taxonomy. |
| `getDefaultMessage(status)` | Return the default user-facing message for a known HTTP status code. |
| `isRetryable(status, type)` | Whether a status-and-type combination should offer retry affordances. |
| `hasError(result)` | Narrow a `LoaderResult` to its error envelope. |
| `extractData(result)` | Extract success data after a `hasError()` check. |
| `extractDataWithFallback(result)` | Extract fallback data from an errored loader result. |
| `extractErrorWithFallback(result)` | Extract both normalized error data and fallback data. |
| `safeParseData(result)` | Return success data, or `null` when the result contains an error. |
| `safeParseDataWithFallback(result)` | Return success data, or fallback data from a loader result. |
| `ErrorDisplay(props)` | Render normalized error data with an overridable presentation slot. |
| `InlineError({ error })` | Render normalized error data in a compact inline layout. |
| `ErrorDisplayProps` | Props accepted by the default error display component. |
| `ErrorPrimitives` | Shared error-display payload for package-owned and app-owned views. |
| `ErrorDisplayContent` | Renderable content accepted and returned by the error display helpers. |

## Related

[Data loading and the query cache  Where loaders run and how their results are cached.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Routing and route contracts  How requests and statuses reach a page.](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Server-validated forms  Surfacing validation failures back to the page.](https://rickylabs.github.io/netscript/netscript/web-layer/form/) [Deferred and streaming UI  Handling failures inside streamed regions.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Testing Fresh pages  Assert on normalized error results.](https://rickylabs.github.io/netscript/netscript/web-layer/testing/) [Live dashboard tutorial  See error handling end-to-end in the flagship build.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/)

See the [Web Layer hub](https://rickylabs.github.io/netscript/web-layer/) for the full pillar map.

_Canonical: https://rickylabs.github.io/netscript/web-layer/error/_

---

# Examples and sandbox

A curated index of runnable Web Layer examples built on `@netscript/fresh`. Start here when you want to see the meta-framework end to end rather than one capability at a time. Each entry below points to a tutorial or how-to that composes the documented Web Layer surface — page builders, routing, data loading, forms, and streaming UI — into something you can run.

## Where to start

The flagship example is the **live dashboard** tutorial. It walks through the full page model: defining a page with the builder, loading data through the query cache, wiring a server-validated form, and streaming deferred regions into the response. It is the most complete demonstration of how the Web Layer fits together.

- [Live dashboard tutorial](https://rickylabs.github.io/netscript/tutorials/live-dashboard/) — the end-to-end Web Layer example.

From there, the Web Layer how-to guides isolate each capability so you can lift a single pattern into your own project.

## The smallest typed example, end to end

The shortest path from a contract to a rendered island: a typed route reference, a contract-derived query, and a `QueryIsland`. It composes three documented surfaces — [routing](https://rickylabs.github.io/netscript/web-layer/route/), the [query cache](https://rickylabs.github.io/netscript/web-layer/query/), and the [SDK bridge](https://rickylabs.github.io/netscript/services-sdk/sdk/) — and nothing in it is hand-typed:

```tsx
// apps/dashboard/islands/OrdersPanel.tsx
import { QueryIsland, useIslandQuery } from "@netscript/fresh/query";
import { createRouteReference } from "@netscript/fresh/route";
import { orders } from "../lib/api-clients.ts"; // createServiceQueryUtils(ordersClient)

const ordersRoute = createRouteReference("/orders");

function OrdersList() {
  const query = useIslandQuery({
    ...orders.list.queryOptions({ input: { limit: 20 } }),
    staleTime: 15_000,
  });

  return (
    <section>
      <a href={ordersRoute.href()}>Orders</a>
      <ul>
        {query.data?.map((order) => <li key={order.id}>{order.reference}</li>)}
      </ul>
    </section>
  );
}

export default function OrdersPanel() {
  return (
    <QueryIsland>
      <OrdersList />
    </QueryIsland>
  );
}
```

The `orders` query utils come from the single `lib/api-clients.ts` module the [query cache page](https://rickylabs.github.io/netscript/web-layer/query/) builds — `createServiceClient` → `createServiceQueryUtils` — so a renamed contract field is a compile error here, not a runtime blank. For the full read/write pair (typed query plus optimistic mutation) see that page.

## The package surface

`@netscript/fresh` keeps its capabilities on explicit subpaths. The package root exposes only the cross-cutting page-loader cache helpers; everything else lives behind a dedicated import. Reading the root module is the fastest way to see how the pieces are organised before opening any one guide.

The documented subpaths are `./builders`, `./route`, `./form`, `./defer`, `./query`, `./server`, `./streams`, `./interactive`, `./vite`, `./error`, and `./testing`.

The root entry itself centres on cache projection — composing a derived cache entry from a cached list response so a detail view can reuse a list query's data without a second round trip:

```ts
import {
  hasAllCacheEntries,
  minCachedAt,
  projectCachedItemFromList,
} from "@netscript/fresh";

// `listEntry` is a cached list response loaded by a page query.
const itemEntry = projectCachedItemFromList(
  listEntry,
  (item) => item.id === selectedId,
);

// Gate rendering on every required cache entry being present.
const ready = hasAllCacheEntries([listEntry, itemEntry]);

// Oldest timestamp across the entries, for staleness display.
const oldest = minCachedAt([listEntry, itemEntry]);
```

`projectCachedItemFromList` preserves the list entry's `cachedAt` timestamp on the projected item, so the detail view stays consistent with the list it was derived from.

## API summary

| Symbol | Description |
| --- | --- |
| `hasAllCacheEntries` | Return `true` when every supplied entry is present. |
| `minCachedAt` | Return the oldest `cachedAt` timestamp across the supplied entries. |
| `projectCachedItemFromList` | Project a single cached item from a cached list response while preserving the list timestamp. |
| `CacheEntryLike` | Cached-entry shape shared by page loaders and partial orchestration. |
| `CachedListEntryLike` | Cached list-entry shape used when projecting a single list item. |

`CacheEntryLike<T>` carries a readonly `data` payload and a readonly `cachedAt` Unix-epoch timestamp in milliseconds. `CachedListEntryLike<TItem>` is the same shape over a `{ items: TItem[] }` payload.

> **StackBlitz sandboxes**
>
> Hosted, one-click sandboxes for the Web Layer examples are a planned addition. Until they ship, clone the tutorial source and run it locally with the project's build task.

## Related

[Live dashboard tutorial  The flagship end-to-end Web Layer example.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/) [The Fresh page model  How a Fresh page is shaped and served.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Pages and the builder  Define a page with the define-page builder.](https://rickylabs.github.io/netscript/netscript/web-layer/builders/) [Routing and route contracts  Map URLs to page contracts.](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Data loading and the query cache  Load data through the page query cache.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Server-validated forms  Validate form submissions on the server.](https://rickylabs.github.io/netscript/netscript/web-layer/form/) [Deferred and streaming UI  Stream deferred regions into the response.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Interactive islands  Add client interactivity to a page.](https://rickylabs.github.io/netscript/netscript/web-layer/interactive/) [Build and Vite integration  The build pipeline and Vite setup.](https://rickylabs.github.io/netscript/netscript/web-layer/vite/) [Error handling and diagnostics  Surface and diagnose page errors.](https://rickylabs.github.io/netscript/netscript/web-layer/error/) [Testing Fresh pages  Test pages built with the Web Layer.](https://rickylabs.github.io/netscript/netscript/web-layer/testing/)

Return to the [Web Layer hub](https://rickylabs.github.io/netscript/web-layer/) for the full pillar overview.

_Canonical: https://rickylabs.github.io/netscript/web-layer/examples/_

---

# Server-validated forms

The `@netscript/fresh` form surface lets a Fresh page own a form end to end: parse the posted payload on the server, validate it against a schema, surface field-level and form-level errors, and render the same managed `Form` component on both the initial GET and the failed POST. Reach for it when a page mutates data and must round-trip submitted values and errors without a client framework, while keeping CSRF protection and idempotent submissions in place.

This entrypoint is intentionally narrow. It exposes the shipped helper surface used by playground consumers and keeps deeper form internals out of the public package contract.

> The shipped `FormState` model is intentionally small. Richer runtime state — field descriptors, collection intents, progressive enhancement — exists in the surface (for example `RuntimeFormState` and `FormEnhancementSnapshot`) and is introduced incrementally. Build server-validated forms on `resolveFormState` and `Form` today; adopt the richer descriptors as your pages need them.

## How the surface fits together

A server-validated form moves through three layers:

1. **Parse** the incoming `FormData` into a plain nested object with `formDataToRawValues`, then normalize empty strings to `undefined` with `normalizeFormValues`.
2. **Validate** the normalized values. A schema adapter such as the one returned by `createStandardSchemaAdapter` turns any Standard Schema v1 validator into a `FormSchemaAdapter`, whose `safeParse` returns a normalized success or failure result. On failure, errors flatten into the canonical `FormErrors` shape.
3. **Render** the managed `Form` component with the resolved `FormState`. On a GET request the state starts from your initial values; on a failed POST it preserves the submitted values and errors so the page re-renders with the user's input intact.

`resolveFormState` is the bridge between the route handler and the component: it inspects the handler `data` and either preserves an existing `FormState` or builds a fresh one from initial values.

## Defining and rendering a form

The `Form` component renders a managed `<form>` element with the submission and CSRF hidden inputs already wired. It accepts a `state` (the resolved `FormState`-compatible value), the form `children`, and optional `formProps` overrides. `formProps` is a `FormElementOverrideProps` bag: an open attribute set (every field optional, plus an `[attribute: string]: unknown` index signature) so you can forward `class`, standard `<form>` attributes (`action`, `method`, `noValidate`, `id`), and any additional ARIA, `data-*`, or framework attribute onto the rendered element — you style and configure the managed form the same way you would a plain one. The four handler slots the managed runtime owns — `onSubmit`, `onBlurCapture`, `onInputCapture`, and `ref` — are typed `never`, so passing one is a compile-time error rather than a silent override of the progressive-enhancement wiring.

```tsx
import { Form, resolveFormState } from "@netscript/fresh/form";

interface ContactValues {
  email: string;
  message: string;
}

export default function ContactForm({ data }: { data: unknown }) {
  const state = resolveFormState<ContactValues>(data, {
    email: "",
    message: "",
  });

  return (
    <Form<ContactValues>
      state={state}
      formProps={ { action: "/contact", method: "POST" } }
    >
      <label htmlFor="email">Email</label>
      <input id="email" name="email" type="email" defaultValue={state.values.email} />

      <label htmlFor="message">Message</label>
      <textarea id="message" name="message">{state.values.message}</textarea>

      <button type="submit">Send</button>
    </Form>
  );
}
```

`FormState` exposes exactly two members: `values` (the current `Partial<TValues>`) and `errors` (a `FormErrors<TValues>` map). To read the first message for a field, call `firstFieldError(state.errors, "email")`.

## Validating on the server

On the server, parse and validate the payload, then return a `FormState` from the handler so the page can re-render with errors. Build a `FormSchemaAdapter` from any Standard Schema v1 schema with `createStandardSchemaAdapter`, and convert a thrown validation error into the canonical `FormErrors` shape with `toFormErrors`.

```ts
import {
  createEmptyFormErrors,
  createStandardSchemaAdapter,
  formDataToRawValues,
  normalizeFormValues,
  toFormErrors,
} from "@netscript/fresh/form";
import type { FormState } from "@netscript/fresh/form";

interface ContactValues {
  email: string;
  message: string;
}

// `schema` is any Standard Schema v1 compatible validator.
const adapter = createStandardSchemaAdapter<typeof schema, ContactValues>(schema);

export async function handleContact(request: Request): Promise<FormState<ContactValues>> {
  const formData = await request.formData();
  const raw = formDataToRawValues(formData);
  const values = normalizeFormValues<ContactValues>(raw);

  const result = await adapter.safeParse(values);
  if (!result.success) {
    return {
      values,
      errors: toFormErrors<ContactValues>({
        flatten: () => ({
          fieldErrors: result.fieldErrors,
          formErrors: result.formErrors,
        }),
      }),
    };
  }

  // Run the mutation with the validated `result.data`, then redirect or return success.
  return { values, errors: createEmptyFormErrors<ContactValues>() };
}
```

`formDataToRawValues` understands dotted paths and bracket indices (`items[0].productId` becomes `{ items: [{ productId: "value" }] }`), so nested values arrive in the shape your schema expects. `normalizeFormValues` recursively converts empty strings to `undefined` before validation runs.

## Posting the validated payload through a typed mutation

Validation gives you a typed `result.data`; the write that follows should be typed too. Instead of a hand-written `fetch`, run the mutation through the same [typed SDK client](https://rickylabs.github.io/netscript/services-sdk/sdk/) the rest of the app uses — the contract that typed the form's schema is the contract that types the write, so the two cannot drift. On the server, the handler calls the typed client directly with the validated data:

```ts
// apps/dashboard/routes/contact.ts (handler excerpt)
import { contactsClient } from "../lib/api-clients.ts";

// `result.data` is the contract-typed ContactValues from adapter.safeParse.
const created = await contactsClient.create(result.data);
// Redirect to the new record; the id is inferred from the contract output.
return Response.redirect(`/contact/${created.id}`, 303);
```

When the form is progressively enhanced with an island, drive the identical contract write from the client with `useIslandMutation` and the query utils' `mutationOptions()` — the mirror of the read path in [Data loading and the query cache](https://rickylabs.github.io/netscript/web-layer/query/). The validated values become the typed mutation input:

```tsx
// apps/dashboard/islands/ContactFormIsland.tsx
import { useIslandMutation } from "@netscript/fresh/query";
import { contacts } from "../lib/api-clients.ts";

interface ContactValues {
  email: string;
  message: string;
}

function useContactSubmit(onDone: () => void) {
  // mutationOptions() supplies the contract-bound mutationFn + mutationKey.
  return useIslandMutation({
    ...contacts.create.mutationOptions(),
    onSuccess: onDone,
  });
}

// After client-side validation succeeds, post the typed payload:
//   submit.mutate(validated); // validated: ContactValues, checked at compile time
export { useContactSubmit, type ContactValues };
```

`contacts` is one entry in the single `lib/api-clients.ts` module described in the [query cache page](https://rickylabs.github.io/netscript/web-layer/query/): `createServiceClient` → `createServiceQueryUtils`. Either path — server handler or enhanced island — writes through the contract, so the form's read schema and its write can never fall out of sync.

## CSRF protection

The form surface carries a CSRF token between the GET that renders the form and the POST that submits it. Generate a token with `generateCsrfToken`, persist it with `setCsrfCookie` on the response headers, and on submission read the cookie token with `readCsrfToken` and compare it to the submitted token with `verifyCsrfToken`.

```ts
import {
  generateCsrfToken,
  readCsrfToken,
  setCsrfCookie,
  verifyCsrfToken,
  CSRF_FIELD_NAME,
} from "@netscript/fresh/form";

// GET: issue a token and set the cookie.
const token = generateCsrfToken();
const headers = new Headers();
setCsrfCookie(headers, token, new URL(request.url));

// POST: verify the submitted token against the cookie.
const formData = await request.formData();
const submitted = formData.get(CSRF_FIELD_NAME)?.toString();
const cookieToken = readCsrfToken(request);
if (!verifyCsrfToken(cookieToken, submitted)) {
  // Reject the submission.
}
```

The cookie name is fixed as `CSRF_COOKIE_NAME` (`"ns_form_csrf"`) and the hidden field name as `CSRF_FIELD_NAME` (`"__csrf__"`). The managed `Form` component renders that hidden CSRF input for you when the state carries a token.

## Idempotent submissions

Each rendered form can round-trip a stable submission identifier so a retried POST is not processed twice. `generateSubmissionId` creates the identifier, and `getSubmissionHiddenInputProps` returns the hidden input props that carry it under `SUBMISSION_ID_FIELD_NAME` (`"__submission_id__"`).

```ts
import {
  generateSubmissionId,
  getSubmissionHiddenInputProps,
} from "@netscript/fresh/form";

const submissionId = generateSubmissionId();
const hiddenProps = getSubmissionHiddenInputProps(submissionId);
```

## Partial form regions

`FormRegion` renders a Fresh partial boundary so a form-driven update can replace, prepend, or append a region of the page without a full navigation. It accepts the partial `name`, an optional `mode` (`"replace"`, `"prepend"`, or `"append"`), and `children`.

```tsx
import { FormRegion } from "@netscript/fresh/form";

<FormRegion name="contact-result" mode="replace">
  {/* Region content updated by the form submission. */}
</FormRegion>;
```

## API summary

### Components

| Symbol | Description |
| --- | --- |
| `Form` | Render a managed form element with submission and CSRF hidden inputs. |
| `FormRegion` | Render a Fresh partial boundary for form-driven updates. |
| `FormProps<TValues>` | Props accepted by the managed form component (`state`, `children`, `formProps`, `enhancement`). |
| `FormElementOverrideProps` | The open `formProps` override bag — optional `class` / `id` / `action` / `method` / `noValidate`, an arbitrary-attribute index signature, and `never`-typed `onSubmit` / `onBlurCapture` / `onInputCapture` / `ref` slots the runtime owns. |
| `FormRegionProps` | Props for the partial-region helper (`name`, `mode`, `children`). |

### Parsing and state

| Symbol | Description |
| --- | --- |
| `formDataToRawValues` | Parse a `FormData` instance into a nested object, handling dotted paths and bracket indices. |
| `normalizeFormValues` | Normalize raw values by converting empty strings to `undefined`. |
| `resolveFormState` | Resolve form state from route handler data, preserving submitted values and errors when present. |
| `FormState<TValues>` | Lightweight shipped form state: `values` and `errors`. |

### Validation

| Symbol | Description |
| --- | --- |
| `createStandardSchemaAdapter` | Create a `FormSchemaAdapter` from any Standard Schema v1 compatible schema. |
| `FormSchemaAdapter<TValues, TOutput>` | Validation boundary with `parse`, `safeParse`, `getConstraints`, and `getDefaults`. |
| `toFormErrors` | Convert a Zod-like validation error into the canonical `FormErrors<T>` shape. |
| `createEmptyFormErrors` | Create an empty form error map. |
| `firstFieldError` | Return the first error message for a field, if present. |
| `FormErrors<TValues>` | Field-level error map; the `_form` key stores form-wide errors. |

### CSRF and idempotency

| Symbol | Description |
| --- | --- |
| `generateCsrfToken` | Generate a new CSRF token for a rendered form. |
| `readCsrfToken` | Read the current CSRF token from a request cookie header. |
| `setCsrfCookie` | Set the CSRF cookie on response headers. |
| `verifyCsrfToken` | Verify that the submitted token matches the cookie token. |
| `CSRF_COOKIE_NAME` / `CSRF_FIELD_NAME` | Cookie and hidden-field names used for the token. |
| `generateSubmissionId` | Create a new form submission identifier. |
| `getSubmissionHiddenInputProps` | Return the hidden input props that carry an idempotent submission id. |
| `SUBMISSION_ID_FIELD_NAME` | Hidden field name used to round-trip the submission id. |

## Related

[The Fresh page model  How a Fresh page is composed.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Pages and builders  The define-page builder.](https://rickylabs.github.io/netscript/netscript/web-layer/builders/) [Routing and route contracts  Map requests to handlers.](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Data loading and the query cache  Load and cache server data.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Deferred and streaming UI  Stream UI as data resolves.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Interactive islands  Hydrate interactive regions.](https://rickylabs.github.io/netscript/netscript/web-layer/interactive/)

- Pillar hub: [Web Layer](https://rickylabs.github.io/netscript/web-layer/)
- Flagship tutorial: [Live dashboard](https://rickylabs.github.io/netscript/tutorials/live-dashboard/)
- [Error handling and diagnostics](https://rickylabs.github.io/netscript/web-layer/error/) · [Testing Fresh pages](https://rickylabs.github.io/netscript/web-layer/testing/) · [Examples and sandbox](https://rickylabs.github.io/netscript/web-layer/examples/)

_Canonical: https://rickylabs.github.io/netscript/web-layer/form/_

---

# Fresh UI & design

A design system earns its keep when the person — or agent — changing the UI can open every file involved. NetScript's Fresh UI layer is **copy-source**: components are installed into your repo as readable TypeScript and CSS you own, driven by design tokens you can edit, with a live gallery inside your own scaffolded app showing every primitive rendered with *your* tokens. Nothing in the visual layer hides behind a package boundary.

## Why copy-source, concretely

The recurring failure in agent-edited UIs is not bad taste — it is a boundary. Ask for "a destructive variant of our button" against a conventional installed component library and the agent cannot edit the component (it lives in an immutable package), so it wraps it, overrides its styles from outside, or hand-writes a lookalike `div`. Repeat that a few times and the codebase carries three button dialects, none of them token-driven, and the next change costs more turns than the first.

Here, `netscript ui:add button` copies the component's source and its CSS into `apps/dashboard/components/ui/`, wired to the token layer in `assets/tokens.json`. The variant is an edit to a file that is already in the repo, in the same grammar as every other component — and the `(design)` route group in the scaffolded app renders the result immediately, next to every other primitive, styled by the same tokens. One vocabulary, visible in one place, owned by you.

The rest of this page maps that layer end to end — and disentangles the two things it is easiest to conflate on the way in.

NetScript gives you a **front end with the same contracts-first rigor as the back end** — and it does so in two distinct layers that are easy to conflate. There is **`@netscript/fresh`, a real meta-framework** (a published package of Fresh runtime extensions, route/island builders, a TanStack-Query bridge, forms, and a streams client), and there is the **scaffolded dashboard app** (`apps/dashboard`) that the meta-framework *powers*. The package is the reusable engine; the app is one fully-wired showcase built on top of it. Both ship in every workspace, but they live at different addresses and you reach for them at different moments.

> Use this when
>
> Reach for this layer when you need a
>
> typed, server-rendered web UI
>
> over your services — an internal admin panel, an operations console, or a customer-facing app — that cannot drift from your oRPC contracts. Use
>
> `@netscript/fresh`
>
> (the meta-framework) to build pages/islands in any Fresh app; use
>
> `apps/dashboard`
>
> (the scaffolded app) as the worked reference to copy patterns from. For the data boundary the UI renders see
>
> Services & contracts
>
> ; to add or regenerate UI pieces see
>
> Customize the Fresh UI
>
> .

## Two layers, one design grammar

**The meta-framework vs. the scaffolded app**

| Name | Type | Description |
| --- | --- | --- |
| `@netscript/fresh` | `meta-framework (package)` | A published Deno package: Fresh runtime extensions, the definePage/island builders, a TanStack-Query bridge, forms, defer primitives, a streams client, and route contracts. Reusable across any Fresh app you build. Reference: /reference/fresh/. |
| `apps/dashboard` | `scaffolded app` | One concrete Fresh 2.x application generated into your repo, built ON @netscript/fresh and wired to your users service. The worked showcase you copy patterns from — not a finished product UI. |
| `@netscript/fresh-ui` | `component registry` | The copy-source component library + design tokens installed into apps/dashboard/components/ui/ via netscript ui:init / ui:add. You own the copied files. Reference: /reference/fresh-ui/. |

> Don't conflate the package with the app
>
> @netscript/fresh
>
> is a
>
> meta-framework you import
>
> — it exposes targeted subpaths (
>
> /server
>
> ,
>
> /builders
>
> ,
>
> /route
>
> ,
>
> /query
>
> ,
>
> /form
>
> ,
>
> /defer
>
> ,
>
> /streams
>
> ,
>
> /interactive
>
> ,
>
> /vite
>
> ,
>
> /testing
>
> ,
>
> /error
>
> ) and can power
>
> any
>
> Fresh app, not just the scaffold.
>
> apps/dashboard
>
> is the
>
> app that consumes it
>
> . When this page says "the dashboard," it means the scaffolded app; when it says "
>
> @netscript/fresh
>
> ," it means the reusable engine.

## The meta-framework: `@netscript/fresh`

`@netscript/fresh` is a published package (`Fresh runtime extensions, builders, forms, defer primitives, and route contracts for NetScript`) built on `@fresh/core` 2.x + Preact. You consume it through **targeted subpath exports** rather than one fat barrel — import only the surface you need. The full generated API for every subpath lives at the [`@netscript/fresh` reference](https://rickylabs.github.io/netscript/reference/fresh/); the table below is the map.

**@netscript/fresh subpath exports (the meta-framework surface)**

| Name | Type | Description |
| --- | --- | --- |
| `@netscript/fresh/server` | `bootstrap` | defineFreshApp(...) — the baseline app bootstrap (static files, file-system routes) so every NetScript Fresh app boots identically. |
| `@netscript/fresh/builders` | `page builder` | The definePage() / route-reference builders that bind a typed route, declare server-loaded layers, and wire telemetry. |
| `@netscript/fresh/route` | `route contracts` | Route-reference primitives (createRouteReference) for typed, generated route patterns consumed via router.ts. |
| `@netscript/fresh/query` | `TanStack bridge` | QueryIsland, useQuery, useMutation, useQueryClient — the TanStack-Query hydration bridge over your contract-derived query factories. |
| `@netscript/fresh/form` | `forms` | Typed form primitives for server-validated, contract-aware form handling. |
| `@netscript/fresh/defer` | `streaming defer` | Defer primitives for streaming/deferred server rendering of slower layers. |
| `@netscript/fresh/streams` | `streams client` | The Fresh-side durable-stream client for consuming HTTP/SSE durable streams in the browser (the producer runtime lives in @netscript/plugin-streams-core). |
| `@netscript/fresh/interactive` | `interactivity` | Interactive island runtime helpers used by the hydrated client islands. |
| `@netscript/fresh/vite` | `build` | The Vite integration the dev/build pipeline uses. |
| `@netscript/fresh/testing` | `testing` | Test helpers for exercising pages, islands, and route contracts. |
| `@netscript/fresh/error` | `diagnostics` | Typed error/diagnostics surface for the Fresh runtime. |

> Distinct from the back-end stream producer
>
> The Fresh-side
>
> @netscript/fresh/streams
>
> client
>
> consumes
>
> durable streams over HTTP/SSE in the browser. The
>
> producer
>
> runtime — the thing that writes stream state — is real and lives server-side in
>
> @netscript/plugin-streams-core
>
> (
>
> createDurableStream
>
> ), served as an Aspire service on
>
> :4437
>
> . See
>
> Streams
>
> for the producer/consumer split.

## The scaffolded app: `apps/dashboard`

Every NetScript workspace ships `apps/dashboard` — a [Fresh](https://fresh.deno.dev/) 2.x application built with Preact, Tailwind CSS v4, and Vite. It is a workspace member registered in the root `deno.json` and orchestrated by Aspire alongside your services. It boots through `defineFreshApp` from `@netscript/fresh/server`, the meta-framework's baseline bootstrap, so every NetScript Fresh app starts the same way. It is **not a placeholder**: the scaffold wires it directly to your oRPC contracts so the dashboard renders typed, server-prefetched data from the same `users` service the back end implements.

**apps/dashboard layout (verbatim from a fresh scaffold)**

| Name | Type | Description |
| --- | --- | --- |
| `main.ts` | `entry` | App entry: export const app = defineFreshApp({ name: 'dashboard' }). Reads PORT (default 8010) and logs a startup banner. |
| `router.ts` | `routing` | Stable route entrypoint. Re-exports generated routePatterns + routes and builds typed appRoutes via createRouteReference. |
| `routes/` | `pages` | File-system routes: index.tsx, dashboard.tsx, health.tsx, examples/service/, examples/telemetry/, the (design) system pages, plus _app.tsx / _layout.tsx shells. |
| `islands/` | `interactivity` | Client-hydrated Preact islands (e.g. ThemeToggle, SidebarToggle, Toast under islands/ui/). |
| `components/ui/` | `design system` | The copy-source component library you own (@netscript/fresh-ui): button, card, data-table, form-field, badge, and more (tsx + matching CSS in assets/ui/). |
| `lib/` | `service wiring` | example-service.ts builds a typed oRPC client + query factories from your contract; cn.ts, public-types.ts. |
| `assets/` | `styling` | design.css, tokens.css/json, theme-bridge.css, and per-component CSS — the Tailwind v4 + design-token layer. |
| `.generated/` | `generated` | manifest.ts + routes.ts produced by the Fresh route generator; consume via router.ts, never directly. |

> Two ports, one app
>
> The dashboard's own dev server reads
>
> PORT
>
> and defaults to
>
> 8010
>
> (
>
> http://localhost:8010
>
> , health at
>
> /health
>
> ). That is distinct from the
>
> Aspire dashboard
>
> at
>
> https://localhost:18888
>
> , which orchestrates the whole resource graph. Bring the platform up first with
>
> cd aspire && aspire start
>
> (Postgres/Redis + every service), or run the app standalone with
>
> deno task --cwd apps/dashboard dev
>
> .

## Contract-driven by default

The dashboard does not hand-roll `fetch` calls. `apps/dashboard/lib/example-service.ts` imports your `UsersContractV1` and turns it into a typed client and TanStack-Query factories through the NetScript SDK — the same contract object the `users` service implements, so the UI cannot drift from the API.

```ts
// apps/dashboard/lib/example-service.ts
import { createServiceClient } from '@netscript/sdk/client';
import { createQueryFactories } from '@netscript/sdk/query';
import { bridgeInvalidation } from '@netscript/sdk/query-client';
import { UsersContractV1 } from '@plugin-smoke/contracts';

export const exampleServiceName = 'users';
export const exampleServiceClient = createServiceClient<typeof UsersContractV1>({
  contract: UsersContractV1,
  serviceName: exampleServiceName,
  routerName: 'users',
});

// queryOptions / mutationOptions derived straight from the contract.
export const exampleServiceQueries = createQueryFactories({
  service: { contract: UsersContractV1, client: exampleServiceClient },
}).service;
```

A **route** is declared with the meta-framework's `definePage()` builder (`@netscript/fresh/builders`) — it binds a typed route reference, declares server-loaded layers, and wires telemetry — while an **island** consumes the query factories above through the `@netscript/fresh/query` bridge for hydration, optimistic mutations, and cache invalidation on the client.

```tsx
// definePage() declares a typed page: route + server-loaded layers + telemetry.
import { appRoutes } from '@app/router.ts';
import { definePage } from '@app/utils.ts';
import { ServiceExampleLabPanel } from './(_components)/lab-panel.tsx';
import { loadServiceShowcaseData } from './(_shared)/service-showcase.ts';

export const serviceExamplePage = definePage()
  .withRoute(appRoutes.serviceExample)
  .withPolicy('balanced')
  .withTelemetry({ enabled: true, spanName: 'scaffold.examples.users' })
  .withMeta(() => ({ title: 'users example', description: 'Backed by the users service.' }))
  .withLayer('lab', ServiceExampleLabPanel, { loader: loadServiceShowcaseData })
  .build();

export const { default: page } = serviceExamplePage;
export { page as default };
```

```tsx
// Client-hydrated island: typed query + optimistic mutation over the contract.
import { QueryIsland, useMutation, useQuery, useQueryClient } from '@netscript/fresh/query';
import { exampleServiceQueries, exampleServiceListInvalidation } from '@app/lib/example-service.ts';

const Lab = (props: { input: { status?: string } }) => {
  const queryClient = useQueryClient();
  const { data, refetch, isRefetching } = useQuery({
    ...exampleServiceQueries.list.queryOptions(props.input),
    staleTime: 15_000,
  });
  const advance = useMutation({
    ...exampleServiceQueries.updateStatus.mutationOptions(),
    onSettled: () => queryClient.invalidateQueries(exampleServiceListInvalidation),
  });
  return <button type='button' onClick={() => void refetch()}>{isRefetching ? '…' : 'Refresh'}</button>;
};

export default (props: { input: { status?: string } }) => (
  <QueryIsland><Lab {...props} /></QueryIsland>
);
```

> Islands are the only client code
>
> Fresh ships zero JavaScript by default. Anything under
>
> islands/
>
> is the
>
> only
>
> code hydrated in the browser; routes and components render on the server. The
>
> users
>
> showcase loads its list on the server, dehydrates the query cache, and the
>
> ServiceShowcaseLab
>
> island re-hydrates it for interactive refetch and optimistic status updates — the contract-to-pixel proof end to end.

## The design system & owned components

The scaffold installs the NetScript Fresh UI foundation (`@netscript/fresh-ui`) into `apps/dashboard/components/ui/` and its CSS into `assets/ui/`, driven by design tokens in `assets/tokens.json` / `tokens.css`. Because the components are copied into your repo, editing the UI is editing your own files — there is no framework component you cannot open. The bundled `(design)` route group renders a live token, component, and composition gallery so you can see every primitive in your project.

Astro's documentation answers "what does this look like?" with one-click browser sandboxes; NetScript answers it from inside your repo — the `(design)` gallery is a live preview of the components you actually installed, rendered with the tokens you actually set, served by your own app. When you edit a token or a copied component, the gallery is where you watch the whole vocabulary absorb the change.

What ships falls into four groups, each installable by registry id (`ui:add <name>`) or as a named collection. The AI/workspace group is worth calling out: it is a finite, token-driven component vocabulary for agent-facing surfaces — message threads, tool-call cards, citations, charts — that an application can map structured model output onto, so generated UI lands in your design language instead of ad-hoc markup:

**What the registry ships**

| Name | Type | Description |
| --- | --- | --- |
| `Interactive namespaces` | `@netscript/fresh-ui/interactive` | Stateful, accessible compound primitives: Accordion, Dialog, Drawer, Popover, Sheet, Tabs, Tooltip, and the headless Combobox seam (useCombobox) that powers the command palette and autocompletes. |
| `L0 primitives` | `@netscript/fresh-ui/primitives` | Small platform-contract helpers: Show (wrapper-free conditional render), VisuallyHidden and its SrOnly alias, and Icon — a first-class stroke-SVG icon primitive also re-exported from the package root. |
| `AI / workspace primitives` | `ui:add` | The agent-surface set: avatar, citation-chip, code-block, model-selector, tool-call-card, chart-block, donut, prompt-input (auto-grows to fit its content), message (renderInline + TypingIndicator), and dropzone (drag, clipboard-paste, and multi-file ingest) — plus the foundation set (button, card, badge, data-table, forms, feedback, dashboard blocks). |
| `Command & search utilities` | `ui:add` | command-palette (.ns-cmdk — the ⌘K modal that wraps the Combobox) and search (.ns-search — a compact nav affordance with a ⌘K hint that opens it). |

You manage that library with two CLI commands (run from the workspace root):

**Fresh UI CLI commands**

| Name | Type | Description |
| --- | --- | --- |
| `netscript ui:init` | `install foundation` | Installs the Fresh UI foundation set into an app workspace. The scaffold runs the equivalent for you; run it once when adding UI to an app that lacks it. |
| `netscript ui:add ` | `add an item` | Copies one registry item or a named collection into components/ui/, wires its CSS, and merges any required deno.json imports. Example: netscript ui:add data-table. |

> DataGrid is a runtime export, not a ui:add block
>
> The generic
>
> DataGrid
>
> component — a typed
>
> columns
>
> /
>
> rows
>
> contract with
>
> strong
>
> /
>
> num
>
> cell variants and plain, button, or Fresh-navigation rows — is exported from the
>
> @netscript/fresh-ui
>
> package root, so you
>
> import it directly
>
> rather than
>
> ui:add
>
> -ing it. It is the runtime successor to the copy-source
>
> data-table
>
> block; both still ship, so reach for
>
> DataGrid
>
> when you want a templated grid you do not have to own and copy in. See the
>
> reference
>
> for its full API.

> Copy-source ownership tradeoff
>
> Because
>
> ui:add
>
> copies code into your repo, you own it: customize freely, but you do
>
> not
>
> get automatic upstream updates. Re-running
>
> ui:add … --force
>
> re-copies the source — and overwrites your local edits — so treat foundation files as yours and keep heavy customization in your own components. Full options live behind
>
> netscript ui:init --help
>
> /
>
> netscript ui:add --help
>
> and in the
>
> @netscript/fresh-ui reference
>
> .

## Scope

The scaffolded dashboard is a working, contract-wired **showcase** — not a finished product UI. It ships the `users` example (server-prefetched list + optimistic status mutation), a telemetry example, a CRUD example, a health page, and the design gallery. Treat these as the canonical patterns to copy from, not features to ship as-is; build your real screens by following the same `definePage` + island + query-factory shape against `@netscript/fresh`. The meta-framework is the durable surface — the app is one application of it.

## Endpoints & ports

**Fresh UI runtime surface**

| Name | Type | Description |
| --- | --- | --- |
| `:8010` | `port` | Dashboard dev server (Deno.env.get('PORT') \|\| '8010'). Standalone: deno task --cwd apps/dashboard dev. |
| `/health` | `HTTP` | App health route logged at startup (http://localhost:8010/health). |
| `:18888` | `Aspire` | Aspire dashboard that orchestrates the dashboard alongside services/plugins; token printed by aspire start. |
| `:3001` | `upstream` | The users service the dashboard's typed client calls — same UsersContractV1, no drift. |
| `:4437` | `streams` | The durable-streams Aspire service the @netscript/fresh/streams client consumes over HTTP/SSE (producer runtime in @netscript/plugin-streams-core). |

## Where to go next

This hub is intentionally thin — the full generated APIs live in the reference. Pick the lane that matches what you're doing.

[Learn — Build a service  Guided tutorial: contract → users service on :3001 → typed client → the island that renders it in the dashboard.](https://rickylabs.github.io/netscript/netscript/tutorials/storefront/02-catalog-service/)

[Do — Customize the Fresh UI  Task recipe: ui:init / ui:add, the copy-source ownership model, and editing the design tokens.](https://rickylabs.github.io/netscript/netscript/web-layer/how-to/customize-fresh-ui/)

[Look up — @netscript/fresh reference  The meta-framework's full generated API: defineFreshApp, definePage, the query/route/form/defer/streams builders, and the server runtime.](https://rickylabs.github.io/netscript/netscript/reference/fresh/)

[Look up — @netscript/fresh-ui reference  The component registry, foundation set, design tokens, and the ui:init / ui:add surface.](https://rickylabs.github.io/netscript/netscript/reference/fresh-ui/)

[Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/) [Authentication](https://rickylabs.github.io/netscript/netscript/identity-access/auth/)

_Canonical: https://rickylabs.github.io/netscript/web-layer/fresh-ui/_

---

# Web Layer — recipes

Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at [All how-to recipes](https://rickylabs.github.io/netscript/netscript/how-to/).

_Canonical: https://rickylabs.github.io/netscript/web-layer/how-to/_

---

# Building a desktop frontend the NetScript way

**Goal:** compose one Fresh frontend that runs as an ordinary browser/Aspire app and gains native window chrome, tray menus, dialogs, notifications, typed RPC, and update-ready UX when hosted by Deno Desktop.

The boundary is capability-based. Your route tree stays a normal Fresh 2 application. The native host owns window creation and policy; `@netscript/fresh/desktop` binds your existing oRPC router to that window, `@netscript/sdk/desktop` creates the typed webview client, and copied `@netscript/fresh-ui` components render the controls. None of those layers exits the process, starts an updater, or invents browser fallbacks.

> Browser and Aspire are first-class modes
>
> The desktop lifecycle and
>
> DesktopOnly
>
> island return inert results when the native capability is absent. Server rendering therefore never opens a dialog, requests notification permission, or calls a window global.

## 1. Install the desktop UI collection

From the workspace root, copy the app-owned desktop controls into the dashboard:

```bash
netscript ui:add desktop --app dashboard
```

The collection installs tray/menu, dialog, notification, window-chrome, update-prompt, and `DesktopOnly` sources plus their token-driven CSS. They are copied code: import components from your app barrel, not from the registry package.

## 2. Bind your existing router in the native host

Create the Deno Desktop window explicitly, then bind the same oRPC router and context you use for other transports. The Fresh adapter accepts a narrow window shape and returns `bound | disabled`, so cleanup is unconditional:

```ts
import { bindDesktopRpcWindow } from '@netscript/fresh/desktop';
import { appRouter } from './rpc/router.ts';

const window = new BrowserWindow({ title: 'NetScript Studio' });
const rpc = bindDesktopRpcWindow({
  window,
  router: appRouter,
  context: { windowId: 'main' },
});

addEventListener('unload', () => void rpc.close());
```

Keep window creation, exit-on-last-window, updater scheduling, and application shutdown in this composition root. Reusable UI must not decide those policies.

## 3. Call the contract from the webview

Use the existing service contract for inference. No ambient `bindings.d.ts`, hand-written JSON protocol, or duplicate RPC contract is needed:

```ts
import { createDesktopServiceClient } from '@netscript/sdk/desktop';
import { appContract } from '../contracts/app.ts';

export const desktopApi = createDesktopServiceClient({ contract: appContract });
const session = await desktopApi.sessions.get({ id: 'session-42' });
```

Outside Deno Desktop, construct this client only behind the same desktop gate. Ordinary browser and Aspire data paths continue to use the normal SDK transport.

## 4. Wire native chrome without hiding policy

`createDesktopChrome` owns the mechanical adapter: declarative menu translation, stable action-ID dispatch, feature-gated dialogs and notifications, documented window operations, replacement, and cleanup. Your host still decides what an action means:

```ts
import { createDesktopChrome } from '@netscript/fresh-ui/desktop';

const chrome = createDesktopChrome({
  window,
  tray: {
    tooltip: 'NetScript Studio',
    menu: [
      { type: 'action', id: 'show-window', label: 'Show window' },
      { type: 'separator' },
      { type: 'role', role: 'quit' },
    ],
  },
  onAction(event) {
    if (event.actionId === 'show-window') chrome.show();
  },
});
```

Only documented operations are exposed: title, show, hide, focus, reload, and close. There are no fake minimize/maximize controls, and `dispose()` releases listeners and tray state without exiting the application.

## 5. Render desktop-gated, app-owned controls

The copied controls emit intents. Connect those intents to an active lifecycle in a small island; keep ordinary page content outside the gate:

```tsx
import DesktopOnly from '@app/islands/DesktopOnly.tsx';
import { DesktopWindowChrome } from '@app/components/ui/mod.ts';

export function NativeChrome() {
  return (
    <DesktopOnly>
      <DesktopWindowChrome
        title='NetScript Studio'
        actions={['focus', 'reload', 'hide', 'close']}
        onAction={(action) => chrome.performWindowAction(action)}
      />
    </DesktopOnly>
  );
}
```

Use `DesktopTrayMenu`, `DesktopDialog`, and `DesktopNotification` the same way: their callbacks carry declarations or requests to the host controller, while server render remains side-effect free.

## 6. Render update-ready events exhaustively

Pass the ready event from `@netscript/sdk/auto-update` directly to `DesktopUpdatePrompt`. Automatic updates say **“Update ready — restart to apply”**. The manual branch uses the event's verified `manualUpdateUrl` for the Windows installer; do not infer the branch from platform strings.

```tsx
<DesktopUpdatePrompt event={readyEvent} onRestart={requestApplicationRestart} />;
```

## Verify both modes

1. Run the Fresh app in a browser or under Aspire and open `/design/components`. Desktop controls render as previews; `DesktopOnly` emits no native-only content and the console stays clean.
2. Test action IDs and controller results with injected structural capabilities—never ambient global declarations.
3. Run native packaging and smoke through the desktop smoke workflow. Browser gallery proof is not a substitute for native window, tray, dialog, or notification validation.

> Keep the native smoke claim honest
>
> This recipe proves composition and browser-safe behavior. The project desktop smoke gate owns the real packaged-runtime check.

## See also

- [Customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/)
- [`@netscript/fresh` reference](https://rickylabs.github.io/netscript/reference/fresh/)
- [`@netscript/sdk` reference](https://rickylabs.github.io/netscript/reference/sdk/)
- [`@netscript/fresh-ui` reference](https://rickylabs.github.io/netscript/reference/fresh-ui/)

_Canonical: https://rickylabs.github.io/netscript/web-layer/how-to/build-a-desktop-frontend/_

---

# Build a server-validated form

Use `definePage().withForm()` when a Fresh page needs route-bound form state, server validation, mutation, and redirect or same-page success handling in one typed page definition.

## Prerequisites

- A Fresh route that can render a NetScript page definition.
- A schema object accepted by the form runtime.
- A server mutation that receives validated input.
- A component that receives `RuntimeFormState` props.

## Define the form

`withForm(id, component, config)` registers a typed layer and a method handler. The config surface includes `schema`, `initial`, `mutate`, `onIntent`, `redirectTo`, `onSuccess`, `invalidate`, `csrf`, `method`, and `spanName`.

```tsx
import { definePage } from '@netscript/fresh';
import { z } from 'zod';

const ContactSchema = z.object({
  email: z.string().email(),
  message: z.string().min(10),
});

function ContactForm(props: {
  values: Record<string, unknown>;
  errors?: Record<string, readonly string[]>;
  message?: string;
}) {
  return (
    <form method="post">
      <input name="email" value={String(props.values.email ?? '')} />
      <textarea name="message">{String(props.values.message ?? '')}</textarea>
      <button type="submit">Send</button>
    </form>
  );
}

export const contactPage = definePage()
  .withForm('contact', ContactForm, {
    schema: ContactSchema,
    method: 'POST',
    csrf: true,
    initial: () => ({ email: '', message: '' }),
    mutate: async (input) => {
      const ticket = await createSupportTicket(input);
      return { ticketId: ticket.id };
    },
    redirectTo: (output) => `/support/thanks?id=${output.ticketId}`,
    spanName: 'form.contact',
  })
  .build('/contact');
```

## Render validation errors

Validation failures stay on the form layer. Keep field rendering defensive: read `values`, show field errors when present, and avoid assuming the mutation ran.

```tsx
function FieldError(props: { errors?: readonly string[] }) {
  if (!props.errors?.length) return null;
  return <p class="field-error">{props.errors[0]}</p>;
}
```

## Test the page definition

Keep one unit test around the builder chain so method, schema, and layer IDs stay wired.

```ts
import { assertEquals } from '@std/assert';
import { contactPage } from './contact.page.tsx';

Deno.test('contact page registers the route pattern', () => {
  assertEquals(contactPage.routePattern, '/contact');
});
```

## Failure modes

- Missing `schema`: the form has no server validation boundary.
- `mutate` throws: the form runtime returns an error state instead of running `redirectTo`.
- `redirectTo` and `onSuccess` both exist: `redirectTo` takes precedence.
- CSRF is enabled by default; disable it only for a route that has another verified protection.

## Next steps

- Use the page-builder model from [Fresh meta-framework](https://rickylabs.github.io/netscript/capabilities/fresh-framework/).
- Connect the page to typed data with [Live Dashboard, chapter 04](https://rickylabs.github.io/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/).
- Look up the builder surface in [fresh reference](https://rickylabs.github.io/netscript/reference/fresh/).

[Add a task runtime adapter](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/add-a-task-runtime-adapter/) [Build a validated ingestion queue](https://rickylabs.github.io/netscript/netscript/durable-workflows/how-to/build-a-validated-ingestion-queue/)

_Canonical: https://rickylabs.github.io/netscript/web-layer/how-to/build-a-server-validated-form/_

---

# Customize Fresh UI

**Goal:** make the scaffolded frontend yours — edit a route, add an interactive island, restyle a component, install more UI primitives, and re-theme the app — without fighting the framework. NetScript scaffolds a real [Fresh](https://fresh.deno.dev) 2 application at `apps/dashboard/`, powered by the [`@netscript/fresh`](https://rickylabs.github.io/netscript/reference/fresh/) meta-framework, and the UI components live in *your* repository as copied source. After the copy, that code is yours to change.

This is a task-oriented recipe. It assumes you already have a NetScript workspace (created with `netscript init`) whose `apps/dashboard/` app type-checks and runs. For the full generated API of the building blocks, follow the reference links at the end — this page never duplicates the [reference](https://rickylabs.github.io/netscript/reference/fresh-ui/).

> The ownership model in one sentence
>
> The Fresh runtime (
>
> @netscript/fresh
>
> ) and the UI registry (
>
> @netscript/fresh-ui
>
> ) are framework packages, but every component you render is
>
> copied into `apps/dashboard/components/ui/`
>
> by
>
> netscript ui:init
>
> /
>
> ui:add
>
> — so editing the UI is editing your own files, not patching a dependency.

## Before you start

You need:

- An existing NetScript workspace with the scaffolded `apps/dashboard/` Fresh app. If you do not have one yet, create it first (`netscript init`) — see the [Quickstart](https://rickylabs.github.io/netscript/quickstart/) or the [Storefront tutorial](https://rickylabs.github.io/netscript/tutorials/storefront/).
- The `netscript` command on your path. Run `netscript --help` to confirm, and `netscript ui:init --help` / `netscript ui:add --help` for the exact option spelling in your installed version. If `netscript` is not found, install it with `deno install --global --allow-all --name netscript jsr:@netscript/cli@0.0.1-beta.11`.

Run the app while you work so you can see each change live. Aspire is step 2 of the normal startup flow — it brings up your database (Postgres is the recommended engine; or `mysql` / `mssql` / `sqlite` chosen at scaffold time via `--db`) and Redis before any `netscript db` command and orchestrates the dashboard for you. You can also run the Fresh app on its own when you only need the UI loop:

```bash
# Brings up Postgres + Redis AND the dashboard; Aspire dashboard graph at https://localhost:18888
cd aspire && aspire start
```

```bash
# Leaner single-process loop — Vite dev server with HMR
deno task --cwd apps/dashboard dev
```

> Start at /design
>
> Before changing anything, open the scaffolded
>
> /design
>
> showcase in the running app. It renders the live component gallery (
>
> /design/components
>
> ), the token reference (
>
> /design/tokens
>
> ), and composition rules (
>
> /design/composition
>
> ) against the active theme — all from the app-owned copies, so it is the fastest way to feel what you already have.

## Where the app lives

Everything for the frontend is under `apps/dashboard/`. The layout follows Fresh 2 file-system routing, with NetScript conventions layered on top:

**apps/dashboard/ — what each path owns**

| Name | Type | Description |
| --- | --- | --- |
| `main.ts` | `app entry` | Bootstraps the Fresh app with defineFreshApp from @netscript/fresh/server. Reads PORT and prints the startup banner you see in aspire start logs. |
| `routes/` | `pages + layouts` | File-system routes. index.tsx, dashboard.tsx, health.tsx, examples/, plus _app.tsx (HTML shell) and _layout.tsx (chrome). Groups like (_components)/, (_shared)/, and (_islands)/ are non-routing co-location folders. |
| `islands/` | `client interactivity` | Hydrated Preact components (ThemeToggle, SidebarToggle, Toast). Everything else renders on the server only. |
| `components/ui/` | `app-owned UI` | The copied @netscript/fresh-ui primitives — Button, Card, Badge, PageHeader, StatsGrid, and friends. Edit these freely; they are yours after the copy. Barrel at components/ui/mod.ts. |
| `assets/` | `styling + tokens` | tokens.css / tokens.json (the --ns-* design tokens), styles.css, design.css, and per-component CSS under assets/ui/. Tailwind v4 is wired through Vite. |
| `lib/` | `app helpers` | cn.ts (class merge), example-service.ts, public-types.ts — non-UI utilities the routes import. |
| `router.ts / utils.ts` | `typed wiring` | router.ts exposes typed route references (appRoutes); utils.ts exports the createDefine() define helper and the definePage() builder. |
| `vite.config.ts / deno.json` | `build + deps` | Vite + Fresh + Tailwind plugins and the @app/* aliases; deno.json pins fresh, preact, @preact/signals, tailwindcss, and the @netscript/fresh* imports. |

The app entry is one call — `defineFreshApp` keeps the static-file and filesystem-route bootstrap framework-managed, so you only author routes, islands, and components:

```ts
import { defineFreshApp } from '@netscript/fresh/server';
import type { State } from '@app/utils.ts';

export const app = defineFreshApp<State>({ name: 'dashboard' });

// PORT is supplied by Aspire; defaults locally. The banner shows in `aspire start` logs.
const port = parseInt(Deno.env.get('PORT') || '8010');
console.log(`[dashboard] listening on http://localhost:${port}`);
```

Aspire injects `PORT` at runtime, so the entrypoint reads it from the environment; the typed source of truth is your `netscript.config.ts` `apps.<name>.port` field, which the scaffold wires as the fallback default — set the port there rather than editing this line.

> Two import roots, two jobs
>
> @netscript/fresh
>
> is the
>
> runtime meta-framework
>
> : it ships the app bootstrap (
>
> /server
>
> ), route and page builders, and a typed data layer (
>
> /query
>
> ), alongside
>
> /builders
>
> ,
>
> /route
>
> ,
>
> /form
>
> ,
>
> /defer
>
> , and
>
> /interactive
>
> subpaths.
>
> @netscript/fresh-ui
>
> is the
>
> component registry
>
> the CLI copies from. You import the runtime directly; you import UI from your own
>
> @app/components/ui/mod.ts
>
> barrel, not from the registry package.

> Meta-framework vs scaffolded app
>
> Keep two ideas distinct:
>
> @netscript/fresh
>
> is the reusable
>
> meta-framework
>
> (server/islands/query primitives that any Fresh app can import), while
>
> apps/dashboard/
>
> is
>
> your scaffolded instance
>
> of it. The concept hub on
>
> Fresh UI
>
> explains how the two relate and where each layer's responsibilities begin and end.

## Edit a route

Create a typed page first with `netscript ui:add page status --route status --island`, then customize its generated view. This writes `routes/status/index.tsx` with `definePage()`; `--island` also creates colocated `(_islands)/` and `(_shared)/query-loaders.ts` seams. The Vite route generator discovers it on the next build.

Routes are plain `.tsx` files under `routes/`. The scaffold uses the `definePage()` builder (from `@app/utils.ts`) so a page declares its route, metadata, and the view it renders in one typed chain. To change the home page, edit `routes/(_components)/home-view.tsx` (the presentational view) and/or `routes/index.tsx` (the page declaration and its data):

```tsx
import HomeView from './(_components)/home-view.tsx';
import { appRoutes } from '@app/router.ts';
import { definePage } from '@app/utils.ts';

export const homePage = definePage()
  .withRoute(appRoutes.home)
  .withMeta(() => ({ title: 'my-app — dashboard', description: 'My app overview.' }))
  .withLayer('home', HomeView, () => ({
    projectName: 'my-app',
    appName: 'dashboard',
    routes: [
      { title: 'Dashboard', href: appRoutes.dashboard.href(), description: 'Operational overview.', cta: 'Open', badge: 'app' },
    ],
  }))
  .withLayout((slots) => slots.home())
  .build();

export const { default: page } = homePage;
export { page as default };
```

```tsx
// routes/status.tsx — a new route at /status
import { definePage } from '@app/utils.ts';
import { appRoutes } from '@app/router.ts';

export const statusPage = definePage()
  .withRoute(appRoutes.home) // swap for a typed route once you add it to router.ts
  .withMeta(() => ({ title: 'Status' }))
  .withLayer('status', () => <main class='ns-shell ns-section'>All systems go.</main>, () => ({}))
  .withLayout((slots) => slots.status())
  .build();

export const { default: page } = statusPage;
export { page as default };
```

The HTML shell (`<html>`, `<head>`, fonts, the theme-seed script) is `routes/_app.tsx`; the top bar / navigation chrome wrapping content pages is `routes/_layout.tsx`. Both use the `define.page(...)` / `define.layout(...)` helpers from `createDefine<State>()`. Edit those to change the global frame rather than repeating markup per page.

> Co-location folders don't become URLs
>
> Folders wrapped in parentheses —
>
> (_components)
>
> ,
>
> (_shared)
>
> ,
>
> (_islands)
>
> ,
>
> (design)
>
> — are Fresh
>
> route groups
>
> : they organize files next to the route that uses them without adding a path segment. Keep a page's view, loader, and demo islands beside the route file and the URL stays clean.

> Add typed route references in router.ts
>
> When you add a permanent page, register it in
>
> apps/dashboard/router.ts
>
> so
>
> appRoutes
>
> exposes a typed
>
> .href()
>
> for it. Linking through
>
> appRoutes
>
> instead of hand-written strings means a renamed or removed route fails the type-check rather than 404-ing at runtime.

## Add interactivity with an island

Generate a standalone signals island with `netscript ui:add island Counter`. Add `--query` for a `QueryIsland` provider wired to `@netscript/fresh/query`, then import the generated island from the route where it should hydrate.

Server-rendered routes ship zero client JavaScript. When you need state in the browser — a toggle, a form, a live panel — add an **island** under `islands/`. Islands are the only components Fresh hydrates on the client. The scaffold ships `ThemeToggle`, `SidebarToggle`, and `Toast` under `islands/ui/` as working examples; model new ones on them using Preact signals:

```tsx
import { useSignal } from '@preact/signals';
import type { VNode } from 'preact';

const Counter = (): VNode => {
  const count = useSignal(0);
  const increment = () => { count.value += 1; };
  return (
    <button type='button' onClick={increment} class='ns-button'>
      Clicked {count.value} times
    </button>
  );
};

export default Counter;
```

```tsx
// routes/(_components)/home-view.tsx
import Counter from '@app/islands/Counter.tsx';

const HomeView = () => {
  return (
    <main class='ns-shell ns-section'>
      {/* Rendered on the server, hydrated on the client */}
      <Counter />
    </main>
  );
};

export default HomeView;
```

A few rules keep islands cheap and correct: keep them small and leaf-shaped; pass plain serializable props in (the island boundary is the hydration boundary); and declare interactive event handlers with arrow functions, as in the scaffolded `ThemeToggle`. Anything that does not need browser state should stay a plain component in `components/` so it ships no JS.

> Fetch typed data with @netscript/fresh/query
>
> When an island or route needs server data, prefer the runtime's typed query layer (
>
> @netscript/fresh/query
>
> ) over hand-rolled
>
> fetch
>
> calls — it carries the oRPC contract types through to the client so a renamed service field surfaces as a type error. See
>
> `@netscript/fresh`
>
> for the query builders, and
>
> Add a service
>
> for the backend half of that contract.

## Restyle: tokens, Tailwind, and component CSS

NetScript styling has three layers, lightest-touch first:

1 · Design tokens (theme-wide)

Edit the CSS custom properties in assets/tokens.css (mirrored in tokens.json). Tokens are named --ns-* (e.g. surface, border, foreground, accent) and drive every component plus the light/dark themes selected by the data-theme attribute. Change a token once and the whole app re-themes.

2 · Tailwind utilities (per element)

Tailwind v4 is wired through Vite (@tailwindcss/vite). Use utility classes in JSX for one-off layout and spacing. The scaffold also defines NetScript layout helpers (ns-shell, ns-section, ns-stack, ns-cluster) in assets/layouts.css for consistent page rhythm.

3 · Component CSS (one primitive)

Each copied primitive has its own stylesheet under assets/ui/ (button.css, card.css, badge.css, …). To restyle just one component everywhere, edit its file there — it is app-owned source, imported by assets/styles.css.

Pick the lightest layer that does the job: reach for a **token** when the change should re-theme the whole app, a **Tailwind utility** for one-off element layout, and **component CSS** when one primitive should look different everywhere it appears.

Theme switching is already wired: `routes/_app.tsx` seeds `data-theme` from the `ns-theme` localStorage key (falling back to the OS preference), and the `ThemeToggle` island flips it at runtime. To ship a different default, change the `data-theme` attribute on `<html>` in `_app.tsx` and adjust the token values for that theme in `assets/tokens.css`.

> Edit tokens, not magic numbers
>
> Reach for a raw hex color or pixel value only when no token fits. Hard-coded values drift away from the theme and break the light/dark switch — the whole point of the
>
> --ns-*
>
> tokens is that one edit re-themes every surface consistently.

## Install more UI from the registry

When you need a primitive the scaffold didn't copy in, pull it from the `@netscript/fresh-ui` registry with the CLI. Two commands do the work, and both **copy source files into your app** rather than adding a runtime dependency:

**Fresh UI CLI commands**

| Name | Type | Description |
| --- | --- | --- |
| `netscript ui:init` | `install the foundation` | Installs the NetScript Fresh UI foundation set into an app workspace. Run once when setting up UI in an app that doesn't have it yet (the scaffold runs the equivalent for you). |
| `netscript ui:add ` | `add one item or collection` | Copies a single registry item or a named collection into the app workspace — component files go to apps/dashboard/components/ui/, island files to islands/ui/, lib helpers to lib/, and assets to assets/ui/ — then wires the CSS and merges any required deno.json imports. |

```bash
# Add one component (or a named collection) to the dashboard app
netscript ui:add dropzone

# Add an AI / workspace primitive — e.g. the chat message renderer
netscript ui:add message

# Add a whole named collection in one call (theme + all its items)
netscript ui:add ai
```

### Available components

Every item below is something you can `ui:add <name>` by its registry id. They fall into four groups. **Interactive namespaces** ship from the `@netscript/fresh-ui/interactive` sub-path (stateful, accessible compound components); the rest are copy-source registry items.

**Interactive namespaces (@netscript/fresh-ui/interactive)**

| Name | Type | Description |
| --- | --- | --- |
| `Accordion` | `disclosure` | Compound accordion with root + item subcomponents. |
| `Dialog` | `overlay` | Modal dialog with structural subcomponents. |
| `Drawer` | `overlay` | Edge-docked drawer with structural subcomponents. |
| `Popover` | `floating` | Anchored popover with positioning subcomponents. |
| `Sheet` | `overlay` | Side-docked inspection panel. |
| `Tabs` | `navigation` | Tabs with list, trigger, and content subcomponents. |
| `Tooltip` | `floating` | Anchored tooltip with positioning subcomponents. |
| `Combobox` | `headless L1` | Headless combobox seam (useCombobox + getRootProps/getInputProps/getContentProps/getItemProps) — the keyboard/selection engine behind the command palette and autocomplete inputs. |

**L0 primitives (@netscript/fresh-ui/primitives)**

| Name | Type | Description |
| --- | --- | --- |
| `Show` | `control flow` | Conditionally renders children without an extra DOM wrapper. |
| `VisuallyHidden` | `a11y` | Renders content for assistive tech while keeping it visually hidden. |
| `SrOnly` | `a11y` | Screen-reader-named alias for VisuallyHidden. |

**AI / workspace primitives (ui:add )**

| Name | Type | Description |
| --- | --- | --- |
| `avatar` | `identity` | Identity chip for a person or agent — initials or image with size, presence, and agent variants. |
| `citation-chip` | `ai` | Inline per-claim source marker [n] that pairs with a sources list — the grounded-agent citation UX. |
| `code-block` | `ai` | Fenced code surface with filename/language header and a copy affordance for assistant messages. |
| `model-selector` | `ai` | Disclosure-backed model/provider picker for the prompt composer (native details). |
| `tool-call-card` | `ai` | Inline MCP/tool invocation + result as a native details disclosure with a status badge and IO panel. |
| `chart-block` | `analytics` | Inline token-driven metric chart — horizontal bars or a vertical column chart with y-axis ticks and data-tone intents. |
| `donut` | `analytics` | Token-driven donut/pie chart — SVG arc segments with a center total and legend. |
| `prompt-input` | `ai composer` | Chat composer: a CSS auto-grow textarea (native field-sizing: content, no JS handler) with a toolbar of research/grounding pills, model picker, attach/screenshot/voice, and send. |
| `message` | `ai chat` | Chat message with author/time, inline-markup body (bold/code/[n] citations), tool-call + chart/code blocks, follow-up chips, and a typing indicator. Exports renderInline + TypingIndicator. |
| `dropzone` | `upload` | File-ingest affordance — a dashed drop target with built-in drag-drop, clipboard-paste, and file-picker ingest; filters by accept / multiple and reports results through onFile / onFiles / onReject. |

**Command & search utilities (ui:add )**

| Name | Type | Description |
| --- | --- | --- |
| `command-palette` | `palette` | Modal ⌘K command palette (.ns-cmdk) — the L1 Dialog backdrop/overlay wrapping the L1 Combobox: grouped, searchable commands with icon/hash/kind sub-parts. |
| `search` | `navigation` | Compact nav search affordance (.ns-search) — a button styled as an input with a ⌘K hint that opens the command palette. |

> Collections copy a whole set at once
>
> Named
>
> collections
>
> are also valid
>
> ui:add
>
> targets. For example
>
> netscript ui:add ai
>
> installs the AI surface set (citation-chip, model-selector, tool-call-card, prompt-input, message, command-palette, search) with their theme seed in one command;
>
> foundation
>
> installs the full dashboard set. See the
>
> reference
>
> for the complete item and collection catalog.

Both commands accept the same useful flags (run `--help` for the version-accurate list):

- `--project-root <path>` — target a workspace other than the current directory.
- `--theme <name>` — install against a specific theme registry item instead of the default official theme.
- `--registry-root <path>` — override the Fresh UI package root (advanced/local development).
- `--force` — overwrite existing copied UI files when re-running.

After the copy, the new component is regular source under `components/ui/` (and its styles under `assets/ui/`). Import it through the `@app/components/ui/mod.ts` barrel like the rest, then edit it however you like — there is no upstream patch to keep in sync.

> Copy-source, not a dependency
>
> This is the deliberate ownership tradeoff:
>
> ui:add
>
> gives you the code, so you carry it. When the registry ships an upstream fix you want, re-run
>
> ui:add … --force
>
> to re-copy — but expect to re-apply any local edits, exactly as you would with any vendored source.

## Verify your changes

With the app running, confirm the loop end to end:

1. Watch the Vite dev server (or `aspire start` logs) recompile on save — Fresh hot module replacement updates the page without a full reload.
2. Open `/design/components` to see restyled primitives render against the active theme, and `/design/tokens` to confirm token edits took effect.
3. Toggle the theme (the `ThemeToggle` in the top bar) to check both light and dark look right after token changes.
4. Type-check the app before committing:

```bash
deno task --cwd apps/dashboard check
```

That task runs `deno fmt --check`, `deno lint`, and `deno check` over the app, so a clean run means your routes, islands, and edited components still type and lint.

> Type-check is your guardrail
>
> Because routes, islands, and UI primitives are all app-owned TypeScript, the
>
> check
>
> task is the single gate that proves a route rename, a changed island prop, or an edited primitive still composes. Run it before every commit — green here means the Fresh build will not break on a missing import or a drifted type.

## Next steps

- Capability hub: [Fresh UI](https://rickylabs.github.io/netscript/capabilities/fresh-ui/) — the concept, the headline API, and the Learn / Do / Reference triplet for the dashboard app.
- Reference: the generated API for the UI registry and the Fresh runtime — [`@netscript/fresh-ui`](https://rickylabs.github.io/netscript/reference/fresh-ui/) and [`@netscript/fresh`](https://rickylabs.github.io/netscript/reference/fresh/). These are the authority for every export (the `/server`, `/query`, and sibling subpaths included); this guide never duplicates them.
- Related recipes: [Add a service](https://rickylabs.github.io/netscript/services-sdk/how-to/add-a-service/) to give your UI a typed oRPC backend, and [Add OpenTelemetry](https://rickylabs.github.io/netscript/observability/how-to/add-opentelemetry/) to trace it.
- Concepts: the [contracts](https://rickylabs.github.io/netscript/explanation/contracts/) explanation shows how a typed contract flows from service to client to island.

[Add OpenTelemetry](https://rickylabs.github.io/netscript/netscript/observability/how-to/add-opentelemetry/) [Build a durable chat](https://rickylabs.github.io/netscript/netscript/ai/how-to/build-a-durable-chat/)

_Canonical: https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/_

---

# Interactive islands

The interactive entrypoint of `@netscript/fresh` is intentionally small. It exposes the browser-facing seams that the framework owns directly, while route builders, server helpers, and copy-based UI registry components stay on explicit subpaths. Reach for this surface when an island needs to read an in-flight promise during render using the Suspense throw-promise protocol, rather than threading loading state through props.

## The interactive entrypoint

`@netscript/fresh` keeps its interactive runtime narrow on purpose. The package documents this boundary directly: the entrypoint is limited to package-owned interactive seams, so anything that is route-shaped, server-shaped, or registry-shaped lives elsewhere and is consumed through its own path.

Today that surface is two functions built around promises:

- `usePromise<T>` reads a promise during render using the Suspense throw-promise protocol. When the promise is still pending, the call throws the promise so a surrounding Suspense boundary can show its fallback; when the promise is fulfilled, the call returns the resolved value of type `T`.
- `resolvedPromise<T>` creates a promise that is already primed as fulfilled with a given value. It pairs with `usePromise()` so a component can be driven with a value that is available synchronously without special-casing the read path.

Because `usePromise` participates in Suspense, the island that calls it should be rendered inside a Suspense boundary that supplies a fallback. The deferred and streaming UI surface covers how those boundaries are wired across the server render; see [Deferred and streaming UI](https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/).

## Reading a promise inside an island

The example below composes only the two documented symbols. `usePromise` reads the promise to get its resolved value, and `resolvedPromise` provides an already-fulfilled promise for the case where the value is available up front.

```tsx
import { resolvedPromise, usePromise } from "@netscript/fresh/interactive";

interface Metric {
  label: string;
  value: number;
}

function MetricReadout({ data }: { data: Promise<Metric> }) {
  // Suspends while `data` is pending; returns the resolved Metric once fulfilled.
  const metric = usePromise(data);
  return (
    <p>
      {metric.label}: {metric.value}
    </p>
  );
}

// An already-fulfilled promise, suitable for synchronous values.
const seeded = resolvedPromise<Metric>({ label: "Sessions", value: 42 });

export default function MetricIsland() {
  return <MetricReadout data={seeded} />;
}
```

> `usePromise` relies on the Suspense throw-promise protocol, so the calling component must render within a Suspense boundary that provides a fallback. Wire that boundary on the server render — see [Deferred and streaming UI](https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/).

## What makes a NetScript island distinct: the typed query island

A vanilla Fresh island is just hydrated Preact — you bring your own data fetching. A NetScript island earns its keep by hydrating **contract-typed** data: a typed route reference names the endpoint, and a `QueryIsland` renders the result of a contract-derived query. Nothing about the URL or the response shape is hand-typed, so the island cannot drift from the service.

The route reference comes from [`@netscript/fresh/route`](https://rickylabs.github.io/netscript/web-layer/route/); the query utils come from the single `lib/api-clients.ts` module described in [Data loading and the query cache](https://rickylabs.github.io/netscript/web-layer/query/):

```tsx
// apps/dashboard/islands/WidgetPanel.tsx
import { QueryIsland, useIslandQuery } from "@netscript/fresh/query";
import { createRouteReference } from "@netscript/fresh/route";
import { widgets } from "../lib/api-clients.ts";

// A typed reference to the page this island lives on — hrefs are checked
// against the pattern, so a broken link is a compile error.
const widgetsRoute = createRouteReference("/widgets");

function WidgetList() {
  // queryKey + queryFn are derived from the widgets contract.
  const query = useIslandQuery({
    ...widgets.list.queryOptions({ input: {} }),
    staleTime: 15_000,
  });

  if (query.isLoading) return <p>Loading…</p>;

  return (
    <div>
      <a href={widgetsRoute.href()}>All widgets</a>
      <ul>
        {query.data?.map((widget) => <li key={widget.id}>{widget.name}</li>)}
      </ul>
    </div>
  );
}

export default function WidgetPanel() {
  return (
    <QueryIsland>
      <WidgetList />
    </QueryIsland>
  );
}
```

The `usePromise`/`resolvedPromise` seam above and this typed query island are the two ways interactivity enters a page: read an in-flight promise during render, or hydrate a contract-typed query. Most data-driven islands use the second.

## API summary

| Symbol | Description |
| --- | --- |
| `usePromise<T>(promise: Promise<T>): T` | Read a promise using the Suspense throw-promise protocol. |
| `resolvedPromise<T>(value: T): Promise<T>` | Create a promise already primed as fulfilled for `usePromise()`. |

## Companion UI helpers

The copy-based registry components of `@netscript/fresh-ui` live on workspace-local deep paths so applications can own and evolve them after copy. Its root entrypoint exposes only the supported helper utilities that are safe to consume as package runtime dependencies, including:

- `cn(...inputs: ClassValue[]): string` — combines clsx and tailwind-merge for class merging.
- `getToast(url: URL): RegistryToast | undefined` — reads a toast payload from a URL when redirect-flash query parameters are present.
- `withToast(path: string, toast: RegistryToast): string` — appends a toast payload to a relative application path.
- `stripToastFromUrl(url: URL): string` — removes all toast query parameters while preserving path and hash.

For the full Web Layer UI surface and the workspace-owned registry components, see the pillar hub at [/web-layer/](https://rickylabs.github.io/netscript/web-layer/).

## Related

[Deferred and streaming UI  Wire the Suspense boundaries that usePromise relies on.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Data loading and the query cache  Load and cache data that islands consume.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [The Fresh page model  Server rendering and the page contract.](https://rickylabs.github.io/netscript/netscript/web-layer/server/)

- [Live dashboard tutorial](https://rickylabs.github.io/netscript/tutorials/live-dashboard/) — the flagship walkthrough that brings interactive islands together end to end.

_Canonical: https://rickylabs.github.io/netscript/web-layer/interactive/_

---

# Data loading and the query cache

The `@netscript/fresh/query` subpath gives islands a package-owned data layer built on TanStack Query, while the package root exposes a small set of cache-entry helpers that page loaders and islands share. Reach for this surface when an island needs cached, refetchable, or live data, and when a server loader wants to prime that cache before the island hydrates.

## The two surfaces

Data loading in NetScript Fresh spans two import points:

- **`@netscript/fresh/query`** — TanStack Query hooks for islands. Island code imports from this subpath rather than from `@tanstack/preact-query` directly, which centralizes the dependency and enables framework-level enhancements. It provides the island provider (`QueryIsland`), the shared `QueryClient` singleton (`getIslandQueryClient`), the query and mutation hooks (`useIslandQuery`, `useIslandMutation`, and friends), live-query hooks (`useLiveQuery`, `useLiveSuspenseQuery`), and hydration utilities for streaming SSR.
- **`@netscript/fresh`** (root) — the cross-cutting page-loader cache helpers. These operate on plain `CacheEntryLike` values: a `data` payload plus a `cachedAt` Unix-epoch timestamp in milliseconds. They let a loader reason about whether its cache is complete and how fresh it is before deciding to serve cached data or refetch.

Every other capability lives on its own explicit subpath (`./builders`, `./route`, `./form`, `./defer`, `./server`, `./streams`, `./interactive`, `./vite`, `./error`, and `./testing`).

## Cache entries at the loader

A `CacheEntryLike<T>` is the shared cache shape across page loaders and partial orchestration:

```ts
interface CacheEntryLike<T> {
  readonly data: T;
  readonly cachedAt: number; // Unix epoch ms
}
```

The root helpers operate over arrays of these entries:

- `hasAllCacheEntries(entries)` returns `true` when every supplied entry is present. `null` and `undefined` entries count as missing, so a loader can pass the raw results of several cache reads and learn in one call whether the page can be served entirely from cache.
- `minCachedAt(entries)` returns the oldest `cachedAt` timestamp across the supplied entries, or `undefined` when there are none. Use it to compute the effective freshness of a composed page — the page is only as fresh as its stalest entry.
- `projectCachedItemFromList(listEntry, predicate)` projects a single cached item out of a `CachedListEntryLike<TItem>` (an entry whose `data` holds an `items` array) while preserving the list's `cachedAt` timestamp. This lets a detail view reuse a list response already in cache instead of issuing a new fetch.

### A cache-first load pattern

A loader can read its cache entries, check completeness, and derive freshness before deciding whether to refetch:

```ts
import {
  hasAllCacheEntries,
  minCachedAt,
  projectCachedItemFromList,
  type CacheEntryLike,
  type CachedListEntryLike,
} from "@netscript/fresh";

interface Widget {
  id: string;
  name: string;
}

// Cache entries gathered earlier in the request.
const widgetList: CachedListEntryLike<Widget> | undefined = readWidgetList();
const summary: CacheEntryLike<number> | undefined = readSummary();

const entries = [widgetList, summary];

if (hasAllCacheEntries(entries)) {
  const oldest = minCachedAt(entries); // freshness floor, in epoch ms
  const selected = projectCachedItemFromList(
    widgetList,
    (item) => item.id === "w-1",
  );

  // Serve cached data along with its freshness floor.
  return { widget: selected?.data, cachedAt: oldest };
}

// Otherwise, fall through to a fresh load.
```

## Querying inside an island

Islands wrap their content in `QueryIsland`, the island-level TanStack Query provider, then call the package-owned hooks. `useIslandQuery` runs a query through the shared client; its options come from `IslandQueryOptions`:

| Option | Meaning |
| --- | --- |
| `queryKey` | Stable cache key (`QueryKey`, a `readonly unknown[]`). |
| `queryFn` | Function that loads query data. |
| `initialData` | Initial data supplied from a Fresh server loader. |
| `enabled` | Whether the query should run automatically. |
| `staleTime` | Cache freshness duration in milliseconds. |
| `gcTime` | Cache garbage-collection duration in milliseconds. |
| `select` | Optional projection applied by the query adapter. |
| `onError` | Optional error callback. |
| `refetchInterval` | Polling cadence in milliseconds (`number \| false`). When set, the query refetches on this cadence; `false` disables polling. Defaults to `false`. |
| `refetchIntervalInBackground` | Whether polling continues while the tab or window is backgrounded (`boolean`). Only relevant when `refetchInterval` is set. Defaults to `false`. |

The hook returns an `IslandQueryResult` with `data`, `error`, `status`, `isLoading`, `isSuccess`, `isError`, and a `refetch()` method.

### From contract to island: the typed query chain

`queryFn` can be any function that returns data — but on a NetScript service it should almost never be a hand-written `fetch`. A raw `fetch("/api/widgets")` re-types the response by hand, hardcodes the path, and drifts silently the moment the service changes. The [`@netscript/sdk`](https://rickylabs.github.io/netscript/services-sdk/sdk/) bridge removes that gap: derive the `queryFn` (and its `queryKey`) straight from the same oRPC contract the service implements, so the island cannot drift from the API.

The chain has three links, and it lives in **one module** per app — the single source of typed clients every loader and island imports:

```ts
// apps/dashboard/lib/api-clients.ts
import { createServiceClient } from "@netscript/sdk/client";
import { createServiceQueryUtils } from "@netscript/sdk/query-client";
import { docsContract, todosContract, widgetsContract } from "@contracts";

// 1. A typed client per service. `serviceName` resolves a URL via Aspire
//    discovery; the contract drives every method signature.
export const widgetsClient = createServiceClient<typeof widgetsContract>({
  contract: widgetsContract,
  serviceName: "widgets",
});
export const docsClient = createServiceClient<typeof docsContract>({
  contract: docsContract,
  serviceName: "docs",
});
export const todosClient = createServiceClient<typeof todosContract>({
  contract: todosContract,
  serviceName: "todos",
});

// 2. Frontend query utils per client. Each exposes `.queryOptions()`,
//    `.mutationOptions()`, `.infiniteOptions()`, and `.key()` for every
//    procedure on the contract — all inferred, no manual annotations.
export const widgets = createServiceQueryUtils(widgetsClient, { path: ["widgets"] });
export const docs = createServiceQueryUtils(docsClient, { path: ["docs"] });
export const todos = createServiceQueryUtils(todosClient, { path: ["todos"] });
```

Islands then import from that module and spread the generated options into the island hooks. `queryOptions({ input })` supplies both the `queryKey` and a `queryFn` bound to the contract, so the hook call only adds island concerns like `staleTime`:

```tsx
// apps/dashboard/islands/WidgetIsland.tsx
import { QueryIsland, useIslandQuery } from "@netscript/fresh/query";
import { widgets } from "../lib/api-clients.ts";

function WidgetView() {
  // queryKey + queryFn come from the contract; the input is typed, too.
  const query = useIslandQuery({
    ...widgets.list.queryOptions({ input: {} }),
    staleTime: 30_000,
  });

  if (query.isLoading) return <p>Loading…</p>;
  if (query.isError) return <p>Could not load widgets.</p>;

  return (
    <ul>
      {query.data?.map((widget) => <li key={widget.id}>{widget.name}</li>)}
    </ul>
  );
}

export default function WidgetIsland() {
  return (
    <QueryIsland>
      <WidgetView />
    </QueryIsland>
  );
}
```

`widgets.list.queryOptions(...)` returns a typed `{ queryKey, queryFn }`; the `widget` element is inferred from the contract's output, so a renamed field is a compile error, not a runtime surprise. The `@netscript/sdk/query-client` bridge (`createServiceQueryUtils`) is the pure client-to-island path; when you also want KV-backed server SWR and prefetch, `createQueryFactories` from the SDK adds a cache-first layer over the same contract — see the [Typed SDK & client](https://rickylabs.github.io/netscript/services-sdk/sdk/) pillar for that variant.

`initialData` is the bridge between a server loader and the island: pass the loader's cached payload as `initialData` so the island renders with data immediately and only refetches once `staleTime` elapses.

### Polling an island with `refetchInterval`

When an island needs to poll for a changing status — a document moving from `pending` to `embedding` to `ready`, say — set `refetchInterval` rather than wiring a manual `setInterval`. The hook refetches on that cadence and cleans the timer up on unmount. Add `refetchIntervalInBackground: true` when polling must continue while the tab is backgrounded (the default stops polling on blur).

```tsx
import { useIslandQuery } from "@netscript/fresh/query";
import { docs } from "../lib/api-clients.ts";

function DocStatus({ id }: { id: string }) {
  const query = useIslandQuery({
    // Contract-derived queryKey + queryFn; `id` is the typed procedure input.
    ...docs.getById.queryOptions({ input: { id } }),
    // Poll every 2s; flip to false from state once the status reaches "ready".
    refetchInterval: 2_000,
    refetchIntervalInBackground: true,
  });

  return <span>{query.data?.status ?? "loading…"}</span>;
}
```

`refetchInterval` is typed `number | false`: pass a millisecond cadence to poll, or `false` to disable it (for example, flip it to `false` from state once the status reaches `ready` to stop polling).

### Mutations, infinite queries, and live data

- `useIslandMutation` runs a mutation through the shared client. Its options (`IslandMutationOptions`) take a `mutationFn` plus optional `onMutate`, `onSuccess`, `onError`, and `onSettled` callbacks; the result exposes `mutate`, `mutateAsync`, `status`, `isPending`, `data`, and `error`. `onMutate` runs before the mutation fires and can return context (for example, a snapshot of prior data) that `onSuccess`, `onError`, and `onSettled` receive back — the seam for optimistic updates with rollback. `onSettled` runs after either a success or an error.
- `useIslandInfiniteQuery` loads paged data. Its options extend the query options with `initialPageParam` and `getNextPageParam`; the result adds `hasNextPage`, `isFetchingNextPage`, and `fetchNextPage()`.
- `useIslandSuspenseQuery` and `useIslandSuspenseInfiniteQuery` are the Suspense variants; the suspense query result guarantees `data` is present for rendered consumers.
- `useLiveQuery` and `useLiveSuspenseQuery` accept an `IslandLiveQueryFactory` and an optional dependency array, returning an `IslandLiveQueryResult` with `data`, `status`, `error`, and a `details` record of preserved upstream fields.

Shorter aliases — `useQuery`, `useMutation`, `useInfiniteQuery`, `useSuspenseQuery`, and `useSuspenseInfiniteQuery` — map to their `useIsland*` counterparts for backward compatibility.

#### A worked mutation: optimistic toggle with rollback

This island toggles a todo's `done` flag through `useIslandMutation`, applying the change optimistically and rolling back if the server rejects it. `onMutate` snapshots the cached list and returns it as context, `onError` restores that snapshot, and `onSettled` re-syncs with the server:

```tsx
// apps/dashboard/islands/TodoIsland.tsx
import {
  QueryIsland,
  useIslandMutation,
  useQueryClient,
} from "@netscript/fresh/query";
import { todos } from "../lib/api-clients.ts";

interface Todo {
  id: string;
  title: string;
  done: boolean;
}

function TodoToggle({ todo }: { todo: Todo }) {
  const queryClient = useQueryClient();
  const listKey = todos.list.queryKey({ input: {} });

  const toggle = useIslandMutation({
    // 1. The round-trip: mutationOptions() supplies the contract-bound
    //    mutationFn and mutationKey; `mutate` takes the typed procedure input.
    ...todos.update.mutationOptions(),

    // 2. Optimistic update: snapshot prior state, write the expected next state.
    onMutate: async (variables: { id: string; done: boolean }) => {
      await queryClient.cancelQueries({ queryKey: listKey });
      const previous = queryClient.getQueryData<Todo[]>(listKey);
      queryClient.setQueryData<Todo[]>(
        listKey,
        (list) =>
          (list ?? []).map((item) =>
            item.id === variables.id ? { ...item, done: variables.done } : item
          ),
      );
      return { previous };
    },

    // 3. Roll back to the snapshot when the server rejects the change.
    onError: (_error, _variables, context) => {
      const snapshot = context as { previous?: Todo[] } | undefined;
      if (snapshot?.previous) queryClient.setQueryData(listKey, snapshot.previous);
    },

    // 4. Re-sync with the server once the mutation settles, either way.
    onSettled: () => queryClient.invalidateQueries({ queryKey: listKey }),
  });

  return (
    <button
      type="button"
      disabled={toggle.isPending}
      onClick={() => toggle.mutate({ id: todo.id, done: !todo.done })}
    >
      {todo.done ? "Mark undone" : "Mark done"}
    </button>
  );
}

export default function TodoIsland({ todo }: { todo: Todo }) {
  return (
    <QueryIsland>
      <TodoToggle todo={todo} />
    </QueryIsland>
  );
}
```

Spreading `todos.update.mutationOptions()` supplies the contract-bound `mutationFn` and `mutationKey`; the optimistic seam — `onMutate`, `onError`, `onSettled` — is added on the island hook, exactly where the query cache lives. `mutate` takes the typed procedure input (`{ id, done }` here), and the `todos.list.queryKey({ input })` helper builds the same key the list query uses, so the snapshot, rollback, and invalidation all target the right cache entry. Call `mutate` for fire-and-forget UI updates, or `mutateAsync` when you need to await the result.

### Endpoints without a NetScript contract

Sometimes an island calls something that has no oRPC contract — a third-party REST API, a legacy endpoint, or a webhook receiver. That is the one case where a hand-written `queryFn` is correct: there is no contract to derive from, so you own the request and its type. Keep it explicit and isolated so it does not read as the default pattern:

```tsx
import { useIslandQuery } from "@netscript/fresh/query";

interface Rate {
  base: string;
  value: number;
}

// No NetScript contract exists for this external endpoint, so the fetch and its
// response type are written by hand — the deliberate exception, not the norm.
function ExchangeRate() {
  const query = useIslandQuery<Rate>({
    queryKey: ["exchange-rate", "USD"],
    queryFn: () =>
      fetch("https://api.example.com/rates/USD").then(
        (res) => res.json() as Promise<Rate>,
      ),
    staleTime: 60_000,
  });

  return <span>{query.data ? `1 ${query.data.base} = ${query.data.value}` : "…"}</span>;
}
```

For any endpoint that *does* have a NetScript contract, reach for the typed chain above instead — the raw `fetch` here exists only because there is nothing typed to bind to.

## Server prefetch and hydration

For streaming SSR, prefetch on the server and hand the cache to the island:

1. Prefetch into a per-request `QueryClient`, then call `dehydrateQueryClient(queryClient)` to produce a serializable `DehydratedState` (its `queries` and `mutations` arrays).
2. Serialize that state into the document with `QueryHydrationScript`, or pass it directly to an island.
3. On the client, restore it with `HydrationBoundary` (which reads either a `state` prop or a script tag by `id`) or call `hydrateFromDehydrated` against the island client.

`getIslandQueryClient()` returns the shared singleton (it throws if called during SSR outside island hydration — use a per-request client for prefetch). `useQueryClient` returns the active handle inside an island, and `resetIslandQueryClient()` clears the singleton, primarily for tests.

> `getIslandQueryClient()` throws when called during server-side rendering outside island hydration. For SSR prefetch, build a per-request `QueryClient`, dehydrate it, and hydrate inside the island.

## API summary

Root cache helpers (`@netscript/fresh`):

| Symbol | Description |
| --- | --- |
| `hasAllCacheEntries` | Return `true` when every supplied entry is present. |
| `minCachedAt` | Return the oldest `cachedAt` timestamp across the supplied entries. |
| `projectCachedItemFromList` | Project a single cached item from a cached list while preserving the timestamp. |
| `CacheEntryLike<T>` | Cached-entry shape: `data` payload plus `cachedAt` epoch-ms timestamp. |
| `CachedListEntryLike<TItem>` | Cached list-entry shape with a `data.items` array, used for projection. |

Query subpath (`@netscript/fresh/query`):

| Symbol | Description |
| --- | --- |
| `QueryIsland` | Island-level TanStack Query provider. |
| `useIslandQuery` | Run an island query through the shared QueryClient. |
| `useIslandMutation` | Run an island mutation through the shared QueryClient. |
| `useIslandInfiniteQuery` | Run an island infinite (paged) query. |
| `useIslandSuspenseQuery` | Suspense variant of the island query. |
| `useLiveQuery` | Run an island live query through the query surface. |
| `useLiveSuspenseQuery` | Suspense variant of the live query. |
| `getIslandQueryClient` | Get (or create) the shared island `QueryClient`. |
| `useQueryClient` | Return the active island QueryClient handle. |
| `resetIslandQueryClient` | Reset the island QueryClient singleton (testing). |
| `useIsFetching` / `useIsMutating` | Count active island queries / mutations. |
| `dehydrateQueryClient` | Dehydrate a QueryClient into serializable state. |
| `hydrateFromDehydrated` | Hydrate a client from server-dehydrated state. |
| `QueryHydrationScript` | Render a JSON script tag of dehydrated state. |
| `HydrationBoundary` | Hydrate the island client from state or a script tag. |
| `IslandQueryOptions` | Options for `useIslandQuery`. |
| `IslandQueryResult` | Result of an island query hook call. |
| `DehydratedState` | State produced by server-side query dehydration. |
| `QueryKey` | Stable query-key shape (`readonly unknown[]`). |
| `LoaderData` | Resolve the awaited return value of a Fresh route loader. |

## Related

[The Fresh page model  How server pages compose and load.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Routing and route contracts  Route definitions and loaders.](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Typed SDK & client  The contract → client → query-utils bridge queryFn is built on.](https://rickylabs.github.io/netscript/netscript/services-sdk/sdk/) [Interactive islands  Where query hooks run on the client.](https://rickylabs.github.io/netscript/netscript/web-layer/interactive/) [Deferred and streaming UI  Stream data into hydrating islands.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Server-validated forms  Pair mutations with form handling.](https://rickylabs.github.io/netscript/netscript/web-layer/form/) [Live dashboard tutorial  Build a cache-first, live-updating page.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/)

See also the [Web Layer hub](https://rickylabs.github.io/netscript/web-layer/).

_Canonical: https://rickylabs.github.io/netscript/web-layer/query/_

---

# Routing and route contracts

The route surface of `@netscript/fresh` turns a Fresh route pattern such as `"/orders/[id]"` into a typed contract. A route contract owns the schemas for its path and search params, parses raw request input into validated state, and builds hrefs and link props that match the same pattern. Reach for it whenever a page reads dynamic segments or query strings and you want one source of truth that both the page handler and its links share.

Import the surface from `@netscript/fresh/route`.

## Route contracts

A route contract is defined independently of any concrete URL. You describe the shape of the path and search params once, then bind that contract to one or more Fresh route patterns. Both schemas are optional: a contract with neither still produces a usable typed reference for a static route.

Create a contract with `defineRouteContract()`. It accepts a `DefineRouteContractOptions` object with an optional `pathSchema` (a `PathParamSchema`) and an optional `searchSchema` (a `SearchParamSchema`), and returns a `DefineRouteContract`. The returned contract exposes:

- `bind(routePattern)` — bind the contract to a concrete pattern, returning a `BoundRouteContract` with parsing and href helpers.
- `createNav(routePattern)` — produce a `RouteNavigation` helper for a pattern.
- `parsePath(input)` / `safeParsePath(input)` — parse raw Fresh path params (`PathParamInput`) into typed path state, throwing or returning a `SchemaParseResult`.
- `parseSearch(input)` / `safeParseSearch(input)` — parse raw search params (`URLSearchParams` or `SearchParamInput`) into typed search state.

A `BoundRouteContract` is a `RouteReference` combined with the contract's compile-time type carrier, so binding adds href and link generation on top of the parsing helpers.

## Route references

A `RouteReference` is the stable object that pages, links, and generated route manifests pass around. It carries the `routePattern` it was built from, the optional `pathSchema` and `searchSchema`, and a `nav` builder, plus manifest metadata (`$pattern`, `$href`, `$id`, `$kind`). Its methods cover both directions of the contract:

- `href(...args)` — build a `ValidatedRouteHref` (a plain string) from optional path and search input.
- `Link` — a Fresh link component already bound to the reference.
- `getLinkProps(input)` — materialize `FreshLinkAttributes` plus a generated `href` for an anchor.
- `parsePath` / `safeParsePath` / `parseSearch` / `safeParseSearch` — the same parsing helpers exposed by the contract.
- `withPartial(partialRoute)` — pair the page route with a Fresh partial route, returning a `PairedRouteTarget`.

When you already have a concrete pattern and no custom schemas, build a reference directly with `createRouteReference(routePattern)`. The path param types are inferred from the pattern itself through `InferRoutePatternPath`, so `createRouteReference("/orders/[id]")` yields a reference whose `href` expects `{ path: { id: string } }`.

```ts
import { createRouteReference } from "@netscript/fresh/route";

const orderRoute = createRouteReference("/orders/[id]");

// "/orders/42"
const href = orderRoute.href({ path: { id: "42" } });
```

To attach explicit schemas, define a contract and bind it:

```ts
import {
  defineRouteContract,
  enumPathParamSchema,
  paginationSearchSchema,
} from "@netscript/fresh/route";

const ordersContract = defineRouteContract({
  pathSchema: enumPathParamSchema("status", ["open", "closed"]),
  searchSchema: paginationSearchSchema({ defaultLimit: 25 }),
});

const ordersRoute = ordersContract.bind("/orders/[status]");

// Parse the request path and query inside a page handler.
const path = ordersRoute.parsePath({ status: "open" });
const search = ordersRoute.parseSearch(new URLSearchParams("page=2"));

// Build a link back to the same route with updated search state.
const next = ordersRoute.href({
  path: { status: path.status },
  search: { page: search.page + 1 },
});
```

## Path params

`bindRoutePattern(contract, routePattern, metadata?)` is the function form of `contract.bind(...)`; both attach a `DefineRouteContract` to a pattern and return a `BoundRouteContract`. The optional `metadata` argument is a `RouteReferenceOptions` carrying a generated `id` and `kind` (`RouteReferenceKind` is `"page"` or `"partial"`).

For enum-valued segments there are two grounded helpers:

- `enumPathParamSchema(paramName, values)` returns a `PathParamSchema` accepted directly as a contract `pathSchema`.
- `defineEnumPathParam(paramName, values)` returns an `EnumPathParamDefinition` that exposes both the `schema` and a standalone `parse(value)` that returns the typed value or `null` when the segment is invalid.

Raw path input is typed as `PathParamInput` (`Record<string, string | undefined>`), and every parse returns a `SchemaParseResult` — either a `SchemaParseSuccess` with `data` or a `SchemaParseFailure` with `success: false` and an optional `error`.

## Search params and pagination

`paginationSearchSchema(options)` builds a `PaginationSearchSchema` over a `PaginationSearchBaseShape` (`page`, `limit`, `sortBy`, `sortOrder`). Its `PaginationSearchSchemaOptions` accept `defaultLimit`, `defaultSort`, and `defaultOrder`. Parsing a query string produces a `PaginationSearchState` with a one-based `page`, a `limit`, a derived zero-based `offset`, and the active `sortBy` / `sortOrder`.

Extend the schema with additional fields through `extend(shape)`, and wrap a field in a default with `fallback(schema, defaultValue)`, which applies a catch wrapper suitable for use inside `paginationSearchSchema().extend(...)`. Raw search values are typed as `SearchParamValue` (`string | string[] | undefined`).

```ts
import {
  fallback,
  paginationSearchSchema,
} from "@netscript/fresh/route";

const listSearch = paginationSearchSchema({ defaultOrder: "desc" });

const state = listSearch.parse({ page: "3", limit: "50" });
// state.page === 3, state.offset === 100, state.sortOrder === "desc"
```

## Paired page and partial routes

`route.withPartial(partialRoute)` returns a `PairedRouteTarget` that builds page and partial hrefs together. It exposes the underlying `route` and `partialRoute` references, an `href(...)` for the page, a `partialHref(...)` for the partial, and `getLinkProps(input)` that materializes `FreshPartialLinkAttributes` with both `href` and `f-partial` set — the attributes Fresh uses to drive partial navigation.

## API summary

| Symbol | Description |
| --- | --- |
| `defineRouteContract(options)` | Define a typed route contract around optional path and search schemas. |
| `bindRoutePattern(contract, routePattern, metadata?)` | Bind a route contract to a concrete Fresh route pattern. |
| `createRouteReference(routePattern, metadata?)` | Build a route reference directly from a Fresh route pattern. |
| `enumPathParamSchema(paramName, values)` | Create an enum-backed path schema for a single dynamic segment. |
| `defineEnumPathParam(paramName, values)` | Create a reusable enum-backed path param helper with `schema` and `parse`. |
| `paginationSearchSchema(options)` | Create a pagination-aware search schema with typed defaults. |
| `fallback(schema, defaultValue)` | Apply a fallback value to a search-param field. |
| `DefineRouteContract` | Public route contract with `bind`, `createNav`, and parse helpers. |
| `RouteReference` | Stable route reference with `href`, `Link`, `getLinkProps`, and parsing. |
| `BoundRouteContract` | A `RouteReference` produced by binding a contract to a pattern. |
| `RouteNavigation` | Minimal typed navigation API exposing `makeHref`. |
| `PairedRouteTarget` | Combined page/partial helper returned by `withPartial`. |
| `PaginationSearchState` | Parsed pagination output (`page`, `limit`, `offset`, `sortBy`, `sortOrder`). |
| `SchemaParseResult` | Success or failure result returned by route schemas. |
| `InferRoutePatternPath` | Infer typed path params directly from a route pattern. |

> Path and search schemas are independent: a contract can carry one, both, or neither. Define only the schemas a route actually reads, and bind the same contract to every pattern that shares those params.

## Related

[The Fresh page model  How pages bind to the server and the request lifecycle.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Pages and the define-page builder  Compose route contracts into pages.](https://rickylabs.github.io/netscript/netscript/web-layer/builders/) [Data loading and the query cache  Load data for the params a route parses.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Server-validated forms  Validate input alongside route contracts.](https://rickylabs.github.io/netscript/netscript/web-layer/form/) [Deferred and streaming UI  Stream a page once its params resolve.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Live dashboard tutorial  Build a routed, data-driven page end to end.](https://rickylabs.github.io/netscript/netscript/tutorials/live-dashboard/)

See the [Web Layer hub](https://rickylabs.github.io/netscript/web-layer/) for the full pillar.

_Canonical: https://rickylabs.github.io/netscript/web-layer/route/_

---

# The Fresh page model

`@netscript/fresh` is NetScript's web layer: a server-first meta-framework built on [Fresh](https://fresh.deno.dev/) that renders pages on the server, sends HTML, and hydrates only the interactive parts of a page as islands. This page frames the whole Web Layer — how the runtime server is composed, where the islands boundary sits, and how a page connects to typed route contracts and the shared page-loader cache. Reach for it first when you want the mental model before diving into any individual leaf.

## Server-first, islands at the edges

A NetScript Fresh page is rendered on the server by default. The handler runs in Deno, loads data, and returns HTML. Interactivity is opt-in: only components designated as islands ship JavaScript to the browser and hydrate there. Everything else stays static server-rendered markup. The result is a small client payload with a clear boundary between server work (data loading, validation, rendering) and client work (the islands).

The package is organized around explicit subpaths, each a leaf of this pillar. The root entry (`@netscript/fresh`) exposes only the cross-cutting page-loader cache helpers; every other capability lives on its own import:

- `./builders` — the define-page builder
- `./route` — typed route contracts
- `./form` — server-validated forms
- `./defer` — deferred and streaming UI
- `./query` — data loading and the query cache
- `./server` — server-only utilities that depend on packages such as `@netscript/kv`
- `./streams`, `./interactive`, `./vite`, `./error`, `./testing`

This split keeps server-only code — anything importing `@netscript/fresh/server` — out of client bundles, which is what preserves the islands boundary.

## Composing the runtime server

The runtime server is a Fresh `App<State>` instance. `App` passes the incoming `Request` through middlewares and routes, exposes verb helpers (`get`, `post`, `patch`, `put`, `delete`, `head`, `all`), a WebSocket endpoint helper (`ws`), file-system route insertion (`fsRoutes`), and produces a handler for `Deno.serve` via `handler()` or starts a server directly with `listen()`.

`defineFreshApp<State>(options)` is the NetScript-managed entry point for building that app. It keeps the default Fresh bootstrap unchanged while exposing optional adapter seams — app construction (`createApp`), static-file middleware (`staticFiles`), app-level `middleware`, lifecycle hooks (`preConfigure`, `configure`), file-system route registration (`fsRoutes`), and reserved telemetry defaults (`telemetry`). It returns a ready `App<State>`.

```ts
import { defineFreshApp } from "@netscript/fresh/server";

interface State {
  requestId: string;
}

const app = defineFreshApp<State>({
  name: "dashboard",
  middleware: [
    (ctx) => {
      ctx.state.requestId = crypto.randomUUID();
      return ctx.next();
    },
  ],
});

await app.listen({ port: 8000 });
```

The `Middleware<State>` type is the basic building block: a function that receives a `Context<State>` and returns a `Response` (or a promise of one), or calls `ctx.next()` to continue the chain. Register app-level middleware through the `middleware` option above or directly with `app.use(...)`.

> The `telemetry` option and `FreshAppTelemetryOptions` (`serviceName`, `attributes`) are reserved bootstrap seams for future Fresh app telemetry defaults. They are accepted today and wired for forward compatibility.

## Pages connect to typed route contracts

Pages do not pass raw strings around. A route is described once as a typed contract and bound to a concrete Fresh route pattern. `defineRouteContract(options)` builds a contract around optional path and search schemas; binding it to a pattern yields a `RouteReference` with typed parsing and href helpers.

```ts
import {
  defineRouteContract,
  paginationSearchSchema,
} from "@netscript/fresh/route";

const ordersContract = defineRouteContract({
  searchSchema: paginationSearchSchema({ defaultLimit: 20 }),
});

const ordersRoute = ordersContract.bind("/orders");

// Typed href with validated search state:
const href = ordersRoute.href({ search: { page: 2 } });

// Parse incoming query params back into typed state:
const search = ordersRoute.parseSearch(new URLSearchParams("page=2"));
```

`createRouteReference("/orders/[id]")` infers path params straight from the pattern, and `paginationSearchSchema()` returns a pagination-aware search schema that parses `page`, `limit`, `sortBy`, `sortOrder` and computes a derived `offset`. Both `parseSearch` and `safeParseSearch` are available — the `safe*` variants return a `SchemaParseResult` instead of throwing. Route contracts are covered in depth on the routing leaf.

## Pages connect to the shared query cache

The root `@netscript/fresh` entry exposes the page-loader cache helpers that page loaders and partial orchestration share. A cached value carries its payload plus the time it was produced, and the helpers let a page reason about freshness and reuse across boundaries.

```ts
import {
  hasAllCacheEntries,
  minCachedAt,
  projectCachedItemFromList,
  type CacheEntryLike,
} from "@netscript/fresh";

function summarize(entries: Array<CacheEntryLike<unknown> | null>) {
  return {
    ready: hasAllCacheEntries(entries),
    oldest: minCachedAt(entries),
  };
}
```

`CacheEntryLike<T>` is the cached-entry shape (`data` plus a `cachedAt` millisecond timestamp) shared by page loaders and partial orchestration. `projectCachedItemFromList` derives a single cached item from a cached list response while preserving the list timestamp. Data loading and the full query cache surface live on the query leaf.

## Streaming responses

Server-first pages can stream HTML progressively. `createStreamingResponse(vnode, options)` returns a streaming HTTP `Response` whose body is a `ReadableStream` of UTF-8 HTML chunks — the high-level API for route handlers that want progressive delivery. `renderToStream` is the lower-level form that returns both the `stream` and an `allReady` promise. `StreamErrorBoundary` wraps a streaming subtree so a single failing data source does not tear down the whole response. These are introduced here and detailed on the deferred-and-streaming-UI leaf.

## API summary

| Symbol | Subpath | Description |
| --- | --- | --- |
| `defineFreshApp` | `/server` | Create a NetScript-managed Fresh `App` with baseline bootstrap defaults and adapter seams. |
| `DefineFreshAppOptions` | `/server` | Options contract for `defineFreshApp` (app, middleware, static files, lifecycle hooks, fs routes, telemetry). |
| `App` | `/server` | Fresh application instance: middleware, verb routing, `ws`, `fsRoutes`, `handler()`, `listen()`. |
| `Middleware` | `/server` | Request-handling building block receiving a `Context<State>`. |
| `createStreamingResponse` | `/server` | Build a streaming HTML `Response` from a Preact VNode tree. |
| `renderToStream` | `/server` | Render a VNode tree to a `ReadableStream` with Suspense streaming. |
| `StreamErrorBoundary` | `/server` | Boundary that catches rendering errors in a streaming subtree. |
| `defineRouteContract` | `/route` | Define a typed route contract around optional path and search schemas. |
| `createRouteReference` | `/route` | Build a route reference directly from a Fresh route pattern. |
| `paginationSearchSchema` | `/route` | Create a pagination-aware search schema with typed defaults. |
| `RouteReference` | `/route` | Bound route with typed parsing and href helpers. |
| `hasAllCacheEntries` | root | Return `true` when every supplied cache entry is present. |
| `minCachedAt` | root | Return the oldest `cachedAt` timestamp across entries. |
| `projectCachedItemFromList` | root | Project one cached item from a cached list while preserving the list timestamp. |
| `CacheEntryLike` | root | Cached-entry shape (`data`, `cachedAt`) shared across loaders. |

## Related

[Pages and the define-page builder  Author server-rendered pages with the page builder.](https://rickylabs.github.io/netscript/netscript/web-layer/builders/) [Routing and route contracts  Typed path and search contracts in depth.](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Data loading and the query cache  Load data and share the page-loader cache.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Server-validated forms  Validate form submissions on the server.](https://rickylabs.github.io/netscript/netscript/web-layer/form/) [Deferred and streaming UI  Stream HTML and defer expensive sections.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/) [Interactive islands  Opt components into client-side hydration.](https://rickylabs.github.io/netscript/netscript/web-layer/interactive/) [Build and Vite integration  Bundle the Web Layer with Vite.](https://rickylabs.github.io/netscript/netscript/web-layer/vite/) [Error handling and diagnostics  Surface and diagnose page errors.](https://rickylabs.github.io/netscript/netscript/web-layer/error/) [Testing Fresh pages  Test server-rendered pages and handlers.](https://rickylabs.github.io/netscript/netscript/web-layer/testing/)

Build a full app end to end in the flagship tutorial: [Live dashboard](https://rickylabs.github.io/netscript/tutorials/live-dashboard/). Return to the pillar hub: [Web Layer](https://rickylabs.github.io/netscript/web-layer/).

_Canonical: https://rickylabs.github.io/netscript/web-layer/server/_

---

# Testing Fresh pages

The `@netscript/fresh` testing export provides fixtures for exercising routes, loaders, and layouts without standing up an HTTP server. Reach for it when you want to unit-test a page's loader logic, assert on the context a route receives, or drive defer-region helpers with a controlled policy. The helpers build the same shape your route code reads at runtime, so a test can call your loader directly and inspect the result.

## What the testing surface provides

The export centers on two factory functions:

- `createMockRouteContext()` builds a minimal page context fixture for route, loader, and layout tests. It returns a `MockRouteContext` that mirrors the request URL, route params, parsed path and search values, layer data, named resources, and an abort signal — everything a loader or layout reads from its context.
- `createMockDeferPolicy()` builds a defer policy fixture accepted by defer-region helpers, so tests that cover deferred or streaming partials can pin freshness and prewarm behavior.

Both factories take a plain options object, so a test composes only the fields it cares about and leaves the rest at their fixture defaults.

## Testing a route loader

`createMockRouteContext()` accepts `MockRouteContextOptions`. Every field is optional: supply a `url`, `params`, `state`, parsed `path` and `search` values, a `routePattern`, named `resources`, an explicit `req`, or a `signal`. The returned `MockRouteContext` exposes those values as readonly properties, plus a `resource(key)` method that returns a single named resource and a `nav` fixture with `makeHref()`.

```ts
import { assertEquals } from "@std/assert";
import { createMockRouteContext } from "@netscript/fresh/testing";

// The loader under test reads params and a named resource from its context.
const loadDashboard = (ctx: {
  path: { id: string };
  resource: (key: "metrics") => { read: () => number };
}) => ({
  id: ctx.path.id,
  total: ctx.resource("metrics").read(),
});

Deno.test("dashboard loader reads the path id and metrics resource", () => {
  const ctx = createMockRouteContext<
    Record<string, never>,
    { metrics: { read: () => number } },
    { id: string }
  >({
    url: "https://example.com/dashboards/42",
    routePattern: "/dashboards/:id",
    path: { id: "42" },
    resources: { metrics: { read: () => 128 } },
  });

  const result = loadDashboard(ctx);

  assertEquals(result.id, "42");
  assertEquals(result.total, 128);
  assertEquals(ctx.resource("metrics").read(), 128);
});
```

The fixture's `url` is a `URL`, `req` is a `Request`, `params` is a `Record<string, string | undefined>`, and `signal` is an `AbortSignal`. Tests that need to assert on cancellation can pass their own `signal` through the options and observe it on the returned context.

## Testing a bound route contract

A [route contract](https://rickylabs.github.io/netscript/web-layer/route/) owns the parsing of a route's path and search params, so its `parsePath`/`parseSearch` (and the non-throwing `safeParsePath`/`safeParseSearch`) are worth testing directly — no context fixture needed. Bind the contract to a pattern, then assert on what it parses and what it rejects. This is the typed alternative to testing hand-rolled `URLSearchParams` juggling: the schema is the single source of truth, and the test pins it.

```ts
import { assert, assertEquals } from "@std/assert";
import {
  defineRouteContract,
  enumPathParamSchema,
  paginationSearchSchema,
} from "@netscript/fresh/route";

const ordersContract = defineRouteContract({
  pathSchema: enumPathParamSchema("status", ["open", "closed"]),
  searchSchema: paginationSearchSchema({ defaultLimit: 25 }),
});
const ordersRoute = ordersContract.bind("/orders/[status]");

Deno.test("orders route parses pagination and derives offset", () => {
  const search = ordersRoute.parseSearch(new URLSearchParams("page=3&limit=50"));
  assertEquals(search.page, 3);
  assertEquals(search.limit, 50);
  assertEquals(search.offset, 100); // (page - 1) * limit
});

Deno.test("orders route rejects an out-of-enum status", () => {
  const ok = ordersRoute.safeParsePath({ status: "open" });
  assert(ok.success);
  assertEquals(ok.data.status, "open");

  const bad = ordersRoute.safeParsePath({ status: "archived" });
  assertEquals(bad.success, false); // not in the ["open","closed"] enum
});
```

`safeParsePath`/`safeParseSearch` return a `SchemaParseResult` — a `{ success: true, data }` success or a `{ success: false, error? }` failure — so a test can assert both the happy path and the rejection without a `try`/`catch`. The throwing `parsePath`/`parseSearch` variants suit tests that expect valid input.

## Testing layouts

Layout tests read `layerData` from the context, a `Record<string, unknown>` carrying the data a layout receives. Construct a fixture with the layer data your layout expects and pass the context to the layout under test.

```ts
import { createMockRouteContext } from "@netscript/fresh/testing";

const ctx = createMockRouteContext({
  url: "https://example.com/reports",
  routePattern: "/reports",
});

// `ctx.layerData` is the Record<string, unknown> a layout reads.
const layerData = ctx.layerData;
```

## Defer policy fixtures

`createMockDeferPolicy()` accepts either a `MockDeferPolicyProfile` name or a `MockDeferPolicyInput` override object, and returns the resolved policy for use with defer-region helpers. The profile names are `"balanced"`, `"aggressive-first-paint"`, `"background-refresh"`, and `"low-bandwidth"`. The `MockDeferPolicyInput` form lets a test start from a named `profile` and then override individual fields: `staleTimeMs` for the freshness window, `prewarmOnMiss` and `prewarmOnStale` for cache-prewarm behavior, and `clientRefreshOnFreshCache` and `skipClientWhenServerPrewarm` for client refresh behavior.

```ts
import { createMockDeferPolicy } from "@netscript/fresh/testing";

// Start from a named profile.
const balanced = createMockDeferPolicy("balanced");

// Or override individual fields on top of a profile.
const tuned = createMockDeferPolicy({
  profile: "background-refresh",
  staleTimeMs: 5_000,
  prewarmOnStale: true,
  skipClientWhenServerPrewarm: true,
});
```

> The defer policy fixture pairs with the deferred and streaming UI surface. See [Deferred and streaming UI](https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/) for how policies drive partial freshness and prewarming at runtime.

## API summary

| Symbol | Kind | Description |
| --- | --- | --- |
| `createMockRouteContext()` | function | Create a minimal page context fixture for route, loader, and layout tests. |
| `createMockDeferPolicy()` | function | Create a defer policy fixture accepted by defer-region helpers. |
| `MockRouteContext` | interface | Mock route context returned by `createMockRouteContext()`. |
| `MockRouteContextOptions` | interface | Options used to construct a route context fixture. |
| `MockDeferPolicyInput` | interface | Mock defer policy override accepted by defer test fixtures. |
| `MockDeferPolicyProfile` | type | Named policy profile: `"balanced"`, `"aggressive-first-paint"`, `"background-refresh"`, `"low-bandwidth"`. |

### `MockRouteContext` properties

| Property | Type | Description |
| --- | --- | --- |
| `url` | `URL` | Request URL for the fixture. |
| `req` | `Request` | Raw request object for the fixture. |
| `params` | `Record<string, string \| undefined>` | Fresh route params for the fixture. |
| `state` | `TState` | Fresh state object for the fixture. |
| `signal` | `AbortSignal` | Request abort signal. |
| `path` | `TPath` | Parsed route path params. |
| `search` | `TSearch` | Parsed route search values. |
| `layerData` | `Record<string, unknown>` | Layer data available to layout tests. |
| `routePattern` | `string` | Route pattern represented by the fixture. |
| `nav` | `{ makeHref(): string }` | Minimal route navigation fixture. |
| `route` | `unknown` | Optional route reference for tests that need routed context. |
| `resources` | `TResources` | Named resources available to route loaders. |
| `resource(key)` | method | Return a named resource from the fixture. |

### `MockDeferPolicyInput` properties

| Property | Type | Description |
| --- | --- | --- |
| `profile` | `MockDeferPolicyProfile` | Named policy profile to start from. |
| `staleTimeMs` | `number` | Override for the freshness window in milliseconds. |
| `prewarmOnMiss` | `boolean` | Prewarm the partial when the cache is missing. |
| `prewarmOnStale` | `boolean` | Prewarm the partial when the cache is stale. |
| `clientRefreshOnFreshCache` | `boolean` | Allow client refresh even when server cache is fresh. |
| `skipClientWhenServerPrewarm` | `boolean` | Skip client refresh when the server is already prewarming. |

## Related

[Routing and route contracts  The route context your loaders read at runtime.](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Data loading and the query cache  Load data into a route from named resources.](https://rickylabs.github.io/netscript/netscript/web-layer/query/) [Deferred and streaming UI  The defer regions your policy fixtures drive.](https://rickylabs.github.io/netscript/netscript/web-layer/defer-streaming-ui/)

- [The Fresh page model](https://rickylabs.github.io/netscript/web-layer/server/)
- [Pages and the define-page builder](https://rickylabs.github.io/netscript/web-layer/builders/)
- [Server-validated forms](https://rickylabs.github.io/netscript/web-layer/form/)
- [Interactive islands](https://rickylabs.github.io/netscript/web-layer/interactive/)
- [Error handling and diagnostics](https://rickylabs.github.io/netscript/web-layer/error/)
- [Examples and sandbox](https://rickylabs.github.io/netscript/web-layer/examples/)
- [Web Layer overview](https://rickylabs.github.io/netscript/web-layer/)
- [Tutorial: Build a live dashboard](https://rickylabs.github.io/netscript/tutorials/live-dashboard/)

_Canonical: https://rickylabs.github.io/netscript/web-layer/testing/_

---

# Build and Vite integration

@netscript/fresh ships a Vite plugin that wires a Fresh workspace into the build: it resolves NetScript app aliases, maps environment variables into `import.meta.env`, and generates route manifests at build and dev time. Reach for it when you set up the Vite config for a NetScript Fresh app and want aliases, env exposure, and route manifest generation handled in one place.

## The plugin factory

`createNetScriptVitePlugin(options)` is the single entry point. It accepts a `NetScriptVitePluginOptions` object and returns a `NetScriptVitePlugin` — the package-owned view of the Vite plugin hooks NetScript Fresh relies on. Add the returned plugin to the `plugins` array of your Vite config.

The returned plugin runs with `enforce: "pre"`, so its hooks order ahead of most other plugins. It contributes four things:

- **Config defaults** through the `config` hook, which returns Vite config defaults for NetScript Fresh workspaces.
- **Alias resolution** through the `resolveId` hook, which resolves NetScript app aliases to absolute file paths.
- **Route manifests** through the `buildStart` hook, which generates route manifests when the Vite build starts.
- **Dev-server watchers** through the `configureServer` hook, which registers development-server watchers for route manifests.

## Basic setup

A minimal integration points the plugin at the Fresh app root. With no alias entries supplied, the plugin generates aliases from the app root.

```ts
import { createNetScriptVitePlugin } from "@netscript/fresh";

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  workspaceRoot: ".",
});

export default {
  plugins: [netscript],
};
```

## Aliases

Aliases are resolved through `resolveId`. There are two ways to control them.

Supply explicit `aliasEntries` to use a fixed set of aliases instead of generated ones. Each `NetScriptViteAlias` has a `find` (the import specifier prefix or exact specifier to match) and a `replacement` (the filesystem path that replaces the matched specifier).

```ts
import {
  createNetScriptVitePlugin,
  type NetScriptViteAlias,
} from "@netscript/fresh";

const aliasEntries: NetScriptViteAlias[] = [
  { find: "@app/", replacement: "./app/" },
];

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  aliasEntries,
});
```

Alternatively, let the plugin generate aliases by listing app-root-relative `aliasDirectories` and an `aliasPrefix`:

```ts
const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  aliasPrefix: "@app/",
  aliasDirectories: ["islands", "components"],
});
```

## Environment variables

Use `envMappings` to expose environment values through `import.meta.env`. Each `NetScriptViteEnvMapping` reads a `source` key from the provided environment map, defines a `target` key on `import.meta.env`, and may supply a `fallback` value used when the source key is absent. Provide the source values through `env`.

```ts
import {
  createNetScriptVitePlugin,
  type NetScriptViteEnvMapping,
} from "@netscript/fresh";

const envMappings: NetScriptViteEnvMapping[] = [
  {
    source: "PUBLIC_API_URL",
    target: "VITE_API_URL",
    fallback: "http://localhost:3000",
  },
];

const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  envMappings,
  env: Deno.env.toObject(),
});
```

## Route manifests

Route manifest generation runs in the `buildStart` hook for builds and through `configureServer` watchers during development. Configure it with `routeManifest`, a `NetScriptRouteManifestOptions` object.

```ts
const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  routeManifest: {
    enabled: true,
    routesDir: "./app/routes",
    outputPath: "./app/_routes.gen.ts",
    logLevel: "changes",
  },
});
```

`logLevel` accepts `"silent"`, `"changes"`, or `"verbose"`.

## Dev-server filesystem access

The plugin sets up the Vite dev server's filesystem allow-list. `watchPaths` adds paths watched by the dev server, `allowFsPaths` adds filesystem paths the dev server is allowed to serve, and `includeWorkspaceRootInFsAllow` controls whether `workspaceRoot` is included in the filesystem allow-list.

```ts
const netscript = createNetScriptVitePlugin({
  appRoot: "./app",
  workspaceRoot: ".",
  watchPaths: ["./app/routes"],
  allowFsPaths: ["./packages"],
  includeWorkspaceRootInFsAllow: true,
});
```

## API summary

| Symbol | Description |
| --- | --- |
| `createNetScriptVitePlugin(options)` | Create the NetScript Fresh Vite plugin for aliases, env mapping, and route manifests. |
| `NetScriptVitePluginOptions` | Options accepted by the NetScript Fresh Vite plugin. |
| `NetScriptVitePlugin` | Package-owned view of the Vite plugin hooks used by NetScript Fresh. |
| `NetScriptViteAlias` | Resolved Vite alias entry generated or accepted by the plugin (`find`, `replacement`). |
| `NetScriptViteEnvMapping` | Environment variable mapping injected into `import.meta.env` (`source`, `target`, `fallback?`). |
| `NetScriptRouteManifestOptions` | Options controlling the NetScript route manifest generator. |

### `NetScriptVitePluginOptions` fields

| Field | Type | Description |
| --- | --- | --- |
| `appRoot?` | `string` | Fresh app root used for aliases and route manifest output. |
| `workspaceRoot?` | `string` | Workspace root allowed through the Vite dev-server filesystem guard. |
| `aliasEntries?` | `NetScriptViteAlias[]` | Explicit Vite aliases to use instead of generated aliases. |
| `aliasDirectories?` | `string[]` | App-root-relative directories used to generate aliases. |
| `aliasPrefix?` | `string` | Alias prefix used for generated aliases. |
| `watchPaths?` | `string[]` | Additional paths watched by the Vite dev server. |
| `envMappings?` | `NetScriptViteEnvMapping[]` | Environment variable mappings to expose through `import.meta.env`. |
| `env?` | `Record<string, string \| undefined>` | Environment source values used by `envMappings`. |
| `allowFsPaths?` | `string[]` | Additional filesystem paths allowed by the Vite dev server. |
| `includeWorkspaceRootInFsAllow?` | `boolean` | Whether to include `workspaceRoot` in the Vite filesystem allow-list. |
| `routeManifest?` | `NetScriptRouteManifestOptions` | Route manifest generation options. |

### `NetScriptVitePlugin` hooks

| Member | Description |
| --- | --- |
| `name` | Vite plugin name. |
| `enforce` | Vite hook ordering (`"pre"`). |
| `config(config, env)` | Return Vite config defaults for NetScript Fresh workspaces. |
| `resolveId(source)` | Resolve NetScript app aliases to absolute file paths. |
| `buildStart()` | Generate route manifests when the Vite build starts. |
| `configureServer(server)` | Register development-server watchers for route manifests. |

## Related

[The Fresh page model  Server rendering and the page lifecycle.](https://rickylabs.github.io/netscript/netscript/web-layer/server/) [Routing and route contracts  Define routes the manifest generator scans.](https://rickylabs.github.io/netscript/netscript/web-layer/route/) [Interactive islands  Client islands resolved through app aliases.](https://rickylabs.github.io/netscript/netscript/web-layer/interactive/)

- [The Fresh page model](https://rickylabs.github.io/netscript/web-layer/server/)
- [Pages and the define-page builder](https://rickylabs.github.io/netscript/web-layer/builders/)
- [Routing and route contracts](https://rickylabs.github.io/netscript/web-layer/route/)
- [Data loading and the query cache](https://rickylabs.github.io/netscript/web-layer/query/)
- [Server-validated forms](https://rickylabs.github.io/netscript/web-layer/form/)
- [Deferred and streaming UI](https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/)
- [Interactive islands](https://rickylabs.github.io/netscript/web-layer/interactive/)
- [Error handling and diagnostics](https://rickylabs.github.io/netscript/web-layer/error/)
- [Testing Fresh pages](https://rickylabs.github.io/netscript/web-layer/testing/)
- [Examples and sandbox](https://rickylabs.github.io/netscript/web-layer/examples/)
- [Web Layer overview](https://rickylabs.github.io/netscript/web-layer/)
- [Live dashboard tutorial](https://rickylabs.github.io/netscript/tutorials/live-dashboard/)

_Canonical: https://rickylabs.github.io/netscript/web-layer/vite/_

---

# Reference

Reference is **information-oriented**: precise, exhaustive API documentation for every public NetScript package and plugin. These pages are generated from the source code with `deno doc`, so they always describe the published surface (US-2). For a guided introduction start with the [tutorials](https://rickylabs.github.io/netscript/tutorials/), for problem-solving recipes see the [how-to guides](https://rickylabs.github.io/netscript/how-to/), and for the ideas behind the API read the [explanation](https://rickylabs.github.io/netscript/explanation/).

_Canonical: https://rickylabs.github.io/netscript/reference/_

---

# `@netscript/ai`

The provider-agnostic AI engine core for NetScript: a composition root, a global model registry, the domain vocabulary and capability ports for chat/embeddings/vision/tools/agents/MCP, and a set of opt-in provider adapters. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The base `@netscript/ai` entrypoint takes **no** `@netscript/*` runtime dependency and pulls no provider SDK into the module graph. Provider adapters (Anthropic, OpenAI-compatible, OpenRouter, Ollama, OpenAI embeddings/vision) live on **separate subpath exports** and **self-register** into the shared registry as a side effect of being imported — so an application chooses its providers with one-line side-effect imports and only those SDKs enter the graph:

```ts
import "@netscript/ai/anthropic"; // self-registers the 'anthropic' provider
import { getModel } from "@netscript/ai";

const handle = await getModel("anthropic:claude-sonnet-4-5");
```

## Export map

The package publishes the following entrypoints. Each is generated from its own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/ai` | `./mod.ts` | Composition root (`createAiRuntime` / `getAiRuntime`) and the model registry accessors. |
| `@netscript/ai/contracts` | `./src/contracts/mod.ts` | Domain vocabulary: messages, content parts, model identity, agent chunks, usage, errors. |
| `@netscript/ai/ports` | `./src/ports/mod.ts` | Capability port interfaces, their no-op/unconfigured defaults, and the provider registries. |
| `@netscript/ai/anthropic` | `./anthropic.ts` | Anthropic model provider (wraps `@tanstack/ai-anthropic`). |
| `@netscript/ai/openai-compatible` | `./openai-compatible.ts` | OpenAI-compatible model provider (any base URL / key / model list). |
| `@netscript/ai/openrouter` | `./openrouter.ts` | OpenRouter model provider with reasoning-effort passthrough. |
| `@netscript/ai/ollama` | `./ollama.ts` | Local Ollama model provider with a reachability preflight. |
| `@netscript/ai/openai-embeddings` | `./openai-embeddings.ts` | OpenAI-compatible embeddings **and** vision provider. |
| `@netscript/ai/tools` | `./tools.ts` | Standard-Schema tool definitions, in-memory registry, and the `render_ui` wire contract. |
| `@netscript/ai/agent` | `./agent.ts` | The E3 agent loop, typestate, and history strategies. |
| `@netscript/ai/mcp` | `./mcp.ts` | MCP transports (stdio, Streamable-HTTP), auth modes, and tool registration. |
| `@netscript/ai/testing` | `./src/testing/mod.ts` | Deterministic fakes for downstream unit tests. |

## Composition root and model registry (`@netscript/ai`)

The root entrypoint is the composition root plus the model-registry accessors. Model providers are resolved through a module-level registry (not stored on the runtime), so provider packages self-register independently of runtime construction.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createAiRuntime` | function | `createAiRuntime(config?: AiRuntimeConfig): AiRuntime` | Compose a runtime, defaulting every unspecified port. Pure wiring — no IO, no global mutation. |
| `getAiRuntime` | function | `getAiRuntime(config?: AiRuntimeConfig): AiRuntime` | Lazy process singleton (shaped like `@netscript/kv`'s `getKv()`); config is used only on first call. |
| `isAiRuntimeInitialized` | function | `isAiRuntimeInitialized(): boolean` | Whether the singleton has been constructed. |
| `resetAiRuntime` | function | `resetAiRuntime(): void` | Clear the singleton (test isolation). |
| `registerModelProvider` | function | `registerModelProvider(id, factory): void` | Register a provider factory under an id (re-registering overwrites). |
| `getModelProvider` | function | `getModelProvider(id, config?): ModelProviderPort` | Resolve a fresh provider instance, or throw `ModelProviderNotFoundError`. |
| `getModel` | function | `getModel(ref: ModelRef, config?): Promise<ModelHandle>` | Resolve a `"<provider>:<model>"` ref (or `ModelSelector`) end-to-end. |
| `listModelProviders` | function | `listModelProviders(): readonly string[]` | Ids of all currently-registered providers. |
| `resetModelRegistry` | function | `resetModelRegistry(): void` | Clear the provider registry (test isolation). |
| `getEmbeddingProvider` / `getVisionProvider` | function | `(id, config?) => …ProviderPort` | Resolve a registered embedding / vision provider. |
| `registerEmbeddingProvider` / `registerVisionProvider` | function | `(id, factory) => void` | Register an embedding / vision provider factory. |
| `listEmbeddingProviders` / `listVisionProviders` | function | `() => readonly string[]` | Ids of registered embedding / vision providers. |
| `resetEmbeddingRegistry` / `resetVisionRegistry` | function | `() => void` | Clear the embedding / vision registries (test isolation). |
| `AiRuntime` | interface | - | Composed runtime: resolved ports plus `getModelProvider` / `getModel` bound to the default provider. |
| `AiRuntimeConfig` | interface | - | Optional ports injected into `createAiRuntime`; each omitted capability falls back to its default. |
| `ModelProviderPort` | interface | - | A concrete model backend (`listModels` / `getModel` / `supports` / optional `createChatClient`). |
| `ModelProviderConfig` | type alias | `Readonly<Record<string, unknown>>` | Opaque, provider-defined config bag passed to a provider factory. |
| `ModelHandle` / `ModelRef` | type alias | - | Resolved model (descriptor + provider id) and its `"<provider>:<model>"`-or-selector reference. |
| `AiError` | class | - | Base error for the AI stack. |
| `AiNotConfiguredError` | class | - | Thrown when a capability/provider is used without required configuration. |
| `ModelProviderNotFoundError` | class | - | Thrown when a ref names an unregistered provider id. |

### Runtime capability ports and their defaults

`createAiRuntime` injects each capability port, defaulting any omitted field to a no-op or a throwing "unconfigured" port. Model providers are **not** on the runtime — they are resolved from the global registry.

| `AiRuntimeConfig` field | Port | Default when omitted |
| --- | --- | --- |
| `telemetry` | `TelemetryPort` | No-op (`createNoopTelemetryPort`). |
| `tools` | `ToolRegistryPort` | No-op (`createNoopToolRegistry`). |
| `embeddings` | `EmbeddingProviderPort` | Throwing unconfigured port. |
| `vision` | `VisionProviderPort` | Throwing unconfigured port. |
| `mcp` | `McpTransportPort` | Throwing unconfigured port. |
| `skills` | `SkillLoaderPort` | No-op returning no skills. |
| `agentLoop` | `AgentLoopPort` | Throwing unconfigured port. |
| `memory` | `AgentMemoryPort` | No-op store. |
| `defaultModelProvider` | `string` | Unset — `getModelProvider()` then requires an explicit id. |

## Domain contracts (`@netscript/ai/contracts`)

The provider-neutral vocabulary. The tables below list the primary surface; the module is the source of truth via `deno doc packages/ai/src/contracts/mod.ts`.

| Group | Symbols |
| --- | --- |
| Messages | `Message`, `MessageRole`, `MessageContent`, `ContentPart`, `TextContentPart`, `ImageContentPart`, `AudioContentPart`, `VideoContentPart`, `DocumentContentPart`, `ContentModality`, `ContentSource`, `DataContentSource`, `UrlContentSource` |
| Model identity | `ModelId`, `ModelDescriptor`, `ModelCapabilities`, `ModelSelector`, `ModelRef`, `ModelHandle` |
| Agent stream chunks | `AgentChunk`, `AgentChunkType`, `TextChunk`, `ToolCallChunk`, `ToolResultChunk`, `MessageChunk`, `UsageChunk`, `ErrorChunk`, `DoneChunk` |
| Tools | `ToolDescriptor`, `ToolParameters`, `ToolCall`, `ToolResult`, `ToolCallState`, `ToolResultState`, `ToolInputIssue`, `JsonSchema`, `RenderUiToolDescriptor`, `RenderUiResult`, `UiResource` |
| Usage | `Usage`, `UsageCostBreakdown`, `PromptTokensDetails`, `CompletionTokensDetails`, `ProviderUsageDetails` |
| Errors | `AiError`, `AiNotConfiguredError`, `InvalidModelRefError`, `ModelProviderNotFoundError`, `ToolNotFoundError`, `ToolInputValidationError` |

## Capability ports (`@netscript/ai/ports`)

The capability seams the engine is programmed against, their default implementations, and the model/embedding/vision registries. Primary surface:

| Group | Symbols |
| --- | --- |
| Model registry | `registerModelProvider`, `getModelProvider`, `getModel`, `parseModelRef`, `listModelProviders`, `isModelProviderRegistered`, `resetModelRegistry`, `ModelProviderPort`, `ModelProviderFactory`, `ModelProviderConfig` |
| Embedding / vision registries | `registerEmbeddingProvider`, `getEmbeddingProvider`, `listEmbeddingProviders`, `isEmbeddingProviderRegistered`, `resetEmbeddingRegistry`, `registerVisionProvider`, `getVisionProvider`, `listVisionProviders`, `isVisionProviderRegistered`, `resetVisionRegistry` |
| Chat | `ChatClientPort`, `ChatModelProviderPort`, `ChatClientRequest`, `ChatClientCallOptions`, `ChatClientEvent`, `ChatTextEvent`, `ChatToolCallEvent`, `ChatFinishEvent`, `ChatErrorEvent`, `ChatFinishReason` |
| Embeddings / vision | `EmbeddingProviderPort`, `EmbeddingCallOptions`, `EmbeddingResponse`, `VisionProviderPort`, `VisionCallOptions`, `VisionResponse` |
| Agent | `AgentLoopPort`, `AgentLoopInput`, `AgentLoopOptions`, `AgentMemoryPort`, `MemoryRecord`, `RecallQuery`, `RecallResult` |
| Tools / skills / telemetry | `ToolRegistryPort`, `ToolHandler`, `SkillLoaderPort`, `SkillDescriptor`, `TelemetryPort`, `TelemetrySpan`, `TelemetryAttributes`, `TelemetryAttributeValue` |
| MCP | `McpTransportPort`, `McpTransportKind`, `McpConnectorConfig`, `McpClientConnection`, `McpConnectOptions`, `McpConnectionState`, `McpAuthConfig`, `McpAuthMode`, `McpToolRegistry`, `McpToolDescriptor`, `McpToolResult` |
| Reachability | `ReachabilityPort`, `ReachabilityCheckOptions`, `ReachabilityResult`, `createAssumeReachablePort` |
| Default factories | `createNoopTelemetryPort`, `createNoopToolRegistry`, `createNoopSkillLoader`, `createNoopAgentMemory`, `createUnconfiguredAgentLoop`, `createUnconfiguredEmbeddingProvider`, `createUnconfiguredVisionProvider`, `createUnconfiguredMcpTransport` |

## Model providers

Each provider lives on its own subpath. Importing the subpath self-registers the provider under its stable id and re-exports the adapter class and config type for direct construction. All chat adapters translate the wrapped SDK to the owned chat vocabulary — no provider-SDK type escapes the public surface — and support per-turn cancellation through the chat client's `stream(_, { signal })` option.

### `@netscript/ai/anthropic`

Registry id `"anthropic"`. Wraps `@tanstack/ai-anthropic`; the model catalog is taken verbatim from the wrapped package's `ANTHROPIC_MODELS`.

| Symbol | Kind | Description |
| --- | --- | --- |
| `AnthropicModelProvider` | class | `ModelProviderPort` backed by `@tanstack/ai-anthropic`. |
| `ANTHROPIC_PROVIDER_ID` | variable | `"anthropic"`. |
| `AnthropicModelProviderConfig` | interface | Provider configuration (below). |

| Config field | Type | Default |
| --- | --- | --- |
| `apiKey` | `string` | Falls back to the `ANTHROPIC_API_KEY` environment variable at client construction. |
| `baseURL` | `string` | Anthropic default (override to route through a gateway/proxy). |

### `@netscript/ai/openai-compatible`

Registry id `"openai-compatible"`. Wraps `@tanstack/ai-openai/compatible` for any endpoint that speaks the OpenAI wire (its own base URL, key, and model list).

| Symbol | Kind | Description |
| --- | --- | --- |
| `OpenAiCompatibleModelProvider` | class | `ModelProviderPort` backed by `@tanstack/ai-openai/compatible`. |
| `OPENAI_COMPATIBLE_PROVIDER_ID` | variable | `"openai-compatible"`. |
| `OpenAiCompatibleModelProviderConfig` | interface | Provider configuration (below). |
| `OpenAiCompatibleApi` | type alias | `"chat-completions" \| "responses"`. |

| Config field | Type | Default |
| --- | --- | --- |
| `baseURL` | `string` | Required to construct a client (e.g. `https://api.deepseek.com/v1`). |
| `apiKey` | `string` | Required to construct a client. No environment fallback — pass it yourself. |
| `models` | `readonly string[]` | Empty; when unset the provider is optimistic (`supports` returns `true`). |
| `api` | `OpenAiCompatibleApi` | `"chat-completions"`. |
| `name` | `string` | `"openai-compatible"`. |

When `baseURL` or `apiKey` is missing, `createChatClient` throws `AiNotConfiguredError` (the provider still lists and reports its configured `models`).

### `@netscript/ai/openrouter`

Registry id `"openrouter"`. Reuses the OpenAI-compatible transport pinned to OpenRouter, with the one wire divergence being reasoning: OpenRouter expects a top-level `reasoning: { effort }` object.

| Symbol | Kind | Description |
| --- | --- | --- |
| `OpenRouterModelProvider` | class | `ModelProviderPort` pinned to the OpenRouter endpoint. |
| `OPENROUTER_PROVIDER_ID` | variable | `"openrouter"`. |
| `DEFAULT_OPENROUTER_BASE_URL` | variable | `"https://openrouter.ai/api/v1"`. |
| `OPENROUTER_API_KEY_ENV` | variable | `"OPENROUTER_API_KEY"` — the env var read when `apiKey` is omitted. |
| `openRouterReasoningModelOptions` | function | Pure normalizer: `ReasoningEffort` → `{ reasoning: { effort } }` (or `undefined`). |
| `OpenRouterModelProviderConfig` | interface | Provider configuration (below). |
| `ReasoningEffort` | type alias | `"low" \| "medium" \| "high"`. |

| Config field | Type | Default |
| --- | --- | --- |
| `apiKey` | `string` | Falls back to the `OPENROUTER_API_KEY` environment variable. `createChatClient` throws `AiNotConfiguredError` when neither is present. |
| `baseURL` | `string` | `https://openrouter.ai/api/v1`. |
| `models` | `readonly string[]` | Empty; optimistic `supports` when unset. |
| `reasoningEffort` | `ReasoningEffort` | Unset — no reasoning object emitted. |

### `@netscript/ai/ollama`

Registry id `"ollama"`. Reuses the OpenAI-compatible transport pinned to a local Ollama daemon at `{host}/v1`, with a reachability preflight and a placeholder key (Ollama ignores authorization).

| Symbol | Kind | Description |
| --- | --- | --- |
| `OllamaModelProvider` | class | `ModelProviderPort` for a local Ollama daemon; exposes `checkReachable()`. |
| `OLLAMA_PROVIDER_ID` | variable | `"ollama"`. |
| `DEFAULT_OLLAMA_HOST` | variable | `"http://localhost:11434"`. |
| `createHttpReachabilityPort` / `HttpReachabilityAdapter` | function / class | Fetch-backed probe of `GET {host}/api/tags`. |
| `DEFAULT_REACHABILITY_PATH` | variable | Default probe path. |
| `createAssumeReachablePort` | function | A port that reports reachable without probing (tests). |
| `OllamaModelProviderConfig` | interface | Provider configuration (below). |
| `ReachabilityPort` / `ReachabilityCheckOptions` / `ReachabilityResult` | interface | Reachability seam and its non-throwing result. |

| Config field | Type | Default |
| --- | --- | --- |
| `host` | `string` | `http://localhost:11434`. |
| `models` | `readonly string[]` | Empty; optimistic `supports` when unset. |
| `reachability` | `ReachabilityPort` | Fetch-backed probe of `GET {host}/api/tags`. |
| `fetch` | `typeof fetch` | Global `fetch` (override for the default probe in tests). |

### `@netscript/ai/openai-embeddings`

Registry id `"openai-embeddings"`, registered for **both** the embedding and vision capabilities. Speaks the OpenAI-compatible HTTP API directly with Web `fetch` (no provider SDK).

| Symbol | Kind | Description |
| --- | --- | --- |
| `OpenAiEmbeddingsProvider` | class | Implements `EmbeddingProviderPort` (`embed`) and `VisionProviderPort` (`analyze`). |
| `OPENAI_EMBEDDINGS_PROVIDER_ID` | variable | `"openai-embeddings"`. |
| `DEFAULT_OPENAI_EMBEDDING_MODEL` | variable | `"text-embedding-3-small"`. |
| `DEFAULT_OPENAI_VISION_MODEL` | variable | `"gpt-4o-mini"`. |
| `OpenAiEmbeddingsProviderConfig` | interface | Provider configuration (below). |

| Config field | Type | Default |
| --- | --- | --- |
| `apiKey` | `string` | Required; sent as a bearer token. No environment fallback. `embed` / `analyze` throw `AiNotConfiguredError` when absent. |
| `baseURL` | `string` | `https://api.openai.com/v1`. |
| `embeddingModel` | `string` | `text-embedding-3-small`. |
| `visionModel` | `string` | `gpt-4o-mini`. |
| `fetch` | `typeof fetch` | Global `fetch` (override in tests). |

## Tools (`@netscript/ai/tools`)

Define server-executable (or client-deferred) tools, validate their input with **Standard Schema** (bring any conforming schema — zod, valibot, arktype, or hand-written), and dispatch them through an in-memory registry that satisfies `ToolRegistryPort`. The core adds no schema DSL and takes no `@netscript/*` dependency.

| Symbol | Kind | Description |
| --- | --- | --- |
| `defineAiTool` | function | Start a tool definition chain (`.parameters(...).input(schema).server(handler)`). |
| `createToolRegistry` | function | Build an in-memory registry from tool definitions. |
| `renderUiTool` | variable | Built-in `render_ui` wire contract (input schema + metadata only, no renderer). |
| `AiToolRegistry` | interface | Registry surface extending `ToolRegistryPort`. |
| `AiToolBuilder` / `AiToolBuilderWithInput` | interface | Typestate builder surfaces. |
| `AiToolDefinition` | interface | A defined tool (input/output typed). |
| `AiToolExecutionResult` | interface | Result of a dispatch (`output`, or `deferred` for client tools). |
| `AiToolInvocationContext` | interface | Context passed to a server handler. |
| `AiToolServerHandler` | type alias | The server execution function. |
| `AiToolExecutionKind` | type alias | `"server" \| "client"`. |
| `RenderUiToolInput` | interface | Input shape of the `render_ui` contract. |
| `ToolInputValidationError` | class | Thrown when a tool's input fails schema validation. |

## Agent loop (`@netscript/ai/agent`)

The E3 agent loop drives a bounded, cancellable model/tool interaction and emits `AgentChunk`s. It consumes its collaborators purely by factory injection — importing this subpath pulls **no** provider SDK.

| Symbol | Kind | Description |
| --- | --- | --- |
| `createAgentLoop` | function | Construct a loop from `AgentLoopDeps` (a `ChatModelProviderPort`, a `ToolRegistryPort`, an optional history strategy). |
| `DEFAULT_MAX_STEPS` | variable | Default step ceiling for a run. |
| `slidingWindowHistory` | function | A `HistoryStrategy` that keeps the last N messages. |
| `DEFAULT_HISTORY_WINDOW` | variable | Default window used by `slidingWindowHistory`. |
| `SlidingWindowOptions` | interface | `{ maxMessages }` for the sliding-window strategy. |
| `HistoryStrategy` | interface | History-trimming seam. |
| `isTerminalState` | function | Narrow an `AgentLoopState` to a terminal state. |
| `AgentLoopState` | type alias | `"idle" \| "running" \| "awaiting-tool" \| "done" \| "aborted" \| "errored"`. |
| `TerminalAgentLoopState` | type alias | `"done" \| "aborted" \| "errored"`. |
| `AgentMaxStepsExceededError` | class | Thrown when a run exceeds its step ceiling. |

The subpath also re-exports the seams the loop is programmed against (`AgentLoopPort`, `ChatClientPort` / `ChatModelProviderPort` and their event types, `ToolRegistryPort`) so it is a self-contained wiring surface.

## MCP (`@netscript/ai/mcp`)

MCP transport adapters and tool registration: stdio, reconnectable Streamable-HTTP, injected auth modes, and lifecycle state.

| Symbol | Kind | Description |
| --- | --- | --- |
| `createMcpTransport` | function | Build a transport from `McpTransportConfig` (`kind: "stdio"` or `"streamable-http"`). |
| `registerMcpTools` | function | Discover and register a transport's tools into a `ToolRegistry`. |
| `StdioMcpTransport` / `StdioMcpTransportConfig` | class / interface | Stdio transport and its config. |
| `StreamableHttpMcpTransport` / `StreamableHttpMcpTransportConfig` | class / interface | Reconnectable Streamable-HTTP transport and its config. |
| `McpTransportPort` | interface | The transport seam. |
| `McpAuthConfig` / `McpAuthMode` | type alias | Injected auth: `"none"`, `"api-token"`, or `"oauth"`. |
| `McpConnectionState` | type alias | `"disconnected" \| "connecting" \| "connected" \| "reconnecting" \| "closed"`. |
| `McpToolRegistration` / `McpToolDescriptor` / `McpToolResult` | interface | Registration and tool-call vocabulary. |

## Testing (`@netscript/ai/testing`)

Deterministic fakes for unit-testing code built on the ports. This subpath is excluded from the provider dependency graph.

| Symbol | Kind | Description |
| --- | --- | --- |
| `createFakeModelProvider` | function | A `ModelProviderPort` over a fixed descriptor list. |
| `createFakeChatModelProvider` | function | A chat provider that replays scripted turns of `ChatClientEvent`s. |
| `createFakeEmbeddingProvider` | function | An `EmbeddingProviderPort` returning a fixed vector. |
| `createFakeVisionProvider` | function | A `VisionProviderPort` returning fixed text. |
| `createFakeAgentLoop` | function | An `AgentLoopPort` that yields a fixed `AgentChunk[]`. |
| `createFakeAgentMemory` | function | An `AgentMemoryPort` with toggleable recall. |
| `createFakeTelemetryPort` | function | A recording `TelemetryPort` (`FakeTelemetryPort`). |
| `createInMemoryToolRegistry` | function | A `ToolRegistryPort` for tests. |

## Configuration

`@netscript/ai` reads no `@netscript/*` config surface — capabilities are wired through `AiRuntimeConfig` (see [runtime capability ports](#runtime-capability-ports-and-their-defaults)) and providers through their config bags. Two adapters resolve an API key from the environment when `apiKey` is omitted:

| Environment variable | Read by | When |
| --- | --- | --- |
| `ANTHROPIC_API_KEY` | `@netscript/ai/anthropic` | When `apiKey` is omitted (via the wrapped `@tanstack/ai-anthropic` client). |
| `OPENROUTER_API_KEY` | `@netscript/ai/openrouter` | When `apiKey` is omitted (exported as `OPENROUTER_API_KEY_ENV`). |

> The `openai-compatible`, `openai-embeddings`, and `ollama` providers do **not** read the environment. Pass `apiKey` (and `baseURL`/`host`) explicitly — commonly from `Deno.env.get(...)` in your composition code. Reading a key from the environment requires `--allow-env` for the variable in question.

> **Provider keys have no typed config surface — by design.** Unlike service topology (typed through `@netscript/config`), AI provider credentials are **not** modelled in `netscript.config.ts`. Reading the key with raw `Deno.env.get(...)` (or letting the Anthropic / OpenRouter adapters resolve their env var) is the **supported** path — secrets stay out of the committed config and are injected by the runtime environment instead.

## Examples

### Compose a runtime

```ts
import { createAiRuntime } from "@netscript/ai";

const ai = createAiRuntime();
// Telemetry defaults to a no-op port — safe to call with nothing wired.
ai.telemetry.recordEvent("agent.start");
```

### Register a provider and resolve a model

```ts
import "@netscript/ai/anthropic"; // self-registers the 'anthropic' provider
import { getModel } from "@netscript/ai";

const handle = await getModel("anthropic:claude-sonnet-4-5");
```

### Configure an OpenAI-compatible endpoint

```ts
import "@netscript/ai/openai-compatible"; // self-registers the provider
import { getModelProvider } from "@netscript/ai";

const provider = getModelProvider("openai-compatible", {
  baseURL: "https://api.deepseek.com/v1",
  apiKey: Deno.env.get("DEEPSEEK_KEY"),
  models: ["deepseek-chat", "deepseek-reasoner"],
});
```

### Stream a reasoning turn through OpenRouter

```ts
import "@netscript/ai/openrouter"; // self-registers the provider
import { getModelProvider } from "@netscript/ai";

const provider = getModelProvider("openrouter", {
  apiKey: Deno.env.get("OPENROUTER_API_KEY"),
  models: ["anthropic/claude-sonnet-4.5"],
  reasoningEffort: "high",
});
```

### Preflight a local Ollama daemon

```ts
import "@netscript/ai/ollama"; // self-registers the provider
import { getModelProvider } from "@netscript/ai";

const provider = getModelProvider("ollama", { models: ["llama3.2"] });
const health = await provider.checkReachable();
if (!health.reachable) {
  console.warn(`Ollama is down: ${health.detail}`);
}
```

### Define, register, and dispatch a tool

```ts
import { createToolRegistry, defineAiTool } from "@netscript/ai/tools";

const add = defineAiTool("add")
  .parameters({
    type: "object",
    properties: { a: { type: "number" }, b: { type: "number" } },
    required: ["a", "b"],
  })
  .input(myAddSchema) // any StandardSchemaV1<unknown, { a: number; b: number }>
  .server(({ a, b }) => ({ sum: a + b }));

const registry = createToolRegistry([add]);
const { output } = await registry.dispatch("add", { a: 2, b: 3 });
```

### Drive a bounded, cancellable agent loop

```ts
import { createAgentLoop, slidingWindowHistory } from "@netscript/ai/agent";

const loop = createAgentLoop({
  modelProvider, // a ChatModelProviderPort
  tools, // a ToolRegistryPort
  history: slidingWindowHistory({ maxMessages: 12 }),
});

for await (const chunk of loop.run({ model: "anthropic:claude-sonnet-4-5", messages })) {
  if (chunk.type === "text") console.log(chunk.delta);
  if (chunk.type === "done") console.log(chunk.usage);
}
```

### Register MCP tools over Streamable-HTTP

```ts
import { createMcpTransport, registerMcpTools } from "@netscript/ai/mcp";
import { createToolRegistry } from "@netscript/ai/tools";

const transport = createMcpTransport({
  kind: "streamable-http",
  serverId: "search",
  url: "https://mcp.example.com",
  auth: { mode: "api-token", token: "injected-at-runtime", scheme: "Bearer" },
});

const registry = createToolRegistry();
await registerMcpTools(registry, transport);
```

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/ai/_

---

# `@netscript/ai/skills`

Load validated **Agent Skills** with progressive disclosure and optional semantic matching. A skill is a `SKILL.md` document — a small frontmatter block plus Markdown instructions — that an agent can discover cheaply by tags (or embeddings) and only fully disclose when it is actually selected. This subpath is a **library surface only**: it has no CLI verbs and takes no `@netscript/*` runtime dependency. For the full package index return to the [`@netscript/ai` reference](https://rickylabs.github.io/netscript/reference/ai/) or the [reference overview](https://rickylabs.github.io/netscript/reference/).

> Library surface vs. installed skills
>
> This page is the
>
> loader API
>
> — the code you call to discover and disclose
>
> SKILL.md
>
> documents at runtime. It is distinct from the
>
> public skill bundle
>
> that
>
> netscript agent init
>
> installs for a coding agent (the next section). The library loads skills; the bundle is a set of three ready-made skills that teach an agent the NetScript vocabulary.

## Installed NetScript skills

`netscript agent init` installs three first-party skills on the **Claude Code host path** (under `.claude/skills/`, alongside `.mcp.json` and the marked `AGENTS.md` section); the VS Code host path writes `.vscode/mcp.json` only, with no skills. They share one vocabulary with the `netscript` CLI and the [NetScript MCP tools](https://rickylabs.github.io/netscript/ai/agent-tooling/#tool-catalog), so an agent routes to a workflow and then reaches for the matching CLI verb or MCP tool.

| Skill | Role |
| --- | --- |
| `netscript` | Router. Dispatches a task to the build or operate skill (or to the Aspire skill for orchestration); it is not useful on its own. |
| `netscript-build` | Scaffold and build with real `netscript` CLI verbs: `init`, the contract-first flow, the database lifecycle, adding and syncing plugins, adding services and UI, and generating registries. |
| `netscript-operate` | Monitor, debug, and analyze a running app through the bounded MCP tools: health, recent runs, one execution end to end, recent errors, job results, service and database performance, and doc search. |

These are the skills named in the bundle manifest and installed as an atomic set; re-running `netscript agent init` is idempotent. See [Agent tooling](https://rickylabs.github.io/netscript/ai/agent-tooling/) for the CLI × skills × MCP combo.

```ts
import {
  createInMemorySkillContentSource,
  createSkillLoader,
} from "jsr:@netscript/ai@0.0.1-beta.11/skills";
```

The subpath is published as the `./skills` export of `@netscript/ai` (version `0.0.1-beta.11`). Nothing here reads the environment or performs IO on its own: content enters through an injected `SkillContentSource`, and semantic ranking is only performed when you supply a `SkillEmbeddingProvider`.

## The skill document

`parseSkillMarkdown` is the single validator for the blessed `SKILL.md` shape. The frontmatter must be a closed `---` block whose only allowed keys are the four required fields; the body is the Markdown that follows and must be non-empty.

| Frontmatter field | Rule |
| --- | --- |
| `id` | Non-empty; matches `^[a-z0-9][a-z0-9._-]*$` (case-insensitive). |
| `name` | Non-empty human-readable label. |
| `tags` | A YAML list with at least one tag; drives tag matching. |
| `description` | Non-empty short summary used for discovery and semantic matching. |

Unknown keys, duplicate keys, a missing required key, an empty body, or a malformed frontmatter line each throw a `TypeError`. A minimal document:

```md
---
id: review
name: Code review
tags: [review, quality]
description: Reviews a change for correctness.
---
Inspect the diff and report actionable findings.
```

## Progressive disclosure

The design keeps cheap metadata enumeration separate from full-content reads. A `SkillContentSource` lists validated `SkillSummary` rows (id, name, tags, description — no body) and loads the raw `SKILL.md` for one id on demand. A `SkillLoaderPort` composes over a source: it matches summaries first, and only `load(id)` parses and validates the full `SkillDocument` (summary + `body`). This is the same two-phase shape the runtime's `skills` capability port speaks.

## Surface

### Composition

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createSkillLoader` | function | `createSkillLoader(source: SkillContentSource, options?: SkillLoaderOptions): SkillLoaderPort` | Compose a loader from an injected content source and optional embeddings. |
| `createInMemorySkillContentSource` | function | `createInMemorySkillContentSource(entries: readonly SkillSourceEntry[]): SkillContentSource` | Build an effect-free source from caller-supplied `SKILL.md` strings (rejects duplicate or mismatched ids). |
| `parseSkillMarkdown` | function | `parseSkillMarkdown(markdown: string): SkillDocument` | Parse and validate one `SKILL.md` into a full document, or throw `TypeError`. |

### Matching primitives

The loader delegates to two pure ranking functions, also exported directly for callers that hold their own summaries. Both return results sorted by descending score.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `matchByTags` | function | `matchByTags(skills: readonly SkillSummary[], triggers: readonly string[]): readonly SkillMatch[]` | Case-insensitive exact (`score 1`) and substring (`score 0.5`) tag triggers. |
| `matchBySemantic` | function | `matchBySemantic(skills: readonly SkillSummary[], query: string, embeddings: SkillEmbeddingProvider, model?: string): Promise<readonly SkillMatch[]>` | Cosine-similarity ranking over `name`/`description`/`tags` text via an injected embedding provider. |
| `SKILL_MATCH_MODES` | variable | `readonly ["tag", "semantic"]` | The trigger modes a `SkillMatch` can report. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `SkillLoaderPort` | interface | Discovery + two-phase loading: `list()`, `load(id)`, `matchByTag(tags)`, `matchByQuery(query, options?)`. |
| `SkillContentSource` | interface | Source boundary: `list()` of summaries and `load(id)` of raw content. |
| `SkillSummary` | interface | Cheap metadata (`id`, `name`, `tags`, `description`) with no body. |
| `SkillDocument` | interface | `SkillSummary` extended with the non-empty `body`. |
| `SkillMatch` | interface | A ranked result: `skill` (summary), `score` (0–1), and contributing `modes`. |
| `SkillMatchMode` | type alias | `"tag" \| "semantic"`. |
| `SkillQueryOptions` | interface | `matchByQuery` options: `tags`, `semantic`, `minScore`, `limit`. |
| `SkillLoaderOptions` | interface | Loader composition options: `embeddings`, `embeddingModel`. |
| `SkillEmbeddingProvider` | interface | Minimal `embed(input, options?)` structural view used for semantic matching. |
| `SkillSourceEntry` | interface | Input to the in-memory source: `{ id, markdown }`. |

## Default runtime port

The runtime's `skills` capability is a `SkillLoaderPort`. When `AiRuntimeConfig.skills` is omitted, `createAiRuntime` injects a no-op loader that lists and matches nothing — so agent code can call the port unconditionally before any skills are wired.

| `AiRuntimeConfig` field | Port | Default when omitted |
| --- | --- | --- |
| `skills` | `SkillLoaderPort` | No-op returning no skills (`createNoopSkillLoader` from `@netscript/ai/ports`). |

Provide a real loader by wiring one built here into the runtime config; see the [runtime capability ports](https://rickylabs.github.io/netscript/reference/ai/#runtime-capability-ports-and-their-defaults) table on the package page.

## Examples

### Build a loader and match by tag

```ts
import {
  createInMemorySkillContentSource,
  createSkillLoader,
} from "@netscript/ai/skills";

const source = createInMemorySkillContentSource([
  {
    id: "review",
    markdown: `---
id: review
name: Code review
tags: [review, quality]
description: Reviews a change for correctness.
---
Inspect the diff and report actionable findings.
`,
  },
]);

const loader = createSkillLoader(source);
const matches = await loader.matchByTag(["review"]);
if (matches.length > 0) {
  const skill = await loader.load(matches[0].skill.id); // full body disclosed here
  console.log(skill?.body);
}
```

### Add semantic ranking

Pass a `SkillEmbeddingProvider` at composition time and set `semantic: true` on the query. The `@netscript/ai/openai-embeddings` provider satisfies the structural `embed` shape.

```ts
import "@netscript/ai/openai-embeddings"; // self-registers the provider
import { getEmbeddingProvider } from "@netscript/ai";
import { createSkillLoader } from "@netscript/ai/skills";

const embeddings = getEmbeddingProvider("openai-embeddings", {
  apiKey: Deno.env.get("OPENAI_API_KEY"),
});

const loader = createSkillLoader(source, { embeddings });
const ranked = await loader.matchByQuery("find bugs in my patch", {
  semantic: true,
  limit: 5,
});
```

### Rank summaries you already hold

`matchByTags` and `matchBySemantic` are pure and usable without a loader:

```ts
import { matchByTags } from "@netscript/ai/skills";

const summaries = await source.list();
const results = matchByTags(summaries, ["quality"]);
// results: [{ skill, score, modes: ["tag"] }, ...] sorted by descending score
```

---

Back to the [`@netscript/ai` reference](https://rickylabs.github.io/netscript/reference/ai/) or the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/ai/skills/_

---

# `@netscript/aspire`

SDK-neutral Aspire diagnostics, config parsing, contribution ports, and TypeScript AppHost generation for NetScript plugin packages. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

> **Generated AppHost runtime behavior.** The TypeScript AppHost this package generates emits **ephemeral ports** (`0`) for the dashboard, OTLP, and resource-service endpoints, so `aspire start --isolated` (an upstream Aspire CLI flag) yields non-colliding, parallel-safe ports and isolated secrets. Generated frontend **app** resources also call `withBrowserLogs()` by default (the AppHost pins `Aspire.Hosting.Browsers`), forwarding browser console output into the Aspire dashboard with no opt-in.

The root entrypoint (`@netscript/aspire`) exposes the diagnostic contract only. Composition, config, schema, type, adapter, and testing APIs live on typed sub-path exports:

- [`@netscript/aspire/config`](#sub-path-exports) — `appsettings.json` parsing, Zod schemas, and entry interfaces.
- [`@netscript/aspire/schema`](#sub-path-exports) — JSON Schema generation from the Zod config schema.
- [`@netscript/aspire/types`](#sub-path-exports) — inferred config types and known-name extractors.
- [`@netscript/aspire/constants`](#sub-path-exports) — config keys, sections, and runtime defaults.
- [`@netscript/aspire/application`](#sub-path-exports) — AppHost composition, the contribution registry, and resolver helpers.
- [`@netscript/aspire/adapters`](#sub-path-exports) — the SDK-neutral TypeScript builder adapter.
- [`@netscript/aspire/testing`](#sub-path-exports) — in-memory builder, contribution base class, and test fixtures.

## Diagnostics (root export)

The root `@netscript/aspire` entrypoint exposes the diagnostic contract.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `inspectAspire` | function | `function inspectAspire(target: string \| readonly InspectableAspireResource[] \| InspectableAspireBuilder): InspectionReport` | Inspect an Aspire target and return a JSON-stable diagnostic report. |
| `InspectableAspireBuilder` | interface | — | Minimal builder shape accepted by the Aspire inspector. |
| `InspectableAspireResource` | interface | — | Minimal resource shape accepted by the Aspire inspector. |
| `InspectionReport` | interface | — | JSON-stable diagnostic report returned by Aspire inspectors. |

## Config parsing (`@netscript/aspire/config`)

Parses and validates `appsettings.json` against the Zod schema.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `parseAppSettings` | function | `async function parseAppSettings(filePath: string, options?: ParseOptions): Promise<ParseResult<NetScriptConfig>>` | Parse an `appsettings.json` file and validate it against the Zod schema. |

### Config interfaces

| Symbol | Description |
| --- | --- |
| `AppSettings` | Top-level `appsettings.json` structure. |
| `NetScriptConfig` | Root NetScript configuration section. |
| `BaseEntry` | Common fields shared by resource entries. |
| `ReferenceEntry` | Reference fields for resources that depend on services or plugins. |
| `ServiceEntry` | Backend service resource entry. |
| `PluginEntry` | Plugin service resource entry. |
| `DatabaseEntry` | Database resource entry. |
| `CacheEntry` | Cache resource entry. |
| `BackgroundProcessorEntry` | Background processor resource entry. |
| `AppEntry` | Frontend, desktop, or task application entry. |
| `ToolEntry` | Development tool entry. |
| `DefaultsConfig` | Defaults section wrapper. |
| `DenoDefaults` | Global Deno runtime defaults. |
| `LoggingConfig` | ASP.NET Core logging configuration. |
| `OtelConfig` | OpenTelemetry endpoint configuration. |
| `ParseOptions` | Options for controlling parser behavior. |
| `ParseResult` | Result of parsing `appsettings.json`. |
| `AspireSchema` | Public parser contract exposed by Aspire schema constants. |
| `AspireSafeParseSuccess` | Successful result from `AspireSchema.safeParse`. |
| `AspireSafeParseFailure` | Failed result from `AspireSchema.safeParse`. |

### Config type aliases

| Symbol | Description |
| --- | --- |
| `AppType` | Application entry variants supported by the AppHost config. |
| `CacheEngine` | Cache engine variants supported by Aspire hosting integrations. |
| `DatabaseEngine` | Database engine variants supported by Aspire hosting integrations. |
| `ResourceMode` | Resource provisioning mode for managed resources. |
| `AspireSafeParseResult` | Result from `AspireSchema.safeParse`. |

### Config Zod schemas

These exported Zod schema values back the config contract above.

| Symbol | Description |
| --- | --- |
| `AppSettingsSchema` | Top-level `appsettings.json` schema. |
| `NetScriptConfigSchema` | Root NetScript configuration schema. |
| `ServiceEntrySchema` | Service entry schema. |
| `PluginEntrySchema` | Plugin entry schema. |
| `DatabaseEntrySchema` | Database entry schema. |
| `CacheEntrySchema` | Cache entry schema. |
| `BackgroundProcessorEntrySchema` | Background processor entry schema. |
| `AppEntrySchema` | Application entry schema. |
| `ToolEntrySchema` | Development tool entry schema. |
| `DefaultsSchema` | Defaults section schema. |
| `DenoDefaultsSchema` | Global Deno runtime defaults schema. |
| `OtelConfigSchema` | OpenTelemetry endpoint configuration schema. |
| `AppTypeSchema` | Application type schema. |
| `CacheEngineSchema` | Cache engine schema. |
| `DatabaseEngineSchema` | Database engine schema. |
| `ResourceModeSchema` | Resource provisioning mode schema. |

## Schema generation (`@netscript/aspire/schema`)

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `generateAppSettingsJsonSchema` | function | `function generateAppSettingsJsonSchema(): Record<string, unknown>` | Generate a JSON Schema (draft-7) from the Zod `AppSettingsSchema`. |

## Config types (`@netscript/aspire/types`)

Inferred config types and helpers that extract known resource names as literal unions from a config type.

| Symbol | Kind | Description |
| --- | --- | --- |
| `AppSettings` | type alias | Full `appsettings.json` structure. |
| `NetScriptConfig` | type alias | Root `NetScript` configuration section. |
| `ServiceEntry` | type alias | A service resource entry. |
| `PluginEntry` | type alias | A plugin resource entry. |
| `DatabaseEntry` | type alias | A database resource entry. |
| `CacheEntry` | type alias | A cache resource entry. |
| `BackgroundProcessorEntry` | type alias | A background processor entry (worker, saga, or trigger). |
| `AppEntry` | type alias | An application resource entry. |
| `ToolEntry` | type alias | A development tool entry. |
| `DenoDefaults` | type alias | Global Deno runtime defaults. |
| `OtelConfig` | type alias | OpenTelemetry exporter configuration. |
| `AppType` | type alias | Application type variant. |
| `CacheEngine` | type alias | Supported cache engine types. |
| `DatabaseEngine` | type alias | Supported database engine types. |
| `ResourceMode` | type alias | Resource provisioning mode. |
| `ResourceDependencies` | interface | Extracted dependency requirements from a resource entry. |
| `AppEntryOf` | type alias | The typed app entry for a known app name. |
| `ServiceEntryOf` | type alias | The typed service entry for a known service name. |
| `PluginEntryOf` | type alias | The typed plugin entry for a known plugin name. |
| `DatabaseEntryOf` | type alias | The typed database entry for a known database name. |
| `CacheEntryOf` | type alias | The typed cache entry for a known cache name. |
| `BackgroundProcessorEntryOf` | type alias | The typed background processor entry for a known processor name. |
| `KnownApps` | type alias | Extract known app names as a literal union from a config type. |
| `KnownServices` | type alias | Extract known service names as a literal union from a config type. |
| `KnownPlugins` | type alias | Extract known plugin names as a literal union from a config type. |
| `KnownDatabases` | type alias | Extract known database names as a literal union from a config type. |
| `KnownCaches` | type alias | Extract known cache names as a literal union from a config type. |
| `KnownBackgroundProcessors` | type alias | Extract known background processor names as a literal union from a config type. |

## Constants (`@netscript/aspire/constants`)

| Symbol | Kind | Description |
| --- | --- | --- |
| `CONFIG_KEYS` | const | Configuration key constants used in `IConfiguration` binding. |
| `CONFIG_SECTIONS` | const | ASP.NET Core `IConfiguration` section paths for NetScript config sections. |
| `DASHBOARD_ENV_VARS` | const | Aspire dashboard environment variable names. |
| `DEFAULT_PERMISSIONS` | const | Default Deno permission flags applied to all resources. |
| `OTEL_DEFAULTS` | const | OpenTelemetry default values. |
| `OTEL_ENV_VARS` | const | OpenTelemetry environment variable names. |
| `RESOURCE_DEFAULTS` | const | Default values for resource configuration. |

## Composition (`@netscript/aspire/application`)

AppHost composition, the plugin contribution registry, and the resolver helpers that turn config entries into Aspire resources.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `composeAppHost` | function | `function composeAppHost(options: ComposeAppHostOptions): ComposeAppHostResult` | Compose plugin Aspire contributions into a supplied builder. |
| `ContributionRegistry` | class | — | Registry of Aspire plugin contributions for one AppHost composition. |
| `createPortAllocator` | function | `function createPortAllocator(options: PortAllocationOptions): (key: string, fallback?: number) => number` | Create a deterministic port allocator for plugin resources. |
| `buildOtelEnvVars` | function | `function buildOtelEnvVars(serviceName: string, serviceVersion: string, mode: OtelMode, otlpEndpoint: string): Record<string, string>` | Build OpenTelemetry environment variables for a Deno resource. |
| `buildViteEnvVarName` | function | `function buildViteEnvVarName(resourceName: string, endpointName: string): ViteEnvVarNames` | Generate VITE-prefixed environment variable names for a resource. |
| `extractDependencies` | function | `function extractDependencies(entry): ResourceDependencies` | Extract infrastructure dependency flags from a resource entry. |
| `extractPluginReferences` | function | `function extractPluginReferences(entry): string[]` | Extract plugin references from a resource entry. |
| `extractServiceReferences` | function | `function extractServiceReferences(entry): string[]` | Extract and deduplicate service references from a resource entry. |
| `resolveDataPath` | function | `function resolveDataPath(appHostDir: string, dataPath: string \| undefined, resourceName: string): string` | Resolve the data path for a persistent resource (database, cache). |
| `resolvePermissions` | function | `function resolvePermissions(entryPermissions: readonly string[] \| undefined, defaultPermissions: readonly string[], watchMode: boolean, watchFlag: string): string[]` | Resolve the effective Deno permission flags for a resource. |
| `resolveWorkdir` | function | `function resolveWorkdir(section: string, key: string, explicitWorkdir?: string): string` | Resolve the default working directory for a resource entry. |
| `resolveWorkspacePath` | function | `function resolveWorkspacePath(appHostDir: string, relativePath: string): string` | Resolve a workspace-relative path from the AppHost directory. |

### Composition interfaces and type aliases

| Symbol | Kind | Description |
| --- | --- | --- |
| `AspireBuilder` | interface | Port implemented by adapters that emit Aspire AppHost resources. |
| `AspireResource` | interface | Resource descriptor returned by Aspire builder ports. |
| `ComposeAppHostOptions` | interface | Options for composing plugin Aspire contributions into an AppHost builder. |
| `ComposeAppHostResult` | interface | Result of composing an AppHost from plugin Aspire contributions. |
| `ComposePluginManifest` | interface | Minimal manifest shape consumed by Aspire composition. |
| `ContributionContext` | interface | Context passed to plugin Aspire contributions during AppHost composition. |
| `PortAllocationOptions` | interface | Port allocation options for Aspire composition. |
| `ViteEnvVarNames` | interface | Generated VITE environment variable name pair. |
| `AspireResourceKind` | type alias | Aspire resource kinds produced by plugin contributions. |
| `OtelMode` | type alias | Registration mode determining which OTEL env vars are needed. |

## Adapters (`@netscript/aspire/adapters`)

The SDK-neutral TypeScript builder adapter used to compose an AppHost.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `AspireTypeScriptBuilder` | class | `class AspireTypeScriptBuilder extends MemoryAspireBuilder` | SDK-neutral builder adapter for TypeScript AppHost composition tests. |
| `createPortAllocator` | function | `function createPortAllocator(options: PortAllocationOptions): (key: string, fallback?: number) => number` | Create a deterministic port allocator for plugin resources. |
| `resolveEnvSource` | function | `function resolveEnvSource(source: EnvSource \| string, options: ResolveEnvSourceOptions): string` | Resolve an environment source into a concrete string. |
| `AspireResource` | interface | — | Resource descriptor returned by Aspire builder ports. |
| `PortAllocationOptions` | interface | — | Port allocation options for Aspire composition. |
| `ResolveEnvSourceOptions` | interface | — | Options for resolving plugin environment variable sources. |
| `EnvSource` | type alias | — | Source for an environment variable value in an AppHost composition. |

## Testing (`@netscript/aspire/testing`)

In-memory builder, the plugin contribution base class, and deterministic fixtures for plugin authors writing Aspire composition tests.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `AspireNSPluginContribution` | class | — | Base class plugins extend to contribute Aspire resources to an AppHost. |
| `MemoryAspireBuilder` | class | `class MemoryAspireBuilder implements AspireBuilder` | In-memory Aspire builder used by tests and examples. |
| `ExampleAspireContribution` | class | `class ExampleAspireContribution extends AspireNSPluginContribution` | Example contribution used by public tests and README snippets. |
| `createContributionContextFixture` | function | `function createContributionContextFixture(overrides: Partial<ContributionContext>): ContributionContext` | Create a deterministic contribution context for Aspire tests. |
| `AspireBuilder` | interface | — | Port implemented by adapters that emit Aspire AppHost resources. |
| `AspireResource` | interface | — | Resource descriptor returned by Aspire builder ports. |
| `ContributionContext` | interface | — | Context passed to plugin Aspire contributions during AppHost composition. |
| `CacheSpec` | interface | — | Cache resource spec consumed by `AspireBuilder`. |
| `ContainerSpec` | interface | — | Container resource spec consumed by `AspireBuilder`. |
| `DatabaseSpec` | interface | — | Database resource spec consumed by `AspireBuilder`. |
| `DenoServiceSpec` | interface | — | Deno service resource spec consumed by `AspireBuilder`. |
| `DenoBackgroundSpec` | interface | — | Deno background process spec consumed by `AspireBuilder`. |
| `HealthCheckSpec` | interface | — | Health check expectation declared by a plugin contribution. |
| `MemoryAspireReference` | interface | — | Recorded relationship between two in-memory Aspire resources. |
| `AspireResourceKind` | type alias | — | Aspire resource kinds produced by plugin contributions. |

## Sub-path exports

The following entrypoints are published alongside the root export. Each is generated from its own `deno doc` surface and documented in the sections above.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/aspire` | `./mod.ts` | Diagnostic contract (`inspectAspire`). |
| `@netscript/aspire/config` | `./config.ts` | `appsettings.json` parsing, Zod schemas, and entry interfaces. |
| `@netscript/aspire/schema` | `./schema.ts` | JSON Schema generation from the Zod config schema. |
| `@netscript/aspire/types` | `./types.ts` | Inferred config types and known-name extractors. |
| `@netscript/aspire/constants` | `./constants.ts` | Config keys, sections, and runtime defaults. |
| `@netscript/aspire/application` | `./src/application/mod.ts` | AppHost composition, contribution registry, and resolvers. |
| `@netscript/aspire/adapters` | `./src/adapters/mod.ts` | SDK-neutral TypeScript builder adapter. |
| `@netscript/aspire/testing` | `./src/testing/mod.ts` | In-memory builder, contribution base class, and fixtures. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/aspire/_

---

# `@netscript/auth-better-auth`

Better Auth integration, authenticator, and backend adapter for NetScript auth. This page is generated from the package's public surface with `deno doc`.

## Factories

| Symbol | Kind | Description |
| --- | --- | --- |
| `createNetscriptBetterAuth` | function | Create a NetScript-oriented Better Auth instance. |
| `createBetterAuthBackend` | function | Create an `AuthBackendPort` adapter backed by Better Auth. |
| `createBetterAuthAuthenticator` | function | Create a Better Auth request authenticator. |

## Options and integration types

| Symbol | Kind | Description |
| --- | --- | --- |
| `NetscriptBetterAuthOptions` | interface | Options for `createNetscriptBetterAuth`. |
| `BetterAuthBackendOptions` | interface | Options for `createBetterAuthBackend`. |
| `BetterAuthAuthenticatorOptions` | interface | Options for `createBetterAuthAuthenticator`. |
| `BetterAuthProviderOptions` | interface | Provider descriptor options for Better Auth. |
| `BetterAuthInstance` | interface | Better Auth instance boundary consumed by this adapter. |
| `BetterAuthSessionPayload` | interface | Better Auth session payload shape. |
| `BetterAuthGetSessionInput` | type alias | Input accepted when looking up a Better Auth session. |
| `BetterAuthSessionLookupResponse` | type alias | Session lookup response returned by the adapter. |
| `BetterAuthPrismaClient` | type alias | Prisma client boundary accepted by the Better Auth integration. |
| `BetterAuthPrismaProvider` | type alias | Prisma provider value accepted by the integration. |

## Re-exported auth contracts

| Symbol | Kind | Description |
| --- | --- | --- |
| `AuthBackendPort` | interface | Backend adapter port implemented by `createBetterAuthBackend`. |
| `AuthenticatorPort` | interface | Authenticator port used by request authentication. |
| `AuthnRequest` | interface | Authentication request shape. |
| `Principal` | interface | Principal payload returned by authenticators. |
| `AuthBackendOperationUnsupportedError` | class | Error for unsupported upstream operations. |
| `InteractiveFlowPort` | interface | Interactive-flow port re-exported from the core auth package. |

Back to the [auth reference hub](https://rickylabs.github.io/netscript/reference/auth/).

_Canonical: https://rickylabs.github.io/netscript/reference/auth-better-auth/_

---

# `@netscript/auth-kv-oauth`

KV-backed OAuth2/OIDC relying-party backend for NetScript auth. This page is generated from the package's public surface with `deno doc`.

## Backend and flow factories

| Symbol | Kind | Description |
| --- | --- | --- |
| `createKvOAuthBackend` | function | Create a KV-backed OAuth backend. |
| `createKvOAuthFlow` | function | Create the OAuth sign-in and callback flow. |
| `createKvOAuthStore` | function | Create the KV-backed OAuth store. |
| `createKvOAuthCrypto` | function | Create crypto helpers for OAuth state and token storage. |
| `defineOAuthProvider` | function | Normalize generic OAuth provider input into an `OAuthProviderConfig`. |
| `providers` | constant | Provider preset collection including GitHub, Google, GitLab, Discord, Slack, Spotify, Facebook, Twitter, Auth0, Okta, AWS Cognito, Azure AD, Logto, and Clerk. |

## Cookie, environment, and discovery helpers

| Symbol | Kind | Description |
| --- | --- | --- |
| `buildCookieHeader` | function | Build a `Set-Cookie` header value. |
| `clearCookieHeader` | function | Build a cookie-clearing header value. |
| `parseCookieHeader` | function | Parse an incoming cookie header. |
| `getRequiredEnv` | function | Read a required environment variable. |
| `deriveHttps` | function | Derive HTTPS defaults for provider configuration. |
| `hasIssuerDiscovery` | function | Check whether provider config includes issuer discovery. |
| `KvOAuthError` | class | OAuth backend error class. |

## Main types

| Symbol | Kind | Description |
| --- | --- | --- |
| `KvOAuthBackend` | interface | Backend object returned by `createKvOAuthBackend`. |
| `KvOAuthFlow` | interface | OAuth flow object returned by `createKvOAuthFlow`. |
| `KvOAuthStore` | interface | KV store port used by the OAuth backend. |
| `KvOAuthCrypto` | interface | Crypto port used by the OAuth backend. |
| `CreateKvOAuthBackendOptions` | type alias | Options for `createKvOAuthBackend`. |
| `CreateKvOAuthFlowOptions` | type alias | Options for `createKvOAuthFlow`. |
| `OAuthProviderInput` | type alias | Generic provider input accepted by `defineOAuthProvider`. |
| `OAuthProviderConfig` | type alias | Normalized provider config. |
| `PresetOAuthProviderOptions` | type alias | Options accepted by provider presets. |
| `KvOAuthCallbackResult` | type alias | Callback result returned by the OAuth flow. |
| `KvOAuthTokenSet` | type alias | Token set stored by the KV OAuth backend. |

## Sub-path exports

| Export | Purpose |
| --- | --- |
| `@netscript/auth-kv-oauth` | Root KV OAuth backend surface. |
| `@netscript/auth-kv-oauth/providers` | Provider presets and `defineOAuthProvider`. |
| `@netscript/auth-kv-oauth/store` | KV OAuth store implementation. |
| `@netscript/auth-kv-oauth/crypto` | KV OAuth crypto helpers. |
| `@netscript/auth-kv-oauth/cookies` | Cookie parsing and header helpers. |
| `@netscript/auth-kv-oauth/flow` | OAuth sign-in and callback flow. |
| `@netscript/auth-kv-oauth/backend` | Backend adapter factory. |
| `@netscript/auth-kv-oauth/errors` | KV OAuth error class and codes. |

Back to the [auth reference hub](https://rickylabs.github.io/netscript/reference/auth/).

_Canonical: https://rickylabs.github.io/netscript/reference/auth-kv-oauth/_

---

# `@netscript/auth-workos`

WorkOS-backed authenticator and backend adapter for NetScript auth. This page is generated from the package's public surface with `deno doc`.

## Factories

| Symbol | Kind | Description |
| --- | --- | --- |
| `createWorkosBackend` | function | Create an `AuthBackendPort` adapter backed by WorkOS. |
| `createWorkosAuthenticator` | function | Create a WorkOS session authenticator. |
| `createWorkosAccessTokenAuthenticator` | function | Create a WorkOS access-token authenticator. |

## Options and result types

| Symbol | Kind | Description |
| --- | --- | --- |
| `WorkosBackendOptions` | interface | Options for `createWorkosBackend`. |
| `WorkosAuthenticatorOptions` | interface | Options for `createWorkosAuthenticator`. |
| `WorkosAccessTokenAuthenticatorOptions` | interface | Options for `createWorkosAccessTokenAuthenticator`. |
| `WorkosProviderOptions` | interface | Provider descriptor options for WorkOS. |
| `WorkosCookieOptions` | interface | WorkOS cookie configuration. |
| `WorkosCookieSession` | interface | Cookie-backed WorkOS session payload. |
| `WorkosSessionClient` | interface | WorkOS session client boundary. |
| `WorkosSessionAuthenticationResult` | type alias | Authentication result returned by WorkOS session authentication. |
| `WorkosSessionRefreshResult` | type alias | Session refresh result. |

## Re-exported auth contracts

| Symbol | Kind | Description |
| --- | --- | --- |
| `AuthBackendPort` | interface | Backend adapter port implemented by `createWorkosBackend`. |
| `AuthenticatorPort` | interface | Authenticator port used by request authentication. |
| `AuthnRequest` | interface | Authentication request shape. |
| `Principal` | interface | Principal payload returned by authenticators. |
| `AuthBackendOperationUnsupportedError` | class | Error for unsupported upstream operations. |
| `InteractiveFlowPort` | interface | Interactive-flow port re-exported from the core auth package. |

Back to the [auth reference hub](https://rickylabs.github.io/netscript/reference/auth/).

_Canonical: https://rickylabs.github.io/netscript/reference/auth-workos/_

---

# Auth reference

NetScript auth is split across one plugin manifest package, one core contract package, and three backend adapters. This hub is generated from the public surfaces verified with `deno doc`.

For capability guidance, start with [Authentication](https://rickylabs.github.io/netscript/capabilities/auth/). For the runtime service builder used by auth-api, see [@netscript/service](https://rickylabs.github.io/netscript/reference/service/).

## Units

| Unit | Package | Purpose |
| --- | --- | --- |
| [plugin-auth](https://rickylabs.github.io/netscript/reference/plugin-auth/) | `@netscript/plugin-auth` | Auth plugin manifest, contribution metadata, and plugin inspection helper. |
| [plugin-auth-core](https://rickylabs.github.io/netscript/reference/plugin-auth-core/) | `@netscript/plugin-auth-core` | Auth contracts, backend ports, session schemas, stream schemas, config schemas, and telemetry primitives. |
| [auth-kv-oauth](https://rickylabs.github.io/netscript/reference/auth-kv-oauth/) | `@netscript/auth-kv-oauth` | KV-backed OAuth2/OIDC relying-party backend and provider presets. |
| [auth-workos](https://rickylabs.github.io/netscript/reference/auth-workos/) | `@netscript/auth-workos` | WorkOS-backed authenticator and backend adapter. |
| [auth-better-auth](https://rickylabs.github.io/netscript/reference/auth-better-auth/) | `@netscript/auth-better-auth` | Better Auth integration, authenticator, and backend adapter. |

## Backend adapter boundary

| Adapter | Primary factory | Notes |
| --- | --- | --- |
| KV OAuth | `createKvOAuthBackend(options)` | Uses provider configs created with `defineOAuthProvider(input)` or the exported provider presets. |
| WorkOS | `createWorkosBackend(options)` | Wraps WorkOS session and token verification behind `AuthBackendPort`. |
| Better Auth | `createBetterAuthBackend(options)` | Wraps a Better Auth instance behind `AuthBackendPort`. |

Unsupported upstream operations are represented by `AuthBackendOperationUnsupportedError` from `@netscript/plugin-auth-core`.

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/auth/_

---

# `@netscript/cli`

Public and maintainer command-line tooling for NetScript workspaces. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/cli`) exposes the embeddable, programmatic CLI surface — the helpers a host binary uses to build and run the NetScript command tree, resolve and dispatch plugin verbs, and scaffold plugin packages. Two sub-path exports carry the lower-level scaffold engine and the test fixtures:

- [`@netscript/cli/scaffolding`](#sub-path-exports) — the template/scaffold engine and filesystem ports.
- [`@netscript/cli/testing`](#sub-path-exports) — in-memory ports and fixture builders for tests.

## CLI composition

| Symbol | Signature | Description |
| --- | --- | --- |
| `createPublicCli` | `function createPublicCli(host: PublicCliHost): PublicCliCommand` | Create the public NetScript CLI command tree. |
| `runPublicCli` | `async function runPublicCli(runtime: PublicCliRuntime): Promise<void>` | Run the public CLI with consistent error formatting. |
| `inspectCli` | `function inspectCli(target: CliInspectionTarget): CliInspectionReport` | Inspect an embeddable CLI target for diagnostics. |

## Plugin host loading

| Symbol | Signature | Description |
| --- | --- | --- |
| `createPluginHostLoader` | `function createPluginHostLoader(options: PluginHostLoaderOptions): PluginHostLoaderPort` | Create a plugin host loader from structural public ports. |
| `resolvePluginManifest` | `function resolvePluginManifest(spec: string, options: ResolvePluginManifestOptions): Promise<PluginHostManifest>` | Resolve a plugin manifest by package spec. |
| `resolvePluginCliSpecifier` | `function resolvePluginCliSpecifier(pkg: string): string` | Resolve the JSR CLI specifier for a plugin package. |

## Plugin verb dispatch

| Symbol | Signature | Description |
| --- | --- | --- |
| `dispatchPluginVerb` | `function dispatchPluginVerb(verb: FrameworkVerb, pkg: string, args: readonly string[], options: DispatchPluginVerbOptions): Promise<PluginDispatchProcessResult>` | Dispatch a framework plugin verb through `deno x -A jsr:<pkg>/cli`. |
| `isFrameworkVerb` | `function isFrameworkVerb(value: string): value is FrameworkVerb` | Return whether a value is a framework-owned plugin verb. |
| `FRAMEWORK_VERBS` | `const FRAMEWORK_VERBS: readonly FrameworkVerb[]` | Framework-owned plugin verb constants. |
| `FrameworkVerb` | `type FrameworkVerb = "add" \| "remove" \| "enable" \| "disable" \| "sync" \| "setup" \| "update" \| "doctor" \| "info"` | Framework-owned plugin verbs. |

## Plugin scaffolding

| Symbol | Signature | Description |
| --- | --- | --- |
| `scaffoldPluginPackage` | `function scaffoldPluginPackage(options: PluginScaffoldOptions, dependencies: PluginScaffoldDependencies): Promise<PluginScaffoldResult>` | Scaffold a plugin package from skeleton templates. |

## Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `PublicCliHost` | interface | Host services supplied by the binary edge. |
| `PublicCliCommand` | interface | Public command tree returned by `createPublicCli`. |
| `PublicCliRuntime` | interface | Runtime hooks supplied by the public CLI binary. |
| `PluginHostManifest` | interface | Plugin manifest value returned by public host loader contracts. |
| `PluginHostLoaderOptions` | interface | Plugin host loader contracts. |
| `PluginHostState` | interface | Resolved plugin host state. |
| `PluginHostLoaderPort` | interface | Public host loader port. |
| `ResolvePluginManifestOptions` | interface | Options for resolving a plugin manifest. |
| `PluginDispatchProcessResult` | interface | Result of a public process dispatch. |
| `DispatchPluginVerbOptions` | interface | Options for dispatching a plugin verb. |
| `PluginScaffoldOptions` | interface | Options for scaffolding a plugin package. |
| `PluginScaffoldResult` | interface | Result returned after plugin package scaffolding. |
| `PluginScaffoldDependencies` | interface | Dependencies for plugin package scaffolding. |
| `CliInspectionTarget` | interface | Target accepted by `inspectCli`. |
| `CliInspectionReport` | interface | Diagnostic summary for an embeddable CLI target. |

## Sub-path exports

The following entrypoints are published alongside the root export. Their reference surface is generated separately from their own `deno doc` output.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/cli` | `./mod.ts` | Embeddable CLI composition, plugin dispatch, and scaffold helpers (documented above). |
| `@netscript/cli/scaffolding` | `./scaffolding.ts` | Plugin scaffold engine. |
| `@netscript/cli/testing` | `./testing.ts` | Test fixtures and in-memory ports. |

### `@netscript/cli/scaffolding`

The scaffold engine that walks template directories, renders `{{var | pipe}}` templates, and writes plugin-owned scaffold definitions.

| Symbol | Signature | Description |
| --- | --- | --- |
| `createPluginScaffoldContext` | `function createPluginScaffoldContext(options: PluginScaffoldContextOptions): PluginScaffoldContext` | Create a normalized plugin scaffold context. |
| `planPluginScaffoldFiles` | `async function planPluginScaffoldFiles(definition, context, dependencies): Promise<readonly PlannedPluginScaffoldFile[]>` | Render all files in a plugin scaffold definition without writing them. |
| `writePluginScaffoldFiles` | `async function writePluginScaffoldFiles(definition, context, dependencies): Promise<ScaffoldResult>` | Render and write a plugin scaffold definition. |
| `renderTemplate` | `function renderTemplate(template: string, context: Record): string` | Render a template string by replacing `{{var}}` / `{{var \| pipe}}`. |
| `Scaffolder` | class | Core scaffold engine that walks template directories and renders templates. |
| `DenoFileSystem` | class | Filesystem adapter backed by Deno APIs and `@std/fs`. |
| `MemoryFileSystemAdapter` | class | In-memory filesystem adapter for tests. |
| `StringTemplateAdapter` | class | Template adapter that uses simple `{{var \| pipe}}` string replacement. |
| `FileSystemPort` | interface | Abstraction over filesystem operations. |
| `ScaffolderPort` | interface | Core scaffolding service. |
| `TemplatePort` | interface | Abstraction over template rendering. |
| `PluginScaffoldDefinition` | interface | Plugin-owned scaffold definition. |
| `PluginScaffoldContext` | interface | Runtime context for a plugin scaffold operation. |
| `PluginScaffoldContextOptions` | interface | Options for creating a plugin scaffold context. |
| `PluginScaffoldTemplate` | interface | One template owned by a plugin package. |
| `PluginScaffoldDirectory` | interface | One directory a plugin scaffold should create. |
| `PlannedPluginScaffoldFile` | interface | Rendered file planned by a plugin scaffold operation. |
| `PluginScaffoldDependencies` | interface | Dependencies needed by plugin scaffold helpers. |
| `ScaffoldOptions` | interface | Options for a single scaffold operation. |
| `ScaffoldResult` | interface | Result of a scaffold operation. |
| `DirEntry` | interface | Entry returned by non-recursive directory reads. |
| `WalkEntry` | interface | Entry yielded by recursive directory walks. |
| `FileInfo` | interface | Metadata returned by filesystem stat operations. |

### `@netscript/cli/testing`

In-memory ports and fixture builders for exercising the CLI and scaffold pipelines in tests.

| Symbol | Signature | Description |
| --- | --- | --- |
| `createInMemoryFileSystem` | `function createInMemoryFileSystem(): MemoryFileSystemAdapter` | Create an in-memory filesystem adapter. |
| `createInMemoryProcess` | `function createInMemoryProcess(): InMemoryProcess` | Create an in-memory process port with queued results. |
| `createInMemoryPrompt` | `function createInMemoryPrompt(): PromptPort` | Create a scripted prompt port for non-interactive tests. |
| `createSilentLogger` | `function createSilentLogger(): LoggerPort` | Create a no-op logger. |
| `buildMinimalScaffoldPlan` | `function buildMinimalScaffoldPlan(): ScaffoldPlan` | Build a minimal scaffold plan fixture for tests. |
| `buildMinimalInitResult` | `function buildMinimalInitResult(): InitResult` | Build a minimal init result fixture for tests. |
| `buildMinimalPromptAnswers` | `function buildMinimalPromptAnswers(): InitPromptAnswers` | Build a minimal prompt-answer fixture for tests. |
| `buildEmptyScaffoldResult` | `function buildEmptyScaffoldResult(): ScaffoldResult` | Build an empty scaffold result fixture for tests. |
| `MemoryFileSystemAdapter` | class | In-memory filesystem adapter for tests. |
| `DbEngine` | type alias | Database engines that have scaffolded workspace support (`"postgres" \| "mysql" \| "mssql" \| "sqlite"`). |
| `DbEngineChoice` | type alias | Database engine selection accepted by init, including the no-database option (`DbEngine \| "none"`). |
| `EditorChoice` | type alias | Optional editor config scaffolded into the workspace root (`"none" \| "zed" \| "vscode"`). |
| `InitPromptAnswers` | interface | Answers collected from interactive prompts during `init`. |
| `InitResult` | interface | Aggregated result of the full `init` pipeline execution. |
| `ScaffoldPlan` | interface | Public scaffold plan derived from validated init options. |
| `ScaffoldServicePlan` | interface | Example service requested for the generated workspace. |
| `LoggerPort` | interface | Structured logger abstraction. |
| `ProcessPort` | interface | Process execution abstraction. |
| `ProcessResult` | interface | Result of an external process invocation. |
| `PromptPort` | interface | User prompt abstraction. |
| `InMemoryProcess` | interface | In-memory process port with deterministic queued results. |
| `RecordedProcessCall` | interface | One recorded in-memory process invocation. |
| `PromptScript` | interface | Scripted answers used by the in-memory prompt port. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/cli/_

---

# `netscript` command reference

The complete verb-and-flag surface of the published `netscript` binary (`@netscript/cli`). The [CLI reference](https://rickylabs.github.io/netscript/cli-reference/) is the curated tour of the everyday path; this page is the exhaustive companion — every command group, subcommand, and flag, spelled exactly as the installed CLI prints it. For the generated package API surface (the embeddable helpers, not the command tree) see the [`@netscript/cli` package page](https://rickylabs.github.io/netscript/reference/cli/).

This page documents the **public `netscript` binary** — the CLI published as `@netscript/cli` and installed on your PATH — not any maintainer-only tree. Everything here is verified against `netscript <group> --help`. To confirm the exact spelling in your installed version, run `netscript --help` or `netscript <group> --help`.

The top-level groups are `agent`, `config`, `deploy`, `init`, `contract`, `db`, `generate`, `marketplace`, `plugin`, `service`, and the `ui:*` commands — each has a section below.

## `init` — scaffold a workspace

`netscript init [name]` scaffolds a new NetScript workspace. The everyday walk-through is in the [quickstart](https://rickylabs.github.io/netscript/quickstart/); every flag is:

| Flag | Description |
| --- | --- |
| `--app-name <name>` | Frontend application name (kebab-case). |
| `--db <engine>` | Database engine: `postgres`, `mysql`, `mssql`, `sqlite`, or `none`. |
| `--service [enabled]` | Scaffold an example oRPC service. |
| `--service-name <name>` | Example service name. |
| `--model-name <name>` | Prisma model name for the scaffolded CRUD surface. |
| `--service-port <port>` | Example service port. |
| `--cache [enabled]` | Scaffold a shared cache resource. |
| `--cache-backend <backend>` | Shared cache backend: `redis`, `garnet`, or `deno-kv`. |
| `--editor <editor>` | Editor config: `none`, `zed`, or `vscode`. |
| `--no-aspire` | Skip the Aspire orchestration layer. |
| `--no-git` | Skip `git init` after scaffolding. |
| `--force` | Overwrite an existing target directory (default `false`). |
| `--ci` | Non-interactive mode (default `false`). |
| `-y, --yes` | Accept defaults without prompting (default `false`). |
| `--path <path>` | Target directory for scaffold output. |
| `--dry-run` | Preview the scaffold plan without writing files (default `false`). |
| `--json` | Emit a single machine-readable JSON result (default `false`). |
| `--from <preset>` | Apply a named scaffold preset. |

## `agent` — install and run agent tooling

`netscript agent` installs and runs the shared CLI × skills × MCP tooling. See [Agent tooling](https://rickylabs.github.io/netscript/ai/agent-tooling/) for the mental model and the [`@netscript/mcp` reference](https://rickylabs.github.io/netscript/reference/mcp/) for the server's tool surface.

| Command | Description |
| --- | --- |
| `netscript agent init` | Install NetScript MCP and skills for detected agent hosts. The Claude Code host path writes `.mcp.json`, installs the `netscript` / `netscript-build` / `netscript-operate` skills under `.claude/skills/`, and updates the marked NetScript section in `AGENTS.md`; the VS Code host path writes `.vscode/mcp.json` only. Flag: `--host <host>` (`claude`, `vscode`, or `all` — `all` runs both host paths). |
| `netscript agent mcp` | Start the NetScript MCP server over standard input/output. Flags: `--endpoint <url>` (telemetry endpoint), `--project-root <path>`, `--docs-root <path>` (public documentation root). |

## `config` — inspect and mutate configuration

`netscript config` reads and writes the resolved project configuration and manages runtime overrides.

| Command | Description |
| --- | --- |
| `netscript config inspect` | Inspect the resolved project configuration. Flags: `--project-root <path>`, `--json` (emit the JSON-stable inspection report). |
| `netscript config get <path>` | Read a resolved configuration value. Flags: `--project-root <path>`, `--json`. |
| `netscript config set <path> <value>` | Set a generated `appsettings` configuration value. Flag: `--project-root <path>`. |
| `netscript config override <sub>` | Manage runtime overrides (see below). |
| `netscript config runtime <sub>` | Compatibility lifecycle aliases for runtime override snapshots — carries the `publish` and `rollback` subcommands only. |

### `config override` subcommands

| Command | Description |
| --- | --- |
| `netscript config override publish <topic> <file>` | Publish and atomically activate a versioned runtime topic file. Flag: `--version <version>` (defaults to the source filename). |
| `netscript config override rollback <topic> <version>` | Atomically point a runtime topic at an existing version. |
| `netscript config override list` | List active versions and payloads. |
| `netscript config override get <path>` | Read an override value at `<path>`. |
| `netscript config override set <path> [value]` | Set an override value. Flag: `--rollout <percent>`. |
| `netscript config override clear <path> [value]` | Clear an override value. Flag: `--rollout <percent>`. |
| `netscript config override enable <path> [value]` | Enable an override. Flag: `--rollout <percent>`. |
| `netscript config override disable <path> [value]` | Disable an override. Flag: `--rollout <percent>`. |

`netscript config runtime publish <topic> <file>` and `netscript config runtime rollback <topic> <version>` are lifecycle aliases for the matching `config override` verbs.

## `marketplace` — discover and publish plugins

| Command | Description |
| --- | --- |
| `netscript marketplace search <query>` | Search the NetScript plugin marketplace. |
| `netscript marketplace publish` | Publish a NetScript plugin to the marketplace. |

## `generate` — code generation

Beyond `generate plugins` and `generate runtime-schemas` (covered in the [CLI reference](https://rickylabs.github.io/netscript/cli-reference/#code-generation)), the group also regenerates the Aspire helper layer.

| Command | Description |
| --- | --- |
| `netscript generate aspire` | Regenerate Aspire AppHost helpers from `appsettings.json`. Flag: `--project-root <path>`. |
| `netscript generate runtime-schemas` | Generate JSON Schema files for runtime config topics. Flags: `--project-root <path>`, `--dry-run`, `--force`, `--verbose`. |
| `netscript generate plugins` | Generate plugin registries from project source. Flags: `--project-root <path>`, `--dry-run`, `--verbose`. |

## `plugin` — extended verbs

The common `plugin` verbs (`install`, `new`, `list`, `doctor`, `info`, `remove`) are in the [CLI reference](https://rickylabs.github.io/netscript/cli-reference/#plugins). The full group also carries:

| Command | Description |
| --- | --- |
| `netscript plugin scaffold <name>` | Scaffold a NetScript plugin package. Flags: `--target <path>`, `--project-root <path>`, `--force`. |
| `netscript plugin sync` | Synchronize plugin contributions and generated registries. Flag: `--project-root <path>`. |
| `netscript plugin update <name>` | Re-pin and regenerate an installed plugin. Flag: `--project-root <path>`. |
| `netscript plugin item-add <name> <item> [args...]` | Scaffold an item with a custom plugin. Flag: `--project-root <path>`. |
| `netscript plugin enable <pkg> [args...]` | Run a plugin's published `enable` command. Flag: `--project-root <path>`. |
| `netscript plugin disable <pkg> [args...]` | Run a plugin's published `disable` command. Flag: `--project-root <path>`. |
| `netscript plugin setup <pkg> [args...]` | Run a plugin's published `setup` command. Flag: `--project-root <path>`. |
| `netscript plugin auth <sub>` | Configure auth and manage sessions (see below). |

### `plugin auth` subcommands

| Command | Description |
| --- | --- |
| `netscript plugin auth backend set <backend>` | Select the active auth backend. Flag: `--project-root <path>`. |
| `netscript plugin auth backend show` | Show the currently selected auth backend. Flag: `--project-root <path>`. |
| `netscript plugin auth provider set` | Configure an auth provider. Flags: `--preset <preset>`, `--client-id <id>`, `--client-secret <secret>`, `--redirect-uri <uri>`, `--issuer <issuer>`, `--api-key <key>`, `--cookie-password <password>`, `--secret <secret>`, `--kv-oauth-key <key>`, `--project-root <path>`. |
| `netscript plugin auth secret generate [kind]` | Generate auth secret material. |
| `netscript plugin auth session list` | List auth sessions. Flag: `--stream-url <url>`. |
| `netscript plugin auth session revoke <id>` | Revoke an auth session by id. Flag: `--auth-url <url>`. |

The backends selectable here are the same ones read at runtime by `NETSCRIPT_AUTH_BACKEND` — see [add authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/).

## `service` — extended verbs

The common `service add`, `service list`, and `service generate` verbs are in the [CLI reference](https://rickylabs.github.io/netscript/cli-reference/#services--contracts). The full group also carries:

| Command | Description |
| --- | --- |
| `netscript service add` | Add a service workspace, v1 contract, and Aspire registration. Flags: `--name <name>` (kebab-case), `--port <port>`, `--refs <refs>` (comma-separated service references), `--project-root <path>`, `--force`, `--with-client` (scaffold app-workspace client and query helpers). |
| `netscript service set <name>` | Update an existing service and regenerate Aspire helpers. Flags: `--port <port>`, `--enabled <enabled>`, `--project-root <path>`. |
| `netscript service remove <name>` | Remove a service workspace and reverse its registrations. Flags: `--keep-contract` (retain paired contract files), `--project-root <path>`. |
| `netscript service add-handler <service> <procedure>` | Bind a contract procedure with a compiling service handler stub. Flags: `--version <version>` (default `v1`), `--project-root <path>`. |
| `netscript service ref add <caller> <callee>` | Add a service reference from `<caller>` to `<callee>`. Flag: `--project-root <path>`. |
| `netscript service ref remove <caller> <callee>` | Remove a service reference. Flag: `--project-root <path>`. |

## `contract` — extended verbs

The common `contract add` and `contract list` verbs are in the [CLI reference](https://rickylabs.github.io/netscript/cli-reference/#contracts). The full group also carries:

| Command | Description |
| --- | --- |
| `netscript contract add-route <contract> <procedure> --method <method> --path <route>` | Append a typed oRPC procedure to a contract. Required flags: `--method <method>`, `--path <route>`. Optional: `--input <schema>`, `--output <schema>`, `--version <version>` (default `v1`), `--project-root <path>`. |
| `netscript contract inspect <name>` | Inspect contract procedures and schema expressions. Flags: `--version <version>` (default `v1`), `--json`, `--path <path>`. |
| `netscript contract remove <name>` | Remove a contract and regenerate version aggregates. Flags: `--version <version>` (remove only the named version), `--path <path>`. |
| `netscript contract version add <name> --from <version> --to <version>` | Promote a contract into a new version directory. Required flags: `--from <version>`, `--to <version>`. Optional: `--path <path>`, `--force`. |

## `db` — extended verbs

The everyday database workflow (`init`, `generate`, `migrate`, `seed`, `status`, `studio`, `introspect`, `reset`) is in the [CLI reference](https://rickylabs.github.io/netscript/cli-reference/#database) — and all `db` commands require Aspire to be running (`cd aspire && aspire start`) unless you scaffolded a file-backed `sqlite` engine. The full group also carries the target-management and migration-history verbs:

| Command | Description |
| --- | --- |
| `netscript db add <engine>` | Add a database workspace to an existing project. `<engine>` is `postgres`, `mysql`, `mssql`, or `sqlite`. Flags: `--name <key>` (config key), `--project-root <path>`, `--force`. |
| `netscript db list` | List registered database targets. Flags: `--project-root <path>`, `--json`. |
| `netscript db remove <configKey>` | Deregister a database target. Flags: `--project-root <path>`, `--purge` (delete the workspace when no target still uses it). |
| `netscript db deploy` | Apply pending migrations without creating one. Flags: `--db <target>` (config key, database name, or `all`), `--project-root <path>`. |
| `netscript db validate` | Validate database schemas. Flags: `--db <target>`, `--project-root <path>`. |
| `netscript db resolve` | Resolve migration history state. Flags: `--db <target>`, `--project-root <path>`, `--applied <migration>` (mark as applied), `--rolled-back <migration>` (mark as rolled back). |

## `ui:*` — Fresh UI registry

`ui:init` and `ui:add` are in the [CLI reference](https://rickylabs.github.io/netscript/cli-reference/#fresh-ui). The full set also lists, updates, and removes copied registry items:

| Command | Description |
| --- | --- |
| `netscript ui:list` | List Fresh UI registry items. Flags: `--project-root <path>`, `--json`, `--collections` (include collections). |
| `netscript ui:update [name]` | Update unmodified Fresh UI registry files. Flag: `--project-root <path>`. |
| `netscript ui:remove <name>` | Remove a copied Fresh UI registry item. Flag: `--project-root <path>`. |

Because Fresh UI is copy-source, `ui:update` only touches registry files you have not modified — your edits are never overwritten. See [customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/).

## `deploy` — cloud and container targets

The [CLI reference](https://rickylabs.github.io/netscript/cli-reference/#deploy) covers the wired Deno Deploy and Windows Service (Servy) paths. The `deploy` group also exposes a family of cloud and container targets, plus artifact-copy and log verbs.

### Cloud and container targets

Each target below shares the same three-verb lifecycle — `plan`, `up`, `down`:

| Command group | Description |
| --- | --- |
| `netscript deploy kubernetes <verb>` | Manage the Kubernetes deployment target. |
| `netscript deploy azure-aca <verb>` | Manage the Azure Container Apps deployment target. |
| `netscript deploy azure-app-service <verb>` | Manage the Azure App Service deployment target. |
| `netscript deploy azure-aks <verb>` | Manage the Azure Kubernetes Service deployment target. |
| `netscript deploy cloud-run <verb>` | Manage the Google Cloud Run deployment target. |

The three lifecycle verbs are:

| Verb | Description |
| --- | --- |
| `plan` | Emit or preflight deployment artifacts. |
| `up` | Bring the deployment up. |
| `down` | Bring the deployment down. |

Every verb on every target shares the same flags: `--project-root <dir>`, `--output-dir <dir>` (directory for emitted deployment artifacts), `--environment <name>` (deployment environment passed to the target), `--clear-cache` (clear target deployment state and do not persist new values), and `--non-interactive`.

### Artifact copy, logs, and upgrade

| Command | Description |
| --- | --- |
| `netscript deploy copy` | Copy build artifacts to the install directory (no Servy registration). Flags: `--deploy-dir <path>` (default `./.deploy/windows`), `--install-dir <path>` (default auto-resolved from the manifest), `--verbose`, `--dry-run`. |
| `netscript deploy logs <service>` | Show recent logs for a service. Flags: `--install-dir <dir>`, `--deploy-dir <dir>` (default `./.deploy/windows`), `-n, --lines <n>` (default 50), `--errors` (show the error log instead of stdout), `--list` (list available log files), `-f, --follow` (tail the log). |
| `netscript deploy upgrade` | Build, sync, reinstall, and restart services in one step. Flags: `--deploy-dir <path>` (default `./.deploy/windows`), `--install-dir <path>`, `--servy-cli <path>`, `--skip-compile`, `--skip-install`, `--skip-start`, `--verbose`, `--dry-run`. |

_Canonical: https://rickylabs.github.io/netscript/reference/cli/commands/_

---

# `@netscript/config`

Typed NetScript project configuration: schemas, loaders, environment helpers, workspace discovery, diagnostics, and scaffold constants. This page is generated from the package public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/config`) exposes the authoring, loading, environment, workspace, and diagnostic contract. The usual path is to define a project config once with `defineConfig` in `netscript.config.ts`, load it at process startup with `initConfig`, and read the validated `NetScriptConfig` synchronously with `getConfig`. Schema-only APIs live on sub-paths so the public root surface does not leak Zod internals:

- [`@netscript/config/merge`](#sub-path-config-merge) merges plugin-contributed partial config fragments.
- [`@netscript/config/paths`](#sub-path-config-paths) exposes scaffold directory, file, and permission constants.
- [`@netscript/config/schema/plugins`](#sub-path-config-schema-plugins) exposes appsettings plugin-entry validation schemas.

## Authoring

| Symbol | Signature | Description |
| --- | --- | --- |
| `defineConfig` | `function defineConfig(config: NetScriptConfigInput): NetScriptConfig` | Type-safe configuration definition with validation. |
| `defineConfigAsync` | `function defineConfigAsync(configFn): () => Promise<NetScriptConfig>` | Configuration definition for async/environment-based configs. |
| `defineSagas` | `function defineSagas(config: SagasConfigInput): SagasConfigInput` | Define a split saga config module. |

## Loading and runtime cache

| Symbol | Signature | Description |
| --- | --- | --- |
| `loadConfig` | `async function loadConfig(options?: LoadConfigOptions): Promise<NetScriptConfig>` | Load and validate a NetScript configuration file. |
| `initConfig` | `async function initConfig(options?: LoadConfigOptions): Promise<NetScriptConfig>` | Initialize and cache the configuration. |
| `getConfig` | `function getConfig(): NetScriptConfig` | Get the cached configuration synchronously after initialization. |
| `isConfigLoaded` | `function isConfigLoaded(): boolean` | Check whether configuration has been loaded. |
| `clearConfigCache` | `function clearConfigCache(): void` | Clear the cached configuration. |

## Environment

| Symbol | Signature | Description |
| --- | --- | --- |
| `getEnv` | `function getEnv<T extends EnvDef>(name: string, options?: T): ResolvedEnvType<T>` | Get a single environment variable with type coercion. |
| `resolveEnv` | `function resolveEnv<T extends Record<string, EnvDef>>(schema: T)` | Resolve environment variables with type coercion and defaults. |
| `hasEnv` | `function hasEnv(name: string): boolean` | Check if an environment variable is set. |
| `getMode` | `function getMode(): "development" \| "production" \| "test"` | Get the current environment mode. |
| `isDev` | `function isDev(): boolean` | Check if running in development mode. |
| `isProd` | `function isProd(): boolean` | Check if running in production mode. |
| `isTest` | `function isTest(): boolean` | Check if running in test mode. |

## Workspace discovery

| Symbol | Signature | Description |
| --- | --- | --- |
| `discoverWorkspace` | `async function discoverWorkspace(rootDir?: string): Promise<WorkspaceMap>` | Discover and classify Deno workspace members. |
| `findWorkspaceRoot` | `async function findWorkspaceRoot(startDir: string): Promise<string>` | Find the nearest Deno workspace root from a starting directory. |
| `findMember` | `function findMember(workspace: WorkspaceMap, memberName: string): WorkspaceMember \| undefined` | Find a workspace member by package name or relative path. |
| `getMemberEntrypoint` | `function getMemberEntrypoint(member: WorkspaceMember): string` | Resolve the default entrypoint for a workspace member. |

## Diagnostics

| Symbol | Signature | Description |
| --- | --- | --- |
| `inspectConfig` | `function inspectConfig(target): InspectionReport` | Inspect a config target and return a JSON-stable diagnostic report. |

## Types

Core authoring/validation contract and per-section configuration shapes exported from the root.

| Symbol | Kind | Description |
| --- | --- | --- |
| `NetScriptConfig` | interface | Fully validated NetScript configuration. |
| `NetScriptConfigInput` | interface | Authoring form accepted by `defineConfig` and `loadConfig`. |
| `ConfigEnv` | interface | Environment context provided to async config functions. |
| `LoadConfigOptions` | interface | Options for loading configuration files. |
| `InspectionReport` | interface | JSON-stable diagnostic report returned by config inspectors. |
| `EnvDef` | interface | Environment variable definition for `resolveEnv`. |
| `ResolvedEnvType` | type alias | Resolved environment variable type based on an `EnvDef`. |
| `ServiceConfig` | interface | Service configuration definition. |
| `AppConfig` | interface | Frontend application configuration definition. |
| `DatabaseConfig` | interface | Database configuration definition. |
| `DatabasesConfig` | interface | Database section with optional active provider selector. |
| `DatabaseProvider` | type alias | Database provider accepted by project configuration. |
| `GatewayConfig` | interface | Gateway configuration section. |
| `LoggingConfig` | interface | Logging configuration used by runtime and CLI entrypoints. |
| `PathsConfig` | interface | Workspace-aware path conventions used by CLI and generators. |
| `SdkConfig` | interface | SDK generation configuration section. |
| `AspireConfig` | interface | Aspire orchestration settings for generated AppHost projects. |
| `DeployConfig` | interface | Top-level deployment configuration type. |
| `WindowsDeployConfig` | interface | Windows-specific deployment configuration type. |
| `WebhookConfig` | interface | Webhook configuration type. |
| `PermissionConfig` | interface | Permission flags for jobs and task execution. |
| `PermissionValue` | type alias | Permission value accepted by Deno-style runtime permission fields. |
| `RuntimeConfigSection` | interface | Runtime schema/config section type. |
| `RuntimeConfigPathEntry` | interface | Runtime schema/config output path entry type. |
| `WorkspaceMap` | interface | Classified snapshot of a Deno workspace. |
| `WorkspaceMember` | interface | Deno workspace member discovered from a member deno.json file. |
| `WorkspaceMemberType` | type alias | Workspace member category inferred from its relative path. |

### Sagas and triggers section types

The `sagas` and `triggers` configuration sections have dedicated validated and authoring-form types exported from the root.

| Symbol | Kind | Description |
| --- | --- | --- |
| `SagasConfig` | interface | Sagas configuration section. |
| `SagasConfigInput` | interface | Authoring form for split saga config files. |
| `SagaGroup` | interface | Saga group configuration for a topic. |
| `SagaGroupInput` | interface | Authoring form for a saga group. |
| `SagaDefinition` | interface | Saga definition configuration. |
| `SagaDefinitionInput` | interface | Authoring form for a saga definition. |
| `SagaRetryConfig` | interface | Saga retry configuration. |
| `SagaTimeoutConfig` | interface | Saga timeout configuration. |
| `SagaScalingConfig` | interface | Per-topic saga scaling configuration. |
| `SagaRetentionConfig` | interface | Per-topic saga retention configuration. |
| `SagaStoreProvider` | type alias | Saga store backend provider selector. |
| `SagaTransportProvider` | type alias | Saga transport backend provider selector. |
| `TriggersConfig` | interface | Triggers configuration section. |
| `TriggersConfigInput` | interface | Authoring form for trigger config. |
| `TriggerGroup` | interface | Trigger group type. |
| `TriggerGroupInput` | type alias | Authoring form for a trigger group. |
| `TriggerDefinitionConfig` | interface | Trigger definition config type. |
| `TriggerDefinitionConfigInput` | type alias | Authoring form for a trigger definition. |
| `TriggerScalingConfig` | interface | Trigger group scaling configuration. |
| `TriggerRetentionConfig` | interface | Trigger group retention configuration. |

## Sub-path exports

The following entrypoints are published alongside the root export.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/config` | `./mod.ts` | Core configuration surface (documented above). |
| `@netscript/config/merge` | `./src/merge/mod.ts` | Merge plugin-contributed partial config fragments. |
| `@netscript/config/paths` | `./src/paths/mod.ts` | Scaffold directory, file, and permission constants. |
| `@netscript/config/schema/plugins` | `./src/schema/plugins/mod.ts` | Appsettings plugin-entry validation schemas. |

### `@netscript/config/merge`

Folds a plugin-contributed partial config fragment into an already-validated project config.

| Symbol | Signature | Description |
| --- | --- | --- |
| `mergePartialConfig` | `function mergePartialConfig(base: NetScriptConfig, contribution: PartialConfig): NetScriptConfig` | Merge a plugin-contributed partial config into a validated NetScript config. |

| Symbol | Kind | Description |
| --- | --- | --- |
| `PartialConfig` | interface | Partial NetScript config fragment contributed by a plugin manifest. |
| `AppContributionEntry` | type alias | Application config entry accepted in plugin contribution fragments. |
| `ServiceContributionEntry` | type alias | Service config entry accepted in plugin contribution fragments. |
| `DatabaseEntry` | type alias | Database config entry accepted in plugin contribution fragments. |

This entrypoint also re-exports the shared section types (`NetScriptConfig`, `ServiceConfig`, `DatabaseConfig`, the saga/trigger config types, and related shapes) documented under the root [Types](#types) section.

### `@netscript/config/paths`

Standard scaffold constants consumed by NetScript generators and CLI commands.

| Symbol | Signature | Description |
| --- | --- | --- |
| `PERMISSIONS` | `const PERMISSIONS: PermissionGroups` | Standard Deno permission flags grouped by intent. |
| `SCAFFOLD_DIRS` | `const SCAFFOLD_DIRS: ScaffoldDirs` | Standard scaffold directory names. |
| `SCAFFOLD_FILES` | `const SCAFFOLD_FILES: ScaffoldFiles` | Standard scaffold file names. |

| Symbol | Kind | Description |
| --- | --- | --- |
| `PermissionGroups` | interface | Standard Deno permission groups used by generated package commands. |
| `ScaffoldDirs` | interface | Standard scaffold directory names used by NetScript generators. |
| `ScaffoldFiles` | interface | Standard scaffold file names used by NetScript generators. |

### `@netscript/config/schema/plugins`

Validation schemas for plugin-backed entries written into generated appsettings.json.

| Symbol | Signature | Description |
| --- | --- | --- |
| `pluginEntrySchema` | `const pluginEntrySchema: PluginSettingsSchema<PluginEntry>` | Validates a NetScript.Plugins. appsettings entry. |
| `backgroundProcessorEntrySchema` | `const backgroundProcessorEntrySchema: PluginSettingsSchema<BackgroundProcessorEntry>` | Validates a NetScript.BackgroundProcessors. appsettings entry. |
| `installedVersionSchema` | `const installedVersionSchema: PluginSettingsSchema<InstalledVersionFields>` | Validates installed plugin version metadata stored on appsettings entries. |

| Symbol | Kind | Description |
| --- | --- | --- |
| `PluginEntry` | interface | Configuration for a plugin-backed HTTP service in appsettings.json. |
| `BackgroundProcessorEntry` | interface | Configuration for a plugin-backed background processor in appsettings.json. |
| `InstalledVersionFields` | interface | Installed plugin version fields stored in appsettings.json. |
| `PluginSettingsSchema` | interface | Minimal public validation contract for plugin appsettings schemas. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/config/_

---

# `@netscript/contracts`

Contract vocabulary shared across NetScript package and plugin boundaries: the oRPC base contract, common error data, pagination schemas, result types, and schema helper factories. Because a contract's input schema is enforced at the transport boundary, a service handler never hand-parses or validates `req.json()` — a request that doesn't match the schema is rejected before your code runs, and the same contract types the client that calls it. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/contracts`) carries the core contract primitives. Three sub-path exports add higher-level builders:

- [`@netscript/contracts/crud`](#sub-path-exports) — CRUD contract generators.
- [`@netscript/contracts/query`](#sub-path-exports) — query, filter, and pagination helpers.
- [`@netscript/contracts/transform`](#sub-path-exports) — typed transformer factories.

## Base contract

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `baseContract` | const | `const baseContract: BaseContract` | Common oRPC contract primitive with NetScript's standard error map applied. |
| `BaseContract` | type alias | `type BaseContract = Readonly<{ route(options): BaseContractRouteBuilder; }>` | Common oRPC contract primitive with NetScript's standard error map applied. |
| `BaseContractRouteOptions` | type alias | `type BaseContractRouteOptions = Readonly<{ method: "HEAD" \| "GET" \| "POST" \| "PUT" \| "DELETE" \| "PATCH"; path: string; }>` | HTTP route options accepted by the base contract. |
| `BaseContractRouteBuilder` | type alias | `type BaseContractRouteBuilder = Readonly<{ input(schema); output(schema); }>` | Builder returned after binding a route to the base contract. |
| `BaseContractOutputBuilder` | type alias | `type BaseContractOutputBuilder<TInput> = Readonly<{ output(schema): BaseContractProcedure; }>` | Builder returned after binding input to the base contract. |
| `BaseContractProcedure` | type alias | `type BaseContractProcedure = Readonly<{ ~orpc: any; }>` | Opaque procedure returned by oRPC after contract composition. |

## Schema helper factories

| Symbol | Signature | Description |
| --- | --- | --- |
| `boundedString` | `function boundedString(options: BoundedStringSchemaOptions): ContractStringSchema` | Creates a bounded string schema. |
| `positiveInt` | `function positiveInt(options: IntegerSchemaOptions): ContractNumberSchema` | Creates a positive integer schema with NetScript's default integer cap. |
| `nonNegativeInt` | `function nonNegativeInt(options: IntegerSchemaOptions): ContractNumberSchema` | Creates a non-negative integer schema with NetScript's default integer cap. |
| `positiveNumber` | `function positiveNumber(options: StringSchemaOptions): ContractNumberSchema` | Creates a positive decimal-number schema. |
| `nonNegativeNumber` | `function nonNegativeNumber(options: StringSchemaOptions): ContractNumberSchema` | Creates a non-negative decimal-number schema. |
| `paginationLimit` | `function paginationLimit(options: DefaultedIntegerSchemaOptions): ContractNumberSchema` | Creates a defaulted pagination-limit schema. |
| `paginationOffset` | `function paginationOffset(options: DefaultedIntegerSchemaOptions): ContractNumberSchema` | Creates a defaulted pagination-offset schema. |
| `stringToInt` | `function stringToInt(outputSchema: ContractDefaultableSchema<number>): ContractSchema<number>` | Coerces an integer string into a number and validates it with `outputSchema`. |
| `stringToNumber` | `function stringToNumber(outputSchema: ContractDefaultableSchema<number>): ContractSchema<number>` | Coerces a numeric string into a number and validates it with `outputSchema`. |

## Errors

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `notFound` | function | `function notFound(options: NotFoundOptions): never` | Throws the contract `NOT_FOUND` oRPC error with inferred resource context. |
| `getResourceType` | function | `function getResourceType(options: { path?: readonly string[]; }): string` | Resolves a singular resource name from an oRPC handler path. |
| `COMMON_ERROR_CODES` | const | `const COMMON_ERROR_CODES: Readonly<{ notFound; validationError; unauthorized; forbidden; rateLimited; serviceUnavailable; }>` | Common oRPC error codes shared by NetScript service contracts. |
| `NotFoundErrorSchema` | const | `const NotFoundErrorSchema: ContractSchema<NotFoundError>` | Common not-found error schema. |
| `ValidationErrorSchema` | const | `const ValidationErrorSchema: ContractSchema<ValidationError>` | Common validation error schema. |
| `UnauthorizedErrorSchema` | const | `const UnauthorizedErrorSchema: ContractSchema<UnauthorizedError>` | Common unauthorized error schema. |
| `ForbiddenErrorSchema` | const | `const ForbiddenErrorSchema: ContractSchema<ForbiddenError>` | Common forbidden error schema. |
| `RateLimitErrorSchema` | const | `const RateLimitErrorSchema: ContractSchema<RateLimitError>` | Common rate-limit error schema. |
| `ServiceUnavailableErrorSchema` | const | `const ServiceUnavailableErrorSchema: ContractSchema<ServiceUnavailableError>` | Common service-unavailable error schema. |
| `SuccessSchema` | const | `const SuccessSchema: ContractSchema<SuccessResponse>` | Common success response schema. |

## Pagination schemas

| Symbol | Signature | Description |
| --- | --- | --- |
| `OffsetPaginationQuerySchema` | `const OffsetPaginationQuerySchema: ContractObjectSchema<OffsetPaginationQuery>` | Offset pagination schema for URL query parameters. |
| `OffsetPaginationInputSchema` | `const OffsetPaginationInputSchema: ContractObjectSchema<OffsetPaginationInput>` | Offset pagination schema for request bodies. |
| `OffsetPaginationMetaSchema` | `const OffsetPaginationMetaSchema: ContractObjectSchema<OffsetPaginationMeta>` | Offset pagination metadata schema for responses. |
| `CursorPaginationQuerySchema` | `const CursorPaginationQuerySchema: ContractObjectSchema<CursorPaginationQuery>` | Cursor pagination schema for URL query parameters. |
| `CursorPaginationInputSchema` | `const CursorPaginationInputSchema: ContractObjectSchema<CursorPaginationInput>` | Cursor pagination schema for request bodies. |
| `CursorPaginationMetaSchema` | `const CursorPaginationMetaSchema: ContractObjectSchema<CursorPaginationMeta>` | Cursor pagination metadata schema for responses. |

## Constants

| Symbol | Value | Description |
| --- | --- | --- |
| `DEFAULT_INTEGER_MAX` | `2147483647` | Maximum integer used by contract numeric schemas. |
| `DEFAULT_PAGINATION_LIMIT` | `10` | Default page size for contract pagination schemas. |
| `DEFAULT_PAGINATION_LIMIT_MAX` | `1000` | Maximum page size accepted by contract pagination schemas. |
| `DEFAULT_PAGINATION_OFFSET` | `0` | Default offset for contract offset-pagination schemas. |

## Diagnostics

| Symbol | Signature | Description |
| --- | --- | --- |
| `inspectContracts` | `function inspectContracts(target: ContractsInspectionTarget): InspectionReport` | Builds a JSON-stable inspection report for a contract primitive. |

## Result and error types

| Symbol | Signature | Description |
| --- | --- | --- |
| `Result` | `type Result<TValue, TError> = OkResult<TValue> \| ErrorResult<TError>` | Discriminated success/error result union. |
| `OkResult` | `type OkResult<TValue> = Readonly<{ ok: true; value: TValue; }>` | Success arm of `Result`. |
| `ErrorResult` | `type ErrorResult<TError> = Readonly<{ ok: false; error: TError; }>` | Error arm of `Result`. |
| `SuccessResponse` | `type SuccessResponse = Readonly<{ success: boolean; message?: string; }>` | Common success response payload. |
| `NotFoundError` | `type NotFoundError = Readonly<{ resourceType: string; resourceId: string \| number; }>` | Not-found error data. |
| `ValidationError` | `type ValidationError = Readonly<{ formErrors: string[]; fieldErrors: Record<string, string[] \| undefined>; }>` | Validation error data. |
| `UnauthorizedError` | `type UnauthorizedError = Readonly<{ reason?: "missing_token" \| "invalid_token" \| "expired_token"; }>` | Unauthorized error data. |
| `ForbiddenError` | `type ForbiddenError = Readonly<{ requiredRole?: string; userRole?: string; }>` | Forbidden error data. |
| `RateLimitError` | `type RateLimitError = Readonly<{ retryAfter: number; limit: number; }>` | Rate-limit error data. |
| `ServiceUnavailableError` | `type ServiceUnavailableError = Readonly<{ retryAfter?: number; reason?: string; }>` | Service-unavailable error data. |

## Schema and pagination types

| Symbol | Signature | Description |
| --- | --- | --- |
| `ContractSchema` | `type ContractSchema<TOutput = unknown>` | Minimal schema contract (`parse`, `safeParse`, `optional`, `describe`). |
| `ContractObjectSchema` | `type ContractObjectSchema<TOutput = unknown>` | Object schema contract with `extend`/`merge`. |
| `ContractDefaultableSchema` | `type ContractDefaultableSchema<TOutput>` | Schema contract with a `default(value)` helper. |
| `ContractNumberSchema` | `type ContractNumberSchema = ContractDefaultableSchema<number>` | Numeric schema contract. |
| `ContractStringSchema` | `type ContractStringSchema = ContractDefaultableSchema<string>` | String schema contract. |
| `ContractParseResult` | `type ContractParseResult<TOutput>` | Result returned by `safeParse`. |
| `OffsetPaginationQuery` | `type OffsetPaginationQuery = Readonly<{ limit: number; offset: number; }>` | Offset pagination query shape. |
| `OffsetPaginationInput` | `type OffsetPaginationInput = Readonly<{ limit: number; offset: number; }>` | Offset pagination input shape. |
| `OffsetPaginationMeta` | `type OffsetPaginationMeta = Readonly<{ total: number; limit: number; offset: number; hasMore: boolean; }>` | Offset pagination response metadata. |
| `CursorPaginationQuery` | `type CursorPaginationQuery = Readonly<{ limit: number; cursor?: string; }>` | Cursor pagination query shape. |
| `CursorPaginationInput` | `type CursorPaginationInput = Readonly<{ limit: number; cursor?: string; }>` | Cursor pagination input shape. |
| `CursorPaginationMeta` | `type CursorPaginationMeta = Readonly<{ limit: number; nextCursor: string \| null; hasMore: boolean; }>` | Cursor pagination response metadata. |

## Schema option types

| Symbol | Signature | Description |
| --- | --- | --- |
| `StringSchemaOptions` | `type StringSchemaOptions = Readonly<{ description?: string; }>` | Options for string-derived schema factories. |
| `BoundedStringSchemaOptions` | `type BoundedStringSchemaOptions = StringSchemaOptions & Readonly<{ min?: number; max: number; }>` | Options for `boundedString`. |
| `IntegerSchemaOptions` | `type IntegerSchemaOptions = Readonly<{ min?: number; max?: number; description?: string; }>` | Options for integer schema factories. |
| `DefaultedIntegerSchemaOptions` | `type DefaultedIntegerSchemaOptions = IntegerSchemaOptions & Readonly<{ default?: number; }>` | Options for defaulted integer factories. |
| `NotFoundOptions` | `type NotFoundOptions = Readonly<{ errors: unknown; path?: readonly string[]; resourceId?: string \| number; message?: string; }>` | Options accepted by `notFound`. |
| `ContractsInspectionTarget` | `type ContractsInspectionTarget = unknown` | Target accepted by `inspectContracts`. |
| `InspectionReport` | `type InspectionReport` | JSON-stable report returned by `inspectContracts`. |
| `InspectionStatus` | `type InspectionStatus = "ok" \| "warning" \| "error"` | Status field of `InspectionReport`. |

## Sub-path exports

The following entrypoints are published alongside the root export. Their symbols are generated from their own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/contracts` | `./mod.ts` | Core contract surface (documented above). |
| `@netscript/contracts/crud` | `./crud.ts` | CRUD contract generators. |
| `@netscript/contracts/query` | `./query.ts` | Query, filter, and pagination helpers. |
| `@netscript/contracts/transform` | `./transform.ts` | Typed transformer factories. |

### `@netscript/contracts/crud`

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createCrudContract` | function | `function createCrudContract<TEntity, TCreate, TUpdate>(options: CrudContractOptions<...>): CrudContract` | Generates a full list/get/create/update/delete oRPC CRUD contract. |
| `createReadOnlyContract` | function | `function createReadOnlyContract<TEntity>(options: { resource; entitySchema; idSchema?; filterSchema?; }): CrudContract` | Generates a read-only (list + get) CRUD contract. |
| `createListOnlyContract` | function | `function createListOnlyContract<TEntity>(options: { resource; entitySchema; filterSchema?; }): CrudContract` | Generates a list-only CRUD contract. |
| `CrudContract` | type alias | `type CrudContract = Readonly<{ list?; getById?; create?; update?; delete?; }>` | The generated CRUD contract map of operations. |
| `CrudContractOperation` | type alias | `type CrudContractOperation = BaseContractProcedure` | A single generated CRUD operation procedure. |
| `CrudContractOptions` | interface | `interface CrudContractOptions<TEntity, TCreate, TUpdate>` | Options accepted by `createCrudContract`. |

### `@netscript/contracts/query`

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `buildPrismaWhere` | function | `function buildPrismaWhere(filters: FilterCondition[]): Record<string, unknown>` | Builds a Prisma `where` clause from filter conditions. |
| `buildSearchCondition` | function | `function buildSearchCondition(query: string, fields: string[]): Record<string, unknown> \| null` | Builds a Prisma search condition across the given fields. |
| `combineConditions` | function | `function combineConditions(options: { filters?; search?; searchFields?; }): Record<string, unknown>` | Combines filter and search conditions into one Prisma clause. |
| `createPaginatedOutput` | function | `function createPaginatedOutput<T>(itemSchema: ContractSchema<T>): ContractObjectSchema<PaginatedResult<T>>` | Wraps an item schema in an offset-paginated output schema. |
| `createCursorPaginatedOutput` | function | `function createCursorPaginatedOutput<T>(itemSchema: ContractSchema<T>): ContractObjectSchema<CursorPaginatedResult<T>>` | Wraps an item schema in a cursor-paginated output schema. |
| `PaginationInputSchema` | const | `const PaginationInputSchema: ContractObjectSchema<PaginationInput>` | Page/limit pagination input schema. |
| `PaginationOutputSchema` | const | `const PaginationOutputSchema: ContractObjectSchema<PaginationOutput>` | Page pagination output metadata schema. |
| `OffsetPaginationInputSchema` | const | `const OffsetPaginationInputSchema: ContractObjectSchema<OffsetPaginationInput>` | Offset/limit pagination input schema. |
| `CursorPaginationInputSchema` | const | `const CursorPaginationInputSchema: ContractObjectSchema<CursorPaginationInput>` | Cursor pagination input schema. |
| `CursorPaginationOutputSchema` | const | `const CursorPaginationOutputSchema: ContractObjectSchema<CursorPaginationOutput>` | Cursor pagination output metadata schema. |
| `SearchInputSchema` | const | `const SearchInputSchema: ContractObjectSchema<SearchInput>` | Search/filter input schema. |
| `FilterConditionSchema` | const | `const FilterConditionSchema: ContractObjectSchema<FilterCondition>` | Single filter condition schema. |
| `FiltersSchema` | const | `const FiltersSchema: ContractSchema<Filters>` | Array-of-filters schema. |
| `FilterOperatorSchema` | const | `const FilterOperatorSchema: ContractSchema<FilterOperator>` | Filter operator enum schema. |
| `PaginationInput` | type alias | `type PaginationInput = Readonly<{ page; limit; sortBy?; sortOrder; }>` | Page/limit pagination input. |
| `PaginationOutput` | type alias | `type PaginationOutput = Readonly<{ page; limit; total; totalPages; hasNext; hasPrev; }>` | Page pagination output metadata. |
| `OffsetPaginationInput` | type alias | `type OffsetPaginationInput = Readonly<{ offset; limit; sortBy?; sortOrder; }>` | Offset/limit pagination input. |
| `CursorPaginationInput` | type alias | `type CursorPaginationInput = Readonly<{ cursor?; limit; direction; }>` | Cursor pagination input. |
| `CursorPaginationOutput` | type alias | `type CursorPaginationOutput = Readonly<{ nextCursor; prevCursor; hasMore; }>` | Cursor pagination output metadata. |
| `FilterCondition` | type alias | `type FilterCondition = Readonly<{ field; operator; value?; }>` | Single filter condition. |
| `Filters` | type alias | `type Filters = readonly FilterCondition[]` | Ordered list of filter conditions. |
| `FilterOperator` | type alias | `type FilterOperator` | Supported filter operators (equals, contains, gt, in, isNull, and so on). |
| `SearchInput` | type alias | `type SearchInput = Readonly<{ search?; searchFields?; filters?; }>` | Search + filter input. |
| `PaginatedResult` | interface | `interface PaginatedResult<T>` | Offset-paginated result shape. |
| `CursorPaginatedResult` | interface | `interface CursorPaginatedResult<T>` | Cursor-paginated result shape. |
| `PaginatedQueryOptions` | interface | `interface PaginatedQueryOptions extends Partial<PaginationInput>` | Options for an offset-paginated query. |
| `OffsetPaginatedQueryOptions` | interface | `interface OffsetPaginatedQueryOptions` | Options for an offset-paginated query. |
| `CursorPaginatedQueryOptions` | interface | `interface CursorPaginatedQueryOptions` | Options for a cursor-paginated query. |
| `PrismaModelDelegate` | interface | `interface PrismaModelDelegate` | Minimal Prisma delegate contract used by query helpers. |

### `@netscript/contracts/transform`

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createTransformer` | function | `function createTransformer<TInput, TOutput>(transform: TransformFn<TInput, TOutput>): Transformer<TInput, TOutput>` | Wraps a transform function into a composable `Transformer`. |
| `composeTransformers` | function | `function composeTransformers(...transformers): Transformer` | Composes 2-4 transformers left-to-right into one transformer. |
| `createPickTransformer` | function | `function createPickTransformer<T>(): PickTransformerFactory<T>` | Creates a factory producing transformers that pick keys. |
| `createOmitTransformer` | function | `function createOmitTransformer<T>(): OmitTransformerFactory<T>` | Creates a factory producing transformers that omit keys. |
| `Transformer` | interface | `interface Transformer<TInput, TOutput>` | A composable input-to-output transformer. |
| `TransformFn` | type alias | `type TransformFn<TInput, TOutput> = (input: TInput) => TOutput` | The underlying transform function signature. |
| `PickTransformerFactory` | type alias | `type PickTransformerFactory<T> = (...keys) => Transformer<T, Pick<T, K>>` | Factory returned by `createPickTransformer`. |
| `OmitTransformerFactory` | type alias | `type OmitTransformerFactory<T> = (...keys) => Transformer<T, Omit<T, K>>` | Factory returned by `createOmitTransformer`. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/contracts/_

---

# `@netscript/cron`

Runtime-agnostic cron scheduling abstraction for NetScript applications. Provides a consistent interface across different backends (native `Deno.cron` and an in-memory scheduler) with timezone support, job-lifecycle event emission, and runtime auto-detection. This page is generated from the package public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/cron`) exposes the scheduler factory, the shared-instance helpers, the cron-expression utilities, and the full port contract (interfaces and type aliases). Three sub-path exports carry the rest of the surface:

- [`@netscript/cron/ports`](#sub-path-exports) - the port contract types only (no factory).
- [`@netscript/cron/adapters`](#sub-path-exports) - the concrete adapter classes.
- [`@netscript/cron/testing`](#sub-path-exports) - the in-memory adapter for tests.

## Scheduler factory

| Symbol | Signature | Description |
| --- | --- | --- |
| `createScheduler` | `function createScheduler(options?: CreateSchedulerOptions): CronScheduler` | Create a cron scheduler, auto-detecting the runtime (native `Deno.cron`, or in-memory for tests). |
| `getScheduler` | `function getScheduler(options?: CreateSchedulerOptions): CronScheduler` | Get the default shared scheduler instance, creating it on first call (options only used on first call). |
| `stopScheduler` | `async function stopScheduler(): Promise<void>` | Stop and reset the default scheduler so the next `getScheduler()` creates a fresh instance. |

## Cron expression utilities

| Symbol | Signature | Description |
| --- | --- | --- |
| `isValidCronExpression` | `function isValidCronExpression(expression: string): boolean` | Validate a cron expression, returning `true` if valid. |
| `parseCronExpression` | `function parseCronExpression(expression: string): ParsedCronExpression \| null` | Parse a cron expression string into its component parts, or `null` if invalid. |

## Constants

| Symbol | Kind | Description |
| --- | --- | --- |
| `CronPresets` | const | Common cron presets (`EVERY_MINUTE`, `EVERY_5_MINUTES`, `EVERY_HOUR`, `EVERY_DAY`, `WEEKDAYS_9AM`, `WEEKENDS_NOON`, and more). |
| `CronProviders` | const | Canonical provider identifiers supported by the built-in factory. |

## Scheduler contract

The core scheduling interface implemented by every adapter.

| Symbol | Kind | Description |
| --- | --- | --- |
| `CronScheduler` | interface | Runtime-agnostic scheduling abstraction: `schedule`, `unschedule`, `list`, `get`, `has`, `enable`, `disable`, `trigger`, `isValid`, `on`/`off`, and `stop`, plus `provider` and `isRunning`. |
| `CreateSchedulerOptions` | interface | Options for creating a scheduler (`provider`, `tickInterval`). |
| `ScheduleOptions` | interface | Options for scheduling a job (timezone, run-on-init, retries). |
| `ScheduledJob` | interface | Scheduled-job metadata. |
| `JobContext` | interface | Job execution context passed to contextual handlers. |
| `JobExecutionResult` | interface | Result of a single job execution. |
| `JobRunEvent` | interface | Event emitted when a job runs. |
| `JobLifecycleEvent` | interface | Event emitted when a job is scheduled or unscheduled. |
| `SchedulerEventMap` | interface | Typed scheduler event-payload map. |
| `ParsedCronExpression` | interface | A cron expression parsed into its component parts. |

## Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `CronExpression` | type alias | Cron expression string. |
| `JobHandler` | type alias | Job handler function signature. |
| `ContextualJobHandler` | type alias | Job handler that receives a `JobContext`. |
| `JobEventListener` | type alias | Event listener for scheduler events. |
| `SchedulerEvent` | type alias | Scheduler event-name union. |
| `CronProvider` | type alias | Cron provider identifier (built-in providers runtime-validated by `createScheduler()`). |
| `KnownCronProvider` | type alias | Union of the known built-in provider identifiers. |
| `CronProviderRegistry` | type alias | Canonical provider-identifier registry shape. |
| `BackoffStrategy` | type alias | Backoff strategy for retry logic. |

## Adapters

Concrete implementations of `CronScheduler`, exported from `@netscript/cron/adapters`.

| Symbol | Kind | Description |
| --- | --- | --- |
| `DenoCronAdapter` | class | Uses the native `Deno.cron` runtime; works on Deno Deploy and local Deno. |
| `MemoryCronAdapter` | class | `setInterval`-based in-memory scheduler with test helpers (`triggerAll`, `waitForExecutions`, `getExecutionCount`, `setTickInterval`). Ideal for tests and development. |

## Sub-path exports

The following entrypoints are published alongside the root export. Their reference surface is generated from their own `deno doc` output.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/cron` | `./mod.ts` | Scheduler factory, expression utilities, constants, and the full port contract (documented above). |
| `@netscript/cron/ports` | `./ports/mod.ts` | The port contract only - every interface and type alias above, without the factory functions. |
| `@netscript/cron/adapters` | `./adapters/mod.ts` | The concrete `DenoCronAdapter` and `MemoryCronAdapter` classes (plus re-exported contract types and utilities). |
| `@netscript/cron/testing` | `./testing/mod.ts` | The `MemoryCronAdapter` for tests. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/cron/_

---

# `@netscript/database`

Database adapter contracts, Prisma driver helpers, tracing, and schema tooling for NetScript packages. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/database`) re-exports the port contracts, the PostgreSQL adapter, the JSON extension helpers, and the OTEL instrumentation toggle. The remaining sub-path exports carry the per-driver adapters, the Prisma extensions, the schema/codegen scripts, the tracing surface, and the test contract harness:

- [`@netscript/database/ports`](#ports) — adapter contracts and shared types.
- [`@netscript/database/adapters`](#adapters) — PostgreSQL adapter (default driver surface).
- [`@netscript/database/adapters/postgres`](#postgresql-adapter) — PostgreSQL driver adapter.
- [`@netscript/database/adapters/mssql`](#sql-server-adapter) — SQL Server driver adapter.
- [`@netscript/database/adapters/mysql`](#mysql-adapter) — MySQL driver adapter.
- [`@netscript/database/extensions`](#extensions) — Prisma JSON serialization extensions.
- [`@netscript/database/scripts`](#scripts) — Prisma/Zod codegen and migration runners.
- [`@netscript/database/tracing`](#tracing) — Prisma OpenTelemetry tracing helpers.
- [`@netscript/database/testing`](#testing) — mock adapter and shared port contract tests.

## Ports

Exported from the root (`@netscript/database`) and from `@netscript/database/ports`. These are the provider-agnostic adapter contracts.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `DatabaseAdapter` | interface | `interface DatabaseAdapter` | Generic database adapter interface. |
| `DatabaseAdapterFactory` | interface | `interface DatabaseAdapterFactory` | Factory for creating database adapters. |
| `DatabaseConnectionOptions` | interface | `interface DatabaseConnectionOptions` | Database connection options. |
| `DatabaseConnectionStatus` | interface | `interface DatabaseConnectionStatus` | Database connection status. |
| `SharedDatabaseConfig` | interface | `interface SharedDatabaseConfig` | Configuration for the shared database instance. |
| `TransactionOptions` | interface | `interface TransactionOptions` | Transaction options. |
| `DatabaseProvider` | type alias | `type DatabaseProvider` | Database provider types. |
| `IsolationLevel` | type alias | `type IsolationLevel` | Transaction isolation levels. |

## Root extras

Additional symbols re-exported from the root entrypoint (`@netscript/database`) beyond the port contracts and the PostgreSQL adapter.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `enableInstrumentation` | function | `function enableInstrumentation(): boolean` | Enable Prisma OTEL instrumentation for database tracing. Call before creating any Prisma clients; only active when `OTEL_DENO=true`. |
| `withTransaction` | function | `function withTransaction(client, fn, options): Promise` | Execute operations within a transaction. |
| `parseConnectionString` | function | `function parseConnectionString(connectionString)` | Parse a database connection string. |
| `buildPostgresConnectionString` | function | `function buildPostgresConnectionString(parts): string` | Build a PostgreSQL connection string from parts. |
| `buildMssqlConnectionString` | function | `function buildMssqlConnectionString(parts): string` | Build a SQL Server connection string from parts. |
| `jsonUtils` | variable | `const jsonUtils` | JSON serialization utilities for manual use. |
| `registerJsonFields` | function | `function registerJsonFields(model, fields): void` | Register additional JSON fields for a model at runtime. |

## Adapters

Exported from `@netscript/database/adapters` (and re-exported from the root). This is the default PostgreSQL driver surface.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createPostgresAdapter` | function | `function createPostgresAdapter(options): PostgresAdapter` | Create a PostgreSQL adapter. |
| `PostgresAdapter` | class | `class PostgresAdapter` | PostgreSQL adapter. |
| `PostgresConnectionOptions` | interface | `interface PostgresConnectionOptions` | PostgreSQL-specific connection options. |

### PostgreSQL adapter

Exported from `@netscript/database/adapters/postgres`.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createPostgresAdapter` | function | `function createPostgresAdapter(options): PostgresAdapter` | Create a PostgreSQL adapter. |
| `PostgresAdapter` | class | `class PostgresAdapter` | PostgreSQL adapter. |
| `PostgresDriverAdapter` | interface | `interface PostgresDriverAdapter` | Public structural type returned by PostgreSQL driver adapter factories. |
| `PostgresConnectionOptions` | interface | `interface PostgresConnectionOptions` | PostgreSQL-specific connection options. |

### SQL Server adapter

Exported from `@netscript/database/adapters/mssql`.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createMssqlAdapter` | function | `function createMssqlAdapter(options): MssqlAdapter` | Create a SQL Server adapter. |
| `MssqlAdapter` | class | `class MssqlAdapter` | SQL Server adapter. |
| `MssqlDriverAdapter` | interface | `interface MssqlDriverAdapter` | Public structural type returned by SQL Server driver adapter factories. |
| `MssqlAdapterConfig` | interface | `interface MssqlAdapterConfig` | Configuration object for `@prisma/adapter-mssql`. |
| `MssqlConnectionOptions` | interface | `interface MssqlConnectionOptions` | MSSQL-specific connection options. |
| `MssqlIsolationLevel` | type alias | `type MssqlIsolationLevel` | SQL Server isolation levels (includes Snapshot). |
| `parseAdoNetConnectionString` | function | `function parseAdoNetConnectionString(connectionString): MssqlAdapterConfig` | Parse an ADO.NET connection string into a config object for `@prisma/adapter-mssql`. |
| `getMssqlConfig` | function | `function getMssqlConfig(env): MssqlAdapterConfig` | Get MSSQL adapter configuration from environment. |
| `getMssqlConfigFromEnv` | function | `function getMssqlConfigFromEnv(env)` | Get MSSQL configuration from structured environment variables. |

### MySQL adapter

Exported from `@netscript/database/adapters/mysql`.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createMysqlAdapter` | function | `function createMysqlAdapter(options): MysqlAdapter` | Create a MySQL adapter. |
| `MysqlAdapter` | class | `class MysqlAdapter` | MySQL adapter. |
| `MysqlDriverAdapter` | interface | `interface MysqlDriverAdapter` | Public structural type returned by MySQL driver adapter factories. |
| `MysqlAdapterConfig` | interface | `interface MysqlAdapterConfig` | Configuration object for `@netscript/prisma-adapter-mysql`. |
| `MysqlConnectionOptions` | interface | `interface MysqlConnectionOptions` | MySQL-specific connection options. |
| `parseMysqlConnectionString` | function | `function parseMysqlConnectionString(connectionString): MysqlAdapterConfig` | Parse a MySQL connection URI into adapter config. |
| `buildMysqlConnectionString` | function | `function buildMysqlConnectionString(parts): string` | Build a MySQL connection string from parts. |
| `getMysqlConfig` | function | `function getMysqlConfig(env): MysqlAdapterConfig` | Get MySQL adapter configuration from environment. |
| `getMysqlConfigFromEnv` | function | `function getMysqlConfigFromEnv(env)` | Get MySQL configuration from structured environment variables. |

## Extensions

Exported from `@netscript/database/extensions`. Prisma extensions that automatically handle JSON serialization across SQL databases.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `sqlJsonExtension` | function | `function sqlJsonExtension(Prisma, options): ReturnType` | Create a Prisma extension that automatically handles JSON serialization. |
| `mysqlJsonExtension` | function | `function mysqlJsonExtension(Prisma, options): ReturnType` | Create a Prisma extension for MySQL JSON serialization. |
| `registerJsonFields` | function | `function registerJsonFields(model, fields): void` | Register additional JSON fields for a model at runtime. |
| `jsonUtils` | variable | `const jsonUtils` | JSON serialization utilities for manual use. |
| `SqlJsonExtensionOptions` | interface | `interface SqlJsonExtensionOptions` | Options for creating the SQL JSON extension. |
| `PrismaExtensionConfig` | interface | `interface PrismaExtensionConfig` | Prisma extension configuration generated by SQL JSON helpers. |
| `PrismaQueryContext` | interface | `interface PrismaQueryContext` | Query context passed by Prisma to extension handlers. |
| `JsonField` | type alias | `type JsonField` | JSON field values. |
| `JsonFieldConfig` | type alias | `type JsonFieldConfig` | Configuration for JSON fields per model. |
| `PrismaQueryHandler` | type alias | `type PrismaQueryHandler` | Query handler used by Prisma extension configuration. |
| `SqlDatabaseType` | type alias | `type SqlDatabaseType` | Supported database types for JSON handling. |

## Scripts

Exported from `@netscript/database/scripts`. Codegen and migration runners (each ships a `*Cli` runner for command-line use).

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `generateZodSchemas` | function | `async function generateZodSchemas(options): Promise` | Generate Zod schemas from Prisma models. |
| `generateZodSchemasCli` | function | `async function generateZodSchemasCli(options): Promise` | CLI runner for Zod generation. |
| `fixZodImports` | function | `async function fixZodImports(zodOutputDir, options): Promise` | Fix relative imports in generated Zod files by adding `.ts` extensions. |
| `runFixZodImports` | function | `async function runFixZodImports(zodOutputDir, options): Promise` | CLI runner for fix-zod-imports. |
| `patchPrismaClient` | function | `async function patchPrismaClient(generatedDir, options): Promise` | Patch a Prisma-generated directory for isomorphic imports. |
| `runPatchPrismaClient` | function | `async function runPatchPrismaClient(generatedDir, options): Promise` | CLI runner: patch a single generated directory and log a summary. |
| `runMigration` | function | `async function runMigration(options): Promise` | Run a Prisma migration. |
| `runMigrationCli` | function | `async function runMigrationCli(options): Promise` | CLI runner for migrations. |
| `GenerateZodOptions` | interface | `interface GenerateZodOptions` | Options for Prisma Zod schema generation. |
| `FixZodImportsOptions` | interface | `interface FixZodImportsOptions` | Options for generated Zod schema post-processing. |
| `FixZodImportsResult` | interface | `interface FixZodImportsResult` | Summary of generated Zod schema post-processing changes. |
| `PatchPrismaClientOptions` | interface | `interface PatchPrismaClientOptions` | Options for Prisma client patching. |
| `PatchPrismaClientResult` | interface | `interface PatchPrismaClientResult` | Summary of Prisma client patching changes. |
| `MigrationOptions` | interface | `interface MigrationOptions` | Prisma migration options. |

## Tracing

Exported from `@netscript/database/tracing`. Prisma OpenTelemetry tracing helpers and the structural span/tracer shapes they consume.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `enablePrismaTracing` | function | `function enablePrismaTracing(config): void` | Enable Prisma OTEL tracing. |
| `disablePrismaTracing` | function | `function disablePrismaTracing(): void` | Disable Prisma OTEL tracing. |
| `isPrismaTracingEnabled` | function | `function isPrismaTracingEnabled(): boolean` | Check whether Prisma OTEL tracing is currently enabled. |
| `PrismaTracingConfig` | interface | `interface PrismaTracingConfig` | Configuration for Prisma OpenTelemetry tracing. |
| `PrismaTracingProvider` | interface | `interface PrismaTracingProvider` | Tracer provider shape accepted by `enablePrismaTracing`. |
| `PrismaTracingTracer` | interface | `interface PrismaTracingTracer` | Minimum OpenTelemetry tracer shape used by Prisma tracing helpers. |
| `PrismaTracingSpan` | interface | `interface PrismaTracingSpan` | Minimum OpenTelemetry span shape used by Prisma tracing helpers. |
| `PrismaTracingSpanContext` | interface | `interface PrismaTracingSpanContext` | Span context fields used by Prisma tracing propagation. |
| `PrismaTracingSpanLink` | interface | `interface PrismaTracingSpanLink` | Span link shape consumed by Prisma tracing helpers. |

## Testing

Exported from `@netscript/database/testing`. A mock adapter and the shared port contract test suite, plus the port types they reference.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createMockDatabaseAdapter` | function | `function createMockDatabaseAdapter(options): MockDatabaseAdapter` | Create a new mock database adapter. |
| `MockDatabaseAdapter` | class | `class MockDatabaseAdapter` | In-memory database adapter used by port contract tests. |
| `runDatabaseAdapterContract` | function | `function runDatabaseAdapterContract(options): void` | Register the shared database adapter contract tests. |
| `DatabaseAdapterContractOptions` | interface | `interface DatabaseAdapterContractOptions` | Options for `runDatabaseAdapterContract`. |
| `DatabaseAdapter` | interface | `interface DatabaseAdapter` | Generic database adapter interface (re-exported from ports). |
| `DatabaseConnectionStatus` | interface | `interface DatabaseConnectionStatus` | Database connection status (re-exported from ports). |
| `DatabaseProvider` | type alias | `type DatabaseProvider` | Database provider types (re-exported from ports). |

## Sub-path exports

The following entrypoints are published alongside the root export. Their symbols are documented in the sections above.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/database` | `./mod.ts` | Root surface: ports, PostgreSQL adapter, JSON helpers, instrumentation toggle. |
| `@netscript/database/ports` | `./ports/mod.ts` | Adapter contracts and shared types. |
| `@netscript/database/adapters` | `./adapters/mod.ts` | PostgreSQL adapter (default driver surface). |
| `@netscript/database/adapters/postgres` | `./adapters/postgres.adapter.ts` | PostgreSQL driver adapter. |
| `@netscript/database/adapters/mssql` | `./adapters/mssql.adapter.ts` | SQL Server driver adapter. |
| `@netscript/database/adapters/mysql` | `./adapters/mysql.adapter.ts` | MySQL driver adapter. |
| `@netscript/database/extensions` | `./extensions/mod.ts` | Prisma JSON serialization extensions. |
| `@netscript/database/scripts` | `./scripts/mod.ts` | Prisma/Zod codegen and migration runners. |
| `@netscript/database/tracing` | `./prisma-tracing.ts` | Prisma OpenTelemetry tracing helpers. |
| `@netscript/database/testing` | `./testing/mod.ts` | Mock adapter and shared port contract tests. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/database/_

---

# `@netscript/fresh-ui`

Fresh UI registry seams and interactive foundations for NetScript. This page is generated from the package public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/fresh-ui`) intentionally stays small: copy-based registry components and islands remain on workspace-local deep paths so applications can own and evolve them after copy. The root module exposes only the supported helper utilities that are safe to consume as package runtime dependencies. Two sub-path exports carry the runtime seams:

- [`@netscript/fresh-ui/interactive`](#sub-path-exports) — package-owned interactive namespaces for stateful, accessible primitives.
- [`@netscript/fresh-ui/primitives`](#sub-path-exports) — L0 platform-contract primitives.

## Class-name helper

| Symbol | Signature | Description |
| --- | --- | --- |
| `cn` | `function cn(...inputs: ClassValue[]): string` | Combines clsx and tailwind-merge for optimal class merging. |

## Icon primitive

`Icon` is a first-class stroke-SVG icon primitive, re-exported at the package root alongside its supporting types from `@netscript/fresh-ui/primitives`.

| Symbol | Kind | Description |
| --- | --- | --- |
| `Icon` | component | Renders a named stroke-SVG icon (`IconName`) at a given `IconSize`, forwarding standard SVG attributes. |
| `ICON_PATHS` | const | The stroke-path lookup table backing every `IconName`. |
| `IconName` / `IconSize` / `IconProps` / `IconSvgAttributes` / `IconSvgAttributeValue` | type aliases / interface | Supporting types for the `Icon` primitive. |

## DataGrid

`DataGrid` is a generic, templated data-grid component exported from the package root (`@netscript/fresh-ui`) — the successor to the earlier `DataTable` registry block. Unlike the copy-source registry items, `DataGrid` is a runtime export you import directly; you do **not** `netscript ui:add` it. It renders a token-styled `role="grid"` region from a `columns` contract and a `rows` contract, and supports plain, button, and Fresh client-navigation rows.

### DataGrid props

| Prop | Type | Description |
| --- | --- | --- |
| `columns` | `readonly DataGridColumn<T>[]` | Ordered column definitions (required). |
| `rows` | `readonly DataGridRow<T>[]` | Ordered row definitions (required). |
| `label` | `string` | Accessible label applied as `aria-label` on the grid region. |
| `class` | `string` | Additional class names appended to the `ns-data-grid` root. |
| `[attribute: string]` | `unknown` | Any further native attributes are forwarded to the grid root. |

### `DataGridColumn<T>`

| Field | Type | Description |
| --- | --- | --- |
| `key` | `string` | Property key used for fallback cell content and stable cell identity. |
| `header` | `string` | Visible column header text. |
| `width` | `string` | CSS grid track width, e.g. `2fr` or `minmax(0, 12rem)`. Defaults to `minmax(0, 1fr)`. |
| `cell` | `DataGridCellVariant` | Optional built-in cell treatment: `"strong"` (bold) or `"num"` (monospace, right-aligned). |
| `render` | `(row: T) => DataGridRenderable` | Optional per-column template receiving the row payload. |

### `DataGridRow<T>`

Every row carries a stable `id`, a caller-owned `data: T` payload, and an optional `selected` flag. A row renders differently based on which navigation field is present — the three shapes are mutually exclusive (supply at most one of `onSelect` or `href`):

| Shape | Distinguishing field | Renders as |
| --- | --- | --- |
| Plain | neither `onSelect` nor `href` | a `role="row"` `<div>`. |
| Button | `onSelect: () => void` | a `role="row"` `<button>` that calls `onSelect` on click. |
| Link | `href: string` | a `role="row"` `<a f-client-nav>` for Fresh client navigation. |

### DataGrid symbols

| Symbol | Kind | Description |
| --- | --- | --- |
| `DataGrid` | component | Generic templated data grid; renders `DataGridColumn` definitions over `DataGridRow` data. |
| `DATA_GRID_CELL_VARIANTS` | const | The supported cell-treatment names: `["strong", "num"]`. |
| `DataGridColumn<T>` / `DataGridProps<T>` / `DataGridRow<T>` | interfaces / types | Column, props, and row contracts. |
| `DataGridNode` / `DataGridRenderable` / `DataGridCellVariant` | types | Structural node, renderable cell content, and the cell-variant union. |

### DataGrid example

```tsx
import { DataGrid, type DataGridColumn, type DataGridRow } from "@netscript/fresh-ui";

interface Invoice {
  id: string;
  customer: string;
  total: number;
}

const columns: DataGridColumn<Invoice>[] = [
  { key: "customer", header: "Customer", width: "2fr", cell: "strong" },
  { key: "total", header: "Total", cell: "num", render: (row) => `$${row.total.toFixed(2)}` },
];

const rows: DataGridRow<Invoice>[] = [
  { id: "inv-1", data: { id: "inv-1", customer: "Acme", total: 420 }, href: "/invoices/inv-1" },
  { id: "inv-2", data: { id: "inv-2", customer: "Globex", total: 130 }, selected: true, href: "/invoices/inv-2" },
];

export function InvoiceGrid() {
  return <DataGrid label="Invoices" columns={columns} rows={rows} />;
}
```

A column with `cell: "num"` renders monospace and right-aligned; `cell: "strong"` renders bold. A column without `render` falls back to `row.data[column.key]` when that key holds a string, number, bigint, boolean, `null`, or `undefined`.

> **Rows are keyed by `id`.** Supply a stable `id` per row so Preact can reconcile rows across re-renders, and provide at most one of `onSelect` or `href` — the row shapes are mutually exclusive, and a link row navigates through Fresh (`f-client-nav`) rather than a full page load.

## Dropzone (registry component)

`Dropzone` is a copy-source registry component, not a package export — install it with `netscript ui:add dropzone`, after which it lives at `components/ui/dropzone.tsx` in your app and is yours to edit. It renders a dashed file-drop target (`<label class="ns-dropzone">`) that ingests files from three sources — drag-and-drop, focused clipboard paste, and the native file picker — and filters each ingest through a shared `accept` / `multiple` policy before calling back.

### Dropzone props

| Prop | Type | Description |
| --- | --- | --- |
| `label` | `string` | Primary call-to-action text. Defaults to `"Drop files or click to upload"`. |
| `hint` | `string` | Secondary hint line (accepted types, size limits). |
| `icon` | `Renderable` | Leading glyph or icon node. Defaults to `↑`. |
| `active` | `boolean` | Forces the drag-over (`data-active`) visual state. |
| `accept` | `string` | Native `accept` string applied to drop, paste, **and** picker ingest. |
| `multiple` | `boolean` | Whether one ingest event may accept more than one file. Defaults to `false`. |
| `onFile` | `(file: File, details: DropzoneIngestDetails) => void` | Called with the first accepted file — the simple single-file path. |
| `onFiles` | `(files: readonly File[], details: DropzoneIngestDetails) => void` | Called with every accepted file. |
| `onReject` | `(files: readonly DropzoneRejectedFile[], details: DropzoneIngestDetails) => void` | Called with every rejected file. |
| `onDrop` / `onDragOver` / `onPaste` | event handlers | Optional passthrough handlers invoked after the built-in ingest runs. |
| `children` | `Renderable` | Additional content rendered inside the label. |
| `class` | `string` | Additional class names appended to the `ns-dropzone` root. |

`DropzoneProps` also extends `JSX.HTMLAttributes<HTMLLabelElement>` (minus `class`, `onDrop`, `onDragOver`, and `onPaste`, which the component owns), so standard label attributes pass through.

### Dropzone ingest types

| Symbol | Kind | Description |
| --- | --- | --- |
| `DROPZONE_INGEST_SOURCES` | const | The ingest source names: `["drop", "paste", "picker"]`. |
| `DROPZONE_REJECTED_REASONS` | const | The rejection reason names: `["type", "too-many"]`. |
| `DropzoneIngestSource` | type | `"drop" \| "paste" \| "picker"`. |
| `DropzoneRejectedReason` | type | `"type" \| "too-many"`. |
| `DropzoneRejectedFile` | interface | A rejected `file`, its `reason`, and the ingest `source` that supplied it. |
| `DropzoneIngestDetails` | interface | `acceptedFiles`, `rejectedFiles`, the ingest `source`, and the original `event`. |
| `DropzoneProps` | interface | The full prop contract documented above. |

### Dropzone example

```tsx
import { Dropzone, type DropzoneIngestDetails } from "@app/components/ui/dropzone.tsx";

export function AvatarUpload() {
  function handleFiles(files: readonly File[], details: DropzoneIngestDetails) {
    console.log(`Accepted ${files.length} file(s) via ${details.source}`);
    for (const rejected of details.rejectedFiles) {
      console.warn(`Rejected ${rejected.file.name}: ${rejected.reason}`);
    }
  }

  return (
    <Dropzone
      label="Drop images or click to upload"
      hint="PNG or JPG, up to 5 MB"
      accept="image/png,image/jpeg"
      multiple
      onFiles={handleFiles}
    />
  );
}
```

Rejections are reported, not silent: a file whose type falls outside `accept` is rejected with reason `"type"`, and — when `multiple` is `false` — every file after the first is rejected with reason `"too-many"`. Each ingest also updates a visually-rendered `aria-live` status node so assistive technology hears how many files were accepted or rejected.

> **Paste ingest requires focus.** Clipboard paste only fires while the dropzone (or a child) holds focus, so pair it with a focusable affordance. The picker `<input>` clears its value after each selection, so re-selecting the same file still triggers `onFile` / `onFiles`.

## Redirect-flash (toast) helpers

| Symbol | Signature | Description |
| --- | --- | --- |
| `getToast` | `function getToast(url: URL): RegistryToast \| undefined` | Reads a toast payload from a URL when redirect-flash query parameters are present. |
| `withToast` | `function withToast(path: string, toast: RegistryToast): string` | Appends a toast payload to a relative application path. |
| `stripToastFromUrl` | `function stripToastFromUrl(url: URL): string` | Removes all toast query parameters from a URL while preserving path and hash. |
| `REGISTRY_TOAST_QUERY_KEYS` | `const REGISTRY_TOAST_QUERY_KEYS: { message: string; title: string; type: string }` | Query-string keys reserved by the redirect-flash helpers. |

### Toast types

| Symbol | Kind | Description |
| --- | --- | --- |
| `RegistryToast` | interface | Redirect-flash payload persisted in URL query parameters (`message`, optional `title`, `type`). |
| `RegistryToastType` | type alias | Toast semantic variants: `"success" \| "error" \| "warning" \| "info"`. |

## Interactive namespaces

Exported from the [`@netscript/fresh-ui/interactive`](#sub-path-exports) sub-path. Each is a compound namespace bundling a root component with its structural subcomponents. The namespace types are package-internal (see note below).

| Symbol | Signature | Description |
| --- | --- | --- |
| `Accordion` | `const Accordion: AccordionNamespace` | Compound accordion namespace with root and item subcomponents. |
| `Dialog` | `const Dialog: DialogNamespace` | Compound dialog namespace with root and structural subcomponents. |
| `Drawer` | `const Drawer: DrawerNamespace` | Compound drawer namespace with root and structural subcomponents. |
| `Popover` | `const Popover: PopoverNamespace` | Compound popover namespace with root and positioning subcomponents. |
| `Sheet` | `const Sheet: SheetNamespace` | Compound sheet namespace — side-docked inspection panel. |
| `Tabs` | `const Tabs: TabsNamespace` | Compound tabs namespace with root, list, trigger, and content subcomponents. |
| `Tooltip` | `const Tooltip: TooltipNamespace` | Compound tooltip namespace with root and positioning subcomponents. |

> **Surface note:** the `*Namespace` types backing these exports are currently package-internal. `deno doc --lint` reports them as `private-type-ref` errors; making them public is planned for a future release. The runtime exports themselves are stable.

## L0 primitives

Exported from the [`@netscript/fresh-ui/primitives`](#sub-path-exports) sub-path. L0 stays small: prefer Preact intrinsic elements and platform attributes, using these helpers only where they encapsulate real behavior.

| Symbol | Signature | Description |
| --- | --- | --- |
| `Show` | `function Show<T>({ when, fallback, children }: ShowProps<T>): PrimitiveChildren` | Conditionally renders children without introducing an extra DOM wrapper. |
| `VisuallyHidden` | `function VisuallyHidden({ children, style, ...props }: VisuallyHiddenProps): PrimitiveNode` | Renders content for assistive technology while keeping it visually hidden. |
| `SrOnly` | `function SrOnly(props: VisuallyHiddenProps): PrimitiveNode` | Alias for `VisuallyHidden` using the common screen-reader naming. |

### Primitive types

| Symbol | Kind | Description |
| --- | --- | --- |
| `PrimitiveNode` | interface | Structural node returned by element-producing L0 primitives (`type`, `props`, `key`). |
| `ShowProps<T>` | interface | Props accepted by `Show` (`when`, optional `fallback`, `children`). |
| `VisuallyHiddenProps` | interface | Props accepted by `VisuallyHidden` and `SrOnly` (`children`, `style`, arbitrary attributes). |
| `PrimitiveChild` | type alias | Primitive value that can be rendered by an L0 helper. |
| `PrimitiveChildren` | type alias | Renderable content accepted by L0 primitives (a child or readonly array of children). |
| `VisuallyHiddenStyle` | type alias | Inline style accepted by visually-hidden primitives. |

## Sub-path exports

The following entrypoints are published alongside the root export.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/fresh-ui` | `./mod.ts` | Stable runtime helpers (`cn`, redirect-flash toast helpers, the `Icon` primitive, and `DataGrid` — documented above). |
| `@netscript/fresh-ui/interactive` | `./interactive.ts` | Package-owned interactive namespaces (documented above). |
| `@netscript/fresh-ui/primitives` | `./primitives.tsx` | L0 platform-contract primitives (documented above). |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/fresh-ui/_

---

# `@netscript/fresh`

Fresh runtime extensions, builders, forms, defer primitives, and route contracts for NetScript. This page is generated from the public surface of the package with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/fresh`) exposes only the cross-cutting page-loader cache helpers. Every other capability lives on an explicit sub-path export. The sub-paths and their reference sections are:

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/fresh` | `./mod.ts` | Page-loader cache helpers (documented below). |
| `@netscript/fresh/server` | `./src/runtime/server/mod.ts` | Fresh app factory and streaming SSR. |
| `@netscript/fresh/builders` | `./src/application/builders/mod.ts` | Fluent page and partial builders. |
| `@netscript/fresh/route` | `./src/application/route/mod.ts` | Typed route contracts and navigation. |
| `@netscript/fresh/defer` | `./src/application/defer/mod.ts` | Deferred rendering primitives. |
| `@netscript/fresh/form` | `./src/application/form/mod.ts` | Managed forms and validation. |
| `@netscript/fresh/error` | `./src/diagnostics/error/mod.ts` | Error normalization and display. |
| `@netscript/fresh/streams` | `./src/runtime/streams/mod.ts` | Durable streams client SDK. |
| `@netscript/fresh/query` | `./src/application/query/mod.ts` | Island TanStack Query hooks. |
| `@netscript/fresh/interactive` | `./src/runtime/interactive/mod.ts` | Suspense promise helpers. |
| `@netscript/fresh/vite` | `./src/application/vite/vite.ts` | NetScript Fresh Vite plugin. |
| `@netscript/fresh/testing` | `./src/testing/mod.ts` | Test fixtures. |

## Root entrypoint

Cross-cutting page-loader cache helpers. Every other capability lives on an explicit sub-path export listed below.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `hasAllCacheEntries` | `hasAllCacheEntries(entries: ReadonlyArray): boolean` | Return `true` when every supplied entry is present. |
| `minCachedAt` | `minCachedAt(entries: ReadonlyArray)` | Return the oldest `cachedAt` timestamp across the supplied entries. |
| `projectCachedItemFromList` | `projectCachedItemFromList(listEntry, predicate)` | Project a single cached item from a cached list response while preserving the list timestamp. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `CacheEntryLike` | interface | Cached-entry shape shared by page loaders and partial orchestration. |
| `CachedListEntryLike` | interface | Cached list-entry shape used when projecting a single list item. |

## `@netscript/fresh/server`

Server-only utilities: the NetScript-managed Fresh app factory and Preact streaming SSR primitives.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `StreamErrorBoundary` | `StreamErrorBoundary(props: StreamErrorBoundaryProps): object` | Preact class component that catches rendering errors within its subtree. |
| `createStreamingResponse` | `createStreamingResponse(vnode: StreamingRenderable, _): Response` | Create a streaming HTTP `Response` from a Preact VNode tree. |
| `defineFreshApp` | `defineFreshApp(_): App` | Create a NetScript-managed Fresh app with the baseline bootstrap defaults. |
| `renderToStream` | `renderToStream(vnode: StreamingRenderable, _): StreamRenderResult` | Render a Preact VNode tree to a `ReadableStream` with Suspense streaming. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `App` | class | Create an application instance that passes the incoming `Request` |
| `DefineFreshAppOptions` | interface | Contract for NetScript-managed Fresh app bootstrap. |
| `FreshAppFactory` | typeAlias | Factory callback that constructs the Fresh app instance. |
| `FreshAppFsRoutes` | typeAlias | Adapter callback that registers file-system routes on a Fresh app. |
| `FreshAppTelemetryAttribute` | typeAlias | Attribute value accepted by Fresh app telemetry bootstrap options. |
| `FreshAppTelemetryOptions` | interface | Telemetry bootstrap options reserved for `defineFreshApp` defaults. |
| `FreshConfig` | interface |  |
| `Middleware` | typeAlias | A middleware function is the basic building block of Fresh. It allows you |
| `StreamBoundaryRenderable` | typeAlias | Renderable content accepted by streaming error boundaries. |
| `StreamErrorBoundaryProps` | interface | Props for {@link StreamErrorBoundary}. |
| `StreamRenderOptions` | interface | Options for streaming HTML rendering. |
| `StreamRenderResult` | interface | Result of a streaming render operation. |
| `StreamingRenderStream` | interface | Readable stream returned by the Preact streaming renderer. |
| `StreamingRenderable` | typeAlias | Renderable Preact tree accepted by Fresh streaming helpers. |
| `StreamingRenderer` | typeAlias | Renderer port used by `renderToStream` to create an HTML byte stream. |

## `@netscript/fresh/builders`

Fluent, typed page and partial builder surface (definePage, definePartial).

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `definePage` | `definePage(): PageRootBuilder` | Start a new typed page builder chain. |
| `definePartial` | `definePartial(options: DefinePartialOptions): DefinedPartialRoute` | Define a framework-owned partial route backed by an async loader. |
| `defineStatsPartial` | `defineStatsPartial(options: DefineStatsPartialOptions): DefinedPartialRoute` | Define a stats-only partial route backed by a context-free query function. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `CollectionDescriptor` | interface | Descriptor for a collection field and its item intent buttons. |
| `CollectionItem` | interface | Descriptor for one item in a collection field. |
| `CollectionKeyInputProps` | interface | Props for a hidden collection-key input. |
| `CollectionKeyMap` | typeAlias | Stable collection item keys by collection field path. |
| `ComponentLike` | interface | Minimal component contract accepted by page and partial builders. |
| `ControlProps` | interface | Props applied to an input, select, textarea, or compatible control. |
| `DefinePartialOptions` | interface | Options for creating a framework-owned partial route. |
| `DefineStatsPartialOptions` | interface | Options for creating a stats-only partial route. |
| `DefinedPartialRoute` | interface | Materialized partial route contract returned by `definePartial()`. |
| `DescriptionProps` | interface | Props applied to a field description element. |
| `EmptyRecord` | typeAlias | Empty object shape used by page builders without typed state. |
| `ErrorFormReplyInit` | interface | Input used to construct an errored form reply. |
| `ErrorProps` | interface | Props applied to a field error element. |
| `FieldConstraints` | interface | HTML constraint attributes derived from a schema field. |
| `FieldDescriptor` | interface | Descriptor for one form field and its generated props. |
| `FieldDescriptorMap` | typeAlias | Field descriptors keyed by form value path. |
| `FormCsrfInputProps` | interface | Props for the hidden CSRF token input. |
| `FormElementProps` | interface | Props applied to the root form element. |
| `FormErrorMessages` | typeAlias | Ordered validation messages for a field or form. |
| `FormFieldErrors` | typeAlias | Canonical field and form error map for submitted values. |
| `FormFieldPath` | typeAlias | Dot-path name for a field in nested form values. |
| `FormIntent` | interface | Structured representation of an encoded form intent. |
| `FormIntentResult` | interface | Result returned after applying an encoded form intent. |
| `FormReplyHelpers` | interface | Factory helpers for constructing typed form submission results. |
| `FormReplyInit` | interface | Base input used to construct a form reply state. |
| `FormSubmissionErrorResult` | interface | Errored form submission state. |
| `FormSubmissionInitialResult` | interface | Initial form submission state. |
| `FormSubmissionInvalidResult` | interface | Invalid form submission state. |
| `FormSubmissionRedirectResult` | interface | Redirect form submission state. |
| `FormSubmissionResult` | typeAlias | Union of all form submission result states. |
| `FormSubmissionSuccessResult` | interface | Successful form submission state. |
| `FormValues` | typeAlias | Generic constraint for form value objects. |
| `InferDefinePageLayerLoaderProps` | typeAlias |  |
| `IntentButtonProps` | interface | Props for an intent submit button generated by a form field helper. |
| `InvalidFormReplyInit` | interface | Input used to construct an invalid form reply. |
| `LabelProps` | interface | Props applied to a field label. |
| `PageBuildOptions` | interface | Build options accepted by `page.build(...)`. |
| `PageBuilder` | interface | Public fluent page builder surface. |
| `PageCacheEntry` | interface | Minimal cache-entry shape accepted by page layer loaders. |
| `PageContext` | interface | Runtime context shared by loaders, handlers, layouts, and metadata resolvers. |
| `PageDeferPolicyInput` | interface | Typed defer policy override accepted by `withPolicy()`. |
| `PageDeferPolicyProfile` | typeAlias | Typed defer policy profile accepted by `withPolicy()`. |
| `PageDefinition` | interface | Unrouted page definition returned by `build()` without a route. |
| `PageErrorPrimitives` | interface | Minimal error payload accepted by builder-owned partial error components. |
| `PageFormConfig` | interface | Configuration for the `withForm()` builder method (legacy `PageBuilder` |
| `PageFormHandlerContext` | interface | Extended context exposed to `withForm()` callbacks. |
| `PageHandlers` | typeAlias | Built page handlers returned by `build()`. |
| `PageHeaderResolver` | typeAlias | Header resolver accepted by `withHeader()`. |
| `PageHooks` | interface | Hook bundle returned on routed page definitions. |
| `PageLayerConfig` | interface | Config object accepted by `withLayer()`. |
| `PageLayerDelivery` | typeAlias | Delivery mode for a deferred page layer. |
| `PageLayerLoader` | typeAlias | Async loader accepted by `withLayer()`. |
| `PageLayerMap` | typeAlias | Layer props keyed by layer id. |
| `PageLayout` | typeAlias | Layout function accepted by `withLayout()`. |
| `PageLayoutContext` | interface | Runtime context variant used for page layouts and metadata. |
| `PageLinkProps` | interface | Link props returned by builder-owned route helpers. |
| `PageMetaDescriptor` | interface | Metadata descriptor accepted by `withMeta()`. |
| `PageMetaResolver` | typeAlias | Metadata resolver accepted by `withMeta()`. |
| `PageMethod` | typeAlias | HTTP methods accepted by `withHandler()`. |
| `PageMethodHandler` | typeAlias | Handler function accepted by `withHandler()`. |
| `PagePairedRouteHrefInput` | typeAlias | Input accepted by paired page/partial route helpers. |
| `PagePairedRouteTarget` | interface | Combined page/partial route helper returned by `route.withPartial(...)`. |
| `PagePartialLinkProps` | interface | Link props produced by paired page/partial route helpers. |
| `PagePathParamInput` | typeAlias | Raw path input keyed by dynamic segment name. |
| `PagePathSchema` | interface | Minimal path schema contract accepted by `definePage()`. |
| `PageRenderContext` | interface | Request context variant used when a page can call `ctx.render()`. |
| `PageRenderable` | typeAlias | Renderable content accepted by builder-owned components, layouts, and slots. |
| `PageRequestContext` | interface | Typed request context exposed to page builders. |
| `PageResourceFactory` | typeAlias | Resource factory accepted by `withResource()` and `withResources()`. |
| `PageRootBuilder` | interface | Root page builder returned by `definePage()`. |
| `PageRouteGetLinkPropsInput` | typeAlias | Input accepted by builder-owned bound route link-prop helpers. |
| `PageRouteHrefInput` | typeAlias | Input accepted by builder-owned route href helpers. |
| `PageRouteLinkComponentProps` | typeAlias | Props accepted by builder-owned route link components. |
| `PageRouteNavigation` | interface | Typed route navigation surface exposed by routed pages. |
| `PageRoutePath` | typeAlias | Infer the typed path state from a route target. |
| `PageRouteReference` | interface | Minimal route reference accepted by `withRoute()`. |
| `PageRouteSearch` | typeAlias | Infer the typed search state from a route target. |
| `PageRouteTarget` | interface | Minimal route target accepted by `withRoute()`. |
| `PageSchemaParseFailure` | interface | Failure result returned by page-owned schemas. |
| `PageSchemaParseResult` | typeAlias | Result returned by page-owned path and search schemas. |
| `PageSchemaParseSuccess` | interface | Success result returned by page-owned schemas. |
| `PageSearchParamInput` | typeAlias | Raw search input keyed by query param name. |
| `PageSearchParamValue` | typeAlias | Raw search-param value accepted by route helpers. |
| `PageSearchSchema` | interface | Minimal search schema contract accepted by `definePage()`. |
| `PageSlot` | typeAlias | Slot function exposed to layouts for a resolved layer. |
| `PageSlots` | typeAlias | Slot map exposed to layouts. |
| `PageTelemetryConfig` | interface | Typed telemetry configuration accepted by `withTelemetry()`. |
| `PartialRouteConfig` | interface | Minimal route config surface emitted by framework partial routes. |
| `RedirectFormReplyInit` | interface | Input used to construct a redirect form reply. |
| `RoutedPageDefinition` | interface | Routed page definition returned by `build()` with route metadata. |
| `RuntimeFormState` | interface | Runtime state passed to a form layer component. |
| `SchemaInput` | typeAlias | Infer the input object accepted by a schema-like value. |
| `SchemaOutput` | typeAlias | Infer the output object carried by a schema-like value. |
| `Simplify` | typeAlias | Flatten mapped and intersected object types for cleaner IntelliSense. |
| `SuccessFormReplyInit` | interface | Input used to construct a successful form reply. |
| `UnknownRecord` | typeAlias | Generic object map used by resources and layer registries. |

## `@netscript/fresh/route`

Explicit, typed route-contract surface: route contracts, path and search schemas, and navigation helpers.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `bindRoutePattern` | `bindRoutePattern(contract: DefineRouteContract, routePattern: string, metadata?: RouteReferenceOptions): BoundRouteContract` | Bind a route contract to a concrete Fresh route pattern. |
| `createRouteReference` | `createRouteReference(routePattern: TRoutePattern, metadata?: RouteReferenceOptions): RouteReference` | Build a route reference directly from a Fresh route pattern. |
| `defineEnumPathParam` | `defineEnumPathParam(paramName: TParamName, values: TValues): EnumPathParamDefinition` | Create a reusable enum-backed path param helper. |
| `defineRouteContract` | `defineRouteContract(_): DefineRouteContract` | Define a typed route contract around optional path and search schemas. |
| `enumPathParamSchema` | `enumPathParamSchema(paramName: TParamName, values: TValues): PathParamSchema` | Create an enum-backed path schema for a single dynamic route segment. |
| `fallback` | `fallback(schema: TSchema, defaultValue: SchemaFieldOutput): TSchema` | Apply a fallback value to a Zod search-param field. |
| `paginationSearchSchema` | `paginationSearchSchema(_): PaginationSearchSchema` | Create a pagination-aware search schema with typed defaults. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `BoundRouteContract` | typeAlias | Bound route reference created from a route contract and concrete route pattern. |
| `DefineRouteContract` | interface | Public route contract produced by `defineRouteContract()`. |
| `DefineRouteContractOptions` | interface | Contract options for defining typed route path and search schemas. |
| `EmptyRecord` | typeAlias | Empty object shape used by route helpers without typed params. |
| `EnumPathParamDefinition` | interface | Enum-backed path param definition returned by `defineEnumPathParam()`. |
| `FreshLinkAttributes` | interface | Fresh-compatible anchor attributes returned by route helpers. |
| `FreshPartialLinkAttributes` | interface | Fresh-compatible partial link attributes returned by paired routes. |
| `InferRouteContractPath` | typeAlias | Infer the typed path state carried by a route contract or route reference. |
| `InferRouteContractSearch` | typeAlias | Infer the typed search state carried by a route contract or route reference. |
| `InferRoutePatternPath` | typeAlias | Infer typed path params directly from a Fresh route pattern. |
| `InferRoutePatternPathSegments` | typeAlias | Infer typed path params from the stripped Fresh route pattern. |
| `InferRoutePatternSegment` | typeAlias | Infer one typed path segment from a Fresh route pattern segment. |
| `PaginationSearchBaseShape` | interface | Base schema shape returned by `paginationSearchSchema()`. |
| `PaginationSearchSchema` | interface | Public facade for pagination-aware query string parsing. |
| `PaginationSearchSchemaOptions` | interface | Options for the default pagination search schema. |
| `PaginationSearchState` | interface | Typed output produced by pagination search schemas. |
| `PairedRouteHrefArgs` | typeAlias | Variadic args accepted by paired route href builders. |
| `PairedRouteHrefInput` | typeAlias | Input accepted by paired page/partial route helpers. |
| `PairedRouteLinkPropsInput` | typeAlias | Input accepted by paired-route `getLinkProps()`. |
| `PairedRouteTarget` | interface | Combined page/partial route helper returned by `route.withPartial(...)`. |
| `PathParamInput` | typeAlias | Raw path input keyed by dynamic segment name. |
| `PathParamSchema` | interface | Minimal schema contract accepted for route path params. |
| `RouteContractTypeCarrier` | interface | Public type carrier used by route contracts and route references. |
| `RouteHrefArgs` | typeAlias | Variadic args accepted by route href builders. |
| `RouteHrefInput` | typeAlias | Input accepted by `route.nav.makeHref()`. |
| `RouteLinkComponentProps` | typeAlias | Props accepted by the route-bound Fresh link component. |
| `RouteLinkPropsInput` | typeAlias | Input accepted by `route.getLinkProps()`. |
| `RouteNavigation` | interface | Minimal typed route navigation API exposed to consumers. |
| `RoutePathInput` | typeAlias | Path input accepted by route href builders. |
| `RouteReference` | interface | Stable route reference returned by route contracts and generated manifests. |
| `RouteReferenceKind` | typeAlias | Route metadata classification used by generated route manifests. |
| `RouteReferenceOptions` | interface | Optional metadata attached to generated route references. |
| `RouteSearchUpdate` | typeAlias | Input used when partially updating typed search state. |
| `SchemaField` | interface | Structural schema contract accepted by pagination search helpers. |
| `SchemaFieldOutput` | typeAlias | Infer the output carried by a schema-like field. |
| `SchemaOutput` | typeAlias | Infer the output object carried by a route schema. |
| `SchemaParseFailure` | interface | Failed schema parse result. |
| `SchemaParseResult` | typeAlias | Result returned by route path and search schemas. |
| `SchemaParseSuccess` | interface | Successful schema parse result. |
| `SearchParamInput` | typeAlias | Raw search input keyed by query param name. |
| `SearchParamSchema` | interface | Minimal schema contract accepted for route search params. |
| `SearchParamValue` | typeAlias | Primitive search-param value accepted by route helpers. |
| `ShapeOutput` | typeAlias | Infer the resolved object output carried by a pagination schema shape. |
| `StripLeadingSlash` | typeAlias | Strip a leading slash from a Fresh route pattern. |
| `ValidatedRouteHref` | typeAlias | Stable href string returned by validated route navigation helpers. |

## `@netscript/fresh/defer`

Deferred rendering primitives: server and island defer wrappers, policy resolution, and telemetry spans.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `DeferComponent` | `DeferComponent(props: DeferComponentProps): object` | Hidden client-side form that revalidates deferred regions when policy allows it. |
| `DeferPage` | `DeferPage(props: DeferPageProps): object` | Render a deferred region with optional server prewarm and telemetry hooks. |
| `Deferred` | `Deferred(props: DeferredProps): DeferredRenderable` | Promise-prop consumer for RFC-style deferred data. |
| `buildDeferFormState` | `buildDeferFormState(searchParams?: string, partialSearchParams?: string)` | Build the hidden form state used by the defer island. |
| `decideDeferClientAction` | `decideDeferClientAction(input: DeferClientDecisionInput): DeferClientDecision` | Decide whether the client island should submit or skip its deferred refresh form. |
| `emitDeferCacheReadSpan` | `emitDeferCacheReadSpan(input: DeferCacheReadSpanInput): Promise` | Emit a span for reading a defer region from cache. |
| `emitDeferClientDecisionSpan` | `emitDeferClientDecisionSpan(attributes: FreshDeferTelemetryAttributes): Promise` | Emit a span for a client-side defer decision. |
| `emitDeferPrewarmDispatchSpan` | `emitDeferPrewarmDispatchSpan(input: DeferPrewarmSpanInput, run): Promise` | Emit a span that wraps a defer prewarm dispatch operation. |
| `emitStreamRenderSpan` | `emitStreamRenderSpan(input: StreamRenderSpanInput, run): Promise` | Emit an OpenTelemetry span that wraps a streaming SSR render. |
| `resolveDeferPolicy` | `resolveDeferPolicy(policy, staleTimeOverrideMs, staleStrategy): DeferPolicyResolved` | Resolve user policy input, stale overrides, and legacy strategy into a complete policy. |
| `resolveDetailDeferConfig` | `resolveDetailDeferConfig(hasCompleteCache: boolean)` | Resolve the detail-page stale window and defer policy for the current cache state. |
| `sanitizeDeferSearchParams` | `sanitizeDeferSearchParams(searchParams?: string)` | Remove Fresh transport-only query parameters from a serialized query string. |

### Constants

| Symbol | Type | Description |
| --- | --- | --- |
| `DEFER_POLICY` |  | Conventional defer policy profiles used by generated pages. |
| `DEFER_STALE_MS` |  | Conventional stale windows used by generated CRUD pages. |
| `DETAIL_FORCE_REFRESH_POLICY` | `DeferPolicyInput` | Detail-page policy that preserves immediate consistency after navigation. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `DeferCacheReadSpanInput` | interface | Input attributes used by a defer cache-read span. |
| `DeferClientDecision` | interface | Client-side deferred refresh decision. |
| `DeferClientDecisionInput` | interface | Inputs used to decide whether a deferred region should refresh on the client. |
| `DeferClientDecisionReason` | typeAlias | Reasons the client island can choose to submit or skip a deferred refresh. |
| `DeferComponentProps` | interface | Props consumed by the hidden client-side defer form. |
| `DeferPagePolicyInput` | interface | Policy overrides accepted by the page wrapper. |
| `DeferPagePolicyProfile` | typeAlias | Named defer policy profiles accepted by the page wrapper. |
| `DeferPageProps` | interface | Props for the `DeferPage` server wrapper. |
| `DeferPageRenderable` | typeAlias | Renderable content accepted by deferred page slots. |
| `DeferPageRequestContextLike` | interface | Fresh request fields consumed by `DeferPage` without depending on app-local ctx types. |
| `DeferPolicyInput` | interface | Policy overrides that tune when deferred regions refresh. |
| `DeferPolicyProfile` | typeAlias | Named policy profiles for deferred rendering freshness behavior. |
| `DeferPolicyResolved` | interface | Fully resolved defer policy used by server and island renderers. |
| `DeferPrewarmResult` | interface | Result metrics captured by a defer prewarm dispatch. |
| `DeferPrewarmSpanInput` | interface | Input attributes used by a defer prewarm dispatch span. |
| `DeferredProps` | interface | Props for the `Deferred` Suspense helper. |
| `DeferredRenderFunction` | typeAlias | Render function used to turn resolved deferred data into content. |
| `DeferredRenderable` | typeAlias | Renderable content accepted by deferred Suspense slots. |
| `FreshDeferTelemetryAttributes` | typeAlias | Attribute map accepted by Fresh defer telemetry helpers. |
| `LegacyStaleStrategy` | typeAlias | Legacy stale strategy accepted by older defer call sites. |
| `StreamRenderSpanInput` | interface | Input for a streaming render telemetry span. |
| `StreamRenderSpanResult` | interface | Result metrics captured after the streaming render completes. |

## `@netscript/fresh/form`

Managed forms: CSRF, intents, progressive enhancement, pagination, and Standard Schema validation.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `Form` | `Form(props: FormProps): object` | Render a managed form element with submission and CSRF hidden inputs. |
| `FormRegion` | `FormRegion(props: FormRegionProps): object` | Render a Fresh partial boundary for form-driven updates. |
| `applyCollectionStrategy` | `applyCollectionStrategy(props: TProps, strategy)` | Apply collection update navigation metadata to intent button props. |
| `applyIntentOperation` | `applyIntentOperation(intent, values: TValues): TValues` | Apply a collection intent to the submitted values. |
| `buildPaginationState` | `buildPaginationState(searchParams: URLSearchParams, total: number, hasMore: boolean, defaultLimit: number): PaginationState` | Build a complete pagination state from URLSearchParams and query results. |
| `collectionIntent` | `collectionIntent(action, name: string, _): string` | Serialize a collection intent into the native field value shape. |
| `createEmptyFormErrors` | `createEmptyFormErrors(): FormErrors` | Create an empty form error map. |
| `createFormEnhancementSnapshot` | `createFormEnhancementSnapshot(state: RuntimeFormState): FormEnhancementSnapshot` | Create a serializable client enhancement snapshot from runtime form state. |
| `createStandardSchemaAdapter` | `createStandardSchemaAdapter(schema: TSchema): FormSchemaAdapter` | Create a form schema adapter from any Standard Schema v1 compatible schema. |
| `firstFieldError` | `firstFieldError(errors: FormErrors, field: Extract)` | Return the first error message for a field, if present. |
| `formDataToRawValues` | `formDataToRawValues(formData: FormData): Record` | Parse a `FormData` instance into a nested object. |
| `generateCsrfToken` | `generateCsrfToken(): string` | Generate a new CSRF token for a rendered form. |
| `generateSubmissionId` | `generateSubmissionId(): string` | Create a new form submission identifier. |
| `getSubmissionHiddenInputProps` | `getSubmissionHiddenInputProps(submissionId: string)` | Return the hidden input props for carrying an idempotent submission id. |
| `normalizeFormValues` | `normalizeFormValues(rawValues: Record): Partial` | Normalize raw form values by converting empty strings to `undefined`. |
| `parseFormIntent` | `parseFormIntent(rawValues: Record)` | Parse an encoded form intent from raw posted values. |
| `readCsrfToken` | `readCsrfToken(request: Request)` | Read the current CSRF token from a request cookie header. |
| `resolveFormState` | `resolveFormState(data: unknown, _): FormState` | Resolve form state from route handler data. |
| `resolvePagination` | `resolvePagination(searchParams: URLSearchParams, defaultLimit: number): PaginationInput` | Resolve pagination input from URLSearchParams. |
| `setCsrfCookie` | `setCsrfCookie(headers: Headers, token: string, requestUrl?: URL): void` | Set the CSRF cookie on response headers. |
| `submitIntent` | `submitIntent(_): string` | Serialize a submit intent into the native field value shape. |
| `toFormErrors` | `toFormErrors(error: FormSchemaValidationError): FormErrors` | Convert a Zod-like validation error into the canonical `FormErrors<T>` shape. |
| `useFormEnhancement` | `useFormEnhancement(snapshot: FormEnhancementSnapshot, _): FormEnhancementState` | Manage progressive form enhancement state and client-side validation handlers. |
| `verifyCsrfToken` | `verifyCsrfToken(cookieToken, formToken): boolean` | Verify that the submitted token matches the cookie token. |

### Constants

| Symbol | Type | Description |
| --- | --- | --- |
| `CSRF_COOKIE_NAME` | `ns_form_csrf` | Cookie used to persist the current CSRF token between GET and POST. |
| `CSRF_FIELD_NAME` | `__csrf__` | Hidden input field used to submit the CSRF token with the form payload. |
| `INTENT_FIELD_NAME` | `__intent__` | Field name reserved for encoded form intents. |
| `SUBMISSION_ID_FIELD_NAME` | `__submission_id__` | Hidden field used to round-trip a submission identifier through form POSTs. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `CollectionDescriptor` | interface | Descriptor for a collection field and its item intent buttons. |
| `CollectionItem` | interface | Descriptor for one item in a collection field. |
| `CollectionKeyInputProps` | interface | Props for a hidden collection-key input. |
| `CollectionKeyMap` | typeAlias | Stable collection item keys by collection field path. |
| `ControlProps` | interface | Props applied to an input, select, textarea, or compatible control. |
| `DescriptionProps` | interface | Props applied to a field description element. |
| `EnhancedFormProps` | interface | Form element props after progressive enhancement handlers are attached. |
| `ErrorFormReplyInit` | interface | Input used to construct an errored form reply. |
| `ErrorProps` | interface | Props applied to a field error element. |
| `FieldConstraints` | interface | HTML constraint attributes derived from a schema field. |
| `FieldDescriptor` | interface | Descriptor for one form field and its generated props. |
| `FieldDescriptorMap` | typeAlias | Field descriptors keyed by form value path. |
| `FormCollectionStrategy` | interface | Client/server ownership policy for a collection field. |
| `FormCollectionStrategyMode` | typeAlias | Progressive enhancement strategy for collection fields. |
| `FormContent` | typeAlias | Renderable content accepted by form helper components. |
| `FormCsrfInputProps` | interface | Props for the hidden CSRF token input. |
| `FormElementProps` | interface | Props applied to the root form element. |
| `FormEnhancementOptions` | interface | Options used to progressively enhance a rendered form. |
| `FormEnhancementSnapshot` | interface | Snapshot consumed by progressive enhancement code for one form. |
| `FormEnhancementState` | interface | Runtime state returned by the progressive form enhancement hook. |
| `FormErrorMessages` | typeAlias | Ordered validation messages for a field or form. |
| `FormErrors` | typeAlias | Field-level error map produced by validation or error normalization. |
| `FormFieldErrors` | typeAlias | Canonical field and form error map for submitted values. |
| `FormFieldPath` | typeAlias | Dot-path name for a field in nested form values. |
| `FormIntent` | interface | Structured representation of an encoded form intent. |
| `FormIntentResult` | interface | Result returned after applying an encoded form intent. |
| `FormPageInvalidateContext` | interface | Invalidation context passed to app-owned cache invalidators after a |
| `FormPageMode` | typeAlias | Mode used by page-owned create/edit forms in the playground consumer. |
| `FormPageProps` | interface | Transitional page-form props still consumed by the playground routes while |
| `FormProps` | interface | Props accepted by the managed form component. |
| `FormRegionProps` | interface | Props accepted by the form partial-region helper. |
| `FormReplyHelpers` | interface | Factory helpers for constructing typed form submission results. |
| `FormReplyInit` | interface | Base input used to construct a form reply state. |
| `FormSchemaAdapter` | interface | Validation boundary abstraction for forms. |
| `FormSchemaParseFailure` | interface | Failed schema parse result normalized for the form runtime. |
| `FormSchemaParseResult` | typeAlias | Adapter-safe parse result used by the canonical form runtime. |
| `FormSchemaParseSuccess` | interface | Successful schema parse result. |
| `FormSchemaValidationError` | interface | Minimal contract for a validation error that can be flattened into |
| `FormState` | interface | Lightweight form state used by the currently shipped helper surface. |
| `FormStateLike` | typeAlias | Server or client snapshot state accepted by the managed form component. |
| `FormSubmissionErrorResult` | interface | Errored form submission state. |
| `FormSubmissionInitialResult` | interface | Initial form submission state. |
| `FormSubmissionInvalidResult` | interface | Invalid form submission state. |
| `FormSubmissionRedirectResult` | interface | Redirect form submission state. |
| `FormSubmissionResult` | typeAlias | Union of all form submission result states. |
| `FormSubmissionSuccessResult` | interface | Successful form submission state. |
| `FormValues` | typeAlias | Generic constraint for form value objects. |
| `IntentButtonProps` | interface | Props for an intent submit button generated by a form field helper. |
| `InvalidFormReplyInit` | interface | Input used to construct an invalid form reply. |
| `LabelProps` | interface | Props applied to a field label. |
| `PaginationInput` | interface | Parsed pagination input derived from URLSearchParams. |
| `PaginationState` | interface | Full pagination state including total count and original search params. |
| `RedirectFormReplyInit` | interface | Input used to construct a redirect form reply. |
| `RuntimeFormState` | interface | Runtime state passed to a form layer component. |
| `SchemaIntrospector` | interface | Vendor-specific schema metadata extractor. |
| `StandardSchemaInput` | typeAlias | Infer the input value type from a Standard Schema. |
| `StandardSchemaIssue` | interface | Validation issue reported by a Standard Schema compatible library. |
| `StandardSchemaOutput` | typeAlias | Infer the output value type from a Standard Schema. |
| `StandardSchemaPathSegment` | typeAlias | Path segment shape accepted by Standard Schema issues. |
| `StandardSchemaResult` | typeAlias | Validation result returned by a Standard Schema compatible schema. |
| `StandardSchemaV1` | interface | Structural Standard Schema v1 contract consumed by the form adapter. |
| `SuccessFormReplyInit` | interface | Input used to construct a successful form reply. |

## `@netscript/fresh/error`

Explicit error-handling surface: normalized error payloads, loader fallbacks, and error display components.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `ErrorDisplay` | `ErrorDisplay(props: ErrorDisplayProps): ErrorDisplayContent` | Render normalized Fresh error data with an overridable presentation slot. |
| `InlineError` | `InlineError(props): ErrorDisplayContent` | Render normalized Fresh error data in a compact inline layout. |
| `classifyErrorType` | `classifyErrorType(status: number): ErrorType` | Classify an HTTP status code into the Fresh error taxonomy. |
| `errorHandler` | `errorHandler(loader, fallback: T)` | Wrap a loader and return fallback data when it throws. |
| `extractData` | `extractData(result: LoaderResult): T` | Extract success data after the caller has checked `hasError()`. |
| `extractDataWithFallback` | `extractDataWithFallback(result: LoaderResult): T` | Extract fallback data from an errored loader result. |
| `extractErrorData` | `extractErrorData(error: unknown): ErrorData` | Extract a normalized Fresh error payload from any thrown value. |
| `extractErrorWithFallback` | `extractErrorWithFallback(result: LoaderResult)` | Extract normalized error data and fallback data from an errored loader result. |
| `getDefaultMessage` | `getDefaultMessage(status: number): string` | Return the default user-facing message for a known HTTP status code. |
| `hasError` | `hasError(result: LoaderResult): result is` | Return whether a loader result contains normalized error data and fallback data. |
| `isRetryable` | `isRetryable(status: number, type: ErrorType): boolean` | Return whether a status and type combination should offer retry affordances. |
| `safeParseData` | `safeParseData(result: LoaderResult)` | Return success data or `null` when the loader result contains an error. |
| `safeParseDataWithFallback` | `safeParseDataWithFallback(result: LoaderResult): T` | Return success data or fallback data from a loader result. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `ErrorData` | interface | Normalized error payload for loaders, handlers, and error displays. |
| `ErrorDisplayContent` | typeAlias | Renderable content accepted and returned by Fresh error display helpers. |
| `ErrorDisplayProps` | interface | Props accepted by the default Fresh error display component. |
| `ErrorPrimitives` | interface | Shared error-display payload used by package-owned and app-owned error views. |
| `ErrorType` | typeAlias | HTTP-derived error category used by Fresh error rendering helpers. |
| `LoaderResult` | typeAlias | Loader result returned by `errorHandler()`. |

## `@netscript/fresh/streams`

Client SDK for end-to-end durable streams backed by a TanStack DB StreamDB.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `createNetScriptStreamDB` | `createNetScriptStreamDB(options: NetScriptStreamDBOptions): NetScriptStreamDB` | Create a NetScript-configured TanStack DB-backed StreamDB. |
| `useLiveQuery` | `useLiveQuery(queryFactory: NetScriptLiveQueryFactory, deps?): NetScriptLiveQueryResult` | Run a TanStack DB live query through the NetScript Fresh streams surface. |
| `useLiveSuspenseQuery` | `useLiveSuspenseQuery(queryFactory: NetScriptLiveQueryFactory, deps?): NetScriptLiveQueryResult` | Run a TanStack DB suspense live query through the NetScript Fresh streams surface. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `NetScriptLiveQueryFactory` | typeAlias | Function that builds a live query from the upstream query builder. |
| `NetScriptLiveQueryResult` | interface | Result returned by NetScript live-query wrappers. |
| `NetScriptStateSchema` | typeAlias | NetScript-owned state schema accepted by the stream DB factory. |
| `NetScriptStreamDB` | interface | NetScript-owned stream database handle returned by the factory. |
| `NetScriptStreamDBFactory` | typeAlias | Factory port used to create a durable stream DB handle. |
| `NetScriptStreamDBFactoryInput` | interface | Input passed to the underlying stream DB factory port. |
| `NetScriptStreamDBOptions` | interface | Options for `createNetScriptStreamDB`. |
| `NetScriptStreamStateDefinition` | typeAlias | NetScript-owned durable stream state definition. |

## `@netscript/fresh/query`

TanStack Query hooks and hydration helpers scoped to Fresh islands.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `HydrationBoundary` | `HydrationBoundary(props: HydrationBoundaryProps): object` | Hydrate the island QueryClient from direct state or a JSON script tag. |
| `QueryHydrationScript` | `QueryHydrationScript(props: QueryHydrationScriptProps): object` | Render a JSON script tag containing dehydrated query state. |
| `QueryIsland` | `QueryIsland(props: QueryIslandProps): object` | Island-level TanStack Query provider. |
| `dehydrateQueryClient` | `dehydrateQueryClient(queryClient: IslandQueryClient): DehydratedState` | Dehydrate a QueryClient into a serializable state object. |
| `getIslandQueryClient` | `getIslandQueryClient(): IslandQueryClient` | Get (or create) the shared island `QueryClient`. |
| `hydrateFromDehydrated` | `hydrateFromDehydrated(queryClient: IslandQueryClient, dehydratedState: DehydratedState): void` | Hydrate a client-side QueryClient from a server-dehydrated state. |
| `resetIslandQueryClient` | `resetIslandQueryClient(): void` | Reset the island QueryClient singleton. |
| `useInfiniteQuery` | `useInfiniteQuery(options: IslandInfiniteQueryOptions): IslandInfiniteQueryResult` | Run an island infinite query through the canonical NetScript Fresh query surface. |
| `useIsFetching` | `useIsFetching(filters?: IslandQueryFilters): number` | Count active island queries matching the optional filters. |
| `useIsMutating` | `useIsMutating(filters?: IslandQueryFilters): number` | Count active island mutations matching the optional filters. |
| `useIslandInfiniteQuery` | `useIslandInfiniteQuery(options: IslandInfiniteQueryOptions): IslandInfiniteQueryResult` | Run an island infinite query through the shared NetScript Fresh QueryClient. |
| `useIslandMutation` | `useIslandMutation(options: IslandMutationOptions): IslandMutationResult` | Run an island mutation through the shared NetScript Fresh QueryClient. |
| `useIslandQuery` | `useIslandQuery(options: IslandQueryOptions): IslandQueryResult` | Run an island query through the shared NetScript Fresh QueryClient. |
| `useIslandSuspenseInfiniteQuery` | `useIslandSuspenseInfiniteQuery(options: IslandInfiniteQueryOptions): IslandInfiniteQueryResult` | Run a suspense island infinite query through the shared NetScript Fresh QueryClient. |
| `useIslandSuspenseQuery` | `useIslandSuspenseQuery(options: IslandQueryOptions): IslandSuspenseQueryResult` | Run a suspense island query through the shared NetScript Fresh QueryClient. |
| `useLiveQuery` | `useLiveQuery(queryFactory: IslandLiveQueryFactory, deps?): IslandLiveQueryResult` | Run an island live query through the NetScript Fresh query surface. |
| `useLiveSuspenseQuery` | `useLiveSuspenseQuery(queryFactory: IslandLiveQueryFactory, deps?): IslandLiveQueryResult` | Run an island suspense live query through the NetScript Fresh query surface. |
| `useMutation` | `useMutation(options: IslandMutationOptions): IslandMutationResult` | Run an island mutation through the canonical NetScript Fresh query surface. |
| `useQuery` | `useQuery(options: IslandQueryOptions): IslandQueryResult` | Run an island query through the canonical NetScript Fresh query surface. |
| `useQueryClient` | `useQueryClient(): IslandQueryClient` | Return the active island QueryClient handle. |
| `useSuspenseInfiniteQuery` | `useSuspenseInfiniteQuery(options: IslandInfiniteQueryOptions): IslandInfiniteQueryResult` | Run an island suspense infinite query through the canonical NetScript Fresh query surface. |
| `useSuspenseQuery` | `useSuspenseQuery(options: IslandQueryOptions): IslandSuspenseQueryResult` | Run an island suspense query through the canonical NetScript Fresh query surface. |

### Constants

| Symbol | Type | Description |
| --- | --- | --- |
| `DEFAULT_QUERY_HYDRATION_SCRIPT_ID` | `__netscript_query_state__` | Default script id used for serialized NetScript query state. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `DehydratedState` | interface | State produced by server-side query dehydration. |
| `HydrationBoundaryProps` | interface | Props for `HydrationBoundary`. |
| `InitialDataFor` | typeAlias | Extract initial data from a query-options object. |
| `IslandInfiniteQueryOptions` | interface | Options accepted by `useIslandInfiniteQuery`. |
| `IslandInfiniteQueryResult` | interface | Result of an island infinite query hook call. |
| `IslandLiveQueryFactory` | typeAlias | Function that builds a live query from the upstream query builder. |
| `IslandLiveQueryResult` | interface | Result returned by NetScript live-query wrappers. |
| `IslandMutationOptions` | interface | Options accepted by `useIslandMutation`. |
| `IslandMutationResult` | interface | Result of an island mutation hook call. |
| `IslandQueryClient` | interface | Client handle returned by the island query-client factory. |
| `IslandQueryFilters` | interface | Filters accepted by query/mutation activity counters. |
| `IslandQueryOptions` | interface | Options accepted by `useIslandQuery`. |
| `IslandQueryResult` | interface | Result of an island query hook call. |
| `IslandSuspenseQueryResult` | interface | Result of a suspense island query hook call. |
| `LoaderData` | typeAlias | Resolve the awaited return value from a Fresh route loader. |
| `QueryHydrationScriptProps` | interface | Props for `QueryHydrationScript`. |
| `QueryIslandChildren` | typeAlias | Renderable children accepted by the query island provider. |
| `QueryIslandProps` | interface | Props for the `QueryIsland` wrapper. |
| `QueryJsonValue` | typeAlias | JSON-compatible value accepted by island query hydration helpers. |
| `QueryKey` | typeAlias | Stable query key shape used by NetScript Fresh query wrappers. |

## `@netscript/fresh/interactive`

Browser-facing interactive helpers using the Suspense throw-promise protocol.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `resolvedPromise` | `resolvedPromise(value: T): Promise` | Create a promise already primed as fulfilled for `usePromise()`. |
| `usePromise` | `usePromise(promise: Promise): T` | Read a promise using the Suspense throw-promise protocol. |

## `@netscript/fresh/vite`

The NetScript Fresh Vite plugin for aliases, env mapping, and route manifest generation.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `createNetScriptVitePlugin` | `createNetScriptVitePlugin(_): NetScriptVitePlugin` | Create the NetScript Fresh Vite plugin for aliases, env mapping, and route manifests. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `NetScriptRouteManifestOptions` | interface | Options controlling the NetScript route manifest generator. |
| `NetScriptViteAlias` | interface | Resolved Vite alias entry generated or accepted by the NetScript Vite plugin. |
| `NetScriptViteEnvMapping` | interface | Environment variable mapping injected into `import.meta.env`. |
| `NetScriptVitePlugin` | interface | Package-owned view of the Vite plugin hooks used by NetScript Fresh. |
| `NetScriptVitePluginOptions` | interface | Options accepted by the NetScript Fresh Vite plugin. |

## `@netscript/fresh/testing`

Testing fixtures: mock route contexts and defer policies for consumer tests.

### Functions and components

| Symbol | Signature | Description |
| --- | --- | --- |
| `createMockDeferPolicy` | `createMockDeferPolicy(_)` | Create a defer policy fixture accepted by defer-region helpers. |
| `createMockRouteContext` | `createMockRouteContext(_): MockRouteContext` | Create a minimal page context fixture for route, loader, and layout tests. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `MockDeferPolicyInput` | interface | Mock defer policy override accepted by defer test fixtures. |
| `MockDeferPolicyProfile` | typeAlias | Mock defer policy profile names accepted by defer test fixtures. |
| `MockRouteContext` | interface | Mock route context returned by `createMockRouteContext()`. |
| `MockRouteContextOptions` | interface | Options used to construct a route context fixture. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/fresh/_

---

# `@netscript/kv`

Reactive key-value storage with a unified API across Deno KV, Redis, and in-memory backends. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/kv`) exposes the stable shared lifecycle API, the portable KV types, and the lightweight Deno KV and in-memory adapters. Three sub-path exports carry the heavier integrations:

- [`@netscript/kv/redis`](#sub-path-exports) — the Redis-backed adapter (self-registers the `'redis'` provider on import).
- [`@netscript/kv/kvdex`](#sub-path-exports) — the [kvdex](https://jsr.io/@olli/kvdex) bridge factory and re-exported kvdex core APIs.
- [`@netscript/kv/testing`](#sub-path-exports) — the shared KV port contract harness for adapter authors.

## Shared lifecycle

The shared singleton resolves a provider once (auto-detecting from the environment) and hands back a `WatchableKv` for the rest of the process.

| Symbol | Signature | Description |
| --- | --- | --- |
| `getKv` | `function getKv(config?: SharedKvConfig): Promise<WatchableKv>` | Resolve the shared `WatchableKv` singleton, initializing on first access. |
| `getRawKv` | `async function getRawKv(config?: SharedKvConfig): Promise<Deno.Kv>` | Resolve the raw `Deno.Kv` instance when the shared provider is Deno KV. |
| `getActiveProvider` | `function getActiveProvider(): KvProvider \| null` | Return the currently active provider, or `null` before initialization. |
| `getKvPath` | `function getKvPath(): string \| undefined` | Return the Deno KV path currently in use, or the discovered default. |
| `getRedisConnectionFromEnv` | `function getRedisConnectionFromEnv(): string \| undefined` | Read a normalized Redis connection string from the environment. |
| `isKvInitialized` | `function isKvInitialized(): boolean` | Check whether the shared adapter has been initialized. |
| `isWatchable` | `function isWatchable(store: KvStore): store is WatchableKv` | Type guard for stores that implement the `WatchableKv` contract. |
| `resetKv` | `async function resetKv(): Promise<void>` | Reset the shared state for tests or isolated validation runs. |
| `closeKv` | `async function closeKv(): Promise<void>` | Close and clear the shared adapter state. |

## Adapters

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `DenoKvAdapter` | class | `class DenoKvAdapter implements WatchableKv` | Deno-native adapter backed by `Deno.Kv`, with native watch support. |
| `MemoryKvAdapter` | class | `class MemoryKvAdapter implements WatchableKv` | Volatile adapter that keeps all data in process memory. |

## Store contracts

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `KvStore` | interface | `interface KvStore extends AsyncDisposable` | Base key-value storage contract (`get`/`set`/`delete`/`has`/`list`/`atomic`/`close`). |
| `WatchableKv` | interface | `interface WatchableKv extends KvStore` | Extends `KvStore` with reactive `watch` and `watchPrefix` capabilities. |
| `SharedKvConfig` | interface | `interface SharedKvConfig` | Options for configuring the shared KV instance. |

## Keys, entries, and options

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `KvKey` | type alias | `type KvKey = readonly Deno.KvKeyPart[]` | Portable key format shared by all adapters. |
| `KvEntry` | interface | `interface KvEntry<T>` | Key-value entry returned from `get()` and `list()`. |
| `KvSetOptions` | interface | `interface KvSetOptions` | Options for `KvStore.set()` (for example `expireIn`). |
| `KvListOptions` | interface | `interface KvListOptions` | Selector and pagination options for `KvStore.list()`. |
| `KvProvider` | type alias | `type KvProvider = 'redis' \| 'deno-kv' \| 'nitro' \| 'auto'` | Providers supported by the shared KV lifecycle helpers. |

## Atomic operations

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `AtomicCheck` | interface | `interface AtomicCheck` | Versionstamp check used by atomic compare-and-swap operations. |
| `AtomicMutation` | type alias | `type AtomicMutation = { type: 'set'; key: KvKey; value: unknown; expireIn?: number } \| { type: 'delete'; key: KvKey } \| { type: 'sum' \| 'min' \| 'max'; key: KvKey; value: bigint }` | Mutation operations accepted by `KvStore.atomic()`. |
| `AtomicResult` | interface | `interface AtomicResult` | Result returned from an atomic operation. |

## Watch events

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `WatchEvent` | interface | `interface WatchEvent<T>` | Event emitted when an observed key changes. |
| `WatchOptions` | interface | `interface WatchOptions` | Options for `WatchableKv.watch()`. |
| `WatchPrefixOptions` | interface | `interface WatchPrefixOptions extends WatchOptions` | Options for `WatchableKv.watchPrefix()`. |

## Sub-path exports

The following entrypoints are published alongside the root export. Each is generated from its own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/kv` | `./mod.ts` | Shared lifecycle, adapters, and types (documented above). |
| `@netscript/kv/redis` | `./redis.ts` | Redis adapter (documented below). |
| `@netscript/kv/kvdex` | `./kvdex.ts` | kvdex bridge factory + re-exported kvdex core (documented below). |
| `@netscript/kv/testing` | `./src/testing/mod.ts` | Shared KV port contract harness (documented below). |

### `@netscript/kv/redis`

Importing this module re-exports the Redis adapter **and** self-registers the `'redis'` provider factory with the shared lifecycle. It also re-exports the shared store contracts (`KvStore`, `WatchableKv`, `KvKey`, `KvEntry`, `KvListOptions`, `KvSetOptions`, `AtomicCheck`, `AtomicMutation`, `AtomicResult`, `WatchEvent`, `WatchOptions`, `WatchPrefixOptions`).

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `RedisKvAdapter` | class | `class RedisKvAdapter implements WatchableKv` | Distributed Redis adapter for `@netscript/kv`. |
| `RedisKvOptions` | interface | `interface RedisKvOptions` | Redis connection options for the adapter. |

### `@netscript/kv/kvdex`

The kvdex bridge factory plus a curated re-export of the [kvdex](https://jsr.io/@olli/kvdex) core APIs and Deno-KV-compatible types.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createNetscriptDb` | function | `async function createNetscriptDb<T>(schema: T, options?: CreateNetscriptDbOptions): Promise<ReturnType<kvdex>>` | Create a kvdex database backed by the active `@netscript/kv` provider. |
| `CreateNetscriptDbOptions` | interface | `interface CreateNetscriptDbOptions` | Options for `createNetscriptDb`. |
| `WatchableKvBridge` | class | `class WatchableKvBridge` | Adapts a `WatchableKv` to the `DenoKv` interface kvdex expects. |
| `KvdexSchema` | type alias | `type KvdexSchema = Record<string, any>` | Accepted schema shape, structurally compatible with kvdex's `SchemaDefinition`. |
| `kvdex` | function | `function kvdex<TSchema>(options: KvdexOptions<TSchema>): Database<TSchema>` | Re-exported kvdex database factory. |
| `collection` | function | `function collection<TInput, TOutput, TOptions>(model, options?): BuilderFn` | Re-exported kvdex collection builder. |
| `model` | function | `function model<TOutput, TInput>(transform?): Model<TInput, TOutput>` | Re-exported kvdex model factory. |

This entrypoint also re-exports the kvdex Deno-KV compatibility types: `KvProvider`, `KvObject`, `DenoAtomicCheck`, `DenoAtomicOperation`, `DenoKvCommitError`, `DenoKvCommitResult`, `DenoKvEnqueueOptions`, `DenoKvEntryMaybe`, `DenoKvGetOptions`, `DenoKvKeyPart`, `DenoKvListIterator`, `DenoKvListOptions`, `DenoKvListSelector`, `DenoKvSetOptions`, `DenoKvStrictKey`, and `DenoKvWatchOptions`.

### `@netscript/kv/testing`

A reusable contract harness for adapter authors. Re-exports the shared `KvStore` and `WatchableKv` contracts alongside the test helpers.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `runKvStoreContract` | function | `function runKvStoreContract(options: KvStoreContractOptions): void` | Register the canonical KV store contract tests against an adapter. |
| `KvStoreContractOptions` | interface | `interface KvStoreContractOptions` | Options for `runKvStoreContract`. |
| `createMemoryKvAdapter` | function | `function createMemoryKvAdapter(): MemoryKvAdapter` | Factory for a clean in-memory KV adapter for downstream tests. |
| `MemoryKvAdapter` | class | `class MemoryKvAdapter implements WatchableKv` | Volatile in-memory adapter (re-exported from the root). |

## See it live

- **How-to:** [Queue / KV / cron](https://rickylabs.github.io/netscript/data-persistence/how-to/queue-kv-cron/) — read, write, and watch a KV store with these symbols in a running workspace.
- **Concept:** [KV, queues & cron](https://rickylabs.github.io/netscript/data-persistence/kv-queues-cron/) — the durable-by-default KV model and how it backs queues and cron.

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/kv/_

---

# `@netscript/logger`

Structured logging for NetScript packages, services, workers, and jobs. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/logger`) exposes the lightweight core surface only: the NetScript logger creators and configuration helpers, plus a curated re-export of the underlying [LogTape](https://jsr.io/@logtape/logtape) primitives. Two sub-path exports carry the framework integrations:

- [`@netscript/logger/middleware`](#sub-path-exports) — Hono request-logging middleware.
- [`@netscript/logger/orpc`](#sub-path-exports) — the oRPC logging plugin.

## Configuration

| Symbol | Signature | Description |
| --- | --- | --- |
| `configureLogging` | `async function configureLogging(config?: LoggingConfig): Promise<void>` | Configure LogTape for NetScript applications, using the provided options or sensible defaults. |
| `ensureLogging` | `async function ensureLogging(config?: LoggingConfig): Promise<void>` | Ensure logging is configured, initializing with defaults if needed. |
| `isLoggingConfigured` | `function isLoggingConfigured(): boolean` | Check whether logging has been configured. |
| `markConfigured` | `function markConfigured(): void` | Mark logging as configured (for manual configuration scenarios). |
| `resetLogging` | `async function resetLogging(): Promise<void>` | Reset the LogTape configuration. |

## Logger creators

| Symbol | Signature | Description |
| --- | --- | --- |
| `createLogger` | `function createLogger(category): Logger` | Create a logger with a custom category hierarchy. |
| `createServiceLogger` | `function createServiceLogger(serviceName: string): Logger` | Create a logger for a NetScript service. |
| `createPackageLogger` | `function createPackageLogger(packageName: string): Logger` | Create a logger for a NetScript package. |
| `createWorkerLogger` | `function createWorkerLogger(workerName: string): Logger` | Create a logger for workers/jobs. |
| `createJobLogger` | `function createJobLogger(jobId: string): Logger` | Create a logger for a job. |
| `createChildLogger` | `function createChildLogger(parent: Logger, name: string): Logger` | Create a child logger from a parent logger, preserving the parent hierarchy. |

## Re-exported LogTape primitives

These symbols are re-exported unchanged from [`@logtape/logtape`](https://jsr.io/@logtape/logtape) and form the core logging contract.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `getLogger` | function | `function getLogger(): Logger` | Get a logger for the given category. |
| `getConsoleSink` | function | `function getConsoleSink()` | A console sink factory that logs records to the console. |
| `configure` | function | `async function configure(config: Config): Promise<void>` | Configure the loggers with the specified sinks, filters, and loggers. |
| `withContext` | function | `function withContext(context: Record, callback): T` | Run a callback with the given implicit context attached to every log record. |
| `Logger` | interface | `interface Logger` | A logger interface providing methods to log messages at different levels. |
| `LogRecord` | interface | `interface LogRecord` | A single log record. |
| `LogLevel` | type alias | `type LogLevel` | The severity level of a `LogRecord`. |
| `Sink` | type alias | `type Sink` | A function that accepts a log record and writes it somewhere. |

## Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `LoggerOptions` | interface | Options for creating loggers. |
| `LoggingConfig` | interface | Logging configuration options accepted by `configureLogging`. |
| `RequestLogContext` | interface | Request context used by the logging middleware. |

## Sub-path exports

The following entrypoints are published alongside the root export. Their reference pages are generated separately from their own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/logger` | `./mod.ts` | Core logging surface (documented above). |
| `@netscript/logger/middleware` | `./middleware.ts` | Hono request-logging middleware. |
| `@netscript/logger/orpc` | `./orpc.ts` | oRPC logging plugin. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/logger/_

---

# `@netscript/mcp`

The Model Context Protocol server for NetScript workspaces. This page describes the package's public surface and is maintained by hand; the authoritative, always-current symbol list is [`deno doc jsr:@netscript/mcp@0.0.1-beta.11`](https://jsr.io/@netscript/mcp/doc). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

`@netscript/mcp` publishes 13 token-bounded MCP tools that let a coding agent monitor a running app, debug a correlated execution, read framework-semantic telemetry, run the doctor, search the public documentation, and trigger allowlisted CLI commands — over newline-delimited JSON-RPC on stdio, with no npm MCP SDK on the dependency graph.

Most consumers never import this package: `netscript agent init` installs it as an MCP server and `netscript agent mcp` runs it. See [Agent tooling](https://rickylabs.github.io/netscript/ai/agent-tooling/) for the CLI × skills × MCP combo, and the package README for the mental model and recipes.

Two entrypoints carry the surface:

- `@netscript/mcp` — tool contracts, the registry, the protocol runner, ports, and default adapters.
- [`@netscript/mcp/cli`](#sub-path-exports) — the executable composition that binds the real telemetry, docs, doctor, and process adapters.

## Server composition

| Symbol | Kind | Summary |
| --- | --- | --- |
| `createMcpServer` | function | Create the MCP server with `initialize` / `tools/list` / `tools/call` support. |
| `createToolRegistry` | function | Immutable, enumerable definitions of the 13 tools. |
| `McpServer` | interface | Callable server subset: `handle(message)` plus the registered `tools`. |
| `McpServerOptions` | interface | Composition seams: `probe`, `environment`, `flows`, `truncation`. |
| `MCP_PROTOCOL_VERSION` | const | The MCP protocol version the runner implements (`2025-11-25`). |

## Tool contracts

| Symbol | Kind | Summary |
| --- | --- | --- |
| `TOOL_NAMES` | const | The 13 tool names, in registry order. |
| `TOOL_INPUT_SCHEMAS` | const | Standard Schema input contract per tool. |
| `TOOL_OUTPUT_SCHEMAS` | const | Standard Schema output contract per tool. |
| `validateSchema` | function | Validate a value against a tool schema, throwing on drift. |
| `ToolDefinition` | interface | A tool's name, contracts, and flow. |
| `ToolFlow` | type | The function a tool executes; depends only on ports. |
| `ToolName` | type | Union of the 13 tool names. |

### Per-tool field overview

The table below is a **top-level field overview** — input names and result field names per tool, taken from the live `tools/list`. It is not the complete contract: types, enum values, numeric bounds, array maxima, nested shapes, and required-vs-optional result fields live in the published Standard Schema contracts (`TOOL_INPUT_SCHEMAS` / `TOOL_OUTPUT_SCHEMAS`), which every `tools/list` response returns in full. **Bold** inputs are required; every other input is optional. Every `limit` input caps the result count server-side before truncation applies.

| Tool | Inputs | Result fields |
| --- | --- | --- |
| `get_app_status` | `service`, `limit` | `status`, `counts`, `domains` |
| `list_runs` | `domain`, `status`, `service`, `sinceUnixMs`, `limit` | `count`, `runs` |
| `get_run` | **`id`** | `id`, `summary`, `traceId`, `outcome`, `errorMessage`, `spans`, `logs` |
| `get_recent_errors` | `service`, `domain`, `sinceUnixMs`, `limit` | `count`, `groups` |
| `get_last_job_result` | `jobId`, `jobName`, `service`, `sinceUnixMs` | `found`, `jobName`, `jobId`, `status`, `outcome`, `exitCode`, `startUnixMs`, `completedUnixMs`, `durationMs`, `errorMessage`, `traceId` |
| `analyze_service_performance` | **`service`**, `sinceUnixMs`, `limit` | `service`, `sinceUnixMs`, `sampleCount`, `errorCount`, `errorRate`, `averageDurationMs`, `p50DurationMs`, `p95DurationMs`, `throughputPerMinute`, `topOperations` |
| `analyze_db_bottlenecks` | `service`, `sinceUnixMs`, `limit` | `sinceUnixMs`, `sampleCount`, `operations` |
| `doctor` | `endpoint` | `status`, `endpoint`, `counts`, `checks`, `families` |
| `search_docs` | **`query`**, `limit` | `count`, `matches` |
| `list_docs` | `limit` | `count`, `docs` |
| `get_doc` | **`slug`**, `section` | `slug`, `title`, `section`, `content` |
| `list_commands` | `filter`, `limit` | `count`, `commands` |
| `execute_command` | **`command`**, `args` | `exitCode`, `durationMs`, `outputTail`, `truncated`, `timedOut` |

**Truncation semantics.** After a flow succeeds, `truncateResult` recursively bounds the result using `DEFAULT_TRUNCATION_POLICY` — arrays are capped at 50 elements and strings at 2,000 UTF-16 code units — before the runner serializes it. The analytics tools (`analyze_service_performance`, `analyze_db_bottlenecks`) additionally never return raw spans: their results are computed aggregates. `execute_command` returns only a bounded combined output tail (4,096 bytes by default) and flags `truncated` when output was cut. A failed flow returns a structured tool error (a stable `code` plus a message), not a truncated success.

## Output bounds

Every successful result is bounded server-side before the runner serializes it, so a tool can never flood the model's context.

| Symbol | Kind | Summary |
| --- | --- | --- |
| `truncateResult` | function | Recursively bound arrays and strings in a JSON-compatible result. |
| `DEFAULT_TRUNCATION_POLICY` | const | The default bounds: 50 array items, 2,000 UTF-16 code units per string. |
| `TruncationPolicy` | interface | `maxItems` and `maxStringLength`. |

## Command policy

`execute_command` is **default-deny**: a normalized command path must match an allow rule and no deny rule. Deny beats allow; anything unmatched is denied.

| Symbol | Kind | Summary |
| --- | --- | --- |
| `decideCommand` | function | Decide whether a normalized command path is allowed by a policy. |
| `DEFAULT_COMMAND_POLICY` | const | Conservative allowlist shipped with the server. |
| `CommandPolicy` | interface | Ordered `allow` / `deny` prefix rules. |
| `CommandPolicyDecision` | type | The decision returned for a command path. |

The default policy **allows** `db init|generate|migrate|seed|status|introspect`, `generate`, `contract`, `service list`, `plugin install|list|sync|doctor`, and `ui:add|ui:init|ui:list|ui:update`; it **denies** `deploy`, `init`, `marketplace`, `db reset`, `plugin remove`, and `ui:remove`.

## Ports

Every tool flow depends on a port, never on a concrete client — which is why this package can report on the CLI without depending on it. `@netscript/cli` implements the ports and injects them at its own composition root.

| Symbol | Kind | Summary |
| --- | --- | --- |
| `TelemetryProbePort` | interface | Telemetry endpoint reachability check. |
| `DocsCorpusPort` | interface | Public Markdown corpus: search, list, get. |
| `CommandCatalogPort` | interface | Supplies the live CLI command tree to `list_commands`. |
| `CommandExecutorPort` | interface | Runs an allowed command, returning structured process data. |
| `ProjectDoctorPort` | interface | Typed project and plugin diagnostics. |
| `DoctorCheckFamily` | interface | One group of doctor checks aggregated into the verdict. |

## Default adapters

| Symbol | Kind | Summary |
| --- | --- | --- |
| `FilesystemDocsCorpus` | class | `DocsCorpusPort` over a local Markdown root (default `docs/site`). |
| `SpawnCommandExecutor` | class | `CommandExecutorPort` that spawns the `netscript` binary. |
| `StaticCommandCatalog` | class | `CommandCatalogPort` used when no live catalog is injected. |
| `PluginDoctorFamily` | class | Plugin diagnostics as a doctor check family. |
| `slugifyDocsHeading` | function | Normalize a Markdown heading into a `get_doc` section slug. |

## Sub-path exports

### `@netscript/mcp/cli`

The executable composition. It binds the real telemetry query, filesystem docs corpus, Aspire / project-wiring / plugin doctor families, and the process executor, and runs them over stdio.

| Symbol | Kind | Summary |
| --- | --- | --- |
| `runMcpStdioServer` | function | Run the server on Deno standard input and output. |
| `createMcpCliServer` | function | Compose the server with optional outer CLI adapters. |
| `resolveDocsRoot` | function | Resolve the docs root from `--docs-root`, `NETSCRIPT_DOCS_ROOT`, or the project root. |
| `McpCliOptions` | interface | `commandCatalog`, `commandExecutor`, `commandPolicy`, `projectDoctor`, `projectRoot`, `docsRoot`, `endpoint`. |

Telemetry endpoint discovery is ordered: an explicit `endpoint` option, then `NETSCRIPT_TELEMETRY_ENDPOINT`, then `ASPIRE_DASHBOARD_PORT`, then `http://localhost:18888`. Only `http:` and `https:` endpoints are accepted, and an unreachable endpoint yields a structured warning rather than a crash.

## Data boundary

The server reads telemetry, project metadata, generated registries, and public documentation. It never returns project source, environment-variable values, credentials, or secrets. Stdio is process-local; the only outbound traffic is the telemetry probe to the resolved endpoint.

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/mcp/_

---

# `@netscript/plugin-ai-core`

The contract-only core for the NetScript AI plugin: the oRPC `/v1/ai` route surface — an SSE-framed `chat` stream plus `models`, `tools/{name}`, `embed`, and `transcribe` — that a connector implements and the typed client calls. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The package ships **zero service implementation** (Archetype 1 — Small Contract). It declares the route shapes and their Zod IO vocabulary; a connector (`@netscript/plugin-ai`) binds the contract to a host and the `@netscript/fresh/ai` client generates a typed caller from it. Every route schema mirrors an engine type from `@netscript/ai/contracts`, and a compile-time drift guard (`z.ZodType<EngineType> = schema`) asserts the mirror cannot silently diverge from the domain contract.

## Entrypoints

The package publishes two entrypoints. Each is generated from its own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/plugin-ai-core` | `./mod.ts` | Contract handles, router helpers, and route IO types (documented below). |
| `@netscript/plugin-ai-core/contracts/v1` | `./src/contracts/v1/mod.ts` | Full contract surface: the Zod `*Schema` validators plus the engine-derived vocabulary types. |

The root path curates to the handles and IO types a typical consumer imports (staying within the ≤20-export doctrine budget); the `./contracts/v1` subpath exposes the complete schema and engine-vocabulary set a connector wires.

## Root surface (`@netscript/plugin-ai-core`)

### Contract handles and router helpers

| Symbol | Kind | Description |
| --- | --- | --- |
| `aiContract` | variable | AI service contract definition for client generation (the real, fully-inferred oRPC contract router — no erasure cast). |
| `aiContractV1` | variable | The implemented, context-bindable v1 contract (`implement(definition)`); `.$context<Ctx>()` returns the precisely-typed router implementer. |
| `createAiRouter` | function | Bind a complete in-process AI implementation to the v1 contract, returning the oRPC handlers for each route. |
| `AiRouterContext` | type alias | Request context accepted by the generated AI router (`Record<PropertyKey, unknown>`). |
| `ContextualAiRouter` | type alias | The router implementer returned by `aiContractV1.$context<TContext>()`. |
| `AiRouteHandler` | type alias | Handler function type for a single named route under a bound context. |
| `AiRouterImplementation` | interface | Per-route handler functions that implement every route in `aiContractV1`. |
| `BoundAiRoute` | type alias | The bound handler type produced by `router.<route>.handler(...)`. |
| `BoundAiRouter` | interface | Contract-bound route handlers returned by `createAiRouter`. |

### Route IO and capability types

| Symbol | Kind | Description |
| --- | --- | --- |
| `AiContract` / `AiContractDefinition` / `AiContractV1` | type alias | The fully-typed v1 contract shape and its context-binding implementer type. |
| `AiRouter` | type alias | The context-bound AI router implementer (`ReturnType<typeof aiContractV1.$context<...>>`). |
| `AiCapabilities` | interface | The capabilities document returned by the mandatory `describe` route (a named alias of `PluginCapabilities`). |
| `ChatInput` | type alias | Input accepted by the `chat` streaming endpoint. |
| `ChatChunk` | type alias | A single streamed chat frame — alias of the engine `AgentChunk` union. |
| `ModelsResponse` | type alias | Response returned by the `models` endpoint. |
| `ToolInvokeInput` / `ToolInvokeResponse` | type alias | Input and response for the `tools/{name}` invocation endpoint. |
| `EmbedInput` / `EmbedResponse` | type alias | Input and response for the `embed` endpoint. |
| `TranscribeInput` / `TranscribeResponse` | type alias | Input and response for the `transcribe` endpoint. |

## Full contract surface (`@netscript/plugin-ai-core/contracts/v1`)

The subpath re-exports both contract handles (`aiContract`, `aiContractV1`), every route IO type above, and the following additional symbols.

### Zod IO schemas

Each schema is a named, explicitly-annotated Zod validator (annotated `z.ZodType<EngineType>` so the module fails to compile if it drifts from the engine contract it mirrors). A connector validates inbound bodies and outbound frames against these.

| Symbol | Kind | Validates |
| --- | --- | --- |
| `ChatInputSchema` | variable | `chat` request body (`ChatInput`). |
| `ChatChunkSchema` | variable | A single streamed `chat` frame (`ChatChunk`). |
| `ModelsInputSchema` | variable | Optional `models` filter (`{ provider? }`). |
| `ModelsResponseSchema` | variable | `models` response (`{ models: ModelDescriptor[] }`). |
| `ToolInvokeInputSchema` | variable | `tools/{name}` request body. |
| `ToolInvokeResponseSchema` | variable | `tools/{name}` response. |
| `EmbedInputSchema` | variable | `embed` request body. |
| `EmbedResponseSchema` | variable | `embed` response. |
| `TranscribeInputSchema` | variable | `transcribe` request body. |
| `TranscribeResponseSchema` | variable | `transcribe` response. |

### Engine-derived vocabulary types

The subpath re-exports the `@netscript/ai/contracts` streaming vocabulary verbatim, so a connector references the same domain types the schemas mirror without reaching into the engine package: `AgentChunk`, `AudioContentPart`, `CompletionTokensDetails`, `ContentModality`, `ContentPart`, `ContentSource`, `DataContentSource`, `DocumentContentPart`, `DoneChunk`, `ErrorChunk`, `ImageContentPart`, `Message`, `MessageChunk`, `MessageContent`, `MessageRole`, `ModelCapabilities`, `ModelDescriptor`, `ModelId`, `ModelRef`, `ModelSelector`, `ModelsInput`, `PromptTokensDetails`, `ProviderUsageDetails`, `TextChunk`, `TextContentPart`, `ToolCall`, `ToolCallChunk`, `ToolCallState`, `ToolDescriptor`, `ToolResult`, `ToolResultChunk`, `ToolResultState`, `UrlContentSource`, `Usage`, `UsageChunk`, `UsageCostBreakdown`, `VideoContentPart`, plus the `AiContractDefinitionShape` structural type.

## The `/v1/ai` route surface

Route paths are relative; the `/v1/ai` prefix is applied where the service host mounts the router. The contract layers five plugin-specific routes onto the base seam `describe` route.

| Route | Method | Path | Input | Output |
| --- | --- | --- | --- | --- |
| `chat` | POST | `/chat` | `ChatInput` | **SSE** `eventIterator<ChatChunk>` |
| `models` | GET | `/models` | `ModelsInput?` | `ModelsResponse` |
| `invokeTool` | POST | `/tools/{name}` | `ToolInvokeInput` | `ToolInvokeResponse` |
| `embed` | POST | `/embed` | `EmbedInput` | `EmbedResponse` |
| `transcribe` | POST | `/transcribe` | `TranscribeInput` | `TranscribeResponse` |
| `describe` | GET | `/describe` | — | `AiCapabilities` |

### `chat` input

`ChatInput` carries the request the connector forwards to its provider adapter.

| Field | Type | Notes |
| --- | --- | --- |
| `model` | `ModelRef` | A `"provider:model"` string or a `{ provider, model }` selector. |
| `messages` | `readonly Message[]` | The conversation transcript. |
| `tools` | `readonly ToolDescriptor[]` (optional) | Tool descriptors offered to the model. |
| `system` | `string` (optional) | System prompt. |
| `temperature` | `number` (optional) | Constrained `0`–`2` by the schema. |
| `maxTokens` | `number` (optional) | Positive integer. |
| `metadata` | `Record<string, unknown>` (optional) | Opaque per-request metadata. |

## SSE chat contract (durable-CHAT)

`chat` is the streaming centerpiece. Its output is not a request/response pair but an oRPC **`eventIterator`** whose element type is `ChatChunk` — an alias of the engine `AgentChunk` union. Because the contract output type is an async event-iterator, a connector's `chat` handler must be an async generator that yields frames; a buffered single-response implementation does not type-check. Recoverable and terminal errors surface **in-stream** as the `error` chunk rather than as an oRPC error, matching the engine's streaming model — so the `chat` route (built with `oc.route`, not the base contract) carries an empty error map.

### Event (chunk) shapes

Each streamed frame is one of seven discriminated shapes, keyed on `type`:

| `type` | Payload | Meaning |
| --- | --- | --- |
| `text` | `{ delta: string }` | Incremental assistant text appended this tick. |
| `tool-call` | `{ toolCall: ToolCall }` | A tool invocation requested by the model. |
| `tool-result` | `{ result: ToolResult }` | The result of an executed tool, fed back into the loop. |
| `message` | `{ message: Message }` | A fully-assembled message committed to the transcript. |
| `usage` | `{ usage: Usage }` | Token usage for the step or run. |
| `error` | `{ error: string, cause?: unknown }` | A recoverable or terminal error surfaced through the stream. |
| `done` | `{ usage?: Usage }` | Terminal frame closing the run, optionally carrying final usage. |

> **The contract declares frame shapes, not wire headers.** `@netscript/plugin-ai-core` is a transport-agnostic oRPC contract: the `text/event-stream` wire framing (per-frame `data:` lines, the response content type) is produced by the oRPC handler at the host mount point when it serves an `eventIterator` output, not declared in this package. This page documents the event *shapes* the stream carries; the HTTP framing belongs to the connector's service host.

## Base-contract extension

`aiContract` spreads `BASE_PLUGIN_CONTRACT_ROUTES` from [`@netscript/plugin/contract-base`](https://jsr.io/@netscript/plugin) verbatim, so it inherits the mandatory `describe` route (GET `/describe`) unchanged. `describe` returns a marketplace-discoverable `AiCapabilities` document — a named alias of `PluginCapabilities`:

| Field | Type | Description |
| --- | --- | --- |
| `pluginName` | `string` | Canonical plugin package name, e.g. `@netscript/plugin-ai`. |
| `contractVersions` | `readonly string[]` | Contract version identifiers served by the plugin. |
| `routeGroups` | `readonly string[]` | Route group names exposed by the plugin. |
| `capabilities` | `readonly string[]` | Capability tags advertised by the plugin. |

The non-streaming routes (`models`, `invokeTool`, `embed`, `transcribe`, `describe`) converge onto the shared plugin error vocabulary from `BASE_PLUGIN_ERRORS`:

| Code | HTTP status | Default message |
| --- | --- | --- |
| `NOT_FOUND` | 404 | Resource not found |
| `VALIDATION_ERROR` | 422 | Validation failed |
| `INTERNAL` | 500 | Internal server error |

## Binding the contract (`aiContractV1` / `AiRouter`)

A connector binds its host request context and implements each route handler. The precise per-route IO types check every handler; there is no erasure cast on the contract or the implementer.

`aiContractV1.$context<TContext>()` returns the contract-bound **implementer** — `AiRouter` is the type alias naming its default (empty-context) shape, and `ContextualAiRouter<TContext>` the context-parameterized one. The implementer is not an assembled handler map: each route on it exposes a `.handler()` call that binds one implementation function.

```typescript
import { aiContractV1 } from '@netscript/plugin-ai-core';

// Bind the host request context; each route is then implemented individually.
const router = aiContractV1.$context<{ requestId: string }>();

// The `chat` output is an event-iterator, so the handler MUST stream frames.
const chat = router.chat.handler(async function* ({ input }) {
  for (const message of input.messages) {
    yield { type: 'text' as const, delta: `echo: ${JSON.stringify(message.content)}` };
  }
  yield { type: 'done' as const };
});
// models / invokeTool / embed / transcribe / describe bind the same way.
```

Assembling all six bound routes by hand is what `createAiRouter` exists to avoid: it wraps `aiContractV1.$context()`, binds a complete per-route implementation (`AiRouterImplementation`) in one call, and returns the bound handler map (`BoundAiRouter`):

```typescript
import { createAiRouter } from '@netscript/plugin-ai-core';

const router = createAiRouter({
  describe: () => ({
    pluginName: '@netscript/plugin-ai',
    contractVersions: ['v1'],
    routeGroups: ['ai'],
    capabilities: ['chat'],
  }),
  async *chat() {
    yield { type: 'done' as const };
  },
  models: () => ({ models: [] }),
  invokeTool: () => ({ content: 'No tools registered.', state: 'error' as const }),
  embed: () => ({ embeddings: [] }),
  transcribe: () => ({ text: '' }),
});
```

## Validating IO on the `./contracts/v1` subpath

The Zod validators let a connector parse an inbound request body against the contract and validate each frame before forwarding it down the stream:

```typescript
import { ChatChunkSchema, ChatInputSchema } from '@netscript/plugin-ai-core/contracts/v1';

// Parse an inbound request body against the streamed-chat input contract.
const request = ChatInputSchema.parse({
  model: 'anthropic:claude-sonnet-4-5',
  messages: [{ role: 'user', content: 'Stream me a haiku.' }],
});

// Validate each frame a provider emits before forwarding it down the SSE stream.
const chunk = ChatChunkSchema.parse({ type: 'text', delta: 'silent...' });
console.log(request.model, chunk.type);
```

## How the AI plugin stack consumes this contract

- **Connector (`@netscript/plugin-ai`)** — re-exports this contract surface from its own `./contracts/v1` (`export * from '@netscript/plugin-ai-core/contracts/v1'`) and declares the loader on its manifest (`withContractVersions`), so a host binds the AI plugin against a single pinned `/v1/ai` contract. It binds `aiContractV1.$context<Ctx>()` and implements each route against a provider adapter.
- **`@netscript/fresh/ai` client** — imports `aiContract` and generates a typed caller, so a Fresh island streams `chat` chunks and calls `models` / `embed` / `transcribe` with full type inference and no hand-written request types.
- **Marketplace tooling** — reads the `describe` route's `AiCapabilities` document to introspect a running AI plugin without parsing source.

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/plugin-ai-core/_

---

# `@netscript/plugin-auth-core`

Auth plugin contracts, backend ports, stream schemas, config schemas, telemetry primitives, and testing primitives for NetScript auth plugins. This page is generated from the package's public surface with `deno doc`.

## Backend ports and errors

| Symbol | Kind | Description |
| --- | --- | --- |
| `AuthBackendPort` | interface | Backend adapter port implemented by auth backends. |
| `AuthProviderRegistryPort` | interface | Registry port for provider descriptors and capabilities. |
| `AuthPrincipalMapperPort` | interface | Port for mapping upstream principals into NetScript auth principals. |
| `AuthSessionCryptoPort` | interface | Port for signing and verifying session tokens. |
| `AuthSessionStorePort` | interface | Port for session persistence. |
| `InteractiveFlowPort` | interface | Port for sign-in and callback flows when the backend supports interactive auth. |
| `AuthBackendOperationUnsupportedError` | class | Error for an adapter operation outside an upstream capability boundary. |
| `AuthBackendNotFoundError` | class | Error thrown when backend resolution cannot find a named backend. |

## Factories and helpers

| Symbol | Kind | Description |
| --- | --- | --- |
| `createAuthBackendRegistry` | function | Create a registry for named `AuthBackendPort` implementations. |
| `createAuthPresetRegistry` | function | Create a registry for auth backend presets. |
| `resolveBackend` | function | Resolve an auth backend from config and registry state. |
| `createAuthTelemetry` | function | Create auth telemetry helpers. |
| `createHmacSessionTokenCrypto` | function | Create an HMAC-backed session token crypto port. |
| `hashSubject` | function | Hash an auth subject for telemetry or storage-safe identity keys. |
| `redactAuthPrincipal` | function | Return a redacted principal snapshot for logging and diagnostics. |
| `authErrorCodeForReason` | function | Map an auth failure reason to an auth error code. |
| `authOutcomeForReason` | function | Map an auth failure reason to an operation outcome. |

## Contracts, schemas, and constants

| Symbol | Kind | Description |
| --- | --- | --- |
| `authContract` | constant | Root auth contract export. |
| `authContractV1` | constant | Versioned v1 auth contract export. |
| `authStreamSchema` | constant | Stream schema for auth events. |
| `AuthConfigSchema` | constant | Schema for auth runtime configuration. |
| `AuthProviderConfigSchema` | constant | Schema for provider configuration. |
| `AuthSessionPolicySchema` | constant | Schema for session policy configuration. |
| `AuthSessionSchema` | constant | Schema for auth sessions. |
| `AuthUserSchema` | constant | Schema for auth user payloads. |
| `AccountSchema` | constant | Schema for auth account payloads. |
| `AUTH_SESSION_STATES` | constant | Supported auth session states. |
| `AUTH_ACCOUNT_STATES` | constant | Supported account states. |
| `AUTH_STREAM_EVENT_TYPES` | constant | Supported auth stream event types. |
| `DEFAULT_AUTH_BACKEND_NAME` | constant | Default backend name used by config and registries. |

## Common types

| Symbol | Kind | Description |
| --- | --- | --- |
| `AuthConfig` | type alias | Parsed auth runtime configuration. |
| `AuthBackendRegistry` | type alias | Named backend registry type. |
| `ResolvedAuthBackendRegistry` | type alias | Resolved backend registry state. |
| `AuthProviderDescriptor` | type alias | Provider descriptor exposed by provider registries. |
| `AuthProviderCapability` | type alias | Capability value reported by auth providers. |
| `AuthSession` | type alias | Auth session payload. |
| `AuthSessionCreateInput` | type alias | Input used to create a session. |
| `AuthSessionLookup` | type alias | Lookup input for session resolution. |
| `AuthSessionState` | type alias | Session state value. |
| `AuthUser` | type alias | Auth user payload. |
| `AuthOperationOutcome` | type alias | Auth operation outcome value. |
| `AuthStreamEvent` | type alias | Auth stream event payload. |

## Sub-path exports

| Export | Purpose |
| --- | --- |
| `@netscript/plugin-auth-core` | Root contract, port, schema, stream, and telemetry surface. |
| `@netscript/plugin-auth-core/domain` | Domain types and schemas. |
| `@netscript/plugin-auth-core/ports` | Backend, provider, session, and interactive-flow ports. |
| `@netscript/plugin-auth-core/contracts/v1` | Versioned auth contract. |
| `@netscript/plugin-auth-core/telemetry` | Auth telemetry attributes and helpers. |
| `@netscript/plugin-auth-core/streams` | Auth stream schema and event types. |
| `@netscript/plugin-auth-core/config` | Runtime config schemas and backend resolution helpers. |
| `@netscript/plugin-auth-core/presets` | Backend preset registry helpers. |
| `@netscript/plugin-auth-core/testing` | Testing primitives for auth adapters and plugins. |

Back to the [auth reference hub](https://rickylabs.github.io/netscript/reference/auth/).

_Canonical: https://rickylabs.github.io/netscript/reference/plugin-auth-core/_

---

# `@netscript/plugin-auth`

Public plugin manifest for NetScript auth. This page is generated from the package's public surface with `deno doc`. For the auth package map, return to the [auth reference hub](https://rickylabs.github.io/netscript/reference/auth/).

The root entrypoint exposes the plugin manifest and auth metadata constants. Shared manifest inspection is provided by `inspectPlugin` from `@netscript/plugin`.

## Plugin manifest

| Symbol | Kind | Description |
| --- | --- | --- |
| `authPlugin` | constant | Plugin manifest for NetScript auth. |

## Constants

| Symbol | Value | Description |
| --- | --- | --- |
| `AUTH_PLUGIN_ID` | `"auth"` | Stable plugin id. |
| `AUTH_PLUGIN_VERSION` | `"{{ releaseVersion }}"` | Auth plugin package version constant. |
| `AUTH_API_SERVICE_NAME` | `"auth-api"` | Service name contributed by the auth plugin. |
| `AUTH_API_DEFAULT_PORT` | `8094` | Default auth-api service port. |

## Sub-path exports

| Export | Purpose |
| --- | --- |
| `@netscript/plugin-auth` | Root plugin manifest. |
| `@netscript/plugin-auth/public` | Public plugin entrypoint. |
| `@netscript/plugin-auth/plugin` | Plugin manifest entrypoint. |
| `@netscript/plugin-auth/contracts` | Auth contract contribution entrypoint. |
| `@netscript/plugin-auth/services` | Auth service contribution entrypoint. |
| `@netscript/plugin-auth/streams` | Auth stream contribution entrypoint. |
| `@netscript/plugin-auth/streams/server` | Server-side auth stream helpers. |

Back to the [auth reference hub](https://rickylabs.github.io/netscript/reference/auth/).

_Canonical: https://rickylabs.github.io/netscript/reference/plugin-auth/_

---

# `@netscript/plugin`

Plugin manifest, validation, discovery, and host-context contracts for NetScript. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/plugin`) is the plugin authoring contract: the `definePlugin` builder DSL, the manifest and contribution types, the plugin error classes, the contribution base class, and the `inspectPlugin` diagnostic. Host tooling, CLI integration, SDK discovery, abstract contribution bases, runtime loaders, testing fixtures, and template assets live on the sub-path exports listed at the end of this page.

## Plugin definition

| Symbol | Signature | Description |
| --- | --- | --- |
| `definePlugin` | `function definePlugin<TName, TVersion>(name: TName, version: TVersion): PluginBuilder` | Start a new plugin manifest builder chain. |
| `PluginBuilder` | `class PluginBuilder` | Fluent builder for assembling plugin manifests. |
| `PluginBuilderState` | `interface PluginBuilderState` | Immutable state accumulated by the plugin builder chain. |
| `PLUGIN_TYPES` | `variable PLUGIN_TYPES` | Supported plugin categories. |

## Diagnostics

| Symbol | Signature | Description |
| --- | --- | --- |
| `inspectPlugin` | `function inspectPlugin(target): InspectionReport` | Inspect a plugin manifest, registry, or path-like target. |
| `InspectionReport` | `interface InspectionReport` | JSON-stable diagnostic report returned by plugin inspectors. |
| `InspectablePluginManifest` | `interface InspectablePluginManifest` | Minimal plugin manifest shape accepted by the plugin inspector. |
| `InspectablePluginRegistry` | `interface InspectablePluginRegistry` | Minimal registry shape accepted by the plugin inspector. |

## Errors

| Symbol | Kind | Description |
| --- | --- | --- |
| `PluginError` | class | Base error for plugin package failures. |
| `PluginValidationError` | class | Error thrown when a plugin definition is invalid. |
| `DuplicatePluginError` | class | Error thrown when a plugin name is registered more than once. |

## Contributions

| Symbol | Kind | Description |
| --- | --- | --- |
| `PluginContribution` | class | Base class for plugin contribution extension axes. |
| `ContributionAxis` | type alias | Supported plugin contribution axes. |
| `ContributionInput` | type alias | Contribution value or callback resolved by the plugin builder. |
| `PluginContributions` | interface | Contribution groups supported by plugin manifests. |
| `BackgroundProcessorContribution` | interface | Background processor contributed by a plugin. |
| `ContractVersionContribution` | interface | Contract version contributed by a plugin. |
| `DbSchemaContribution` | interface | Database schema file contributed by a plugin. |
| `E2eContribution` | interface | End-to-end test contribution. |
| `MigrationContribution` | interface | Data or schema migration contribution. |
| `RuntimeConfigTopicContribution` | interface | Runtime config topic contributed by a plugin. |
| `ServiceContribution` | interface | Service contributed by a plugin. |
| `StreamTopicContribution` | interface | Stream topic contributed by a plugin. |
| `TelemetryContribution` | interface | Telemetry instrumentation contribution. |

## Manifest types

| Symbol | Kind | Description |
| --- | --- | --- |
| `PluginManifest` | interface | Plugin manifest consumed by NetScript hosts and tooling. |
| `PluginManifestParser` | interface | Minimal parser shape for manifest validators exposed by this package. |
| `PluginMetadata` | type alias | Metadata attached to plugin manifests. |
| `PluginMetadataValue` | type alias | Runtime-safe metadata values. |
| `PluginType` | type alias | Supported plugin categories. |
| `PluginDependencies` | type alias | Typed plugin dependency record keyed by caller-chosen aliases. |
| `DependencyContext` | type alias | Dependency context supplied to contribution callback inputs. |

## Lifecycle and context

| Symbol | Kind | Description |
| --- | --- | --- |
| `PluginLifecycleHooks` | interface | Lifecycle hooks supported by plugin definitions. |
| `PluginContext` | interface | Context supplied to plugin lifecycle hooks. |
| `PluginLogger` | interface | Logger shape supplied to plugin lifecycle hooks. |

## Sub-path exports

The following entrypoints are published alongside the root export. Their public surfaces are generated separately from their own `deno doc` output and summarized below.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/plugin` | `./mod.ts` | Plugin authoring contract (documented above). |
| `@netscript/plugin/config` | `./src/config/mod.ts` | Builder, manifest schema, and contribution type contracts. |
| `@netscript/plugin/abstracts` | `./src/abstracts/mod.ts` | Abstract contribution base classes per axis. |
| `@netscript/plugin/cli` | `./src/cli/mod.ts` | Plugin CLI base classes, command mounting, and doctor reports. |
| `@netscript/plugin/sdk` | `./src/sdk/mod.ts` | Discovery ports, alpha adapters, and runtime host stubs. |
| `@netscript/plugin/loader` | `./loader.ts` | Host-side plugin service bootstrap helpers. |
| `@netscript/plugin/testing` | `./src/testing/mod.ts` | In-memory adapters, fixtures, and the CLI contract harness. |
| `@netscript/plugin/templates` | `./src/templates/mod.ts` | Plugin skeleton template asset paths. |

### `@netscript/plugin/config`

| Symbol | Signature | Description |
| --- | --- | --- |
| `definePlugin` | `function definePlugin<TName, TVersion>(name, version): PluginBuilder` | Start a new plugin manifest builder chain. |
| `mergeContributions` | `function mergeContributions(base, overrides): PluginContributions` | Merge plugin contribution groups without mutating inputs. |
| `isContributionAxis` | `function isContributionAxis(value: string): boolean` | Check whether a value is a supported contribution axis. |
| `isReservedPluginName` | `function isReservedPluginName(name: string): boolean` | Return true when a plugin name is reserved by NetScript. |
| `PluginManifestSchema` | `variable PluginManifestSchema` | Zod schema for plugin manifests. |
| `CONTRIBUTION_AXES` | `variable CONTRIBUTION_AXES` | Supported plugin contribution axes. |
| `PLUGIN_TYPES` | `variable PLUGIN_TYPES` | Supported plugin categories. |

This entrypoint also re-exports the manifest, contribution, and builder types documented in the root sections above.

### `@netscript/plugin/abstracts`

| Symbol | Kind | Description |
| --- | --- | --- |
| `PluginContribution` | class | Base class for plugin contribution extension axes. |
| `PluginAspireContribution` | class | Base class for Aspire contribution implementations. |
| `PluginBackgroundProcessorContribution` | class | Base class for background processor contribution implementations. |
| `PluginContractVersionContribution` | class | Base class for contract version contribution implementations. |
| `PluginDbSchemaContribution` | class | Base class for database schema contribution implementations. |
| `PluginE2eContribution` | class | Base class for end-to-end contribution implementations. |
| `PluginMigrationContribution` | class | Base class for migration contribution implementations. |
| `PluginRuntimeConfigTopicContribution` | class | Base class for runtime config topic contribution implementations. |
| `PluginServiceContribution` | class | Base class for service contribution implementations. |
| `PluginStreamTopicContribution` | class | Base class for stream topic contribution implementations. |
| `PluginTelemetryContribution` | class | Base class for telemetry contribution implementations. |
| `PluginPayloadSchema` | interface | Minimal Standard Schema-compatible shape accepted by plugin contribution contracts. |
| `PluginSchemaIssue` | interface | Validation issue reported by package-owned schema contracts. |
| `PluginSchemaResult` | type alias | Validation result returned by package-owned schema contracts. |
| `ContributionAxis` | type alias | Supported plugin contribution axes. |

### `@netscript/plugin/cli`

| Symbol | Signature | Description |
| --- | --- | --- |
| `PluginCli` | `class PluginCli` | Abstract base class for plugin-owned CLI command groups. |
| `PluginItemScaffolder` | `class PluginItemScaffolder` | Abstract base for plugin item scaffolders (the `add <item>` command). |
| `PluginRuntimeConfigCli` | `class PluginRuntimeConfigCli` | Abstract base for plugin runtime configuration commands. |
| `mountPluginCli` | `function mountPluginCli(clis)` | Mount plugin CLI command groups into a flat command list. |
| `runMountedCommand` | `async function runMountedCommand(commands, args: PluginCliArgs): Promise` | Run a mounted command list without depending on Cliffy at package level. |
| `routeVerb` | `async function routeVerb(commands, args: PluginCliArgs): Promise` | Route a command by verb name. |
| `formatPluginHelp` | `function formatPluginHelp(commands): string` | Format command help text for a mounted plugin CLI. |
| `isDoctorReportPassing` | `function isDoctorReportPassing(report: DoctorReport): boolean` | Return true when every doctor check is passing. |
| `PluginCliArgs` | `interface PluginCliArgs` | Command arguments passed to plugin CLI handlers. |
| `PluginCliCommand` | `interface PluginCliCommand` | A mounted CLI command handler. |
| `PluginCliResult` | `interface PluginCliResult` | Result returned by plugin CLI handlers. |
| `PluginScaffoldResult` | `interface PluginScaffoldResult` | Result returned by plugin item scaffolders. |
| `DoctorCheck` | `interface DoctorCheck` | Diagnostic entry produced by plugin doctor commands. |
| `DoctorReport` | `interface DoctorReport` | Aggregate doctor report for a plugin CLI. |

### `@netscript/plugin/sdk`

| Symbol | Signature | Description |
| --- | --- | --- |
| `runWalkerPipeline` | `async function runWalkerPipeline(options: RunWalkerPipelineOptions): Promise` | Run the plugin SDK discovery pipeline. |
| `startWalker` | `function startWalker(root: string): Promise` | Start a one-shot SDK walker with default alpha adapters. |
| `startWatcher` | `function startWatcher(): WatcherHandle` | Start a no-op alpha watcher for plugin SDK discovery. |
| `createSourceGraph` | `function createSourceGraph(files, contributions): SourceGraph` | Create a source graph snapshot from walked files and extracted contributions. |
| `createWatcherHandle` | `function createWatcherHandle(): WatcherHandle` | Create a no-op watcher handle for alpha SDK discovery. |
| `createInstrumentationBridge` | `function createInstrumentationBridge()` | Create a recording instrumentation bridge. |
| `createPluginContext` | `function createPluginContext(projectRoot: string): PluginContext` | Create a minimal plugin context for SDK runtime helpers. |
| `createPluginHostBootstrap` | `function createPluginHostBootstrap(plugins): PluginHostBootstrap` | Create a plugin host bootstrap snapshot. |
| `runDoctorReport` | `function runDoctorReport(plugin: string, checks): DoctorReport` | Run plugin doctor checks and return an aggregate report. |
| `AstExtractor` | class | Extractor for exported plugin contribution builder call sites. |
| `FilesystemWalker` | class | Filesystem walker for plugin source discovery. |
| `MemoryManifestResolver` | class | In-memory manifest resolver used by tests and alpha SDK stubs. |
| `ModuleManifestResolver` | class | Manifest resolver backed by dynamic imports. |
| `RegistryEmitter` | class | Registry emitter that writes one generated TypeScript module per contribution axis. |
| `EmitterPort` | interface | Port for emitting generated plugin registry files. |
| `ExtractorPort` | interface | Port for extracting plugin contributions from walked files. |
| `ManifestResolverPort` | interface | Port for resolving a plugin manifest from a package or module specifier. |
| `WalkerPort` | interface | Port for discovering plugin source files. |
| `WalkedFile` | interface | File discovered by a plugin source walker. |
| `SourceGraph` | interface | Source graph snapshot produced by discovery. |
| `RegistryEmission` | interface | Output emitted by the registry emitter. |
| `ExtractedContribution` | interface | Extracted contribution candidate from source. |
| `WatcherHandle` | interface | Watcher handle returned by SDK watch presets. |
| `ModuleManifestResolverOptions` | interface | Options for resolving manifests from importable module specifiers. |
| `RunWalkerPipelineOptions` | interface | Options for running the SDK walker pipeline. |
| `InstrumentationBridge` | interface | Bridge between plugin runtime and telemetry instrumentation. |
| `PluginHostBootstrap` | interface | Result of bootstrapping plugin host state. |
| `PluginServiceContext` | interface | Context supplied to a plugin service at runtime. |

### `@netscript/plugin/loader`

| Symbol | Signature | Description |
| --- | --- | --- |
| `createPluginLogger` | `function createPluginLogger(pluginName: string): PluginLogger` | Create a logger scoped to a plugin service process. |
| `PluginLogger` | `interface PluginLogger` | Minimal logger shape supplied to plugin service contexts. |

### `@netscript/plugin/testing`

| Symbol | Signature | Description |
| --- | --- | --- |
| `createPluginManifestFixture` | `function createPluginManifestFixture(overrides?): PluginManifest` | Example plugin manifest fixture. |
| `createWalkedFileFixture` | `function createWalkedFileFixture(overrides?): WalkedFile` | Example walked file fixture. |
| `runPluginCliContract` | `function runPluginCliContract(cli: PluginCli): boolean` | Run the shared plugin CLI contract against a CLI instance. |
| `MemoryManifestResolver` | class | In-memory manifest resolver used by tests and alpha SDK stubs. |
| `MemoryWalker` | class | In-memory walker for plugin source discovery. |
| `MemoryEmitter` | class | In-memory registry emitter for plugin tests. |
| `MemoryFileSystemAdapter` | class | In-memory file system adapter for plugin tests. |
| `FileSystemPort` | interface | Minimal file system port used by plugin scaffolding. |

### `@netscript/plugin/templates`

| Symbol | Kind | Description |
| --- | --- | --- |
| `PLUGIN_SKELETON_TEMPLATES` | variable | Paths for plugin skeleton template assets. |
| `PluginSkeletonTemplatePath` | type alias | Plugin skeleton template path. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/plugin/_

---

# `@netscript/prisma-adapter-mysql`

Prisma driver adapter for MySQL and MariaDB on Deno. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The package exposes a single root entrypoint (`@netscript/prisma-adapter-mysql` → `./mod.ts`). `PrismaMySql` is the factory you construct with a connection configuration; `connect()` returns a [`PrismaMySqlConnectedAdapter`](#connected-adapter) that you pass to a Prisma client.

## Adapter factory

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `PrismaMySql` | class | `new PrismaMySql(config: MySqlConnectionConfig, options?: PrismaMySqlOptions)` | Factory for creating Prisma MySQL adapter instances. Exposes `provider: "mysql"`, `adapterName: string`, and `connect(): Promise<PrismaMySqlConnectedAdapter>`. |
| `PrismaMySqlAdapterFactory` | reference | `PrismaMySqlAdapterFactory` | Re-export alias of `PrismaMySql`. |
| `inferCapabilities` | function | `function inferCapabilities(version: unknown): MySqlCapabilities` | Infer server capabilities from a version string. |

## Connected adapter

| Symbol | Kind | Description |
| --- | --- | --- |
| `PrismaMySqlConnectedAdapter` | interface | Connected MySQL adapter returned by `PrismaMySql.connect()`. Provides `queryRaw`, `executeRaw`, `executeScript`, `getConnectionInfo`, `startTransaction`, `dispose`, and `underlyingDriver`. |
| `PrismaMySqlTransactionAdapter` | interface | Connected transaction adapter returned by `startTransaction`. Provides `queryRaw`, `executeRaw`, `commit`, and `rollback`. |
| `PrismaMySqlConnectionInfo` | interface | Connection details reported to Prisma (`schemaName?`, `supportsRelationJoins`). |

## Query and result types

| Symbol | Kind | Description |
| --- | --- | --- |
| `PrismaMySqlQuery` | interface | A Prisma query: `sql: string`, `args: unknown[]`, and `argTypes` metadata for each argument. |
| `PrismaMySqlResultSet` | interface | Result set from raw queries: `columnNames`, `columnTypes`, `rows`, and optional `lastInsertId`. |
| `PrismaMySqlIsolationLevel` | type alias | `"READ UNCOMMITTED" \| "READ COMMITTED" \| "REPEATABLE READ" \| "SNAPSHOT" \| "SERIALIZABLE"` — isolation levels accepted by the adapter. |

## Configuration types

| Symbol | Kind | Description |
| --- | --- | --- |
| `MySqlConnectionConfig` | interface | MySQL connection configuration: `hostname?`, `port?`, `username?`, `password?`, `db?`, `poolSize?`, `timeout?`, and `tls?`. |
| `PrismaMySqlOptions` | interface | Adapter options: `database?` (schema name) and `onConnectionError?` callback. |
| `MySqlCapabilities` | interface | Capabilities of the connected MySQL server (`supportsRelationJoins`). |

## Driver interfaces

These describe the underlying `deno_mysql` client surface the adapter wraps.

| Symbol | Kind | Description |
| --- | --- | --- |
| `DenoMySqlClient` | interface | `deno_mysql` client: `connect`, `query`, `execute`, `transaction`, `useConnection`, and `close`. |
| `DenoMySqlConnection` | interface | Connection used inside transactions: `query` and `execute`. |
| `ExecuteResult` | interface | Result from an `execute()` call for INSERT/UPDATE/DELETE: `affectedRows?` and `lastInsertId?`. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/prisma-adapter-mysql/_

---

# `@netscript/queue`

Provider-agnostic message queue abstraction for NetScript applications. It wraps [Fedify](https://fedify.dev/) battle-tested queue adapters behind a single, unified `MessageQueue` interface with optional Zod validation and Aspire-based backend auto-discovery. This page is generated from the package public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/queue`) re-exports the factory functions, the port contracts (`./ports`), the error hierarchy (`./errors`), and the validation helpers (`./validation`). The remaining sub-path exports carry the concrete provider adapters and a test double:

- [`@netscript/queue/ports`](#sub-path-exports) — the core interfaces and enums.
- [`@netscript/queue/errors`](#sub-path-exports) — the queue error classes and codes.
- [`@netscript/queue/validation`](#sub-path-exports) — Zod validation helpers.
- [`@netscript/queue/adapters/deno-kv`](#sub-path-exports) — Deno KV adapter.
- [`@netscript/queue/adapters/redis`](#sub-path-exports) — Redis adapter.
- [`@netscript/queue/adapters/amqp`](#sub-path-exports) — RabbitMQ (AMQP) adapter.
- [`@netscript/queue/adapters/kv-polling`](#sub-path-exports) — KV-polling adapter for KV Connect.
- [`@netscript/queue/testing`](#sub-path-exports) — in-memory adapter for tests.

## Factory functions

| Symbol | Signature | Description |
| --- | --- | --- |
| `createQueue` | `function createQueue<T = unknown>(name: string, options?: QueueOptions): MessageQueue<T>` | Create a message queue instance with auto-discovery (RabbitMQ, then Redis, then Deno KV). |
| `createTypedQueue` | `function createTypedQueue<T>(name: string, schema: ValidationSchema<T>, options?: TypedQueueOptions): TypedMessageQueue<T>` | Create a type-safe message queue with Zod validation at enqueue and dequeue time. |
| `createParallelQueue` | `function createParallelQueue<T = unknown>(name: string, options?: ParallelQueueOptions): MessageQueue<T>` | Create a queue with concurrent processing via Fedify ParallelMessageQueue. |

## Port contracts

Exported from the root and from [`@netscript/queue/ports`](#sub-path-exports).

| Symbol | Kind | Description |
| --- | --- | --- |
| `MessageQueue` | interface | Core message queue interface that all adapters implement (`enqueue`, `listen`). |
| `TypedMessageQueue` | interface | `MessageQueue` extended with runtime schema validation. |
| `MessageContext` | interface | Metadata and acknowledgment controls passed to handlers during processing. |
| `EnqueueOptions` | interface | Options for enqueueing messages (for example, delay). |
| `ListenOptions` | interface | Options for listening to messages. |
| `QueueOptions` | interface | Base options for creating a queue. |
| `TypedQueueOptions` | interface | Options for a typed queue with Zod validation. |
| `ParallelQueueOptions` | interface | Options for a parallel queue (concurrency). |
| `QueueConnectionOptions` | interface | Provider-specific connection options. |
| `QueueProvider` | enum | Supported queue providers (Deno KV, Redis, RabbitMQ). |

## Errors

Exported from the root and from [`@netscript/queue/errors`](#sub-path-exports).

| Symbol | Kind | Description |
| --- | --- | --- |
| `QueueError` | class | Base error class for all queue operations. |
| `QueueConnectionError` | class | Thrown when a queue connection fails. |
| `QueueConfigurationError` | class | Thrown when queue configuration is invalid. |
| `QueueHandlerError` | class | Thrown when a message handler fails. |
| `QueueValidationError` | class | Thrown when message validation fails. |
| `QueueErrorCode` | enum | Error codes for queue operations. |

## Validation

Exported from the root and from [`@netscript/queue/validation`](#sub-path-exports).

| Symbol | Signature | Description |
| --- | --- | --- |
| `safeValidate` | `function safeValidate<T>(schema: ValidationSchema<T>, message: unknown): ValidationResult<T>` | Validate a message against a schema, returning a result object instead of throwing. |
| `validateOrThrow` | `function validateOrThrow<T>(schema: ValidationSchema<T>, message: unknown, context?: Record): T` | Validate a message and throw `QueueValidationError` if invalid. |
| `withValidation` | `function withValidation<T>(schema: ValidationSchema<T>, handler)` | Wrap a handler so messages are validated before it runs. |
| `ValidationSchema` | interface | Minimal schema contract supported by the validation helpers. |
| `ValidationResult` | interface | Result type returned by `safeValidate`. |

## Adapters

Each provider adapter is published under its own sub-path and implements the `MessageQueue` contract directly. Most applications use `createQueue` and never import an adapter explicitly.

| Symbol | Kind | Entrypoint | Description |
| --- | --- | --- | --- |
| `DenoKvAdapter` | class | `@netscript/queue/adapters/deno-kv` | Deno KV queue adapter (default backend). |
| `DenoKvAdapterOptions` | interface | `@netscript/queue/adapters/deno-kv` | Options for `DenoKvAdapter`. |
| `RedisAdapter` | class | `@netscript/queue/adapters/redis` | Redis queue adapter. |
| `AmqpAdapter` | class | `@netscript/queue/adapters/amqp` | AMQP (RabbitMQ) queue adapter. |
| `KvPollingAdapter` | class | `@netscript/queue/adapters/kv-polling` | KV-polling adapter for remote KV Connect (HTTP) backends. |
| `KvPollingAdapterOptions` | interface | `@netscript/queue/adapters/kv-polling` | Options for `KvPollingAdapter`. |

The `kv-polling` adapter additionally re-exports the portable KV store contracts from [`@netscript/kv`](https://rickylabs.github.io/netscript/reference/): `KvStore`, `WatchableKv`, `KvEntry`, `KvKey`, `AtomicMutation`, `AtomicCheck`, `AtomicResult`, `WatchEvent`, and their option interfaces (`KvListOptions`, `KvSetOptions`, `WatchOptions`, `WatchPrefixOptions`), so KV-Connect consumers can type their backing store without a second import.

## Testing

Exported from [`@netscript/queue/testing`](#sub-path-exports).

| Symbol | Kind | Description |
| --- | --- | --- |
| `MemoryQueueAdapter` | class | In-memory `MessageQueue` implementation for port-contract tests. |
| `MemoryQueueAdapterOptions` | interface | Options for `MemoryQueueAdapter`. |

## Sub-path exports

The following entrypoints are published alongside the root export. Their symbols are documented in the sections above.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/queue` | `./mod.ts` | Factories plus re-exported ports, errors, and validation. |
| `@netscript/queue/ports` | `./ports/mod.ts` | Core interfaces and enums. |
| `@netscript/queue/errors` | `./ports/errors.ts` | Error classes and codes. |
| `@netscript/queue/validation` | `./validation/mod.ts` | Zod validation helpers. |
| `@netscript/queue/testing` | `./testing/mod.ts` | In-memory adapter for tests. |
| `@netscript/queue/adapters/deno-kv` | `./adapters/deno-kv.adapter.ts` | Deno KV adapter. |
| `@netscript/queue/adapters/redis` | `./adapters/redis.adapter.ts` | Redis adapter. |
| `@netscript/queue/adapters/amqp` | `./adapters/amqp.adapter.ts` | RabbitMQ (AMQP) adapter. |
| `@netscript/queue/adapters/kv-polling` | `./adapters/kv-polling.adapter.ts` | KV-polling adapter for KV Connect. |

## See it live

- **How-to:** [Queue / KV / cron](https://rickylabs.github.io/netscript/data-persistence/how-to/queue-kv-cron/) — enqueue, consume, and schedule against these symbols end to end.
- **How-to:** [Choose a queue provider](https://rickylabs.github.io/netscript/data-persistence/how-to/choose-a-queue-provider/) — pick and pin a backend from the `QueueProvider` enum above.
- **Concept:** [KV, queues & cron](https://rickylabs.github.io/netscript/data-persistence/kv-queues-cron/) — why a queue is provider-agnostic and how Aspire wires the four backends.

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/queue/_

---

# `@netscript/runtime-config`

Hot-reloadable NetScript runtime override types, loaders, watchers, and diagnostics. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

Runtime config files live under the configured runtime directory and are loaded through a version pointer named `current`. Missing files produce empty defaults so service startup can continue while operators roll out runtime overrides independently. The package exposes a single root entrypoint (`@netscript/runtime-config`); there are no sub-path exports.

## Loaders and watchers

| Symbol | Signature | Description |
| --- | --- | --- |
| `loadRuntimeConfig` | `async function loadRuntimeConfig(): Promise<RuntimeConfig>` | Load runtime overrides from the configured runtime config directory. Returns empty defaults when the directory, pointer file, or topic files are missing. |
| `watchRuntimeConfig` | `function watchRuntimeConfig(onChange: (config: RuntimeConfig) => Promise<void>, options: { signal?: AbortSignal; prefix?: string }): void` | Watch runtime config files and invoke `onChange` after debounced reloads. |

## Override accessors

| Symbol | Signature | Description |
| --- | --- | --- |
| `getJobOverride` | `function getJobOverride(config: RuntimeConfig, jobId: string): JobOverride \| undefined` | Get the override for a specific job ID. |
| `getSagaOverride` | `function getSagaOverride(config: RuntimeConfig, sagaId: string): SagaOverride \| undefined` | Get the override for a specific saga ID. |
| `getTriggerOverride` | `function getTriggerOverride(config: RuntimeConfig, triggerId: string): TriggerOverride \| undefined` | Get the override for a specific trigger ID. |
| `getRuntimeTask` | `function getRuntimeTask(config: RuntimeConfig, taskId: string): RuntimeTask \| undefined` | Get a runtime task definition by ID. |
| `isFeatureEnabled` | `function isFeatureEnabled(config: RuntimeConfig, flagId: string, defaultValue: boolean): boolean` | Check whether a feature flag is enabled, falling back when the flag is absent. |

## Diagnostics

| Symbol | Signature | Description |
| --- | --- | --- |
| `summarizeRuntimeConfig` | `function summarizeRuntimeConfig(config: RuntimeConfig, prefix: string): RuntimeConfigSummary` | Summarize active runtime overrides without emitting presentation output. |

## Configuration types

| Symbol | Kind | Description |
| --- | --- | --- |
| `RuntimeConfig` | interface | Complete runtime override snapshot (jobs, sagas, triggers, features, tasks). |
| `JobOverride` | interface | Job-level runtime override loaded from `runtime/jobs/*.json`. |
| `SagaOverride` | interface | Saga-level runtime override loaded from `runtime/sagas/*.json`. |
| `TriggerOverride` | interface | Trigger-level runtime override loaded from `runtime/triggers/*.json`. |
| `FeatureFlag` | interface | Feature flag loaded from `runtime/features/*.json`. |
| `RuntimeTask` | interface | Task definition that can be added or overridden at runtime. |

## Diagnostics types

| Symbol | Kind | Description |
| --- | --- | --- |
| `RuntimeConfigSummary` | interface | Structured summary of active runtime overrides. |
| `RuntimeConfigTriggerPathOverride` | interface | Trigger path override included in a runtime config summary. |

## Topic constants and aliases

| Symbol | Kind | Description |
| --- | --- | --- |
| `RUNTIME_CONFIG_TOPICS` | variable | Runtime config topic names backed by versioned JSON files (`jobs`, `sagas`, `triggers`, `features`, `tasks`). |
| `RUNTIME_TASK_RUNTIMES` | variable | Supported runtime task execution kinds (`deno`, `python`, `dotnet`, `cmd`, `powershell`, `shell`, `executable`). |
| `RuntimeConfigTopic` | type alias | Runtime config topic name (a member of `RUNTIME_CONFIG_TOPICS`). |
| `RuntimeTaskRuntime` | type alias | Runtime task execution kind (a member of `RUNTIME_TASK_RUNTIMES`). |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/runtime-config/_

---

# `@netscript/plugin-sagas`

NetScript plugin for durable saga orchestration, workflow APIs, and saga runtime metadata. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The published plugin exposes the host-facing plugin manifest, the executable saga runtime and supervisor, the HTTP publisher, the versioned API contract, and the browser-safe stream surface. The userland saga DSL (`defineSaga`, the cascaded-message constructors) is authored against [`@netscript/plugin-sagas-core`](#internals) and re-exported through the runtime entrypoint; the core package is documented as an [Internals](#internals) subsection below.

## Entrypoints

The plugin publishes the following entrypoints. Each is generated from its own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/plugin-sagas` | `./mod.ts` | Plugin manifest, identifiers, and inspection helper (documented below). |
| `@netscript/plugin-sagas/public` | `./src/public/mod.ts` | Curated public manifest surface for host integration. |
| `@netscript/plugin-sagas/plugin` | `./src/public/mod.ts` | Plugin manifest and contribution types (alias of the public surface). |
| `@netscript/plugin-sagas/runtime` | `./src/runtime/mod.ts` | Executable saga runtime, engine, scheduler, publisher, and supervisor. |
| `@netscript/plugin-sagas/contracts` | `./contracts/v1/mod.ts` | Versioned API contract (`sagasContract`) and router types. |
| `@netscript/plugin-sagas/streams` | `./streams/mod.ts` | Browser-safe saga stream schema and collection. |
| `@netscript/plugin-sagas/cli` | `./src/cli/mod.ts` | Plugin CLI commands (inspect, codemod, generate registry). |
| `@netscript/plugin-sagas/scaffolding` | `./src/scaffolding/mod.ts` | Saga item scaffolders and runtime scaffold manifest. |
| `@netscript/plugin-sagas/aspire` | `./src/aspire/mod.ts` | Aspire contribution for the sagas API service. |
| `@netscript/plugin-sagas/services` | `./services/src/main.ts` | Saga API service entrypoint. |
| `@netscript/plugin-sagas/e2e` | `./src/e2e/mod.ts` | End-to-end test contributions. |
| `@netscript/plugin-sagas/streams/server` | `./streams/server.ts` | Server-side stream wiring. |

## Plugin manifest (`@netscript/plugin-sagas`)

The root entrypoint exposes the plugin manifest and stable identifiers. Shared manifest inspection is provided by `inspectPlugin` from `@netscript/plugin`.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `sagasPlugin` | variable | `PluginManifest` | Plugin manifest for NetScript sagas. |
| `SAGAS_PLUGIN_ID` | variable | `"sagas"` | Stable plugin identifier used by manifests, scaffolding, and runtime ownership checks. |
| `SAGAS_PLUGIN_VERSION` | variable | `"1.0.0"` | Plugin manifest version advertised to the NetScript host. |
| `SAGAS_API_SERVICE_NAME` | variable | `"sagas-api"` | Service contribution name for the sagas API process. |
| `SAGAS_API_DEFAULT_PORT` | variable | `8092` | Default HTTP port for the sagas API process. |

## Runtime (`@netscript/plugin-sagas/runtime`)

The runtime entrypoint provides the executable saga runtime and the building blocks a composition root wires together. It also re-exports the userland DSL types and cascaded-message vocabulary from [`@netscript/plugin-sagas-core`](#internals).

### Runtime entry functions and classes

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `startSagaRunner` | function | `startSagaRunner(options: StartSagaRunnerOptions): Promise<SagaRuntimeSupervisor>` | Start the saga runner process and return its supervisor. |
| `runSagaRunner` | function | `runSagaRunner(options: RunSagaRunnerOptions): Promise<void>` | Run the saga runner until a shutdown signal is received. |
| `SagaRuntimeSupervisor` | class | - | Owns one saga runtime process lifecycle. |
| `SagaEngine` | class | - | Native saga engine with indexed dispatch and per-key concurrency throttling. |
| `SagaScheduler` | class | - | Durable timer scheduler for `schedule()` cascaded messages. |
| `SagaCompensator` | class | - | Runtime primitive for `sagaFail()` and `sagaCompensate()` cascades. |
| `createSagaPublisher` | function | `createSagaPublisher(options: HttpSagaPublisherOptions): SagaPublisherPort` | Create a plugin-layer HTTP publisher for sagas API publish endpoints. |
| `HttpSagaPublisher` | class | - | HTTP implementation of the saga publisher port. |
| `loadSagaRegistryModule` | function | `loadSagaRegistryModule(specifier, importer): Promise` | Load saga definitions from the generated static registry module. |
| `SagaIdempotencyDedupTable` | class | - | In-memory idempotency table for local development and tests; use a durable port in production. |

### Runtime ports and facade

| Symbol | Kind | Description |
| --- | --- | --- |
| `SagaRuntime` | interface | Runtime facade returned by the composition root. |
| `SagaRuntimeAdapter` | type alias | Adapter selected by the saga runtime composition root. |
| `SagaBusPort` | interface | Replaceable bus contract implemented by the native saga adapter. |
| `SagaStorePort` | interface | Persistent state store boundary for T1 saga runtime guarantees. |
| `SagaPublisherPort` | interface | Explicit publisher boundary implemented by plugin-layer HTTP clients. |
| `SagaIdempotencyPort` | interface | Durable idempotency boundary for saga publish and cascade deduplication. |
| `CreateSagaRuntimeOptions` | type alias | Options accepted by `createSagaRuntime()`. |
| `SagaEngineOptions` | type alias | Options for the native saga engine. |

### Durability and lifecycle vocabulary

| Symbol | Kind | Description |
| --- | --- | --- |
| `SAGA_DURABILITY_TIERS` | variable | Durability tiers supported by saga definitions. |
| `SAGA_INSTANCE_STATUSES` | variable | Saga instance lifecycle statuses. |
| `CASCADED_MESSAGE_KINDS` | variable | Cascaded message kinds emitted by saga handlers. |
| `SagaDurabilityTier` | type alias | Saga durability tier. |
| `SagaInstanceStatus` | type alias | Saga instance lifecycle status. |
| `SagaDefinition` | type alias | Frozen saga definition produced by the fluent DSL. |
| `SagaContext` | type alias | Handler context passed to pure saga projections. |
| `SagaMessage` | type alias | Base event or command delivered to a saga handler. |
| `SagaSignal` | type alias | External signal delivered to a running saga instance. |
| `CascadedMessage` | type alias | Message emitted by a saga handler as its only side-effect ledger. |
| `SagaStateEnvelope` | type alias | Persisted saga state envelope. |
| `RetryPolicy` | type alias | Retry policy for saga handlers and cascaded messages. |

> The runtime entrypoint exports 95 symbols in total. The tables above list the primary surface. Branded id aliases (`SagaId`, `SagaInstanceId`, `SagaMessageId`, `SagaCorrelationKey`), scheduler records and publisher receipt/JSON types are part of the published surface and resolve through `deno doc plugins/sagas/src/runtime/mod.ts`.

## API contract (`@netscript/plugin-sagas/contracts`)

Version 1 of the sagas plugin API contract, its Zod schemas, and the router types.

| Symbol | Kind | Description |
| --- | --- | --- |
| `sagasContract` / `sagasContractV1` | variable | The versioned sagas API contract definition. |
| `SagasContractDefinition` / `SagasContractV1` | type alias | Contract shape for the sagas API. |
| `SagasRouter` | interface | Router type derived from the sagas contract. |
| `SagaDefinitionResponse` / `SagaDefinitionResponseSchema` | type / schema | Saga definition response payload and its Zod schema. |
| `SagaInstanceResponse` / `SagaInstanceResponseSchema` | type / schema | Saga instance response payload and its Zod schema. |
| `PublishMessageInput` / `PublishMessageInputSchema` | type / schema | Publish-message request payload and its Zod schema. |
| `SagaSSEEvent` / `SagaSSEEventSchema` | type / schema | Server-sent event payload streamed to subscribers. |
| `SagaFilters` / `InstanceFilters` | type | List/query filters for sagas and instances. |
| `ListSagasInput` / `ListSagasOutput` | type | List-sagas request and response. |
| `ListInstancesInput` / `ListInstancesOutput` | type | List-instances request and response. |
| `GetInstanceHistoryInput` / `GetInstanceHistoryOutput` | type | Instance-history request and response. |

## Streams (`@netscript/plugin-sagas/streams`)

Browser-safe stream exports for the sagas plugin.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `createSagasStreamDB` | function | `createSagasStreamDB(...): SagasStreamDB` | Create the saga instance stream database. |
| `SagasStreamDB` | type alias | - | Stream database type for saga instances. |
| `SagaInstance` | type alias | - | Saga instance row materialized into the stream. |
| `SagaInstanceSchema` | variable | - | Zod schema for a saga instance stream row. |
| `sagasStreamSchema` | variable | - | Stream schema describing the saga collections. |
| `SAGA_INSTANCE_STATUSES` | variable | - | Saga instance lifecycle statuses. |

## CLI, scaffolding, and Aspire

| Entrypoint | Primary exports |
| --- | --- |
| `@netscript/plugin-sagas/cli` | `SagasCli`, `SAGAS_CLI_COMMANDS`, `generateSagaRegistry`, `codemodSagaImports`, `inspectSagasProject` |
| `@netscript/plugin-sagas/scaffolding` | `createSagasItemScaffolders`, `SAGAS_RUNTIME_SCAFFOLD_MANIFEST`, `SagaDefinitionScaffolder`, `SagaConfigScaffolder` |
| `@netscript/plugin-sagas/aspire` | `SagasAspireContribution`, `SagasAspireBuilder`, `SagasAspireResource`, `SagasHealthCheckSpec` |

---

## Internals

> The following surface belongs to `@netscript/plugin-sagas-core`, the framework-internal package that implements the saga DSL, runtime ports, adapters, telemetry, config, and testing primitives. Application authors normally import these symbols through `@netscript/plugin-sagas`; the core package is documented here for completeness (US-8). It is not a separate top-level reference entry.

### `@netscript/plugin-sagas-core`

Saga DSL, runtime ports, adapters, telemetry, config, and testing primitives for NetScript sagas plugins. Its root entrypoint (`./mod.ts`) is the authoring surface for saga definitions.

#### DSL constructors (root export)

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `defineSaga` | function | `defineSaga(id: TId): SagaBuilder` | Start a userland saga definition chain. |
| `defineQuery` | function | `defineQuery(name: TName): QueryDefinition` | Define a synchronous read-only query for a running saga instance. |
| `defineSignal` | function | `defineSignal(name: TName): SignalDefinition` | Define a signal that can be sent to a running saga instance. |
| `send` | function | `send(target, payload: unknown, options?: SendOptions): CascadedMessage` | Create a cascaded send message. |
| `spawn` | function | `spawn(child, input: unknown, options?: SpawnOptions): CascadedMessage` | Create a cascaded child-saga spawn message. |
| `schedule` | function | `schedule(message, delay: SagaScheduleDelay): CascadedMessage` | Create a cascaded scheduled message. |
| `sagaComplete` | function | `sagaComplete(result: unknown): CascadedMessage` | Create a terminal saga completion message. |
| `sagaFail` | function | `sagaFail(reason): CascadedMessage` | Create a terminal saga failure message. |
| `sagaCompensate` | function | `sagaCompensate(message, reason: string): CascadedMessage` | Create a cascaded compensation message. |

#### DSL types (root export)

| Symbol | Kind | Description |
| --- | --- | --- |
| `SagaBuilder` | interface | Userland fluent saga builder. |
| `SagaBuilderPhase` | type alias | Typestate phase for the userland saga builder. |
| `SagaEvent` | type alias | Event shape inferred by `defineSaga().on(type, handler)`. |
| `SagaHandler` | type alias | Synchronous saga handler that returns cascaded messages. |
| `SagaState` | type alias | Base state shape accepted by saga definitions. |
| `SagaConcurrencyOptions` / `SagaConcurrencyPolicy` | type alias | Concurrency options/policy for a saga definition. |
| `CascadedMessage` / `CascadedMessageKind` / `CascadedMessageTarget` | type alias | Cascaded-message side-effect ledger vocabulary. |
| `QueryDefinition` / `SignalDefinition` | type alias | Query/signal definitions reserved by the public DSL. |
| `SendOptions` / `SpawnOptions` / `SagaScheduleDelay` | type alias | Options for the `send()`, `spawn()`, and `schedule()` constructors. |

#### Core sub-path entrypoints

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/plugin-sagas-core` | `./mod.ts` | DSL constructors and types (documented above). |
| `@netscript/plugin-sagas-core/builders` | `./src/builders/mod.ts` | Fluent `defineSaga` builder and DSL constructors. |
| `@netscript/plugin-sagas-core/domain` | `./src/domain/mod.ts` | Domain primitives, `SagasError`, defaults, and branded ids. |
| `@netscript/plugin-sagas-core/ports` | `./src/ports/mod.ts` | Runtime port interfaces (`SagaBusPort`, `SagaStorePort`, idempotency). |
| `@netscript/plugin-sagas-core/runtime` | `./src/runtime/mod.ts` | Native runtime engine wiring consumed by the plugin runtime. |
| `@netscript/plugin-sagas-core/adapters` | `./src/adapters/mod.ts` | Bus/store adapters. |
| `@netscript/plugin-sagas-core/transports` | `./src/transports/mod.ts` | Transport implementations. |
| `@netscript/plugin-sagas-core/stores` | `./src/stores/mod.ts` | State store implementations. |
| `@netscript/plugin-sagas-core/middleware` | `./src/middleware/mod.ts` | Saga middleware primitives. |
| `@netscript/plugin-sagas-core/telemetry` | `./src/telemetry/mod.ts` | Saga telemetry instrumentation. |
| `@netscript/plugin-sagas-core/config` | `./src/config/mod.ts` | Saga runtime configuration. |
| `@netscript/plugin-sagas-core/contracts/v1` | `./src/contracts/v1/mod.ts` | Core contract primitives. |
| `@netscript/plugin-sagas-core/streams` | `./src/streams/mod.ts` | Core stream schema primitives. |
| `@netscript/plugin-sagas-core/presets` | `./src/presets/mod.ts` | Runtime presets. |
| `@netscript/plugin-sagas-core/abstracts` | `./src/abstracts/mod.ts` | Abstract base primitives. |
| `@netscript/plugin-sagas-core/testing` | `./src/testing/mod.ts` | Deterministic saga test helpers. |
| `@netscript/plugin-sagas-core/agent` | `./src/agent/mod.ts` | Agent-integration primitives. |
| `@netscript/plugin-sagas-core/integration/workers` | `./src/integration/workers/mod.ts` | Workers integration seam. |
| `@netscript/plugin-sagas-core/integration/publisher` | `./src/integration/publisher/mod.ts` | Publisher integration seam. |

#### Domain primitives (`@netscript/plugin-sagas-core/domain`)

| Symbol | Kind | Description |
| --- | --- | --- |
| `SagasError` | class | Structured error thrown by sagas core APIs. |
| `SAGAS_ERROR_CODES` / `SagasErrorCode` | variable / type | Error codes produced by `SagasError`. |
| `DEFAULT_RETRY_POLICY` | variable | Default retry policy used when a saga does not override retry behavior. |
| `DEFAULT_SAGA_DURABILITY_TIER` | variable | Default durability tier for saga definitions. |
| `DEFAULT_RETRY_MAX_ATTEMPTS` | variable | Default maximum retry attempts for cascaded messages. |
| `DEFAULT_IDEMPOTENCY_WINDOW_MS` | variable | Default idempotency deduplication window in milliseconds. |
| `SAGA_ADAPTER_KINDS` / `SagaAdapterKind` | variable / type | Runtime adapter kinds supported by `createSagaRuntime`. |
| `SagaMessageType` | type alias | Extracts the message type discriminator from a saga message. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/sagas/_

---

# `@netscript/sdk`

Service discovery, oRPC clients, and cache-backed query factories for NetScript. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/sdk`) is the high-level composition preset for service-aware applications: it re-exports the client, query, query-client, discovery, cache, telemetry, and OpenAPI surfaces and adds the `defineServices()` preset. A single `defineServices()` call wires the whole typed stack — service clients, cache-aware query factories, and query utils — from one service map, so a component imports ready-to-use `queryOptions()` / `mutationOptions()` instead of hand-writing fetch wrappers. Focused sub-path exports carry the same values for narrow imports - see [Sub-path exports](#sub-path-exports).

## Composition preset (`defineServices`)

These symbols are available only from the root export.

| Symbol | Kind | Description |
| --- | --- | --- |
| `defineServices` | function | Create SDK clients, query factories, and query utils from one service map. |
| `DefineServiceConfig` | interface | Service definition consumed by `defineServices()`. |
| `DefineServicesConfigMap` | type alias | Input map accepted by `defineServices()`. |
| `DefinedServices` | interface | Result object returned by `defineServices()`. |
| `DefinedServiceClients` | type alias | Service clients produced by `defineServices()`. |
| `DefinedServiceQueries` | type alias | Query factories produced by `defineServices()`. |
| `DefinedServiceQueryUtils` | type alias | Service query utils produced by `defineServices()`. |

## Service clients (`@netscript/sdk/client`)

| Symbol | Kind | Signature / Description |
| --- | --- | --- |
| `createServiceClient` | function | Type-safe service client using Aspire service discovery and oRPC. Signature: `createServiceClient<TContract>(options): ServiceClient<TContract>`. |
| `safe` | function | Resolve a promise into a tuple/object result mirroring the oRPC safe-call ergonomics. |
| `isDefinedError` | function | Narrow an unknown error to an oRPC defined error. |
| `ServiceClient` | type alias | Typed service client derived from a contract router. |
| `ServiceClientShape` | type alias | Recursive callable/router shape for a typed service client. |
| `ServiceClientMethod` | type alias | Typed service-client method derived from a contract procedure. |
| `ServiceClientContext` | interface | Per-call service client context. |
| `ServiceClientContract` | interface | Compile-time marker that preserves the source contract for inference. |
| `ServiceRequestOptions` | interface | Optional second argument passed to service-client methods. |
| `CreateServiceClientOptions` | interface | Options for creating a discovered service client. |
| `ContractLike` | type alias | Recursive structural representation of an oRPC contract router. |
| `ContractProcedureLike` | interface | Minimal structural representation of an oRPC contract procedure. |
| `ContractProcedureMetadata` | interface | Public oRPC metadata used to derive client typing. |
| `ContractProcedureNames` | type alias | Procedure names available on a contract router. |
| `ContractSchema` | interface | Minimal structural representation of a standard-schema-compatible type. |
| `ContractSchemaInput` | type alias | Infer the input type from a standard schema. |
| `ContractSchemaOutput` | type alias | Infer the output type from a standard schema. |
| `ProcedureInputFromNode` | type alias | Input payload for a contract procedure node. |
| `ProcedureOutputFromNode` | type alias | Output payload for a contract procedure node. |
| `DefinedError` | interface | Public shape of an oRPC defined error. |
| `SafeResult` | type alias | Tuple/object result returned by `safe`. |
| `SafeSuccess` | type alias | Success branch returned by `safe`. |
| `SafeFailure` | type alias | Failure branch returned by `safe`. |

## Server-side query factories (`@netscript/sdk/query`)

| Symbol | Kind | Signature / Description |
| --- | --- | --- |
| `createQueryFactory` | function | Query factory for an oRPC contract. Signature: `createQueryFactory<TContract>(resource, contract, client, defaultOptions): QueryFactory<TContract>`. |
| `createQueryFactories` | function | Create multiple query factories at once from a resource-to-config map. |
| `createCompositeQuery` | function | Combine multiple endpoints under one cache key. |
| `setCacheProvider` | function | Register the cache engine (server bootstrap). |
| `hasCacheProvider` | function | Check whether a cache provider has been registered. |
| `QueryFactory` | type alias | Generated query helpers for a contract resource. |
| `ActionMethod` | interface | Query helper bound to a specific resource action. |
| `CompositeQuery` | interface | Composite query helper contract for multi-endpoint aggregations. |
| `FactoryConfig` | interface | Configuration for a single query factory. |
| `CacheProvider` | interface | Minimal interface the query-factory layer needs from the cache engine. |
| `ProcedureInput` | type alias | Input payload for a contract procedure. |
| `ProcedureOutput` | type alias | Output payload for a contract procedure. |

## Cache engine (`@netscript/sdk/cache`)

Server-side only. Importing this subpath auto-registers the shared KV-backed cache provider.

| Symbol | Kind | Description |
| --- | --- | --- |
| `cacheQuery` | variable | Shared cache-query singleton. |
| `CacheQuery` | class | Query cache engine with stale-while-revalidate semantics. |
| `KvCacheStore` | class | SDK cache store backed by the shared `@netscript/kv` singleton. |
| `setCacheProvider` | function | Register the cache engine (call once during server bootstrap). |
| `getCacheProvider` | function | Retrieve the registered cache provider. |
| `hasCacheProvider` | function | Check whether a cache provider has been registered. |
| `resetCacheProvider` | function | Reset the cache provider (primarily for testing). |
| `createActionQueryKey` | function | Build a canonical resource/action/input query key. |
| `serializeQueryKeyInput` | function | Serialize structured query input into the canonical cache-key segment. |
| `isCacheEntryStale` | function | Determine whether a cached entry is stale for a freshness window. |
| `toCachedEntry` | function | Convert a persisted cache entry into the public cached-entry shape. |
| `CacheEntry` | interface | Persisted cache payload stored by the SDK cache engine. |
| `CachedEntry` | interface | Public cache entry shape returned to framework consumers. |
| `CacheProvider` | interface | Minimal interface the query-factory layer needs from the cache engine. |
| `CacheQueryOptions` | interface | Full cache-query execution options. |
| `QueryParams` | interface | Cache policy overrides for a query execution. |
| `QueryKey` | type alias | Serializable query key used to address cached entries. |
| `QueryKeyPart` | type alias | Primitive query-key segment supported by the SDK cache layer. |

## Query client / TanStack integration (`@netscript/sdk/query-client`)

Browser- and island-facing TanStack Query integration.

| Symbol | Kind | Signature / Description |
| --- | --- | --- |
| `createNetScriptQueryClient` | function | TanStack QueryClient with server-first defaults. Signature: `createNetScriptQueryClient(options): QueryClientPort`. |
| `createServiceQueryUtils` | function | TanStack Query utils from an oRPC service client. Signature: `createServiceQueryUtils<TContract>(client, options?): ServiceQueryUtils<TContract>`. |
| `createKvCachePersister` | function | KV-backed async storage adapter for TanStack Query persistence. |
| `bridgeInvalidation` | function | Build a client-side invalidation filter from a resource and optional action. |
| `toClientKeyPrefix` | function | Convert an SDK resource/action pair to a client-side TanStack key prefix. |
| `DEFAULT_STALE_TIME` | variable | Default stale time (30 s) matching the server-first philosophy. |
| `DEFAULT_GC_TIME` | variable | Default garbage-collection time (5 min) matching the server KV cache TTL. |
| `QueryClientPort` | interface | Structural query-client port used by SDK factories and collection adapters. |
| `QueryClientFilters` | interface | Cache selector for invalidation and lookup operations. |
| `QueryClientFetchOptions` | interface | Options accepted by query fetch operations. |
| `QueryClientSetOptions` | interface | Options accepted by cache write operations. |
| `QueryClientPredicate` | type alias | Predicate filtering query cache operations by key or metadata. |
| `QueryOptionsWithInitialData` | interface | TanStack-compatible options produced by the query-options helper. |
| `ActionQueryOptions` | interface | Configuration for the action query-options helper. |
| `ActionMutationOptions` | interface | Configuration for the action mutation-options helper. |
| `MutationOptionsResult` | interface | TanStack-compatible mutation options produced by the SDK. |
| `CreateServiceQueryUtilsOptions` | interface | Options for creating TanStack Query utils from an SDK service client. |
| `NetScriptQueryClientOptions` | interface | Options for `createNetScriptQueryClient`. |
| `KvCachePersisterOptions` | interface | Options for `createKvCachePersister`. |
| `KvCachePersisterStorage` | interface | Async storage adapter shape used by the persister. |
| `ServiceQueryUtils` | type alias | TanStack Query utilities derived from a service contract. |
| `ServiceProcedureQueryUtils` | interface | TanStack Query utilities for one service procedure. |
| `ServiceProcedureQueryOptions` | type alias | Query options accepted by a service procedure utility. |
| `ServiceProcedureQueryResult` | interface | Query options returned by a service procedure utility. |
| `ServiceProcedureMutationOptions` | interface | Mutation options accepted by a service procedure utility. |
| `ServiceProcedureMutationResult` | interface | Mutation options returned by a service procedure utility. |
| `ServiceProcedureInfiniteOptions` | interface | Infinite-query options accepted by a service procedure utility. |
| `ServiceProcedureInfiniteResult` | interface | Infinite-query options returned by a service procedure utility. |
| `ServiceProcedureStreamedOptions` | type alias | Streamed-query options accepted by a service procedure utility. |
| `ServiceProcedureStreamedResult` | type alias | Streamed-query options returned by a service procedure utility. |
| `ServiceProcedureLiveResult` | type alias | Live-query options returned by a service procedure utility. |
| `ServiceOperationKey` | type alias | Partial matching key generated by service query utilities. |
| `ServiceOperationKeyOptions` | interface | Partial matching-key options at router or procedure level. |
| `ServiceOperationType` | type alias | Operation kinds accepted by service query utility keys. |
| `ServiceOptionalInputRest` | type alias | Optional/required single-option tuple based on input optionality. |
| `ServicePartialInput` | type alias | Deep partial input used by matching-key helpers. |
| `ServiceQueryKeyOptions` | type alias | Query-key options for a single service procedure. |
| `ServiceStreamedKeyOptions` | interface | Serializable streamed-query key options. |
| `ServiceQueryClientContext` | type alias | Empty oRPC client context used by SDK-created service clients. |

## Collections (`@netscript/sdk/collections`)

| Symbol | Kind | Description |
| --- | --- | --- |
| `createQueryCollection` | function | Create a TanStack DB collection backed by TanStack Query for data fetching. |
| `QueryCollection` | interface | Structural collection returned by `createQueryCollection()`. |
| `QueryCollectionOptions` | interface | Options for `createQueryCollection`. |
| `QueryCollectionStatus` | type alias | Collection status values exposed by the SDK collection port. |
| `QueryCollectionTransaction` | interface | Opaque transaction returned by collection mutation operations. |
| `QueryCollectionUpdate` | type alias | Callback used to update one collection item. |
| `QueryCollectionUpdateMany` | type alias | Callback used to update multiple collection items. |

## Service discovery (`@netscript/sdk/discovery`)

Resolves Aspire-managed service URLs and database/KV connections from environment variables.

| Symbol | Kind | Description |
| --- | --- | --- |
| `getServiceUrl` | function | Get a service URL from Aspire browser or server environment variables. |
| `getServiceInfo` | function | Get all endpoints for a service. |
| `getAllServices` | function | Get all available server-side Aspire service names. |
| `isServiceAvailable` | function | Check whether a service endpoint is available. |
| `getKvConnection` | function | Get KV connection from SQLite or remote Deno KV environment variables. |
| `getPostgresConnection` | function | Get PostgreSQL connection settings from environment variables. |
| `getPostgresUri` | function | Get the PostgreSQL connection URI. |
| `getMysqlConnection` | function | Get MySQL connection settings from environment variables. |
| `getMysqlUri` | function | Get the MySQL connection URI. |
| `getMssqlConnection` | function | Get SQL Server connection settings from environment variables. |
| `getMssqlUri` | function | Get the SQL Server connection URI. |
| `ServiceInfo` | interface | Resolved service endpoint metadata discovered from Aspire env vars. |
| `ServiceProtocol` | type alias | Supported protocols for Aspire service discovery endpoints. |
| `PostgresConnectionInfo` | interface | PostgreSQL connection details discovered from Aspire env vars. |
| `MysqlConnectionInfo` | interface | MySQL connection details discovered from Aspire env vars. |
| `MssqlConnectionInfo` | interface | SQL Server connection details discovered from Aspire env vars. |

## Durable streams (`@netscript/sdk/streams`)

Server-side writers and schema helpers for NetScript durable streams (State Protocol).

| Symbol | Kind | Description |
| --- | --- | --- |
| `createStreamProducer` | function | Create or reuse a durable stream producer for a stream path. |
| `createDurableStream` | reference | Re-export alias for the durable stream producer factory. |
| `defineStreamSchema` | function | Define a type-safe durable stream schema. |
| `inspectStreamTopic` | function | Inspect a stream schema and optional producer metadata. |
| `buildStreamUrl` | function | Build the full stream URL for a NetScript stream path. |
| `getStreamsUrl` | function | Resolve the base URL of the durable streams server. |
| `getStreamsAuth` | function | Resolve authentication headers for the durable streams server. |
| `DurableStreamProducer` | class | Server-side writer for a named durable stream. |
| `DurableStreamProducerOptions` | interface | Options accepted by `DurableStreamProducer`. |
| `StreamProducerPort` | interface | Port implemented by stream producers that publish State Protocol changes. |
| `StateSchema` | type alias | Schema map returned by `defineStreamSchema`. |
| `StreamStateDefinition` | type alias | Input map accepted by `defineStreamSchema`. |
| `CollectionDefinition` | interface | A single collection definition inside a durable stream schema. |
| `CollectionEventHelpers` | interface | Helper methods attached to collections by the durable-streams state layer. |
| `CollectionWithHelpers` | type alias | Collection definition after durable-streams helpers are attached. |
| `ChangeEvent` | interface | Entity change event emitted by durable stream producers. |
| `ControlEvent` | interface | Control event emitted for non-entity lifecycle changes. |
| `StateEvent` | type alias | Durable stream event union. |
| `Operation` | type alias | State Protocol operation names supported by durable streams. |
| `StreamTopicInspectionInput` | interface | Input accepted by `inspectStreamTopic`. |
| `StreamTopicInspectionReport` | interface | Diagnostic report returned by `inspectStreamTopic`. |

## Telemetry (`@netscript/sdk/telemetry`)

| Symbol | Kind | Description |
| --- | --- | --- |
| `otelMiddleware` | function | Create a typed passthrough OpenTelemetry middleware for oRPC composition. |
| `MiddlewareHandler` | type alias | Minimal async middleware signature used by the SDK. |
| `MiddlewareNext` | type alias | Next-handler signature for the SDK middleware chain. |

## Ports (`@netscript/sdk/ports`)

Package-owned, upstream-type-free structural ports shared with other NetScript packages. The port surface re-exports the structural contracts documented in the sections above (`QueryClientPort`, `CacheStore`, `ServiceMetadata`, `ServiceQueryUtils`, `HealthCheckResponse`, `PaginatedResponse`, the service operation/key types, and the cache/contract structural aliases). Import from `@netscript/sdk/ports` when implementing or consuming these contracts without pulling in the concrete client, query, or cache engines.

| Representative symbol | Kind | Description |
| --- | --- | --- |
| `QueryClientPort` | interface | Structural query-client port used by SDK factories and collection adapters. |
| `CacheStore` | interface | Structural cache store contract. |
| `CacheStoreEntry` | interface | Entry shape stored by a `CacheStore`. |
| `CacheKey` | type alias | Structural cache key contract. |
| `ServiceMetadata` | interface | Service metadata port. |
| `ServiceTransport` | interface | Transport port for service clients. |
| `HealthCheckResponse` | interface | Standard health-check response contract. |
| `PaginatedResponse` | interface | Standard paginated response contract. |
| `ServiceQueryUtils` | type alias | Query-utility port derived from a service contract. |

## OpenAPI helpers

Available from the root export.

| Symbol | Kind | Description |
| --- | --- | --- |
| `createOpenAPIGenerator` | function | Create an OpenAPI generator configured for Zod-backed oRPC contracts. |
| `generateOpenAPISpec` | function | Generate an OpenAPI document from a contract router. |
| `OpenAPIConfig` | interface | Shared OpenAPI configuration contract used by higher-level packages. |
| `OpenAPIDocument` | type alias | Public OpenAPI document shape returned by the SDK. |
| `OpenAPIGeneratorLike` | interface | Minimal generator contract exposed by the SDK. |

## Sub-path exports

The following entrypoints are published alongside the root export. Each carries the same values exposed by the root for narrow imports.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/sdk` | `./mod.ts` | High-level composition preset (`defineServices`) plus all surfaces below. |
| `@netscript/sdk/client` | `./src/client/mod.ts` | `createServiceClient` and the contract algebra. |
| `@netscript/sdk/query` | `./src/query/mod.ts` | Server-side cache-aware query factories. |
| `@netscript/sdk/query-client` | `./src/query-client/mod.ts` | TanStack Query integration for browser/island code. |
| `@netscript/sdk/cache` | `./src/cache/mod.ts` | Server-side KV-backed cache engine (auto-registers the provider). |
| `@netscript/sdk/collections` | `./src/collections/mod.ts` | TanStack DB collection backed by TanStack Query. |
| `@netscript/sdk/discovery` | `./src/discovery/mod.ts` | Aspire service URL and database/KV connection discovery. |
| `@netscript/sdk/ports` | `./src/ports/mod.ts` | Package-owned structural ports (upstream-type-free). |
| `@netscript/sdk/streams` | `./src/streams.ts` | Durable stream producers and schema helpers. |
| `@netscript/sdk/telemetry` | `./src/telemetry/mod.ts` | OpenTelemetry middleware for oRPC. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/sdk/_

---

# `@netscript/service`

Service bootstrap builders, health probes, and Hono/oRPC runtime wiring for NetScript applications. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The package has three layers. **Layer 1** exposes small primitives for health, error, RPC, OpenAPI, and Scalar docs handlers. **Layer 2** exposes `createService()`, a fluent builder that materializes a mountable `ServiceApp` or starts a listener. **Layer 3** exposes `defineService()`, the preset used by generated service entrypoints.

The service router is always an input to the builder. `build()` returns a non-listening `ServiceApp`, which keeps the RFC 14 unified-platform seam open for callers that mount service apps into another host. `serve()` starts a Deno listener and returns a `RunningService` handle with `stop()` for tests, local development, and process supervisors.

Public types are package-owned structural mirrors: callers do not need to import Hono or oRPC types to describe a service surface. Runtime interoperability still uses the real Hono app and oRPC handlers internally. `LoggerMiddlewareOptions` is re-exported from the sibling [`@netscript/logger/middleware`](https://rickylabs.github.io/netscript/reference/logger/) package because it is a first-party `@netscript/*` contract, not an upstream vendor surface.

## Builder and presets

| Symbol | Signature | Description |
| --- | --- | --- |
| `createService` | `function createService<T extends ServiceRouter>(router: T, config: ServiceConfig): ServiceBuilder<T>` | Factory function to create a new service builder. |
| `defineService` | `async function defineService<T extends ServiceRouter>(router: T, options: DefineServiceOptions): Promise<RunningService>` | One-liner preset for creating a fully-configured service. |

## Health primitives

| Symbol | Signature | Description |
| --- | --- | --- |
| `createHealthHandler` | `function createHealthHandler(options?: HealthHandlerOptions): ServiceHandler` | Creates a comprehensive health check handler that runs all checks in parallel. |
| `createLivenessHandler` | `function createLivenessHandler(): ServiceHandler` | Creates a simple liveness check handler. |
| `createReadinessHandler` | `function createReadinessHandler(checks: Array<() => Promise<boolean>>): ServiceHandler` | Creates a readiness check handler that runs multiple async checks. |
| `healthChecks` | `const healthChecks: { database; kv; service; custom }` | Pre-built health checks for common dependencies (`database`, `kv`, `service`, `custom`). |
| `HEALTH_STATUS` | `const HEALTH_STATUS: { healthy; degraded; unhealthy }` | Health status values emitted by service health handlers. |

## RPC, OpenAPI, and docs handlers

| Symbol | Signature | Description |
| --- | --- | --- |
| `createRPCHandler` | `function createRPCHandler<T extends ServiceRouter>(router: T, config?: RPCHandlerConfig): FetchHandler` | Creates an oRPC RPC handler for type-safe client communication. |
| `createRPCPlugins` | `function createRPCPlugins(config: RPCHandlerConfig): ServiceHandlerPlugin[]` | Creates the standard set of oRPC plugins. |
| `createOpenAPIHandler` | `function createOpenAPIHandler<T extends ServiceRouter>(router: T, config?: RPCHandlerConfig): FetchHandler` | Creates an oRPC OpenAPI handler for REST-style API access. |
| `createOpenAPISpec` | `function createOpenAPISpec<T extends ServiceRouter>(router: T, config: OpenAPIConfig): ServiceHandler` | Creates an OpenAPI specification endpoint handler. |
| `createScalarDocs` | `function createScalarDocs(options: ScalarDocsOptions): ServiceHandler` | Creates a Scalar API documentation UI handler. |
| `createScalarJs` | `function createScalarJs(): ServiceHandler` | Creates a handler to serve the bundled Scalar JS file. |

## Error and routing handlers

| Symbol | Signature | Description |
| --- | --- | --- |
| `createErrorHandler` | `function createErrorHandler(serviceName: string): ServiceErrorHandler` | Creates a global error handler for uncaught exceptions. |
| `createNotFoundHandler` | `function createNotFoundHandler(serviceName: string): ServiceHandler` | Creates a 404 Not Found handler for unmatched routes. |

## Configuration and option types

| Symbol | Kind | Description |
| --- | --- | --- |
| `ServiceConfig` | interface | Service configuration options (input to `createService`). |
| `DefineServiceOptions` | interface | Options for the `defineService` preset. |
| `ServeOptions` | interface | Options for starting a service listener. |
| `CorsOptions` | interface | CORS options supported by `withCors()`. |
| `OpenAPIConfig` | interface | Configuration for OpenAPI spec generation. |
| `RPCHandlerConfig` | interface | Configuration options for RPC handlers. |
| `ScalarDocsOptions` | interface | Configuration for the Scalar docs UI. |
| `HealthHandlerOptions` | interface | Options for `createHealthHandler`. |
| `LoggerMiddlewareOptions` | interface | Options for the logger middleware (re-exported from `@netscript/logger/middleware`). |

## Service surface types

| Symbol | Kind | Description |
| --- | --- | --- |
| `ServiceBuilder` | interface | Fluent builder for configuring and materializing a NetScript service. |
| `ServiceApp` | interface | Minimal mountable service application returned by `build()`. |
| `RunningService` | interface | Running service handle returned by `serve()` and `defineService()`. |
| `RunningServiceAddress` | interface | Network address assigned to a running service listener. |
| `ServiceContext` | interface | Minimal context shape exposed to service middleware and handlers. |
| `ServiceRequest` | interface | Minimal request shape exposed to service middleware and handlers. |
| `ServiceMiddleware` | interface | Middleware function accepted by the service builder. |
| `ServiceHandler` | interface | Service route handler accepted by the builder route API. |
| `ServiceHandlerPlugin` | interface | Structural oRPC plugin accepted by service handler factories. |
| `ServiceErrorHandler` | interface | Error handler used by service applications. |
| `FetchHandler` | interface | Structural fetch handler used by RPC and OpenAPI service adapters. |
| `FetchHandlerResult` | interface | Result returned by oRPC-compatible fetch handlers. |

## Health types

| Symbol | Kind | Description |
| --- | --- | --- |
| `HealthCheck` | interface | A single health check definition. |
| `HealthResponse` | interface | Response format for the health endpoint. |
| `Database` | interface | Database client capable of a health-check query. |
| `HealthStatus` | type alias | Health status emitted by the service health endpoint (`typeof HEALTH_STATUS[keyof typeof HEALTH_STATUS]`). |

## Router and context type aliases

| Symbol | Signature | Description |
| --- | --- | --- |
| `ServiceRouter` | `type ServiceRouter = Record<string, unknown>` | Router definition accepted by the service builder and handler factories. |
| `ContextFactory` | `type ContextFactory = (context: ServiceContext) => Record<string, unknown>` | Creates per-request service handler context. |
| `DbContext` | `type DbContext = Record<string, unknown>` | Database context injected into service handler context. |

## Exports

`@netscript/service` publishes a single root entrypoint. There are no sub-path exports.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/service` | `./mod.ts` | Full service surface (documented above). |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/service/_

---

# `@netscript/plugin-streams`

Durable Streams development plugin for NetScript: a plugin manifest plus CLI, scaffolding, end-to-end gate, and Aspire integration surfaces for a durable, change-data stream service. This page is generated from the plugin public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The plugin ships five published entrypoints. The root export (`@netscript/plugin-streams`) carries the manifest and the typed topic/producer/consumer authoring helpers; four sub-path exports carry the framework integrations:

- [`@netscript/plugin-streams/cli`](#sub-path-cli) — plugin CLI command group.
- [`@netscript/plugin-streams/scaffolding`](#sub-path-scaffolding) — scaffolder descriptor.
- [`@netscript/plugin-streams/e2e`](#sub-path-e2e) — E2E gate definitions.
- [`@netscript/plugin-streams/aspire`](#sub-path-aspire) — Aspire AppHost contribution.

The schema, producer, telemetry, testing, and diagnostics primitives that the plugin builds on live in the internal `@netscript/plugin-streams-core` package, documented in [Internals](#internals) below.

## Plugin manifest

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `streamsPlugin` | variable | `const streamsPlugin: PluginManifest` | Plugin manifest for the NetScript Durable Streams service. |

## Topic authoring

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `defineStreamTopic` | function | `function defineStreamTopic(name, schema): StreamTopicDefinition` | Define a typed stream topic. |
| `defineStreamProducer` | function | `function defineStreamProducer(topic): StreamProducerHandle` | Return a manifest-layer producer handle. Not wired to a transport: the returned `publish()` **rejects** with `StreamUnsupportedOperationError`. |
| `defineStreamConsumer` | function | `function defineStreamConsumer(topic): StreamConsumerHandle` | Return a manifest-layer consumer handle. Not wired to a transport: the returned `subscribe()` **throws** `StreamUnsupportedOperationError` synchronously. |
| `StreamUnsupportedOperationError` | class | `class StreamUnsupportedOperationError extends Error` | Raised by the manifest topic helpers when asked to perform runtime IO; points callers at `@netscript/plugin-streams-core`. |
| `StreamTopicDefinition` | interface | `interface StreamTopicDefinition` | Typed stream topic definition. |
| `StreamPayloadSchema` | interface | `interface StreamPayloadSchema` | Package-owned structural payload schema accepted by stream topic definitions. |
| `StreamProducerHandle` | interface | `interface StreamProducerHandle` | Stub producer handle for downstream plugin manifests; its `publish()` rejects (see above). |
| `StreamConsumerHandle` | interface | `interface StreamConsumerHandle` | Stub consumer handle for downstream plugin manifests; its `subscribe()` throws (see above). |

> **Not yet wired.** `defineStreamProducer` and `defineStreamConsumer` are manifest-layer stubs. A producer's `publish()` returns a rejected promise and a consumer's `subscribe()` throws synchronously, both with `StreamUnsupportedOperationError`. For real producer work use `createDurableStream` (or the Service-facing `createServiceStreamProducer`) and `defineStreamSchema` from [`@netscript/plugin-streams-core`](#internals). See the [durable streams capability page](https://rickylabs.github.io/netscript/capabilities/streams/) for the full producer/consumer model.

> **Browser consumers read over HTTP/SSE.** There is no in-process `subscribe()`; a browser consumes a stream by reading its HTTP/SSE endpoint (for example with `EventSource`). The local AppHost serves the generated app over `http://`, and under HTTP/1.1 browsers typically allow only about **six concurrent connections per origin** — so several long-lived stream subscriptions from one page can starve later requests. Serve over HTTPS (HTTP/2) when a page needs many simultaneous stream consumers.

### Re-exported plugin framework types

The root export re-exports the shared NetScript plugin-framework contribution types unchanged from [`@netscript/plugin`](https://rickylabs.github.io/netscript/reference/plugin/). See the [`@netscript/plugin` reference](https://rickylabs.github.io/netscript/reference/plugin/) for their full definitions.

| Symbol | Kind |
| --- | --- |
| `PluginManifest` | interface |
| `PluginContributions` | interface |
| `PluginContext` | interface |
| `PluginLifecycleHooks` | interface |
| `PluginLogger` | interface |
| `ServiceContribution` | interface |
| `TelemetryContribution` | interface |
| `E2eContribution` | interface |
| `DbSchemaContribution` | interface |
| `MigrationContribution` | interface |
| `BackgroundProcessorContribution` | interface |
| `ContractVersionContribution` | interface |
| `RuntimeConfigTopicContribution` | interface |
| `StreamTopicContribution` | interface |
| `PluginDependencies` | type alias |
| `PluginMetadata` | type alias |
| `PluginMetadataValue` | type alias |
| `PluginType` | type alias |
| `PLUGIN_TYPES` | variable |

## Sub-path exports

### `@netscript/plugin-streams/cli`

CLI command group for the plugin, mounted under `deno x -A jsr:@netscript/plugin-streams{{ releaseSpecifier }}/cli`.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `streamsCli` | variable | `const streamsCli: StreamsCli` | Default CLI instance for the streams plugin. |
| `StreamsCli` | class | `class StreamsCli` | CLI command group for `@netscript/plugin-streams`. |

The CLI types `PluginCli`, `PluginCliArgs`, `PluginCliCommand`, and `PluginCliResult` are re-exported from [`@netscript/plugin`](https://rickylabs.github.io/netscript/reference/plugin/) and document the base command contract `StreamsCli` extends.

### `@netscript/plugin-streams/scaffolding`

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `streamsScaffolder` | variable | `const streamsScaffolder: StreamsScaffolder` | Minimal scaffolder descriptor for streams plugin packages. |
| `StreamsScaffolder` | interface | `interface StreamsScaffolder` | Scaffolding descriptor for the streams plugin package. |

### `@netscript/plugin-streams/e2e`

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `getStreamsE2eGates` | function | `function getStreamsE2eGates()` | Return E2E gate definitions owned by the streams plugin. |
| `StreamsE2eGate` | interface | `interface StreamsE2eGate` | E2E gate definition for the streams plugin. |

### `@netscript/plugin-streams/aspire`

The Aspire entrypoint contributes the Durable Streams development service to an Aspire AppHost.

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `StreamsAspireContribution` | class | `class StreamsAspireContribution` | Aspire contribution for the Durable Streams development service. |

The remaining symbols on this entrypoint (`AspireBuilder`, `AspireResource`, `AspireResourceKind`, `AspireNSPluginContribution`, `ContributionContext`, `CacheSpec`, `ContainerSpec`, `DatabaseSpec`, `DenoServiceSpec`, `DenoBackgroundSpec`, `HealthCheckSpec`, `EnvSource`) are re-exported unchanged from [`@netscript/aspire`](https://rickylabs.github.io/netscript/reference/aspire/); see that reference page for their definitions.

## Internals

The following surface belongs to the internal **`@netscript/plugin-streams-core`** package. It is a supporting package — not part of the public plugin contract — and is documented here per the single-page internals convention (US-8). It provides the schema, producer, configuration, telemetry, testing, and diagnostics primitives that `@netscript/plugin-streams` builds on. Its root export is `@netscript/plugin-streams-core` with two sub-path exports (`/telemetry`, `/testing`).

### Schema and producers (`@netscript/plugin-streams-core`)

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `defineStreamSchema` | function | `function defineStreamSchema(collections): StateSchema` | Define a type-safe durable stream schema. |
| `createDurableStream` | function | `function createDurableStream(options): DurableStreamProducer` | Create or reuse a durable stream producer for a stream path. |
| `createServiceStreamProducer` | function | `function createServiceStreamProducer(options): DurableStreamProducer` | Blessed Service-facing producer factory. Wraps `createDurableStream` reusing `getStreamsUrl`/`getStreamsAuth`; eagerly resolves the streams URL and auth (`assertResolvable`, default `true`) so a mis-wired Service **throws at construction** instead of silently dropping writes. |
| `DurableStreamProducer` | class | `class DurableStreamProducer` | Server-side writer for a named durable stream. |
| `DurableStreamProducerOptions` | interface | `interface DurableStreamProducerOptions` | Options accepted by `createDurableStream` / `DurableStreamProducer`. |
| `ServiceStreamProducerOptions` | interface | `interface ServiceStreamProducerOptions extends DurableStreamProducerOptions` | Options for `createServiceStreamProducer`: the `DurableStreamProducerOptions` fields plus the optional `assertResolvable` fail-fast gate (default `true`). |
| `StreamProducerPort` | interface | `interface StreamProducerPort` | Port implemented by stream producers that publish State Protocol changes. |
| `inspectStreamTopic` | function | `function inspectStreamTopic(input): StreamTopicInspectionReport` | Inspect a stream schema and optional producer metadata. |
| `StreamTopicInspectionInput` | interface | `interface StreamTopicInspectionInput` | Input accepted by `inspectStreamTopic`. |
| `StreamTopicInspectionReport` | interface | `interface StreamTopicInspectionReport` | Diagnostic report returned by `inspectStreamTopic`. |

#### Configuration helpers

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `getStreamsUrl` | function | `function getStreamsUrl(): string` | Resolve the base URL of the durable streams server. |
| `getStreamsAuth` | function | `function getStreamsAuth(): Record` | Resolve authentication headers for the durable streams server. |
| `buildStreamUrl` | function | `function buildStreamUrl(path, baseUrl): string` | Build the full stream URL for a NetScript stream path. |

#### Schema and event types

| Symbol | Kind | Description |
| --- | --- | --- |
| `StateSchema` | type alias | Schema map returned by `defineStreamSchema`. |
| `StreamStateDefinition` | type alias | Input map accepted by `defineStreamSchema`. |
| `CollectionDefinition` | interface | A single collection definition inside a durable stream schema. |
| `CollectionWithHelpers` | type alias | Collection definition after durable-streams helper methods are attached. |
| `CollectionEventHelpers` | interface | Helper methods attached to collections by `@durable-streams/state`. |
| `StateEvent` | type alias | Durable stream event union. |
| `ChangeEvent` | interface | Entity change event emitted by durable stream producers. |
| `ControlEvent` | interface | Control event emitted by durable streams for non-entity lifecycle changes. |
| `Operation` | type alias | State Protocol operation names supported by durable streams. |

### Telemetry (`@netscript/plugin-streams-core/telemetry`)

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `streamsInstrumentation` | variable | `const streamsInstrumentation: StreamsInstrumentationRegistration` | Telemetry registration for stream publish, consume, and subscribe spans. |
| `StreamsInstrumentationRegistration` | interface | `interface StreamsInstrumentationRegistration` | Minimal instrumentation contract understood by NetScript telemetry hosts. |
| `STREAMS_SPAN_NAMES` | variable | `const STREAMS_SPAN_NAMES` | Span names emitted by stream producers and consumers. |
| `STREAMS_TELEMETRY_ATTRIBUTES` | variable | `const STREAMS_TELEMETRY_ATTRIBUTES` | Attribute keys used by stream telemetry. |
| `StreamsSpanName` | type alias | Span name emitted by stream instrumentation. |  |
| `StreamsTelemetryAttributeKey` | type alias | Attribute key used by stream telemetry. |  |
| `StreamsTelemetryAttributes` | type alias | Attribute bag accepted by stream instrumentation hooks. |  |

### Testing (`@netscript/plugin-streams-core/testing`)

| Symbol | Kind | Signature | Description |
| --- | --- | --- | --- |
| `MemoryStreamProducer` | class | `class MemoryStreamProducer` | In-memory stream producer for tests that should not open network sockets. |
| `MemoryStreamEvent` | interface | `interface MemoryStreamEvent` | Event recorded by `MemoryStreamProducer`. |
| `createStreamTopicFixture` | function | `function createStreamTopicFixture(): StreamTopicFixtureSchema` | Create a small stream schema fixture with one `execution` collection. |
| `StreamTopicFixtureSchema` | type alias | Schema shape returned by `createStreamTopicFixture`. |  |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/streams/_

---

# `@netscript/telemetry`

OpenTelemetry tracing primitives, context propagation, instrumentation registries, and NetScript runtime adapters for jobs, queues, RPC, and SSE. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The root entrypoint (`@netscript/telemetry`) exposes the stable package diagnostic and instrumentation registry contract only. Runtime helpers live on typed sub-path exports so callers import just the layer they need:

- [`@netscript/telemetry/config`](#sub-path-exports) — telemetry configuration and OTEL env resolution.
- [`@netscript/telemetry/tracer`](#sub-path-exports) — tracer accessors and span helpers.
- [`@netscript/telemetry/context`](#sub-path-exports) — W3C trace context propagation.
- [`@netscript/telemetry/attributes`](#sub-path-exports) — semantic attribute and span-name constants.
- [`@netscript/telemetry/instrumentation`](#sub-path-exports) — worker/queue/scheduler/SSE instrumentation.
- [`@netscript/telemetry/registry`](#sub-path-exports) — instrumentation lifecycle registry.
- [`@netscript/telemetry/orpc`](#sub-path-exports) — oRPC tracing and error-handling plugins.

## Root entrypoint

Diagnostics, traced-job helpers, and the instrumentation registry contract.

### Functions

| Symbol | Signature | Description |
| --- | --- | --- |
| `inspectTelemetry` | `function inspectTelemetry(target): InspectionReport` | Inspect a telemetry target and return a JSON-stable diagnostic report. |
| `initJobTracing` | `function initJobTracing(): Context \| null` | Initialize tracing in a job subprocess, continuing the trace from the worker. |
| `runTracedJob` | `async function runTracedJob<T>(jobId: string, fn): Promise<T>` | Wrap a job main function with context extraction and span creation. |

### Classes

| Symbol | Signature | Description |
| --- | --- | --- |
| `InstrumentationRegistry` | `class InstrumentationRegistry` | Registry for telemetry instrumentation lifecycle hooks (`register`, `resolve`, `list`, `setupAll`, `teardownAll`). |
| `DuplicateInstrumentationError` | `class DuplicateInstrumentationError extends Error` | Error thrown when an instrumentation registration name is duplicated. |

### Types

| Symbol | Kind | Description |
| --- | --- | --- |
| `InspectionReport` | interface | JSON-stable diagnostic report returned by telemetry inspectors. |
| `InstrumentationContext` | interface | Context supplied to instrumentation lifecycle hooks. |
| `InstrumentationEntry` | interface | Diagnostic snapshot of a registry entry. |
| `InstrumentationRegistration` | interface | Instrumentation lifecycle hooks accepted by `InstrumentationRegistry.register`. |

## Configuration (`@netscript/telemetry/config`)

| Symbol | Signature | Description |
| --- | --- | --- |
| `getTelemetryConfig` | `function getTelemetryConfig(): TelemetryConfig` | Resolve the telemetry configuration from the environment. |
| `getConfig` | `function getConfig(): TelemetryConfig` | Get the cached singleton telemetry configuration. |
| `resetConfig` | `function resetConfig(): void` | Reset the cached singleton configuration. |
| `describeTelemetryConfig` | `function describeTelemetryConfig(): TelemetryConfigDescription` | Describe the effective configuration for diagnostics. |
| `isTelemetryEnabled` | `function isTelemetryEnabled(): boolean` | Whether telemetry is enabled in the current environment. |
| `getServiceName` | `function getServiceName(): string` | Resolve the configured OTEL service name. |
| `getOtlpEndpoint` | `function getOtlpEndpoint(): string \| undefined` | Resolve the OTLP exporter endpoint, if set. |
| `getOtelEnvVars` | `function getOtelEnvVars(): Record<string, string>` | Collect the resolved OTEL environment variables. |
| `OTEL_ENV_VARS` | `const OTEL_ENV_VARS` | Map of the supported OTEL environment variable names. |
| `TelemetryConfig` | interface | Resolved telemetry configuration shape. |
| `TelemetryConfigDescription` | interface | Human-readable configuration description. |

## Tracer (`@netscript/telemetry/tracer`)

| Symbol | Signature | Description |
| --- | --- | --- |
| `getTracer` | `function getTracer(name: string, version: string): Tracer` | Get a named tracer at a version. |
| `getQueueTracer` | `function getQueueTracer(): Tracer` | Tracer for queue operations. |
| `getWorkerTracer` | `function getWorkerTracer(): Tracer` | Tracer for worker operations. |
| `getSchedulerTracer` | `function getSchedulerTracer(): Tracer` | Tracer for scheduler operations. |
| `getJobTracer` | `function getJobTracer(): Tracer` | Tracer for job operations. |
| `getSagaTracer` | `function getSagaTracer(): Tracer` | Tracer for saga operations. |
| `getSSETracer` | `function getSSETracer(): Tracer` | Tracer for SSE operations. |
| `getKVTracer` | `function getKVTracer(): Tracer` | Tracer for KV operations. |
| `createSpan` | `function createSpan(tracer, name, options): Span` | Create a span on the given tracer. |
| `withSpan` | `async function withSpan<T>(tracer, name, fn, options): Promise<T>` | Run an async function inside a span. |
| `withSpanSync` | `function withSpanSync<T>(tracer, name, fn, options): T` | Run a sync function inside a span. |
| `getActiveSpan` | `function getActiveSpan(): Span \| undefined` | Get the currently active span. |
| `getActiveContext` | `function getActiveContext(): Context` | Get the currently active context. |
| `addSpanEvent` | `function addSpanEvent(span, name, attributes?): void` | Add an event to a span. |
| `setSpanAttributes` | `function setSpanAttributes(span, attributes): void` | Set attributes on a span. |
| `setSpanError` | `function setSpanError(span, message, error?): void` | Mark a span as errored. |
| `setSpanOk` | `function setSpanOk(span): void` | Mark a span status as OK. |
| `isTracingEnabled` | `function isTracingEnabled(): boolean` | Whether tracing is currently enabled. |
| `TracerNames` | `const TracerNames` | Canonical tracer names: QUEUE, WORKER, SCHEDULER, JOB, SAGA, SSE, KV, DEFAULT. |
| `SpanKind` | `const SpanKind` / `type SpanKind` | Span kind enum: INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER. |
| `SpanStatusCode` | `const SpanStatusCode` / `type SpanStatusCode` | Span status code enum: UNSET, OK, ERROR. |
| `Context`, `Span`, `Tracer`, `CreateSpanOptions`, `Link`, `Attributes` | type aliases / interfaces | Core OpenTelemetry-compatible span and context types. |

## Context (`@netscript/telemetry/context`)

W3C trace-context propagation across job subprocesses and message headers.

| Symbol | Signature | Description |
| --- | --- | --- |
| `withContext` | `function withContext<T>(ctx, fn): T` | Run a sync function with the given context active. |
| `withContextAsync` | `async function withContextAsync<T>(ctx, fn): Promise<T>` | Run an async function with the given context active. |
| `contextWithSpan` | `function contextWithSpan(span, parentContext?): Context` | Build a context carrying the given span. |
| `getSpanFromContext` | `function getSpanFromContext(ctx): Span \| undefined` | Extract the span from a context. |
| `getTraceId` | `function getTraceId(ctx?): string \| undefined` | Get the trace id from a context. |
| `getSpanId` | `function getSpanId(ctx?): string \| undefined` | Get the span id from a context. |
| `hasActiveSpan` | `function hasActiveSpan(ctx?): boolean` | Whether a context carries an active span. |
| `injectContext` | `function injectContext(headers, ctx?): PropagationHeaders` | Inject context into propagation headers. |
| `extractContext` | `function extractContext(headers): Context` | Extract a context from propagation headers. |
| `createMessageHeaders` | `function createMessageHeaders(additionalHeaders): PropagationHeaders` | Build message headers with trace context. |
| `formatTraceparent` | `function formatTraceparent(spanContext): string` | Format a `traceparent` header value. |
| `parseTraceparent` | `function parseTraceparent(traceparent): ParsedTraceparent \| null` | Parse a `traceparent` header value. |
| `resolveParentContextFromHeaders` | `function resolveParentContextFromHeaders(headers?): Context` | Resolve a parent context from headers. |
| `resolveTraceContext` | `function resolveTraceContext(ctx?): SerializedTraceContext \| null` | Serialize the active trace context. |
| `resolveTraceContextFromSpan` | `function resolveTraceContextFromSpan(span): SerializedTraceContext` | Serialize trace context from a span. |
| `extractFromTraceContext` | `function extractFromTraceContext(traceContext): Context` | Rehydrate a context from a serialized payload. |
| `createJobTraceEnv` | `function createJobTraceEnv(ctx?): JobTraceEnv` | Build job subprocess env carrying trace context. |
| `extractJobTraceContext` | `function extractJobTraceContext(): Context \| null` | Extract trace context from the job subprocess env. |
| `JobTraceEnv`, `ParsedTraceparent`, `SerializedTraceContext` | interfaces | Context-propagation payload shapes. |

## Attributes (`@netscript/telemetry/attributes`)

Semantic attribute keys, span-name constants, and attribute builders. The TC-1..TC-14 checklist is published in [`convention.md`](https://rickylabs.github.io/netscript/convention.md).

| Symbol | Signature | Description |
| --- | --- | --- |
| `spanName` | `function spanName(base: string, suffix?: string): string` | Compose a namespaced span name. |
| `createJobAttributes` | `function createJobAttributes(job): Record<string, AttributeValue>` | Build job span attributes with beta.5 deprecated aliases. |
| `createMessagingAttributes` | `function createMessagingAttributes(options): Record<string, AttributeValue>` | Build messaging span attributes. |
| `createSagaAttributes` | `function createSagaAttributes(saga): Record<string, AttributeValue>` | Build saga span attributes with beta.5 deprecated aliases. |
| `createExecutionAttributes` | `function createExecutionAttributes(execution): Record<string, AttributeValue>` | Build execution lifecycle span attributes. |
| `createGenAiAttributes` | `function createGenAiAttributes(genai): Record<string, AttributeValue>` | Build GenAI semantic-convention attributes. |
| `createTriggerAttributes` | `function createTriggerAttributes(trigger): Record<string, string>` | Build trigger span attributes. |
| `createTriggerFileAttributes` | `function createTriggerFileAttributes(payload): Record<string, string \| number>` | Build file-trigger span attributes. |
| `TelemetryConventionChecklist` | `const TelemetryConventionChecklist` | TC-1..TC-14 conformance checklist. |
| `SpanNames` | `const SpanNames` | Canonical span-name constants for scheduler, queue, worker, job, saga, execution, RPC, GenAI, SSE, KV, and trigger spans. |
| `NetScriptAttributeDomains` | `const NetScriptAttributeDomains` | Single-root `netscript.*` proprietary attribute domains. |
| `NetScriptCorrelationAttributes` | `const NetScriptCorrelationAttributes` | Shared `netscript.correlation.id` attribute floor. |
| `ExecutionAttributes` / `NetScriptExecutionAttributes` | `const` | Deprecated execution aliases and canonical execution lifecycle attribute keys. |
| `JobAttributes` / `NetScriptJobAttributes` / `JobStatuses` / `JobTriggers` | const | Deprecated job aliases, canonical job keys, and enumerated status/trigger values. |
| `WorkerAttributes` | `const WorkerAttributes` | Worker attribute keys. |
| `SchedulerAttributes` | `const SchedulerAttributes` | Scheduler attribute keys. |
| `MessagingAttributes` / `MessagingOperations` / `MessagingSystems` | const | Messaging attribute keys and enumerated operations/systems. |
| `SagaAttributes` | `const SagaAttributes` | Saga attribute keys. |
| `GenAiAttributes` | `const GenAiAttributes` | GenAI semantic-convention attribute keys. |
| `KVAttributes` / `KVOperations` | const | KV attribute keys and operation values. |
| `SSEAttributes` | `const SSEAttributes` | SSE attribute keys. |
| `TriggerAttributes` | `const TriggerAttributes` | Trigger attribute keys. |

## Instrumentation (`@netscript/telemetry/instrumentation`)

Span builders and recorders for workers, queues, schedulers, SSE, and job dispatch.

| Symbol | Signature | Description |
| --- | --- | --- |
| `startWorkerSpan` | `function startWorkerSpan(config): Span` | Start a worker span. |
| `createWorkerStopSpan` | `function createWorkerStopSpan(workerId, activeJobs): Span` | Span for worker shutdown. |
| `recordWorkerMetrics` | `function recordWorkerMetrics(span, metrics): void` | Record worker metrics on a span. |
| `traceJobExecution` | `async function traceJobExecution<T>(options, fn): Promise<T>` | Trace a job execution. |
| `createJobSpawnSpan` | `function createJobSpawnSpan(job, executionId): Span` | Span for spawning a job subprocess. |
| `createJobSubprocessEnv` | `function createJobSubprocessEnv(additionalEnv): Record<string, string>` | Build the traced subprocess env. |
| `getJobTraceContext` | `function getJobTraceContext(): SerializedTraceContext \| null` | Read serialized trace context in a job. |
| `initJobTracing` | `function initJobTracing(): Context \| null` | Initialize tracing in a job subprocess. |
| `runTracedJob` | `async function runTracedJob<T>(jobId, fn): Promise<T>` | Wrap a job main with tracing. |
| `addJobStepEvent` | `function addJobStepEvent(stepName, attributes?): void` | Add a step event to the active job span. |
| `recordJobProgress` | `function recordJobProgress(current, total, unit): void` | Record job progress on the active span. |
| `createJobLinkAttributes` | `function createJobLinkAttributes(traceContext): Attributes` | Build span-link attributes for a job. |
| `startJobDispatchSpan` | `function startJobDispatchSpan(context, options)` | Start a job-dispatch span and propagation headers. |
| `traceJobDispatch` | `async function traceJobDispatch(context, fn, options): Promise<void>` | Trace a job dispatch. |
| `isTracedQueue` | `function isTracedQueue<T>(queue): queue is TracedQueue<T>` | Type guard for a traced queue. |
| `startSchedulerTickSpan` | `function startSchedulerTickSpan(context): Span` | Span for a scheduler tick. |
| `createSchedulerStartSpan`, `createSchedulerStopSpan` | functions returning `Span` | Spans for scheduler start/stop. |
| `createScheduleJobSpan`, `createUnscheduleJobSpan` | functions returning `Span` | Root spans for scheduling/unscheduling a job. |
| `recordCronJobRun`, `recordSchedulerReload` | functions returning `void` | Record scheduler run/reload outcomes. |
| `startSSEConnection` | `function startSSEConnection(context, options): TracedSSEConnection` | Start a traced SSE connection. |
| `createSSEEventSpan`, `createSSESubscribeSpan` | functions returning `Span` | Spans for SSE events and subscribe. |
| `generateSSEClientId` | `function generateSSEClientId(): string` | Generate an SSE client id. |
| `recordSSEMetrics` | `function recordSSEMetrics(metrics): void` | Record SSE metrics. |
| `extractTraceContextFromRecord` | `function extractTraceContextFromRecord(record): SerializedTraceContext \| null` | Extract trace context from a queue record. |

## Registry (`@netscript/telemetry/registry`)

Instrumentation lifecycle registry (also re-exported from the root entrypoint).

| Symbol | Kind | Description |
| --- | --- | --- |
| `InstrumentationRegistry` | class | Registry for instrumentation lifecycle hooks. |
| `DuplicateInstrumentationError` | class | Duplicate registration name error. |
| `InstrumentationContext` | interface | Lifecycle hook context. |
| `InstrumentationEntry` | interface | Diagnostic registry snapshot. |
| `InstrumentationRegistration` | interface | Registered lifecycle hooks. |

## oRPC (`@netscript/telemetry/orpc`)

Tracing and error-handling plugins for the NetScript oRPC handler.

| Symbol | Signature | Description |
| --- | --- | --- |
| `createTracingPlugin` | `function createTracingPlugin(options?): TracingPlugin` | Create the oRPC tracing plugin. |
| `TracingPlugin` | `class TracingPlugin` | oRPC tracing plugin. |
| `createErrorHandlingPlugin` | `function createErrorHandlingPlugin(options?): ErrorHandlingPlugin` | Create the oRPC error-handling plugin. |
| `ErrorHandlingPlugin` | `class ErrorHandlingPlugin` | oRPC error-handling plugin. |
| `createTraceContext` | `function createTraceContext(): TraceContext` | Create a handler-scoped trace context. |
| `addEvent` | `function addEvent(name, attributes?): void` | Add an event to the active handler span. |
| `setAttributes` | `function setAttributes(attributes): void` | Set attributes on the active handler span. |
| `getTraceId`, `getSpanId` | functions returning `string \| undefined` | Read the active handler trace/span id. |
| `TraceContext` | interface | Handler-scoped trace context contract. |
| `TracingPluginOptions`, `ErrorHandlingPluginOptions` | interfaces | Plugin options. |
| `ErrorContext`, `ErrorLogger` | interfaces | Error plugin payload and logger contracts. |

## Sub-path exports

The following entrypoints are published alongside the root export. Each is generated from its own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/telemetry` | `./mod.ts` | Diagnostics + instrumentation registry contract (documented above). |
| `@netscript/telemetry/config` | `./config.ts` | Telemetry configuration and OTEL env resolution. |
| `@netscript/telemetry/tracer` | `./tracer.ts` | Tracer accessors and span helpers. |
| `@netscript/telemetry/context` | `./context.ts` | W3C trace-context propagation. |
| `@netscript/telemetry/attributes` | `./attributes.ts` | Semantic attribute and span-name constants. |
| `@netscript/telemetry/instrumentation` | `./instrumentation.ts` | Worker/queue/scheduler/SSE instrumentation. |
| `@netscript/telemetry/registry` | `./src/runtime/mod.ts` | Instrumentation lifecycle registry. |
| `@netscript/telemetry/orpc` | `./orpc.ts` | oRPC tracing and error-handling plugins. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/telemetry/_

---

# `@netscript/plugin-triggers`

NetScript plugin for trigger ingress, scheduling, file watching, and the trigger runtime APIs. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The plugin's root entrypoint (`@netscript/plugin-triggers`) exposes the public **plugin manifest** surface — the manifest value and its metadata constants. Shared manifest inspection is provided by `inspectPlugin` from `@netscript/plugin`. The handler-first authoring DSL (`defineWebhook`, `defineScheduledTrigger`, `defineFileWatch`, `enqueueJob`) and the runtime ports live in the sibling core package and are documented in [Internals](#internals) below.

Additional integration entrypoints are published as [sub-path exports](#sub-path-exports): `./public`, `./plugin`, `./runtime`, `./scaffolding`, `./aspire`, `./cli`, `./services`, `./streams`, and `./streams/server`. Their reference detail is generated from their own `deno doc` surface.

## Plugin manifest

| Symbol | Signature | Description |
| --- | --- | --- |
| `triggersPlugin` | `const triggersPlugin: PluginManifest` | Plugin manifest for NetScript triggers. |

## Manifest constants

| Symbol | Signature | Description |
| --- | --- | --- |
| `TRIGGERS_PLUGIN_ID` | `const TRIGGERS_PLUGIN_ID = "triggers"` | Stable plugin identifier for NetScript triggers. |
| `TRIGGERS_PLUGIN_VERSION` | `const TRIGGERS_PLUGIN_VERSION = "0.1.0"` | Initial plugin package version. |
| `TRIGGERS_API_SERVICE_NAME` | `const TRIGGERS_API_SERVICE_NAME = "triggers-api"` | Default HTTP service name for trigger ingress and management APIs. |
| `TRIGGERS_API_DEFAULT_PORT` | `const TRIGGERS_API_DEFAULT_PORT = 8093` | Default HTTP port for trigger ingress and management APIs. |

## Manifest types

| Symbol | Kind | Description |
| --- | --- | --- |
| `TriggersPluginId` | type alias | Literal type for the triggers plugin id. |
| `TriggersPluginVersion` | type alias | Literal type for the triggers plugin version. |
| `TriggersApiServiceName` | type alias | Literal type for the triggers API service name. |

## Sub-path exports

The following entrypoints are published alongside the root export.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/plugin-triggers` | `./mod.ts` | Public plugin manifest surface (documented above). |
| `@netscript/plugin-triggers/public` | `./src/public/mod.ts` | Public manifest re-export (identical to the root surface). |
| `@netscript/plugin-triggers/plugin` | `./src/public/mod.ts` | Plugin lifecycle composition (alias of the public surface). |
| `@netscript/plugin-triggers/runtime` | `./src/runtime/mod.ts` | Trigger runtime wiring. |
| `@netscript/plugin-triggers/scaffolding` | `./src/scaffolding/mod.ts` | Handler-first trigger definition scaffolders (webhook, scheduled, file-watch). |
| `@netscript/plugin-triggers/aspire` | `./src/aspire/mod.ts` | Aspire contribution for trigger services and background workers. |
| `@netscript/plugin-triggers/cli` | `./src/cli/composition/main.ts` | Trigger CLI composition root. |
| `@netscript/plugin-triggers/services` | `./services/src/main.ts` | Trigger ingress/management HTTP service entrypoint. |
| `@netscript/plugin-triggers/streams` | `./streams/mod.ts` | Stream integration surface. |
| `@netscript/plugin-triggers/streams/server` | `./streams/server.ts` | Stream server entrypoint. |

### Scaffolding (`./scaffolding`)

| Symbol | Signature | Description |
| --- | --- | --- |
| `triggerScaffolder` | `function triggerScaffolder(kind): TriggerDefinitionScaffolder` | Resolve the concrete scaffolder for a trigger kind. |
| `WebhookTriggerScaffolder` | class | Scaffold a webhook trigger definition module. |
| `ScheduledTriggerScaffolder` | class | Scaffold a scheduled trigger definition module. |
| `FileWatchTriggerScaffolder` | class | Scaffold a file-watch trigger definition module. |
| `TriggerDefinitionScaffolder` | interface | Generate handler-first trigger definition modules. |
| `TriggerScaffoldInput` | type alias | Input shared by trigger definition scaffolders. |
| `TriggerScaffoldKind` | type alias | Trigger kinds supported by the F29 scaffolders. |
| `toTriggerExportName` | `function toTriggerExportName(id: string): string` | Convert a trigger id into a stable TypeScript identifier prefix. |
| `toTriggerFileStem` | `function toTriggerFileStem(id: string): string` | Convert a trigger id into the project file stem convention. |
| `renderStringArray` | `function renderStringArray(values): string` | Render an immutable string array expression. |

### Aspire (`./aspire`)

| Symbol | Kind | Description |
| --- | --- | --- |
| `TriggersAspireContribution` | class | Aspire contribution for the NetScript triggers plugin. |
| `TRIGGERS_PLUGIN_PACKAGE_NAME` | const | Package name reported by the triggers Aspire contribution. |
| `TriggersAspireBuilder` | interface | Aspire builder methods required by the triggers contribution. |
| `TriggersAspireResource` | interface | Resource returned by the triggers Aspire builder boundary. |
| `TriggersContributionContext` | interface | Contribution context required by the triggers Aspire contribution. |
| `TriggersDenoServiceSpec` | interface | Deno service resource spec used by the triggers Aspire contribution. |
| `TriggersDenoBackgroundSpec` | interface | Deno background resource spec used by the triggers Aspire contribution. |
| `TriggersHealthCheckSpec` | interface | Health check declaration emitted by the triggers Aspire contribution. |
| `TriggersEnvSource` | type alias | Environment source reference accepted by triggers Aspire declarations. |

---

## Internals

> **Internals — `@netscript/plugin-triggers-core`.** This section documents the sibling **core** package that backs the triggers plugin. It is the implementation surface: the handler-first trigger DSL, the trigger runtime (ingress + processor), the runtime ports, configuration schemas, and deterministic testing primitives. Application code that authors trigger definitions imports the DSL from here; everything below is generated from `@netscript/plugin-triggers-core`'s own `deno doc` surface (US-8).

### Authoring DSL

| Symbol | Signature | Description |
| --- | --- | --- |
| `defineWebhook` | `function defineWebhook(handler: WebhookHandler, spec: WebhookSpec): WebhookDefinition` | Define a webhook trigger from a handler and static spec. |
| `defineScheduledTrigger` | `function defineScheduledTrigger(handler: ScheduledTriggerHandler, spec: DefineScheduledTriggerSpec): ScheduledTriggerDefinition` | Define a scheduled trigger from a handler and static cron spec. |
| `defineFileWatch` | `function defineFileWatch(handler: FileWatchHandler, spec: FileWatchSpec): FileWatchDefinition` | Define a file-watch trigger from a handler and static spec. |
| `enqueueJob` | `function enqueueJob(job: JobDefinition, options: EnqueueJobOptions): EnqueueJobAction` | Create an action that enqueues a typed worker job from a trigger handler. |

### Runtime

| Symbol | Signature | Description |
| --- | --- | --- |
| `createTriggerIngress` | `function createTriggerIngress(options: TriggerIngressOptions): TriggerIngressPort` | Create an ack-then-process webhook ingress boundary. |
| `createTriggerProcessor` | `function createTriggerProcessor(options: TriggerProcessorOptions): TriggerProcessor` | Create a trigger processor runtime from explicit dependencies. |
| `TriggerProcessor` | class | T1 trigger processor with idempotency, retry, concurrency, DLQ, and circuit breaker handling. |

### Runtime ports

| Symbol | Kind | Description |
| --- | --- | --- |
| `TriggerIngressPort` | interface | Fast ack-then-process ingress boundary. |
| `TriggerProcessorPort` | interface | Processes unified trigger events through the T1 dispatch pipeline. |
| `TriggerSchedulerPort` | interface | Scheduler boundary for scheduled trigger definitions. |
| `TriggerEventStorePort` | interface | Persistent trigger event store boundary. |
| `TriggerIdempotencyPort` | interface | Event-boundary idempotency store with a TTL window. |
| `TriggerDlqPort` | interface | Dead-letter queue boundary for exhausted trigger events. |
| `WebhookVerifierPort` | interface | Verifies inbound webhook authenticity and extracts provider event ids. |
| `LoggerPort` | interface | Structured logger boundary consumed by trigger runtime code. |
| `TriggerActionDispatcher` | type alias | Dispatches actions emitted by trigger handlers. |
| `TriggerIngressEventIdFactory` | type alias | Generates event ids for accepted ingress events. |
| `TriggerIngressOptions` | type alias | Options accepted by the trigger ingress composition root. |
| `TriggerProcessorOptions` | type alias | Options accepted by the trigger processor runtime. |

### Trigger definitions and payloads

| Symbol | Kind | Description |
| --- | --- | --- |
| `TriggerDefinition` | type alias | Trigger definitions known by the Group F public surface. |
| `RuntimeTriggerDefinition` | type alias | Trigger definitions implemented by the Group F runtime. |
| `ProcessableTriggerDefinition` | type alias | Trigger definition accepted by runtime processor ports. |
| `WebhookDefinition` | type alias | Webhook trigger definition discovered by the runtime walker. |
| `ScheduledTriggerDefinition` | type alias | Scheduled trigger definition discovered by the runtime walker. |
| `FileWatchDefinition` | type alias | File-watch trigger definition discovered by the runtime walker. |
| `ManualTriggerDefinition` | type alias | Reserved manual trigger definition for CLI/API fire paths. |
| `QueueTriggerDefinition` | type alias | Reserved queue-source trigger definition. Runtime execution is deferred. |
| `StreamTriggerDefinition` | type alias | Reserved stream-source trigger definition. Runtime execution is deferred. |
| `TriggerDefinitionBase` | type alias | Common immutable fields shared by trigger definitions. |
| `WebhookSpec` | type alias | Webhook definition fields accepted by `defineWebhook`. |
| `ScheduledTriggerSpec` | type alias | Static scheduled trigger spec consumed by scheduler ports and builders. |
| `DefineScheduledTriggerSpec` | type alias | Scheduled trigger definition fields accepted by `defineScheduledTrigger`. |
| `FileWatchSpec` | type alias | File-watch definition fields accepted by `defineFileWatch`. |
| `WebhookHandler` | type alias | Webhook handler signature used by `defineWebhook`. |
| `ScheduledTriggerHandler` | type alias | Scheduled trigger handler signature used by `defineScheduledTrigger`. |
| `FileWatchHandler` | type alias | File-watch handler signature used by `defineFileWatch`. |
| `TriggerHandler` | type alias | Handler invoked by the processor for a trigger event. |
| `TriggerContext` | type alias | Context passed to trigger handlers by the processor. |
| `TriggerEvent` | type alias | Unified event envelope consumed by every trigger processor path. |
| `TriggerPayload` | type alias | Payload union for known Group F trigger kinds. |
| `WebhookTriggerPayload` | type alias | HTTP payload captured by webhook ingress before processing. |
| `ScheduledTriggerPayload` | type alias | Scheduled payload emitted by a scheduler adapter. |
| `FileWatchTriggerPayload` | type alias | Filesystem payload captured by a file-watch adapter. |
| `ManualTriggerPayload` | type alias | Reserved manual-fire payload for CLI and API dispatch. |
| `QueueTriggerPayload` | type alias | Reserved queue-source payload. Runtime execution is deferred. |
| `StreamTriggerPayload` | type alias | Reserved stream-source payload. Runtime execution is deferred. |
| `FileWatchLifecycle` | type alias | File lifecycle event names supported by file-watch triggers. |
| `FileWatchStabilityThreshold` | type alias | Stability threshold for network-filesystem tolerant file-watch triggers. |

### Actions, policies, and branded ids

| Symbol | Kind | Description |
| --- | --- | --- |
| `TriggerActionResult` | type alias | Action result emitted by trigger handlers. |
| `EnqueueJobAction` | type alias | Action emitted when a trigger should enqueue a worker job. |
| `EnqueueJobOptions` | type alias | Options for dispatching a worker job from a trigger handler. |
| `DeferAction` | type alias | Action emitted when a trigger yields without holding a worker slot. |
| `JobDefinition` | type alias | Root-surface job definition derived from the thin public schema. |
| `TriggerRetryPolicy` | type alias | Retry policy applied by the trigger processor before DLQ handoff. |
| `TriggerCircuitBreakerSpec` | type alias | Circuit breaker policy for repeated trigger dispatch failures. |
| `TriggerConcurrencySpec` | type alias | Bounded dispatch concurrency for a trigger definition. |
| `TriggerDeduplicationSpec` | type alias | Event-boundary deduplication policy. |
| `TriggerBackfillSpec` | type alias | Quartz-style misfire handling for scheduled trigger backfill. |
| `TriggerBackfillPolicy` | type alias | Scheduled trigger backfill misfire policy. |
| `TriggerDurabilityTier` | type alias | Trigger durability tier. |
| `CronExpression` | type alias | Cron expression accepted by scheduled trigger definitions. |
| `TriggerKind` | type alias | Open trigger discriminator. |
| `TriggerKnownKind` | type alias | Canonical known trigger kind. |
| `TriggerEventStatus` | type alias | Trigger event lifecycle status. |
| `TriggerId` | type alias | Branded trigger definition identifier. |
| `TriggerEventId` | type alias | Branded trigger event identifier. |
| `WebhookId` | type alias | Branded webhook definition identifier. |
| `JobId` | type alias | Branded worker job identifier. |
| `WebhookVerifierKind` | type alias | Webhook verifier selector declared by a webhook trigger. |
| `RuntimeWebhookDefinition` | type alias | Webhook definition shape accepted by the trigger ingress runtime. |

### Runtime constants

| Symbol | Description |
| --- | --- |
| `TRIGGER_KINDS` | Canonical trigger kinds known by Group F. |
| `TRIGGER_EVENT_STATUSES` | Trigger event lifecycle statuses. |
| `TRIGGER_DURABILITY_TIERS` | Durability tiers supported by trigger definitions. |
| `TRIGGER_BACKFILL_POLICIES` | Scheduled trigger backfill misfire policies. |

### DLQ, event-store, and idempotency support types

| Symbol | Kind | Description |
| --- | --- | --- |
| `TriggerDlqEntry` | type alias | Dead-letter entry recorded after trigger retry exhaustion. |
| `TriggerDlqListOptions` | type alias | Dead-letter list filters. |
| `TriggerEventListOptions` | type alias | Event store list filters. |
| `TriggerIdempotencyClaim` | type alias | Idempotency claim result. |
| `TriggerIdempotencyKeyInput` | type alias | Idempotency key resolution input. |
| `TriggerIngressRequest` | type alias | Ingress request passed to trigger ingress adapters. |
| `TriggerIngressResponse` | type alias | Fast ack response returned by ingress adapters. |
| `TriggerProcessResult` | type alias | Result returned after processing a trigger event. |
| `TriggerProcessorStopOptions` | type alias | Stop options for processor drain. |
| `TriggerSchedulerStopOptions` | type alias | Scheduler stop options. |
| `ScheduledTriggerHandle` | type alias | Scheduled trigger handle returned by scheduler adapters. |
| `WebhookVerificationRequest` | type alias | Request shape passed to a webhook verifier adapter. |
| `WebhookVerificationResult` | type alias | Result returned by a webhook verifier adapter. |

### Internals sub-path exports

The core package publishes the following sub-path entrypoints. Each is generated from its own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/plugin-triggers-core` | `./mod.ts` | Curated root surface (DSL, runtime, ports, types — documented above). |
| `@netscript/plugin-triggers-core/public` | `./src/public/mod.ts` | Public root re-export. |
| `@netscript/plugin-triggers-core/builders` | `./src/builders/mod.ts` | Handler-first definition builders (`defineWebhook`, `defineScheduledTrigger`, `defineFileWatch`, `enqueueJob`) and `TRIGGER_*` constants. |
| `@netscript/plugin-triggers-core/config` | `./src/config/mod.ts` | `netscript.config.ts` trigger schemas and `defineTriggers`. |
| `@netscript/plugin-triggers-core/domain` | `./src/domain/mod.ts` | Domain definitions, payloads, and branded ids. |
| `@netscript/plugin-triggers-core/ports` | `./src/ports/mod.ts` | Runtime port boundaries. |
| `@netscript/plugin-triggers-core/runtime` | `./src/runtime/mod.ts` | Ingress and processor runtime. |
| `@netscript/plugin-triggers-core/adapters` | `./src/adapters/mod.ts` | Concrete port adapters. |
| `@netscript/plugin-triggers-core/telemetry` | `./src/telemetry/mod.ts` | Trigger telemetry instrumentation. |
| `@netscript/plugin-triggers-core/contracts/v1` | `./src/contracts/v1/mod.ts` | Versioned wire contracts. |
| `@netscript/plugin-triggers-core/testing` | `./src/testing/mod.ts` | Deterministic in-memory adapters, stores, and clock for trigger tests. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/triggers/_

---

# `@netscript/watchers`

Reusable file-watching primitives for NetScript: composable strategies, filters, and a pipeline-based `FileWatcher` for detecting file-system changes across local and network filesystems. This page is generated from the package's public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The package exposes a single root entrypoint (`@netscript/watchers` -> `./mod.ts`). There are no sub-path exports. The watcher auto-selects its strategy (native OS notifications for local paths, polling for network paths) so most callers only need `createWatcher`; the strategy classes themselves are internal implementation details.

```ts
import { createWatcher } from '@netscript/watchers';

const watcher = createWatcher({
  paths: ['./incoming'],
  patterns: ['*.csv'],
  events: ['create'],
  stabilityThreshold: { checkIntervalMs: 1000, stableChecks: 3 },
});

for await (const event of watcher.watch()) {
  console.log(`${event.kind}: ${event.path}`);
}
```

## Factory

| Symbol | Signature | Description |
| --- | --- | --- |
| `createWatcher` | `function createWatcher(options: WatcherOptions): FileWatcher` | Factory function to create a `FileWatcher` with the given options. |

## Watcher

| Symbol | Kind | Member | Signature | Description |
| --- | --- | --- | --- | --- |
| `FileWatcher` | class | `constructor` | `new FileWatcher(options: WatcherOptions)` | Composable file watcher that combines a strategy with a filter pipeline; auto-selects native vs. polling. |
|  |  | `watch` | `async *watch(): AsyncGenerator<WatchEvent>` | Start watching and yield file events through the filter pipeline. |
|  |  | `stop` | `stop(): void` | Stop the watcher by signaling abort. |
|  |  | `running` | `get running(): boolean` | Whether the watcher is currently running. |

## Filters

Filters consume an async iterable of events and yield only the events that pass. They run in configured order inside the `FileWatcher` pipeline. Each implements the `WatchFilter` contract.

| Symbol | Kind | Member | Signature | Description |
| --- | --- | --- | --- | --- |
| `GlobFilter` | class | `constructor` | `new GlobFilter(patterns: readonly string[])` | Yields only events whose filenames match at least one glob pattern. |
|  |  | `apply` | `async *apply(events: AsyncIterable<WatchEvent>): AsyncIterable<WatchEvent>` | Apply the glob filter to an event stream. |
|  |  | `matches` | `matches(filePath: string): boolean` | Check if a file path matches any configured glob pattern. |
| `StabilityFilter` | class | `constructor` | `new StabilityFilter(options?: StabilityOptions, signal?: AbortSignal)` | Waits for file writes to complete (size stops changing) before yielding events. |
|  |  | `apply` | `async *apply(events: AsyncIterable<WatchEvent>): AsyncIterable<WatchEvent>` | Apply the stability filter to an event stream. |
|  |  | `waitForStability` | `async waitForStability(filePath: string): Promise<WatchEvent["fileInfo"]>` | Wait for a file to stop growing. |
| `DedupFilter` | class | `constructor` | `new DedupFilter(options?: DedupFilterOptions)` | Skips events for files with previously-seen content hashes (in-memory, time-evicted). |
|  |  | `apply` | `async *apply(events: AsyncIterable<WatchEvent>): AsyncIterable<WatchEvent>` | Apply the dedup filter to an event stream. |
|  |  | `clear` | `clear(): void` | Clear all tracked hashes. |

## Failure tracking

| Symbol | Kind | Member | Signature | Description |
| --- | --- | --- | --- | --- |
| `AccessFailureTracker` | class | `constructor` | `new AccessFailureTracker(options: { maxConsecutiveFailures?: number; onPersistentFailure: (path: string, count: number) => void })` | Tracks consecutive access failures per path and surfaces persistent errors via callback. |
|  |  | `recordSuccess` | `recordSuccess(path: string): void` | Record a successful access -- resets the counter for the path. |
|  |  | `recordFailure` | `recordFailure(path: string): boolean` | Record a failed access; returns `true` when the threshold is crossed. |
|  |  | `clear` | `clear(): void` | Clear all tracked state. |

## Filesystem helpers

Low-level helpers that swallow only "missing/inaccessible" errors and re-throw the rest.

| Symbol | Signature | Description |
| --- | --- | --- |
| `safeReadFile` | `async function safeReadFile(path: string): Promise<Uint8Array<ArrayBuffer> \| null>` | Read a file's content, returning `null` when the file is missing or inaccessible. |
| `safeStat` | `async function safeStat(path: string): Promise<FileInfo \| null>` | Stat a file, returning `null` when the file is missing or inaccessible (only `NotFound`/`PermissionDenied`). |
| `computeContentHash` | `async function computeContentHash(filePath: string): Promise<string \| null>` | Compute a SHA-256 hex digest of a file's content, or `null` if unreadable. |

## Interfaces

| Symbol | Description |
| --- | --- |
| `WatcherOptions` | Configuration for a `FileWatcher` instance (paths, patterns, events, stability threshold, signal, force polling). |
| `WatchEvent` | A single file-system event yielded by a watcher strategy. |
| `WatchFilter` | A filter takes an async iterable of events and yields only those that pass. |
| `WatchStrategyHandler` | A watch strategy produces raw file-system events as an async iterable. |
| `FileInfo` | Metadata about a watched file, built from `Deno.FileInfo`. |
| `StabilityOptions` | Configuration for the stability filter (`checkIntervalMs`, `stableChecks`). |
| `DedupFilterOptions` | Options for creating a `DedupFilter` (`windowMs`, default `60000`). |

## Type aliases

| Symbol | Definition | Description |
| --- | --- | --- |
| `KnownEventKind` | `"create" \| "modify" \| "remove"` | Built-in file-system event kinds the watcher can detect. |
| `EventKind` | `KnownEventKind \| (string & Record<never, never>)` | File-system event kind; new runtime kinds require doctrine review. |
| `KnownWatchStrategy` | `"native" \| "polling" \| "hybrid"` | Built-in watch strategies for detecting file changes. |
| `WatchStrategy` | `KnownWatchStrategy \| (string & Record<never, never>)` | Watch-strategy identifier; built-in factory values remain runtime validated. |

## Internals

The concrete strategy classes (`NativeStrategy`, `PollingStrategy`, `HybridStrategy`) and their option interfaces (`NativeStrategyOptions`, `PollingStrategyOptions`, `HybridStrategyOptions`) are marked `@internal`. They are selected automatically by `FileWatcher` based on the configured paths and are not part of the supported public contract -- construct watchers via `createWatcher` or `new FileWatcher(...)` instead.

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/watchers/_

---

# `@netscript/plugin-workers`

The NetScript background-workers plugin: background jobs, task execution, workflow orchestration, a Workers API service, CLI commands, scaffolding, durable streams, and Aspire process wiring. This page is generated from the package public surface with `deno doc` (US-2). For the full index of packages and plugins return to the [reference overview](https://rickylabs.github.io/netscript/reference/).

The deployable plugin (`@netscript/plugin-workers`) binds the host plugin system to the reusable worker primitives that live in [`@netscript/plugin-workers-core`](#internals-netscriptplugin-workers-core). The plugin root entrypoint exposes the plugin manifest and a pure inspection helper; framework integrations are carried by sub-path exports documented below.

## Plugin manifest (`@netscript/plugin-workers`)

The root entrypoint exposes the plugin manifest consumed by the NetScript host. Shared manifest inspection is provided by `inspectPlugin` from `@netscript/plugin`.

| Symbol | Kind | Description |
| --- | --- | --- |
| `workersPlugin` | variable | Plugin manifest for NetScript background workers. |

## Sub-path exports

The following entrypoints are published alongside the plugin root export. Each is generated from its own `deno doc` surface.

| Export | Entrypoint | Purpose |
| --- | --- | --- |
| `@netscript/plugin-workers` | `./mod.ts` | Plugin manifest and inspection helper (documented above). |
| `@netscript/plugin-workers/aspire` | `./src/aspire/mod.ts` | Aspire AppHost contribution and resource ports. |
| `@netscript/plugin-workers/cli` | `./src/cli/composition/main.ts` | Host-mounted workers CLI command group. |
| `@netscript/plugin-workers/contracts` | `./contracts/v1/mod.ts` | Versioned oRPC worker service contracts and schemas. |
| `@netscript/plugin-workers/scaffolding` | `./src/scaffolding/mod.ts` | Job, task, and workflow item scaffolders. |
| `@netscript/plugin-workers/services` | `./services/src/main.ts` | Workers API service entrypoint. |
| `@netscript/plugin-workers/streams` | `./streams/mod.ts` | Browser-facing StreamDB factory and entity schemas. |
| `@netscript/plugin-workers/streams/server` | `./streams/server.ts` | Server-side durable stream producer wiring. |
| `@netscript/plugin-workers/worker` | `./worker/mod.ts` | Worker and Scheduler runtime processes. |

### `@netscript/plugin-workers/aspire`

| Symbol | Kind | Description |
| --- | --- | --- |
| `WorkersAspireContribution` | class | Aspire contribution for the NetScript workers plugin. |
| `AspireNSPluginContribution` | class | Base class plugins extend to contribute Aspire resources to an AppHost. |
| `AspireBuilder` | interface | Port implemented by adapters that emit Aspire AppHost resources. |
| `AspireResource` | interface | Resource descriptor returned by Aspire builder ports. |
| `AspireResourceKind` | type alias | Aspire resource kinds produced by plugin contributions. |
| `CacheSpec` | interface | Cache resource spec consumed by AspireBuilder. |
| `ContainerSpec` | interface | Container resource spec consumed by AspireBuilder. |
| `ContributionContext` | interface | Context passed to plugin Aspire contributions during AppHost composition. |
| `DatabaseSpec` | interface | Database resource spec consumed by AspireBuilder. |
| `DenoBackgroundSpec` | interface | Deno background process spec consumed by AspireBuilder. |
| `DenoServiceSpec` | interface | Deno service resource spec consumed by AspireBuilder. |
| `EnvSource` | type alias | Source for an environment variable value in an AppHost composition. |
| `HealthCheckSpec` | interface | Health check expectation declared by a plugin contribution. |

### `@netscript/plugin-workers/cli`

| Symbol | Kind | Description |
| --- | --- | --- |
| `WorkersCli` | class | CLI command group for `@netscript/plugin-workers`. |
| `PluginCli` | class | Abstract base class for plugin-owned CLI command groups. |
| `PluginCliArgs` | interface | Command arguments passed to plugin CLI handlers. |
| `PluginCliCommand` | interface | A mounted CLI command handler. |
| `PluginCliResult` | interface | Result returned by plugin CLI handlers. |
| `CliCommand` | class | Stub-only base contract for CLI command implementations. |
| `WorkersCommand` | class | Stub-only contract for workers CLI commands. |
| `WorkersCommandDefinition` | interface | Definition supplied to worker CLI commands. |
| `AddJobCommand` | class | Create a worker job definition file. |
| `AddTaskCommand` | class | Create a worker task definition file. |
| `CompileRegistryCommand` | class | Compile the static worker registry used by compiled runtimes. |
| `ConfigEditCommand` | class | Edit a worker runtime configuration topic. |
| `ConfigPublishCommand` | class | Publish a worker runtime configuration topic. |
| `DisableCommand` | class | Disable a worker job. |
| `EnableCommand` | class | Enable a worker job. |
| `ListJobsCommand` | class | List configured worker jobs. |
| `ListTasksCommand` | class | List configured worker tasks. |
| `LogsCommand` | class | Show logs for a worker execution. |
| `RunJobCommand` | class | Run a configured worker job. |
| `WorkersCliCommand` | class | Base class for concrete workers CLI commands. |
| `WORKERS_CLI_COMMANDS` | variable | Worker CLI commands exposed through the plugin CLI subpath. |
| `WorkersCliBackend` | interface | Backend invoked by concrete command classes. |
| `WorkersCliCategory` | type alias | Worker CLI command category used for grouped help output. |
| `WorkersCliCommandDefinition` | interface | Workers command definition mounted by the plugin CLI. |
| `WorkersCliCommandName` | type alias | Worker CLI command identifier. |
| `WorkersCliFlagDefinition` | interface | Flag metadata shown by host CLI help renderers. |
| `workersCli` | variable | Default CLI instance used by the host CLI walker. |

### `@netscript/plugin-workers/contracts`

Versioned oRPC service contracts plus the request/response schemas and types used to generate worker service clients.

| Symbol | Kind | Description |
| --- | --- | --- |
| `ExecutionRecord` | type alias | Runtime execution record. |
| `JobContext` | type alias | Context supplied to runtime job handlers. |
| `JobDefinition` | type alias | Runtime job definition. |
| `JobHandler` | type alias | Function that executes a runtime job. |
| `JobMessage` | type alias | Message enqueued to trigger a job execution. |
| `JobResult` | type alias | Result returned by runtime job handlers. |
| `RegisterJobInput` | type alias | Input for registering a job definition. |
| `RegisterTaskInput` | type alias | Input for registering a task definition. |
| `RuntimePermissions` | type alias | Runtime permission bag accepted by task and job execution. |
| `RuntimePermissionValue` | type alias | Runtime permission value accepted by task and job execution. |
| `TaskDefinition` | type alias | Runtime task definition. |
| `TaskExecutionOptions` | type alias | Options supplied when executing a task. |
| `TaskMessage` | type alias | Message enqueued to trigger a task execution. |
| `TaskResult` | type alias | Result returned by task execution. |
| `ExecutionFiltersSchema` | variable | Schema for list-executions filters. |
| `ExecutionRecordResponseSchema` | variable | Schema for worker execution record responses. |
| `JobCreateInputSchema` | variable | Schema for creating worker job definitions. |
| `JobDefinitionResponseSchema` | variable | Schema for worker job definition responses. |
| `JobFiltersSchema` | variable | Schema for list-jobs filters. |
| `JobTriggerInputSchema` | variable | Schema for triggering a worker job by id. |
| `JobUpdateInputSchema` | variable | Schema for updating worker job definitions. |
| `JobUpdateWithIdSchema` | variable | Schema for updating a worker job definition by id. |
| `SSEEventSchema` | variable | Schema for server-sent event payloads emitted by the workers service. |
| `TaskDefinitionResponseSchema` | variable | Schema for worker task definition responses. |
| `TaskFiltersSchema` | variable | Schema for list-tasks filters. |
| `workersContract` | variable | Worker service contract definition for client generation. |
| `workersContractV1` | variable | Context-bindable worker service contract definition. |
| `ContractProcedureLike` | type alias | Structural oRPC procedure reference used by worker contracts. |
| `ContractSchema` | interface | Package-owned structural schema surface for worker contracts. |
| `ContractSchemaResult` | type alias | Result returned by contract schema validation. |
| `ExecutionRecordResponse` | type alias | Public response returned for worker execution records. |
| `JobDefinitionResponse` | type alias | Public response returned for worker job definitions. |
| `JobTriggerInput` | type alias | Input accepted by the trigger-job procedure. |
| `JobTriggerOutput` | type alias | Output returned by the trigger-job procedure. |
| `SSEEvent` | type alias | Server-sent event payload emitted by the workers service. |
| `StandardSchemaLike` | type alias | Structural Standard Schema reference used by contract metadata. |
| `TaskDefinitionResponse` | type alias | Public response returned for worker task definitions. |
| `TaskTriggerInput` | type alias | Input accepted by the trigger-task procedure. |
| `TaskTriggerOutput` | type alias | Output returned by the trigger-task procedure. |
| `WorkersContract` | type alias | Explicit public contract shape for worker service clients. |
| `WorkersContractV1` | type alias | Context-binding contract wrapper for the v1 worker contract. |
| `WorkersRouteHandler` | type alias | Structural route handler exposed by the implemented worker router. |
| `WorkersRouter` | type alias | Structural worker router returned after binding a context. |

#### Trigger procedures (RPC routes)

`workersContract` exposes two enqueue procedures. A generated typed client (`createServiceClient<typeof workersContract>({ contract: workersContract, serviceName: 'workers-api', routerName: 'workers' })`) reaches them over `/api/rpc/*`; the same routes answer REST callers under `/api/v1/workers/...`. For each, the `{id}` path segment is the single source of truth for the target — a request-body `id` is optional and ignored when sent, and a missing id short-circuits to a typed `VALIDATION_ERROR` (HTTP 422) via the centralized `validationFailed` contract helper before any KV write.

| Procedure | Route | Input (`JobTriggerInput` / `TaskTriggerInput`) | Output |
| --- | --- | --- | --- |
| `triggerJob` | `POST /jobs/{id}/trigger` | `{ id, payload?, priority?, delay?, correlationId?, traceparent?, tracestate? }` | `{ jobId, triggered }` |
| `triggerTask` | `POST /tasks/{id}/trigger` | `{ id, payload?, priority?, delay?, correlationId? }` | `{ taskId, triggered }` |

See the [background-jobs capability page](https://rickylabs.github.io/netscript/capabilities/background-jobs/#trigger-a-job-from-a-typed-client) for the typed-client walkthrough.

### `@netscript/plugin-workers/scaffolding`

| Symbol | Kind | Description |
| --- | --- | --- |
| `JobBuilderScaffolder` | class | Scaffold a worker job builder module. |
| `JobHandlerScaffolder` | class | Scaffold a standalone worker job handler module. |
| `DenoTaskScaffolder` | class | Scaffold a Deno task definition module. |
| `PsTaskScaffolder` | class | Scaffold a PowerShell task script. |
| `PythonTaskScaffolder` | class | Scaffold a Python task script. |
| `ShellTaskScaffolder` | class | Scaffold a POSIX shell task script. |
| `WorkflowScaffolder` | class | Scaffold a worker workflow definition module. |
| `WorkersItemScaffolder` | class | Stub-only contract for generated workers items. |
| `createWorkersItemScaffolders` | function | Create all first-party workers item scaffolders. |
| `WORKERS_TASK_SCAFFOLD_RUNTIMES` | variable | Task runtimes covered by first-party workers scaffolding templates. |
| `WorkersScaffoldInput` | interface | Input accepted by workers item scaffolders. |
| `WorkersTaskScaffoldRuntime` | type alias | First-party task runtime scaffold kind. |

### `@netscript/plugin-workers/services`

| Symbol | Kind | Description |
| --- | --- | --- |
| `PluginServiceContext` | interface | Context supplied to a plugin service at runtime. |
| `default` | function | Starts the Workers API service using host-provided infrastructure. |

### `@netscript/plugin-workers/streams`

Browser-facing StreamDB factory and the entity schemas mirrored from worker execution state.

| Symbol | Kind | Description |
| --- | --- | --- |
| `createWorkersStreamDB` | function | Create a TanStack DB-backed StreamDB for worker execution and job entities. |
| `WorkerExecution` | type alias | Worker execution entity stored in the durable stream. |
| `WorkerJob` | type alias | Worker job entity stored in the durable stream. |
| `WorkersStreamDB` | type alias | Browser-facing StreamDB surface returned by the workers stream factory. |
| `WorkerExecutionSchema` | variable | Stream entity schema for worker executions. |
| `WorkerJobSchema` | variable | Stream entity schema for worker jobs. |
| `workersStreamSchema` | variable | Stream schema definition for worker executions and jobs. |
| `StreamSchemaDefinition` | type alias | Structural stream schema definition map. |
| `WorkersStreamDefinition` | type alias | Durable stream definition for worker execution and job entities. |
| `WorkersStreamSchema` | type alias | Package-owned structural workers stream schema surface. |
| `WorkerStreamCollectionDefinition` | interface | Package-owned structural stream collection definition. |
| `WorkerStreamEntitySchema` | interface | Package-owned structural schema surface for worker stream entities. |
| `WorkerStreamStandardSchema` | interface | Standard Schema compatible public schema surface for stream entities. |

### `@netscript/plugin-workers/streams/server`

Server-side wiring that mirrors execution-state changes into the durable stream producer.

| Symbol | Kind | Description |
| --- | --- | --- |
| `createStreamMutationHook` | function | Create an ExecutionState mutation hook that publishes to the durable stream. |
| `emitJobToStream` | function | Emit a job entity to the durable stream. |
| `getWorkersStreamProducer` | function | Get (or create) the singleton workers execution stream producer. |
| `ExecutionConcept` | type alias | Execution concept discriminator. |
| `ExecutionMutationHook` | type alias | Hook invoked after execution state mutations. |
| `ExecutionRecord` | type alias | Worker execution record stored in KV. |
| `ExecutionStatus` | type alias | Execution status discriminator. |
| `ExecutionTriggerType` | type alias | Execution trigger discriminator. |
| `WorkersStreamProducer` | type alias | Durable stream producer type for the workers stream schema. |
| `WorkerExecutionSchema` | variable | Stream entity schema for worker executions. |
| `WorkerJobSchema` | variable | Stream entity schema for worker jobs. |
| `workersStreamSchema` | variable | Stream schema definition for worker executions and jobs. |
| `StreamSchemaDefinition` | type alias | Structural stream schema definition map. |
| `WorkerExecution` | type alias | Worker execution entity stored in the durable stream. |
| `WorkerJob` | type alias | Worker job entity stored in the durable stream. |
| `WorkersStreamDefinition` | type alias | Durable stream definition for worker execution and job entities. |
| `WorkersStreamSchema` | type alias | Package-owned structural workers stream schema surface. |
| `WorkerStreamCollectionDefinition` | interface | Package-owned structural stream collection definition. |
| `WorkerStreamEntitySchema` | interface | Package-owned structural schema surface for worker stream entities. |
| `WorkerStreamStandardSchema` | interface | Standard Schema compatible public schema surface for stream entities. |

### `@netscript/plugin-workers/worker`

The long-running runtime processes: the `Worker` job/task consumer and the cron `Scheduler`.

| Symbol | Kind | Description |
| --- | --- | --- |
| `ScheduledJobInfo` | interface | Scheduled job info. |
| `Scheduler` | class | Scheduler process that loads scheduled jobs and dispatches cron ticks. |
| `SchedulerOptions` | interface | Scheduler configuration options. |
| `JobContext` | type alias | Context supplied to runtime job handlers. |
| `JobDefinition` | type alias | Runtime job definition. |
| `JobHandler` | type alias | Function that executes a runtime job. |
| `JobResult` | type alias | Result returned by runtime job handlers. |
| `RuntimePermissions` | type alias | Runtime permission bag accepted by task and job execution. |
| `RuntimePermissionValue` | type alias | Runtime permission value accepted by task and job execution. |
| `StaticJobRegistry` | type alias | Registry of statically imported runtime job handlers. |
| `TaskDefinition` | type alias | Runtime task definition. |
| `TaskExecutionOptions` | type alias | Options supplied when executing a task. |
| `WorkerCronJob` | interface | Cron job handle used by the workers scheduler. |
| `WorkerCronScheduler` | interface | Cron scheduler surface consumed by the workers scheduler. |
| `WorkerSchedulerExecutionState` | interface | Execution-state surface consumed by the workers scheduler. |
| `WorkerSchedulerJobRegistry` | interface | Job registry surface consumed by the workers scheduler. |
| `Worker` | class | Worker process that consumes queued jobs and tasks for one runtime instance. |
| `QueueTriggerConfig` | interface | Configuration for a queue that triggers a job when messages arrive. |
| `WorkerCompleteExecutionOptions` | type alias | Options for completing a worker execution record. |
| `WorkerCreateExecutionOptions` | type alias | Options for creating a worker execution record. |
| `WorkerExecutionRecord` | interface | Execution record returned by the worker execution-state port. |
| `WorkerExecutionState` | interface | Execution-state surface consumed by the worker process. |
| `WorkerHealthStatus` | interface | Health snapshot for a worker runtime. |
| `WorkerJobRegistry` | interface | Job registry surface consumed by the worker process. |
| `WorkerOptions` | interface | Worker configuration options. |
| `WorkerPayloadSchema` | interface | Structural validation schema accepted by worker queue triggers. |
| `WorkerTaskExecutor` | interface | Task executor surface consumed by the worker process. |
| `WorkerTaskRegistry` | interface | Task registry surface consumed by the worker process. |
| `WorkerTaskResult` | type alias | Task execution result surface consumed by the worker process. |
| `WorkerPoolOptions` | type alias | Options for the plugin-layer in-process job runner pool. |

## Internals: `@netscript/plugin-workers-core`

> **Internals.** The `@netscript/plugin-workers-core` package holds the reusable worker definition builders, runtime composition, registries, executors, and testing primitives that `@netscript/plugin-workers` binds to the host. It is published separately and may be imported directly, but most applications consume it through the plugin above (US-8). The surface below is generated from its own `deno doc` exports.

### `@netscript/plugin-workers-core`

Root entrypoint: the thin public definition builders, runtime starters, and inspection helpers.

| Symbol | Kind | Description |
| --- | --- | --- |
| `defineJob` | function | Start a worker job definition chain. |
| `defineTask` | function | Start a worker task definition chain. |
| `defineWorkflow` | function | Start a worker workflow definition chain. |
| `cron` | variable | Cron schedule helpers for worker jobs. |
| `permissions` | variable | Permission presets for worker jobs and tasks. |
| `defineJobHandler` | function | Define a worker job handler. |
| `createWorkersRuntime` | function | Create a fresh workers runtime from explicit dependencies. |
| `createFailureResult` | function | Create a failed job result. |
| `createSuccessResult` | function | Create a successful job result. |
| `startWorkers` | function | Create and start a workers runtime using default composition. |
| `inspectJob` | function | Inspect a job definition without starting a runtime. |
| `inspectTask` | function | Inspect a task definition without starting a runtime. |
| `inspectWorkflow` | function | Inspect a workflow definition without starting a runtime. |
| `JobId` | type alias | Branded worker job identifier. |
| `TaskId` | type alias | Branded worker task identifier. |
| `CronHelpers` | type alias | Cron schedule helper surface for worker jobs. |
| `PermissionPresets` | type alias | Worker permission preset surface for common job execution modes. |
| `JobBuilder` | interface | Root-surface job builder typestate API. |
| `JobDefinition` | type alias | Root-surface job definition derived from the thin public schema. |
| `JobHandlerContext` | type alias | Context passed to root-surface job handlers. |
| `JobResult` | type alias | Result returned by worker job handlers. |
| `TaskBuilder` | interface | Root-surface task builder typestate API. |
| `TaskDefinition` | type alias | Root-surface task definition derived from the thin public schema. |
| `WorkflowBuilder` | interface | Root-surface workflow builder typestate API. |
| `WorkflowDefinition` | type alias | Root-surface workflow definition derived from the thin public schema. |

### `@netscript/plugin-workers-core/builders`

Typestate builders for jobs, tasks, and workflows.

| Symbol | Kind | Description |
| --- | --- | --- |
| `defineJob` | function | Start a worker job definition chain. |
| `JobBuilder` | interface | Typestate builder interface for job definitions. |
| `JobBuilderState` | type alias | Job builder state used to gate `build()`. |
| `RetryOptions` | type alias | Retry configuration options for job definitions. |
| `JobRetentionOptions` | type alias | Execution retention settings for job definitions. |
| `defineTask` | function | Start a worker task definition chain. |
| `TaskBuilder` | interface | Typestate builder interface for task definitions. |
| `TaskBuilderState` | type alias | Task builder state used to gate `build()`. |
| `defineWorkflow` | function | Start a worker workflow definition chain. |
| `WorkflowBuilder` | interface | Typestate builder interface for workflow definitions. |
| `WorkflowBuilderState` | type alias | Workflow builder state used to gate `build()`. |
| `WorkflowJobStepOptions` | type alias | Options for adding a job-backed workflow step. |
| `WorkflowTaskStepOptions` | type alias | Options for adding a task-backed workflow step. |
| `BuilderPermissions` | interface | Deno permission set accepted by job and task builders. |
| `BuilderPermissionValue` | type alias | Permission value accepted by job and task builders. |
| `BuilderTaskType` | type alias | Runtime used to execute a task built by the task builder. |
| `JobDefinition` | interface | Public job definition produced by the job builder. |
| `JobHandler` | type alias | Function that executes a job. |
| `JobHandlerContext` | interface | Context passed to job handlers declared with the builder. |
| `JobId` | type alias | Branded worker job identifier used by builder surfaces. |
| `JobResult` | type alias | Worker job handler result. |
| `TaskDefinition` | interface | Public task definition produced by the task builder. |
| `TaskHandler` | type alias | Function that executes a task. |
| `TaskId` | type alias | Branded worker task identifier used by builder surfaces. |
| `WorkflowDefinition` | interface | Public workflow definition produced by the workflow builder. |
| `WorkflowId` | type alias | Branded worker workflow identifier used by builder surfaces. |
| `WorkflowStep` | type alias | Single workflow step produced by the workflow builder. |
| `CronExpression` | type alias | Cron expression type used by worker schedules. |

### `@netscript/plugin-workers-core/contracts/v1`

Versioned worker service contract schemas and types (the source of the plugin contracts export).

| Symbol | Kind | Description |
| --- | --- | --- |
| `ExecutionFiltersSchema` | variable | Schema for list-executions filters. |
| `ExecutionRecordResponseSchema` | variable | Schema for worker execution record responses. |
| `JobCreateInputSchema` | variable | Schema for creating worker job definitions. |
| `JobDefinitionResponseSchema` | variable | Schema for worker job definition responses. |
| `JobFiltersSchema` | variable | Schema for list-jobs filters. |
| `JobTriggerInputSchema` | variable | Schema for triggering a worker job by id. |
| `JobUpdateInputSchema` | variable | Schema for updating worker job definitions. |
| `JobUpdateWithIdSchema` | variable | Schema for updating a worker job definition by id. |
| `SSEEventSchema` | variable | Schema for server-sent event payloads emitted by the workers service. |
| `TaskDefinitionResponseSchema` | variable | Schema for worker task definition responses. |
| `TaskFiltersSchema` | variable | Schema for list-tasks filters. |
| `workersContract` | variable | Worker service contract definition for client generation. |
| `workersContractV1` | variable | Context-bindable worker service contract definition. |
| `ContractProcedureLike` | type alias | Structural oRPC procedure reference used by worker contracts. |
| `ContractSchema` | interface | Package-owned structural schema surface for worker contracts. |
| `ContractSchemaResult` | type alias | Result returned by contract schema validation. |
| `ExecutionRecordResponse` | type alias | Public response returned for worker execution records. |
| `JobDefinitionResponse` | type alias | Public response returned for worker job definitions. |
| `JobTriggerInput` | type alias | Input accepted by the trigger-job procedure. |
| `JobTriggerOutput` | type alias | Output returned by the trigger-job procedure. |
| `SSEEvent` | type alias | Server-sent event payload emitted by the workers service. |
| `StandardSchemaLike` | type alias | Structural Standard Schema reference used by contract metadata. |
| `TaskDefinitionResponse` | type alias | Public response returned for worker task definitions. |
| `TaskTriggerInput` | type alias | Input accepted by the trigger-task procedure. |
| `TaskTriggerOutput` | type alias | Output returned by the trigger-task procedure. |
| `WorkersContract` | type alias | Explicit public contract shape for worker service clients. |
| `WorkersContractV1` | type alias | Context-binding contract wrapper for the v1 worker contract. |
| `WorkersRouteHandler` | type alias | Structural route handler exposed by the implemented worker router. |
| `WorkersRouter` | type alias | Structural worker router returned after binding a context. |

### `@netscript/plugin-workers-core/registry`

KV-backed and in-memory job/task registries.

| Symbol | Kind | Description |
| --- | --- | --- |
| `KvJobRegistry` | class | KV-backed job registry for runtime composition. |
| `KvTaskRegistry` | class | KV-backed task registry for runtime composition. |
| `MemoryJobRegistry` | class | In-memory job registry for tests and local composition. |
| `Registry` | class | Generic registry base for named worker definitions. |
| `JobFilterOptions` | type alias | Filters accepted when listing worker jobs. |
| `TaskFilterOptions` | type alias | Filters accepted when listing worker tasks. |
| `ExecutionRecord` | type alias | Execution record shape stored by job registries. |
| `JobDefinition` | type alias | Job definition shape stored by registries. |
| `JobSource` | type alias | Job source value accepted by registry filters. |
| `RegisterJobInput` | type alias | Input accepted when registering a job. |
| `RegisterTaskInput` | type alias | Input accepted when registering a task. |
| `RegistryJobStoragePort` | type alias | Storage contract implemented by job registries. |
| `RuntimePermissions` | type alias | Runtime permission bag accepted by registry task and job definitions. |
| `RuntimePermissionValue` | type alias | Runtime permission value accepted by registry task and job definitions. |
| `TaskDefinition` | type alias | Task definition shape stored by registries. |
| `TaskSource` | type alias | Task source value accepted by registry filters. |
| `KvEntry` | type alias | Deno KV-compatible entry shape. |
| `KvListSelector` | type alias | Deno KV-compatible list selector. |
| `RegistryKvStore` | interface | Minimal KV shape consumed by registry adapters. |
| `RegistryOptions` | type alias | Registry adapter options. |

### `@netscript/plugin-workers-core/state`

KV-backed worker execution-state store.

| Symbol | Kind | Description |
| --- | --- | --- |
| `KvExecutionState` | class | KV-backed execution state store with explicit construction. |
| `CompleteExecutionOptions` | type alias | Options for completing a worker execution record. |
| `CreateExecutionOptions` | type alias | Options for creating a worker execution record. |
| `ExecutionConcept` | type alias | Execution concept discriminator. |
| `ExecutionMutationHook` | type alias | Hook invoked after execution state mutations. |
| `ExecutionRecord` | type alias | Worker execution record stored in KV. |
| `ExecutionStatus` | type alias | Execution status discriminator. |
| `ExecutionTriggerType` | type alias | Execution trigger discriminator. |
| `ListExecutionOptions` | type alias | Options for listing worker execution records. |

### `@netscript/plugin-workers-core/executor`

Multi-runtime task executor and per-runtime adapters.

| Symbol | Kind | Description |
| --- | --- | --- |
| `TaskExecutor` | class | Stub-only contract for the workers task orchestrator. |
| `TaskRuntimeAdapter` | class | Stub-only contract for a single task runtime adapter. |
| `CmdRuntimeAdapter` | class | Runtime adapter for Windows cmd tasks. |
| `DaxProcessRunner` | class | Run task subprocesses through Dax with streaming output capture. |
| `DenoRuntimeAdapter` | class | Runtime adapter for Deno task scripts. |
| `DotNetRuntimeAdapter` | class | Runtime adapter for .NET task programs. |
| `ExecutableRuntimeAdapter` | class | Runtime adapter for direct executable tasks. |
| `PowerShellRuntimeAdapter` | class | Runtime adapter for PowerShell task scripts. |
| `PythonRuntimeAdapter` | class | Runtime adapter for Python task scripts. |
| `runProcess` | function | Run a subprocess through Dax with result capture and log callbacks. |
| `RuntimeAdapterBase` | class | Shared adapter delegation for built-in subprocess runtimes. |
| `ShellRuntimeAdapter` | class | Runtime adapter for POSIX or Git Bash shell scripts. |
| `EnvironmentReader` | type alias | Function used by command builders to read process environment. |
| `ProcessRunInput` | type alias | Process runner input shared by built-in runtime adapters. |
| `ProcessRunner` | interface | Subprocess primitive used by runtime adapters. |
| `RuntimeCommandBuildContext` | type alias | Context passed to runtime command builders. |
| `RuntimeCommandSpec` | type alias | Command and arguments prepared for a task runtime adapter. |
| `RuntimeTaskMetadata` | type alias | Runtime-specific task metadata recognized by built-in adapters. |
| `createDefaultRuntimeAdapterMap` | function | Create the default built-in runtime adapter map. |
| `createDefaultTaskExecutor` | function | Create the default executor with all built-in runtime adapters. |
| `MultiRuntimeTaskExecutor` | class | Dispatches task execution to runtime-specific adapters. |
| `ResolvedTaskExecutionOptions` | type alias | Execution options resolved by the task orchestrator before adapter dispatch. |
| `TaskDefinition` | type alias | Task definition shape consumed by executor adapters. |
| `TaskExecutionOptions` | type alias | Options supplied to a task execution. |
| `TaskInstrumentationLike` | type alias | Executor instrumentation hook shape. |
| `TaskInstrumentationSpan` | type alias | Span shape accepted by executor instrumentation hooks. |
| `TaskLogEntry` | type alias | Log entry emitted while a task subprocess is running. |
| `TaskResult` | type alias | Result returned by task execution. |
| `TaskRuntimeAdapterLike` | type alias | Task adapter contract consumed by the multi-runtime executor. |
| `TaskType` | type alias | Worker task runtime identifier supported by built-in adapters. |
| `WorkerTaskPermissionField` | type alias | Permission field accepted by Deno task execution. |
| `WorkerTaskPermissions` | type alias | Permission set accepted by Deno task execution. |
| `MultiRuntimeTaskExecutorOptions` | type alias | Options for the default multi-runtime task executor. |

### `@netscript/plugin-workers-core/workflow`

Workflow executor, step runner, and durable state store.

| Symbol | Kind | Description |
| --- | --- | --- |
| `defineWorkflow` | function | Start a worker workflow definition chain. |
| `WorkflowBuilder` | interface | Typestate builder interface for workflow definitions. |
| `WorkflowBuilderState` | type alias | Workflow builder state used to gate `build()`. |
| `WorkflowJobStepOptions` | type alias | Options for adding a job-backed workflow step. |
| `WorkflowTaskStepOptions` | type alias | Options for adding a task-backed workflow step. |
| `WorkflowExecutor` | class | Executes workflow definitions as explicit durable state machines. |
| `WorkflowExecutorOptions` | type alias | Options for creating a workflow executor. |
| `MemoryWorkflowStateStore` | class | In-memory workflow state store for tests and local runtime composition. |
| `WorkflowClock` | type alias | Clock contract used by workflow runtime code. |
| `WorkflowStateStore` | interface | Store contract for durable workflow state and routed events. |
| `WorkflowStepRunner` | class | Executes individual workflow steps through explicit runtime callbacks. |
| `WorkflowJobStepRunner` | type alias | Function that executes a job-backed workflow step. |
| `WorkflowStepRunnerOptions` | type alias | Options for executing workflow steps. |
| `WorkflowTaskStepRunner` | type alias | Function that executes a task-backed workflow step. |
| `JobId` | type alias | Branded worker job identifier used by builder surfaces. |
| `TaskId` | type alias | Branded worker task identifier used by builder surfaces. |
| `WorkflowDefinition` | interface | Public workflow definition produced by the workflow builder. |
| `WorkflowEvent` | type alias | Event routed to a workflow execution. |
| `WorkflowExecutionOptions` | type alias | Options supplied when starting a workflow execution. |
| `WorkflowExecutionStatus` | type alias | Workflow execution lifecycle status. |
| `WorkflowId` | type alias | Branded worker workflow identifier used by builder surfaces. |
| `WorkflowResults` | type alias | Map of workflow step results by step id. |
| `WorkflowState` | type alias | Durable workflow execution state. |
| `WorkflowStep` | type alias | Single workflow step produced by the workflow builder. |
| `WorkflowStepKind` | type alias | Workflow step kind. |
| `WorkflowStepResult` | type alias | Result produced by a workflow step. |
| `WorkflowStepStatus` | type alias | Workflow step lifecycle status. |

### `@netscript/plugin-workers-core/streams`

Server-side durable stream producer and execution-state mirror hooks.

| Symbol | Kind | Description |
| --- | --- | --- |
| `createStreamMutationHook` | function | Create a mutation hook that mirrors execution state into the durable stream. |
| `createWorkersStreamProducer` | function | Create a workers durable stream producer for execution and job entities. |
| `emitJobToStream` | function | Emit a job entity to the workers durable stream. |
| `toExecutionStreamEntity` | function | Convert an execution record into the durable stream execution entity shape. |
| `ExecutionMutation` | type alias | Execution-state mutation published to the workers durable stream. |
| `ExecutionMutationHook` | type alias | Hook called when execution state changes. |
| `WorkerExecutionRecord` | type alias | Execution record shape mirrored into the workers durable stream. |
| `WorkersStreamProducer` | type alias | Durable stream producer type for the workers stream schema. |
| `WorkersStreamProducerOptions` | type alias | Options for creating a workers durable stream producer. |
| `WorkerExecutionSchema` | variable | Stream entity schema for worker executions. |
| `WorkerJobSchema` | variable | Stream entity schema for worker jobs. |
| `workersStreamSchema` | variable | Stream schema definition for worker executions and jobs. |
| `StreamSchemaDefinition` | type alias | Structural stream schema definition map. |
| `WorkerExecution` | type alias | Worker execution entity stored in the durable stream. |
| `WorkerJob` | type alias | Worker job entity stored in the durable stream. |
| `WorkersStreamDefinition` | type alias | Durable stream definition for worker execution and job entities. |
| `WorkersStreamSchema` | type alias | Package-owned structural workers stream schema surface. |
| `WorkerStreamCollectionDefinition` | interface | Package-owned structural stream collection definition. |
| `WorkerStreamEntitySchema` | interface | Package-owned structural schema surface for worker stream entities. |
| `WorkerStreamStandardSchema` | interface | Standard Schema compatible public schema surface for stream entities. |

### `@netscript/plugin-workers-core/presets`

Default composition preset (`startWorkers`) and runtime port contracts.

| Symbol | Kind | Description |
| --- | --- | --- |
| `startWorkers` | function | Create and start a workers runtime using default composition. |
| `StartWorkersOptions` | type alias | Options for the default workers startup preset. |
| `ExecutionRecord` | type alias | Runtime execution record. |
| `JobContext` | type alias | Context supplied to runtime job handlers. |
| `JobDefinition` | type alias | Runtime job definition. |
| `JobHandler` | type alias | Function that executes a runtime job. |
| `JobMessage` | type alias | Message enqueued to trigger a job execution. |
| `JobResult` | type alias | Result returned by runtime job handlers. |
| `RuntimeJobStoragePort` | type alias | Runtime job storage contract. |
| `RuntimeSchedulerPort` | type alias | Runtime scheduler contract. |
| `RuntimeShutdownManager` | type alias | Runtime shutdown manager contract. |
| `RuntimeShutdownOptions` | type alias | Runtime shutdown configuration. |
| `RuntimeShutdownResource` | type alias | Resource managed during runtime shutdown. |
| `RuntimeTaskExecutor` | type alias | Runtime task executor contract. |
| `RuntimeTaskExecutorOptions` | type alias | Runtime task executor configuration. |
| `RuntimeWorkerPort` | type alias | Runtime worker dispatch contract. |
| `RuntimeWorkflowDefinition` | type alias | Runtime workflow definition accepted by composition. |
| `RuntimeWorkflowExecutor` | type alias | Runtime workflow executor contract. |
| `RuntimeWorkflowOptions` | type alias | Runtime workflow executor options. |
| `StaticJobRegistry` | type alias | Registry of statically imported runtime job handlers. |
| `TaskDefinition` | type alias | Runtime task definition. |
| `TaskExecutionOptions` | type alias | Options supplied when executing a task. |
| `TaskRegistryPort` | type alias | Registry contract for task definitions. |
| `TaskResult` | type alias | Result returned by task execution. |
| `WorkersClock` | type alias | Clock contract used by runtime tests and schedulers. |
| `WorkersRuntime` | type alias | Runtime handle returned by the workers composition root. |
| `WorkersRuntimeOptions` | type alias | Explicit dependencies and overrides for a workers runtime instance. |
| `WorkflowId` | type alias | Runtime workflow identifier. |

### `@netscript/plugin-workers-core/shutdown`

Graceful shutdown manager for runtime resources.

| Symbol | Kind | Description |
| --- | --- | --- |
| `ShutdownManager` | class | Coordinates graceful shutdown for runtime resources. |
| `ShutdownManagerOptions` | type alias | Options for creating or invoking a shutdown manager. |
| `ShutdownReport` | type alias | Result returned after a shutdown attempt. |
| `ShutdownResource` | type alias | Resource registered for graceful shutdown. |
| `ShutdownState` | type alias | Resource lifecycle state managed during shutdown. |

### `@netscript/plugin-workers-core/schemas`

Thin public definition schemas for the root quick-start surface.

| Symbol | Kind | Description |
| --- | --- | --- |
| `PublicStandardSchema` | interface | Standard Schema compatible public schema surface. |
| `PublicDefinitionSchemaShape` | type alias | Structural object-shape map used by public definition schemas. |
| `PublicDefinitionSchema` | interface | Package-owned structural schema surface for public definition schemas. |
| `PublicJobDefinitionOutput` | type alias | Thin public job definition output. |
| `PublicTaskDefinitionOutput` | type alias | Thin public task definition output. |
| `PublicWorkflowDefinitionOutput` | type alias | Thin public workflow definition output. |
| `JobDefinitionPublicBaseSchema` | variable | Public base schema for thin job definitions. |
| `TaskDefinitionPublicBaseSchema` | variable | Public base schema for thin task definitions. |
| `WorkflowDefinitionPublicBaseSchema` | variable | Public base schema for thin workflow definitions. |
| `PublicJobDefinitionSchema` | variable | Thin public job definition schema for root-level quick-start APIs. |
| `PublicTaskDefinitionSchema` | variable | Thin public task definition schema for root-level quick-start APIs. |
| `PublicWorkflowDefinitionSchema` | variable | Thin public workflow definition schema for root-level quick-start APIs. |

### `@netscript/plugin-workers-core/telemetry`

Worker telemetry span/attribute names and instrumentation classes.

| Symbol | Kind | Description |
| --- | --- | --- |
| `WorkerSpanNames` | variable | Worker telemetry span names. |
| `WorkerTelemetryAttributes` | variable | Worker telemetry attribute names. |
| `WorkerTelemetryEvents` | variable | Worker telemetry event names. |
| `WorkerTelemetryStatuses` | variable | Worker execution statuses used in telemetry attributes. |
| `WorkerSpanName` | type alias | Worker telemetry span name. |
| `WorkerTelemetryAttribute` | type alias | Worker telemetry attribute name. |
| `WorkerTelemetryEvent` | type alias | Worker telemetry event name. |
| `WorkerTelemetryStatus` | type alias | Worker telemetry status. |
| `applyWorkerInstrumentations` | function | Applies a set of worker instrumentation instances to a span. |
| `JobExecuteInstrumentation` | class | Adds common job execution attributes and lifecycle events. |
| `JobMainInstrumentation` | class | Adds job-main attributes used inside a job handler span. |
| `QueueDequeueInstrumentation` | class | Adds queue dequeue attributes for consumer spans. |
| `QueueEnqueueInstrumentation` | class | Adds queue enqueue attributes for producer spans. |
| `TaskExecuteInstrumentation` | class | Adds task execution attributes and lifecycle events. |
| `WorkerInstrumentation` | class | Base class for workers telemetry instrumentation. |
| `TaskInstrumentation` | class | Stub-only contract for task-scoped worker telemetry instrumentation. |
| `AbstractWorkerInstrumentation` | class | Stub-only contract for worker telemetry instrumentation. |
| `AbstractWorkerInstrumentationContext` | type alias | Context supplied to worker instrumentation hooks. |
| `AbstractWorkerInstrumentationSpan` | type alias | Span shape accepted by worker instrumentation hooks. |
| `InstrumentationContext` | type alias | Context passed to worker instrumentation instances. |
| `TelemetryAttributes` | type alias | Attribute map accepted by worker telemetry instrumentation. |
| `TelemetryAttributeValue` | type alias | Attribute value accepted by worker telemetry instrumentation. |
| `WorkerTelemetrySpan` | interface | Structural span contract used by workers core without binding to one tracer package. |

### `@netscript/plugin-workers-core/abstracts`

Stub-only abstract contracts shared across worker subsystems.

| Symbol | Kind | Description |
| --- | --- | --- |
| `JobDispatcher` | class | Stub-only contract for job dispatchers. |
| `JobLifecycleAdapter` | class | Stub-only contract for job lifecycle adapters. |
| `JobScheduler` | class | Stub-only contract for job schedulers. |
| `Registry` | class | Stub-only contract for keyed workers registries. |
| `TaskInstrumentation` | class | Stub-only contract for task-scoped worker telemetry instrumentation. |
| `TaskExecutor` | class | Stub-only contract for the workers task orchestrator. |
| `TaskRuntimeAdapter` | class | Stub-only contract for a single task runtime adapter. |
| `WorkerInstrumentation` | class | Stub-only contract for worker telemetry instrumentation. |
| `CliCommand` | class | Stub-only base contract for CLI command implementations. |
| `WorkersCommand` | class | Stub-only contract for workers CLI commands. |
| `WorkersItemScaffolder` | class | Stub-only contract for generated workers items. |
| `DisposeContext` | interface | Job disposal context. |
| `InitContext` | interface | Job initialization context. |
| `DispatchContext` | interface | Runtime dispatch context supplied to scheduled jobs. |
| `ExecutionContext` | interface | Execution context shared by worker runtime dispatchers. |
| `ResolvedTaskExecutionOptions` | type alias | Execution options resolved by the task orchestrator before adapter dispatch. |
| `RuntimeTaskMetadata` | type alias | Runtime-specific task metadata recognized by built-in adapters. |
| `TaskDefinition` | type alias | Task definition shape consumed by executor adapters. |
| `TaskExecutionOptions` | type alias | Options supplied to a task execution. |
| `TaskLogEntry` | type alias | Log entry emitted while a task subprocess is running. |
| `TaskResult` | type alias | Result returned by task execution. |
| `TaskType` | type alias | Worker task runtime identifier supported by built-in adapters. |
| `WorkerTaskPermissionField` | type alias | Permission field accepted by Deno task execution. |
| `WorkerTaskPermissions` | type alias | Permission set accepted by Deno task execution. |
| `JobContext` | type alias | Context supplied to runtime job handlers. |
| `JobDefinition` | type alias | Runtime job definition. |
| `JobHandler` | type alias | Function that executes a runtime job. |
| `JobResult` | type alias | Result returned by runtime job handlers. |
| `WorkerInstrumentationContext` | type alias | Context supplied to worker instrumentation hooks. |
| `WorkerInstrumentationSpan` | type alias | Span shape accepted by worker instrumentation hooks. |
| `WorkersCommandDefinition` | interface | Definition supplied to worker CLI commands. |

### `@netscript/plugin-workers-core/testing`

Fixtures and memory-backed runtime for tests.

| Symbol | Kind | Description |
| --- | --- | --- |
| `createExecutionRecordFixture` | function | Create an execution record with realistic defaults. |
| `createJobFixture` | function | Create a runnable job definition for tests. |
| `createJobResultFixture` | function | Create a successful job result for fixture handlers. |
| `createTestWorkersRuntime` | function | Create a test runtime with memory-backed storage and worker ports. |
| `ExecutionRecordFixtureOptions` | type alias | Partial execution record fields used to override fixture defaults. |
| `JobFixtureOptions` | type alias | Options for creating a test job definition. |
| `TestWorkersRuntime` | type alias | Workers runtime fixture with direct access to memory ports. |
| `TestWorkersRuntimeOptions` | type alias | Options for creating a memory-backed workers runtime fixture. |
| `MemoryJobRegistry` | class | In-memory job registry for tests and local composition. |
| `MemoryJobStorage` | class | In-memory job storage for package consumers and tests. |
| `MemoryWorker` | class | In-memory worker port that records dispatches and executes registered handlers. |
| `MemoryWorkerDispatch` | type alias | Recorded memory-worker dispatch with the job, context, and result. |
| `MemoryWorkerOptions` | type alias | Options for constructing an in-memory worker. |
| `ExecutionRecord` | type alias | Execution record shape stored by job registries. |
| `RegistryJobDefinition` | type alias | Job definition shape stored by registries. |
| `RegistryJobSource` | type alias | Job source value accepted by registry filters. |
| `RegistryRegisterJobInput` | type alias | Input accepted when registering a job. |
| `Registry` | class | Generic registry base for named worker definitions. |
| `RegistryJobStoragePort` | type alias | Storage contract implemented by job registries. |
| `RuntimeExecutionRecord` | type alias | Runtime execution record. |
| `JobContext` | type alias | Context supplied to runtime job handlers. |
| `JobDefinition` | type alias | Runtime job definition. |
| `JobHandler` | type alias | Function that executes a runtime job. |
| `JobMessage` | type alias | Message enqueued to trigger a job execution. |
| `JobResult` | type alias | Result returned by runtime job handlers. |
| `RuntimeJobStoragePort` | type alias | Runtime job storage contract. |
| `RuntimeSchedulerPort` | type alias | Runtime scheduler contract. |
| `RuntimeShutdownManager` | type alias | Runtime shutdown manager contract. |
| `RuntimeShutdownOptions` | type alias | Runtime shutdown configuration. |
| `RuntimeShutdownResource` | type alias | Resource managed during runtime shutdown. |
| `RuntimeTaskExecutor` | type alias | Runtime task executor contract. |
| `RuntimeTaskExecutorOptions` | type alias | Runtime task executor configuration. |
| `RuntimeWorkerPort` | type alias | Runtime worker dispatch contract. |
| `RuntimeWorkflowDefinition` | type alias | Runtime workflow definition accepted by composition. |
| `RuntimeWorkflowExecutor` | type alias | Runtime workflow executor contract. |
| `RuntimeWorkflowOptions` | type alias | Runtime workflow executor options. |
| `StaticJobRegistry` | type alias | Registry of statically imported runtime job handlers. |
| `TaskDefinition` | type alias | Runtime task definition. |
| `TaskExecutionOptions` | type alias | Options supplied when executing a task. |
| `TaskRegistryPort` | type alias | Registry contract for task definitions. |
| `TaskResult` | type alias | Result returned by task execution. |
| `WorkersClock` | type alias | Clock contract used by runtime tests and schedulers. |
| `WorkersRuntime` | type alias | Runtime handle returned by the workers composition root. |
| `WorkersRuntimeOptions` | type alias | Explicit dependencies and overrides for a workers runtime instance. |
| `WorkflowId` | type alias | Runtime workflow identifier. |

### `@netscript/plugin-workers-core/config`

Worker config file schemas plus defineWorkers and defineJobs helpers.

| Symbol | Kind | Description |
| --- | --- | --- |
| `ConfigSchema` | interface | Package-owned structural schema type for worker config validation. |
| `ConfigSchemaResult` | type alias | Result returned by a package-owned schema parse attempt. |
| `JobConfigSchema` | variable | Worker job configuration schema. |
| `RetentionConfigSchema` | variable | Retention settings for worker job executions. |
| `JobConfig` | interface | Worker job configuration. |
| `RetentionConfig` | interface | Retention settings for worker job executions. |
| `WorkerConfigPermissions` | interface | Partial Deno permission set accepted by worker config files. |
| `WorkerConfigPermissionValue` | type alias | Permission value accepted by worker config files. |
| `WorkerJobSource` | type alias | Origin of a worker job definition. |
| `TaskConfigSchema` | variable | Runtime task configuration. |
| `TaskConfig` | interface | Runtime task configuration. |
| `WorkerTaskSource` | type alias | Origin of a worker task definition. |
| `WorkerTaskType` | type alias | Runtime used to execute a task. |
| `defineJobs` | function | Define a per-topic job array. |
| `defineWorkers` | function | Define a split worker config module. |
| `QueueProviderSchema` | variable | Queue provider configuration schema. |
| `ScalingConfigSchema` | variable | Per-topic scaling configuration schema. |
| `TopicRetentionConfigSchema` | variable | Per-topic retention policy schema. |
| `WorkerGroupSchema` | variable | Worker group configuration schema. |
| `WorkersConfigSchema` | variable | Workers plugin configuration schema. |
| `JobConfigInput` | type alias | Authoring form for a worker job before schema defaults are applied. |
| `QueueProvider` | type alias | Queue backend provider selector. |
| `QueueProviderData` | type alias | Queue backend provider selector. |
| `ScalingConfig` | type alias | Per-topic worker scaling configuration. |
| `ScalingConfigData` | interface | Per-topic worker scaling configuration. |
| `TopicRetentionConfig` | type alias | Per-topic worker retention configuration. |
| `TopicRetentionConfigData` | interface | Per-topic retention policy configuration. |
| `WorkerGroup` | type alias | Worker group configuration for a topic. |
| `WorkerGroupData` | interface | Worker group configuration for a topic. |
| `WorkersConfig` | type alias | Workers configuration section. |
| `WorkersConfigData` | interface | Workers configuration section. |
| `WorkersConfigInput` | interface | Authoring form for split worker config files before schema defaults are applied. |

### `@netscript/plugin-workers-core/runtime`

Runtime composition root, in-process job runner, and worker messaging types.

| Symbol | Kind | Description |
| --- | --- | --- |
| `DEFAULT_TOPIC` | variable | Default topic for jobs and tasks without explicit topic assignment. |
| `SSEEventTypes` | variable | SSE event names for real-time worker updates. |
| `createWorkersRuntime` | function | Create a fresh workers runtime from explicit dependencies. |
| `TaskRegistryPort` | type alias | Registry contract for task definitions. |
| `WorkersClock` | type alias | Clock contract used by runtime tests and schedulers. |
| `WorkersRuntime` | type alias | Runtime handle returned by the workers composition root. |
| `WorkersRuntimeOptions` | type alias | Explicit dependencies and overrides for a workers runtime instance. |
| `ExecutionRecord` | type alias | Runtime execution record. |
| `JobContext` | type alias | Context supplied to runtime job handlers. |
| `JobDefinition` | type alias | Runtime job definition. |
| `JobDispatcherOptions` | type alias | Options for resolving runtime job handlers. |
| `JobHandler` | type alias | Function that executes a runtime job. |
| `JobId` | type alias | Runtime job identifier. |
| `JobMessage` | type alias | Message enqueued to trigger a job execution. |
| `JobModuleImporter` | type alias | Dynamic runtime module importer. |
| `JobResolution` | type alias | Result of resolving a runtime job handler. |
| `JobResolutionSource` | type alias | Runtime job handler resolution source. |
| `JobResult` | type alias | Result returned by runtime job handlers. |
| `RegisterJobInput` | type alias | Input for registering a job definition. |
| `RegisterTaskInput` | type alias | Input for registering a task definition. |
| `RuntimeJobKvKeyFactories` | type alias | Public shape for runtime KV key factories. |
| `RuntimeJobStoragePort` | type alias | Runtime job storage contract. |
| `RuntimePermissions` | type alias | Runtime permission bag accepted by task and job execution. |
| `RuntimePermissionValue` | type alias | Runtime permission value accepted by task and job execution. |
| `RuntimeSchedulerPort` | type alias | Runtime scheduler contract. |
| `RuntimeShutdownManager` | type alias | Runtime shutdown manager contract. |
| `RuntimeShutdownOptions` | type alias | Runtime shutdown configuration. |
| `RuntimeShutdownResource` | type alias | Resource managed during runtime shutdown. |
| `RuntimeTaskExecutor` | type alias | Runtime task executor contract. |
| `RuntimeTaskExecutorOptions` | type alias | Runtime task executor configuration. |
| `RuntimeWorkerPort` | type alias | Runtime worker dispatch contract. |
| `RuntimeWorkflowDefinition` | type alias | Runtime workflow definition accepted by composition. |
| `RuntimeWorkflowExecutor` | type alias | Runtime workflow executor contract. |
| `RuntimeWorkflowOptions` | type alias | Runtime workflow executor options. |
| `StaticJobRegistry` | type alias | Registry of statically imported runtime job handlers. |
| `TaskDefinition` | type alias | Runtime task definition. |
| `TaskExecutionOptions` | type alias | Options supplied when executing a task. |
| `TaskId` | type alias | Runtime task identifier. |
| `TaskMessage` | type alias | Message enqueued to trigger a task execution. |
| `TaskResult` | type alias | Result returned by task execution. |
| `WorkflowId` | type alias | Runtime workflow identifier. |
| `JobKvKeys` | variable | KV key factories used by the runtime storage adapters. |
| `InProcessJobDispatcher` | class | Resolve job handlers from a static registry, definition, or explicit import fallback. |
| `InProcessJobRunner` | class | Registry-first job runner for tests, compiled binaries, and local composition. |
| `InProcessJobRunnerOptions` | type alias | Options for creating an in-process job runner. |
| `JOB_STATE_CHANNEL` | variable | Broadcast channel name for job execution state updates. |
| `ExecuteJobMessage` | type alias | Message sent to a runner to execute a job. |
| `JobCompleteMessage` | type alias | Message emitted when a job completes successfully. |
| `JobErrorMessage` | type alias | Message emitted when a job fails. |
| `JobLogMessage` | type alias | Message emitted for job logs. |
| `JobProgressMessage` | type alias | Message emitted to report job progress. |
| `StateUpdateMessage` | type alias | State update emitted by runtimes that expose execution progress. |
| `TerminateMessage` | type alias | Message used to stop a long-lived runner. |
| `WorkerInboundMessage` | type alias | Messages accepted by a job runner. |
| `WorkerOutboundMessage` | type alias | Messages emitted by a job runner. |

---

Back to the [reference overview](https://rickylabs.github.io/netscript/reference/).

_Canonical: https://rickylabs.github.io/netscript/reference/workers/_

---

# Explanation

Explanation pages are the **why** lane. They build the mental model: how NetScript is put together, why each boundary is shaped the way it is, and which trade-offs that shape buys you. Read them when you want to understand the framework, not when you are hunting for a specific command.

NetScript is a **Deno-native, contracts-first backend framework**. Its design is governed by one thesis — *the published surface is the product* — and everything in this zone is a consequence of that single idea: types before implementation, a small predictable surface at every boundary, and durable behavior modeled as explicit state machines rather than scattered event handlers.

> How this zone fits the others
>
> These pages are
>
> understanding-oriented
>
> . For a guided first path use the
>
> tutorials
>
> ; to get a concrete job done use the
>
> how-to guides
>
> ; to look up the exact symbols, ports, and signatures of any package use the generated
>
> reference
>
> ; and for a one-screen tour of each subsystem use the
>
> capabilities
>
> hubs.

## The concept map

Seven topics, ordered from the broadest framing down to the individual subsystems. The first two explain the framework as a whole; the next two cover the durable runtime model; the last three explain the cross-cutting concerns every plugin shares — the local orchestrator, the telemetry it emits, and the pure-backend authentication seam.

[The NetScript architecture  The published-surface thesis, the contracts-first workflow, the six package archetypes, and the publish gate that enforces all of it.](https://rickylabs.github.io/netscript/netscript/explanation/architecture/)

[Contracts first  How an oRPC contract flows from defineContract through implement() and a typed handler into a fully typed client, query layer, and island.](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)

[The plugin system  How a plugin relates to its core package, what it contributes through its manifest, and how the host discovers it through generated registries.](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/)

[Durability model  Sagas as explicit state machines: correlation, the kv or prisma durable store, and compensation modeled as message-handler effects.](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/)

[Observability  Where OpenTelemetry traces are real and automatic, where the scaffold handler helpers are still no-op stubs, and how Aspire collects it all.](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

[The Aspire orchestrator  The generated TypeScript AppHost, the resource graph (the Postgres container (the recommended engine) — or mysql / mssql via --db; sqlite is file-backed with no container — plus Redis and every *-api service), and the dashboard on :18888.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

[The pure-backend auth model  Core defines the AuthBackendPort; backends are pure adapters; the plugin composes exactly one active backend. Why only kv-oauth is interactive.](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/)

## A suggested reading order

These pages stand alone, but they compound. If you are new to the design, read them top to bottom: the architecture page sets the vocabulary the rest assume, and the auth model is easiest to grasp once you already understand plugins and ports.

1. [Architecture](https://rickylabs.github.io/netscript/netscript/explanation/architecture/)
2. [Contracts](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)
3. [Plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/)
4. [Durability model](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/)
5. [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/)
6. [Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)
7. [Auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/)

## Themes that recur across every page

A handful of ideas surface again and again. Recognizing them early makes the rest of this zone read as one coherent argument rather than seven separate articles.

- **Contracts before implementation.** Every subsystem starts from a schema and type contract — an oRPC contract for a service, a `defineSaga` definition for a workflow, an `AuthBackendPort` for an auth adapter — and the implementation is written to satisfy it. The [architecture](https://rickylabs.github.io/netscript/explanation/architecture/) and [contracts](https://rickylabs.github.io/netscript/explanation/contracts/) pages establish this; everything else applies it.
- **Ports own the seam; adapters stay swappable.** A package owns the *port* and wires one default adapter through a `createX()` factory, while technology-specific adapters and in-memory testing helpers live behind their own subpaths. The [auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) is the sharpest example — `AuthBackendPort` is defined once in core and satisfied by three independent backends.
- **Durable state is explicit.** Long-running behavior is a named state machine with a persistence backend, not an implicit ladder of callbacks. See [durable workflows](https://rickylabs.github.io/netscript/explanation/durability-model/) for sagas (`kv` or `prisma` store) and the [auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) for durable `auth.*` events.
- **Plugins extend without redefining.** First-party plugins under `plugins/*` re-export their core package's contract and contribute service entrypoints, runtime declarations, and schema fragments — covered in the [plugin model](https://rickylabs.github.io/netscript/explanation/plugin-system/).
- **Alpha reality stated plainly.** Where the scaffold ships a stub — the worker handler trace helpers, the streams *manifest* helpers, the absent auth audit surface — these pages say so plainly. The [observability](https://rickylabs.github.io/netscript/explanation/observability/) page draws the exact line between real automatic traces and the no-op handler stubs.

> Where to verify a claim
>
> Every command, port, and import specifier in this zone is grounded in the generated
>
> reference
>
> (one page per published package). When an explanation page names a symbol, follow its link to
>
> reference/<unit>/
>
> for the exact signature — the reference is the single source of truth, and these pages never duplicate it.

## Where to go next

- Start with [The NetScript architecture](https://rickylabs.github.io/netscript/explanation/architecture/) for the framework-wide model and vocabulary.
- Jump straight to [The pure-backend auth model](https://rickylabs.github.io/netscript/explanation/auth-model/) if you are evaluating NetScript's authentication seam.
- Cross over to the [capabilities](https://rickylabs.github.io/netscript/capabilities/) hubs for a per-subsystem tour with headline APIs, or to the [reference](https://rickylabs.github.io/netscript/reference/) for exact symbols.

_Canonical: https://rickylabs.github.io/netscript/explanation/_

---

# The NetScript architecture

NetScript is a set of Deno-native framework packages, published on [JSR](https://jsr.io) and composed into a running backend by **first-party plugins**, orchestrated locally by **Aspire**. This essay answers one question: when you build an app on NetScript, what are the layers you actually work with, what runs where, and which way do the dependencies point?

![A NetScript workspace as four stacked layers: typed contracts at the base, packages and plugins composed on top, the host wiring plugins through generated registries, and the runtime executing services and background processors — all orchestrated by Aspire.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/architecture-overview.svg)

*The four layers an app author works with: typed contracts, packages and plugins, the host that assembles them, and the runtime that executes services and background processors.*

Read this for orientation, not step-by-step work. The [tutorials]( [Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) ) and [how-to guides]( [How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/) ) are the practical paths; the [glossary](https://rickylabs.github.io/netscript/glossary/) defines every term of art; and each layer below routes you onward to the capability hub or reference unit that elaborates it.

> How to read this page
>
> This is a
>
> mental-model
>
> page. It explains
>
> why
>
> NetScript is split the way it is. If you want exact exports, jump to a
>
> reference unit
>
> ; if you want to ship something, start with a
>
> tutorial
>
> .

## The thesis: the published surface is the product

NetScript treats publishing as the whole point. A package's `mod.ts` is not an implementation detail that happens to be exported — it is the contract the framework makes with you, the caller. The shape you see through `deno doc`, the JSR doc score, and the type checker is the surface everything else serves.

Two consequences explain most of the design decisions you will meet:

1. **Types are designed before implementation.** The public types and the README come first; the code that satisfies them comes second. If `deno doc <package>` does not read end-to-end as a manual, the surface is considered broken, regardless of how the internals work.
2. **Simple is preferred over easy at every boundary.** Approachability comes from a small, predictable surface rather than hidden magic. The common 80% case is one chained call; advanced cases unfold one method deeper rather than appearing as required configuration on the entry point.

The deeper rationale for this contract-first stance is the subject of [Contracts & type flow]( [Contracts & type flow](https://rickylabs.github.io/netscript/netscript/explanation/contracts/) ).

## Four layers, one direction of dependency

The single most useful thing to hold in your head is the **direction** of the arrows. Every layer below depends only on the layers beneath it, and **nothing ever edits another boundary's code**. Build that picture once and the rest of the framework stops surprising you.

### 1. Typed contracts — the base, with no dependencies

At the bottom sits the contract layer: schemas and types that describe what a service accepts and returns, with essentially no runtime and no dependencies of their own. A contract is a plain object built from `@orpc/contract` and zod schemas; the same object is imported by the service that *implements* it and by the client that *calls* it, so the two can never drift. Because contracts depend on nothing, everything above can depend on them freely.

This is why "change the shape" is a type error you see at compile time rather than a 500 you discover in production. The contract machinery — `@orpc/contract`, zod, and `implement()` — is the subject of [Contracts & type flow]( [Contracts & type flow](https://rickylabs.github.io/netscript/netscript/explanation/contracts/) ); the generated reference is [`@netscript/contracts`]( [contracts](https://rickylabs.github.io/netscript/netscript/reference/contracts/) ).

### 2. Packages and plugins — composing the substrate

Above the contracts sit two kinds of building block:

- **Platform packages** (the `@netscript/*` kernel) know nothing about any one capability. They are the shared substrate: [`config`]( [config](https://rickylabs.github.io/netscript/netscript/reference/config/) ), [`service`]( [service](https://rickylabs.github.io/netscript/netscript/reference/service/) ), [`database`]( [database](https://rickylabs.github.io/netscript/netscript/reference/database/) ), [`queue`]( [queue](https://rickylabs.github.io/netscript/netscript/reference/queue/) ), [`kv`]( [kv](https://rickylabs.github.io/netscript/netscript/reference/kv/) ), [`telemetry`]( [telemetry](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) ), and the rest. A package wraps one concern behind a small surface and never reaches across into another package's internals.
- **Plugins** turn that substrate into a *capability* — workers, sagas, triggers, auth, streams. A plugin **composes** packages; it does not redefine them. It declares its capability by registering named **contributions** (a service, a background processor, a Prisma schema fragment, a stream topic) and leaves the wiring to the host.

The rule that keeps this clean: a plugin depends on packages, packages depend on contracts, and the arrow never reverses. A workers plugin imports the contract types from its sibling [`@netscript/plugin-workers-core`]( [workers](https://rickylabs.github.io/netscript/netscript/reference/workers/) ) package rather than inventing its own; an auth plugin composes the auth seam rather than embedding a provider. The mechanics — public plugin versus core package, manifests, contributions, and the generated registry — live in [The plugin system]( [The plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) ).

> The key insight
>
> A plugin is just a unit that
>
> composes packages
>
> and
>
> registers contributions
>
> . It is never a patch to framework code. Adding a capability is a manifest plus a regenerated registry, not an edit to the kernel. That single rule is what lets the framework grow without the layers tangling.

(You may see the word *archetype* in the doctrine and tooling. That is an internal classification the framework uses for its own quality gates — as an app author you meet it only indirectly, through the shape of a scaffolded plugin. See [The plugin system]( [The plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) ) if you are curious; it is not something you configure.)

### 3. The host — assembling plugins through generated registries

A workspace is more than a pile of plugins; something has to *assemble* them. That is the host's job. When you run the scaffold's generate step, NetScript reads the plugin list from `netscript.config.ts`, validates each plugin's contributions against fixed extension axes, and writes **generated registry** files that wire the contributions together. The host then loads those registries at startup.

The discipline here is the same as everywhere else: the host *reads* plugin manifests and *generates* wiring; it never asks you to hand-edit one plugin to make room for another. Two enabled plugins coexist because the host merged their registrations, not because either was patched. This is why enabling a capability is a config line plus a regenerate, and why the generated files are reproducible output you do not author by hand.

### 4. The runtime — executing services and background processors

At the top, the host's assembled workspace *runs*. NetScript is not one process: it is a small constellation of single-purpose services, each owned by a plugin and each speaking a contract, brought up together by Aspire. Two kinds of thing execute here:

- **Services** answer requests. They are [oRPC services]( [Services & contracts](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) ) mounted at `/api/rpc/*` — including triggers, which serve a typed v1 oRPC contract for trigger and event introspection plus management. The exception is the webhook *ingress* endpoint, a raw signature-verifying route because inbound webhooks are webhook-shaped, not contract-shaped.
- **Background processors** do work outside the request path: the worker job runtime, the durable saga runtime, schedulers, and file watchers. They own state and lifecycle, persist through a store, and shut down cleanly through a `{ stop() }` handle.

The topology below is the canonical shape of a fully-loaded workspace, with every first-party plugin enabled.

```text
                              ┌───────────────────────────────────┐
                              │            Aspire AppHost          │
                              │   dashboard  https://localhost:18888│
                              │  provisions Postgres + Redis (KV)  │
                              └───────────────┬───────────────────┘
                                              │ wires env, ports, resources
            ┌─────────────────────────────────┼─────────────────────────────────┐
            │                                  │                                 │
   ┌────────▼────────┐                ┌────────▼─────────────────────────┐
   │  example service │                │      PLUGIN SERVICES (oRPC)      │
   │   users :3001    │                ├──────────────────────────────────┤
   │  /api/rpc/*      │                │  workers  :8091   (jobs/tasks)   │
   │  oRPC contract   │                │  sagas    :8092   (durable flows)│
   └────────┬─────────┘                │  triggers :8093   (raw ingress)  │
            │                          │  auth     :8094   (oRPC /api/rpc)│
            │ contracts                └────────┬─────────────────────────┘
            │ (@orpc/contract + zod)            │
            │                          ┌────────▼─────────┐
   ┌────────▼──────────────────────────┴──────────────────┴──────────────────────┐
   │                  PACKAGES  (@netscript/* platform substrate)                  │
   │  config · runtime-config · service · contracts · sdk · plugin · database      │
   │  queue · kv · cron · logger · telemetry · aspire                              │
   └────────┬──────────────────────────────────────────────────────────┬──────────┘
            │ produces durable change-data events                       │
   ┌────────▼─────────┐                                      ┌──────────▼─────────┐
   │  streams  :4437   │  durable-stream service             │  Postgres / Redis   │
   │  HTTP / SSE       │  workers · auth · sagas mirror here  │  (relational + KV)  │
   └───────────────────┘                                      └────────────────────┘
```

Read the picture in three bands. **Aspire** sits on top as the local orchestrator: `cd aspire && aspire start` brings up Postgres and Redis (the default cache backend; `garnet` or `deno-kv` are selectable via `--cache-backend`) and starts every service *before* any `netscript db` command runs, with traces, logs, and health landing in the dashboard at `https://localhost:18888`. **Plugin services** sit in the middle, each owning exactly one service on a fixed port; your own scaffolded `users` service sits alongside them, speaking the same contract machinery. **The packages** sit underneath as the shared substrate every plugin composes against. See [Orchestration with Aspire]( [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) ) for the control-plane detail.

**Workspace ports and surfaces**

| Surface | Port | Protocol | Owner |
| --- | --- | --- | --- |
| Aspire dashboard | :18888 | HTTP (UI) | Aspire AppHost |
| Example service (users) | :3001 | oRPC over `/api/rpc/*` | your service |
| Workers | :8091 | oRPC | `@netscript/plugin-workers` |
| Sagas | :8092 | oRPC | `@netscript/plugin-sagas` |
| Triggers | :8093 | oRPC (raw webhook ingress) | `@netscript/plugin-triggers` |
| Auth | :8094 | oRPC over `/api/rpc/v1/auth/*` | `@netscript/plugin-auth` |
| Streams | :4437 | durable-stream HTTP / SSE | `@netscript/plugin-streams` |

A subtlety worth fixing early: **triggers serve a typed v1 oRPC contract**, like every other plugin service — the exception is narrower than it looks. Only the webhook *ingress* endpoint (`POST /api/v1/webhooks/:triggerId`) stays a raw, signature-verifying route, because it verifies an HMAC over the raw request bytes from external senders. Service RPC is mounted at `/api/rpc/*` (not `/rpc`). Those two facts trip people up more than any other detail here.

## The pure-backend seam: a port with interchangeable adapters

There is one recurring pattern that, once you see it, you will recognize across the whole framework: the **pure-backend seam**. It is how NetScript keeps a capability open to several implementations without leaking any of them into the contract.

The shape is always the same:

1. A package defines a **port** — a pure interface, no IO — that says what the capability must be able to do.
2. **Adapter** code implements that port against a concrete technology. Adapters are *pure backends*: they depend on the port, never the reverse, and add no public surface of their own beyond the factory you call.
3. A **plugin** composes **exactly one** active adapter, selected by configuration, and exposes it as a running service.

Auth is the most visible instance: a core seam defines an `AuthBackendPort`, three pure adapters implement it (a default interactive KV-OAuth backend, plus WorkOS and Better-Auth), and the auth plugin composes the one backend named by `NETSCRIPT_AUTH_BACKEND`. A capability a given backend cannot honor fails loud through a typed `AuthBackendOperationUnsupportedError` rather than silently doing nothing. The full treatment — the port, the three backends, and the per-backend capability matrix — lives in [The auth model]( [Auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) ); the capability hub is [Authentication]( [Authentication](https://rickylabs.github.io/netscript/netscript/identity-access/auth/) ).

> The seam is the design, not the adapter
>
> You will see the same port-and-adapter shape everywhere: the
>
> `queue`
>
> defines one port behind four backends (Deno KV, Redis, RabbitMQ, and PostgreSQL), the
>
> `database`
>
> wraps a relational engine behind a port — Postgres (the recommended engine; or
>
> mysql
>
> /
>
> mssql
>
> /
>
> sqlite
>
> via
>
> --db
>
> at scaffold time) — and durable sagas persist through a
>
> kv
>
> or
>
> prisma
>
> store. Auth simply makes the pattern most visible because it ships three adapters in the box.

This is why "swap the backend" is a configuration change in NetScript and not a rewrite: the contract is the port, and adapters are interchangeable behind it.

## Configuration records intent before runtime wiring

NetScript keeps *authored intent* separate from the concrete *runtime wiring* that makes a workspace run. The project-level intent lives in `netscript.config.ts`, authored with [`defineConfig`]( [config](https://rickylabs.github.io/netscript/netscript/reference/config/) ) or `defineConfigAsync`. That object says what the project *is* — its name, paths, enabled plugins, services, apps, database declarations, saga groups, trigger groups, and runtime-config output paths. At startup, `loadConfig` and `initConfig` resolve that authored form into a validated `NetScriptConfig`, and `getConfig` is the synchronous read path after initialization.

The split matters because the host needs both halves: `netscript.config.ts` carries workspace intent such as `paths` and the plugin list (`./plugins/workers/mod.ts`, `./plugins/sagas/mod.ts`, and the rest), while the operational database and resource details are carried by `appsettings.json` and the Aspire AppHost. Plugin packages can contribute partial config fragments through `@netscript/config/merge`, but those fragments merge *into* the already-validated project shape rather than replacing project identity. Runtime overrides are a third layer exposed by [`@netscript/runtime-config`]( [runtime-config](https://rickylabs.github.io/netscript/netscript/reference/runtime-config/) ) for topics such as jobs, sagas, triggers, features, and tasks.

Think of it as three nested layers: `netscript.config.ts` declares project intent, plugin config contributions extend that intent, and appsettings/Aspire/runtime-config materialize the environment-specific wiring. This is also where the capability switches live — the saga durable store (`NETSCRIPT_SAGA_STORE=kv|prisma`), the queue provider, and the active auth backend (`NETSCRIPT_AUTH_BACKEND`) are all selected here rather than in code. It is also why the database docs note a scaffold reality: `databases.config` can be empty in `netscript.config.ts` while the chosen engine — Postgres (the recommended choice), or `mysql` / `mssql` / `sqlite` selected with `--db` at scaffold time — is still provisioned by Aspire (sqlite is file-backed, so it has no Aspire container resource) and described in `appsettings.json`. See [Runtime configuration]( [Runtime configuration](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/runtime-config/) ).

### Naming is part of the contract

Entry points follow fixed verbs, so you can predict behavior from the name alone:

- `defineX(...)` returns a frozen *definition* and does no runtime work.
- `createX(...)` constructs a *runtime* object that owns state and IO.
- `startX(...)` constructs *and* starts a runtime, returning a `{ stop() }` handle.
- `useX(...)` is a hook-style accessor inside a request, render, or handler scope.
- `withX(...)` is a builder method that returns a new builder and never mutates.

When a `mod.ts` would re-export more than roughly twenty symbols, the surface splits into **subpath exports** (for example `@netscript/logger/middleware` and `@netscript/logger/orpc`) to keep bundles lean and isolate adapter-specific code from production exports.

## Durable behavior is modeled as state machines

For the background processors that own *durable* flows, NetScript models them as explicit state machines rather than generic event-handler ladders. [Durable sagas]( [Durable sagas](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/) ) are the clearest example: a saga is named phases with explicit correlation, persistence, and compensation, declared through a builder.

```ts
// plugins/sagas/user-registration.saga.ts
import { defineSaga } from "@netscript/plugin-sagas-core";

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

const saga = defineSaga("user-registration")
  .state<State>({ status: "started" })
  .on("UserRegistered", (s, _message, _context) => {
    s.state = { status: "welcoming" };
  })
  .on("WelcomeEmailSent", (s, _message, _context) => {
    s.state = { status: "complete" };
  })
  .build();
```

Failure handling is just as explicit. Handlers throw rich errors; a supervisor — not a scatter of defensive `try/catch` inside the handler — decides whether to restart or escalate, and owns the telemetry for that decision. The durable runtime persists through a selectable `kv` or `prisma` store. The full flow is covered in [The durability model]( [The durability model](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) ).

## Observability is built into the substrate

Because every plugin composes the same packages, observability is wired once and inherited everywhere. aspire starts an OTLP collector, and the worker job path — dispatch, execution, scheduler, and subprocess continuation — emits **real OpenTelemetry spans automatically**, so job traces appear in the Aspire dashboard without any handler code.

> Limitation
>
> The scaffold
>
> createJobTools(ctx)
>
> helpers handed to your job handler (
>
> trace.addEvent
>
> ,
>
> withChildSpan
>
> ,
>
> progress
>
> ) are currently no-op stubs — a tracked limitation with a fix planned. For custom handler spans today, call
>
> @netscript/telemetry
>
> helpers directly.

The full picture is in [Observability]( [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/) ).

## The publish gate is the architecture gate

Tests are treated as fitness functions, and the publish gate is where the architecture is *enforced* rather than merely described. `deno publish --dry-run`, `deno doc`, the workspace type checks, the semantic tests, and an export/docs audit are not optional steps — they are the mechanism by which every boundary rule above survives contact with real code. A surface that does not pass them is broken by definition, which is precisely why the published surface can be trusted as the product.

> Alpha package pins
>
> Scaffold output pins exact alpha specifiers such as
>
> jsr:@netscript/plugin-auth-core@0.0.1-beta.11
>
> .

## Where to go next

- **The contract machinery:** how types flow from a contract to a client in [Contracts & type flow]( [Contracts & type flow](https://rickylabs.github.io/netscript/netscript/explanation/contracts/) ).
- **The plugin mechanics:** public-versus-core split, manifests, and registries in [The plugin system]( [The plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) ).
- **The auth seam in depth:** the port, the three backends, and the capability matrix in [The auth model]( [Auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) ).
- **Durable behavior:** how sagas and workers persist and recover in [The durability model]( [The durability model](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) ).
- **The local control plane:** how Aspire provisions everything in [Orchestration with Aspire]( [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) ).
- **Exact symbols:** open any package's [reference unit](https://rickylabs.github.io/netscript/reference/).
- **Hands-on:** the [tutorials]( [Tutorials](https://rickylabs.github.io/netscript/netscript/tutorials/) ) and [how-to guides]( [How-to guides](https://rickylabs.github.io/netscript/netscript/how-to/) ).

[Explanation](https://rickylabs.github.io/netscript/netscript/explanation/) [Contracts & type flow](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)

_Canonical: https://rickylabs.github.io/netscript/explanation/architecture/_

---

# Orchestration with Aspire

A NetScript app is never one process. This essay explains *why* it needs an orchestrator at all, *how* the orchestrator's resource graph is generated from your plugins rather than hand-wired, and *what* a single `aspire start` actually stands up — so you can reason about the running system instead of treating it as a black box.

![The Aspire AppHost resource graph: appsettings.json and plugin contributions feed createNetScriptAppHost, which registers infrastructure (Postgres, Redis), services, plugin APIs, and background processors, with cross-references resolved into injected environment variables, all observed by the dashboard at :18888.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/aspire-resource-graph.svg)

*One `aspire start` derives a coherent resource graph from your plugins, resolves the wiring between resources, and surfaces the whole thing in a dashboard.*

## Why an orchestrator at all

Picture what "run my app locally" really means for a multi-plugin NetScript project. It is not a single server. It is a small fleet:

- An example oRPC **service** (`defineService`) at `:3001`.
- A **Fresh** dashboard app.
- Each runtime plugin's **HTTP API** — `workers-api` (`:8091`), `sagas-api` (`:8092`), `triggers-api` (`:8093`), `auth-api` (`:8094`), the durable-`streams` runtime (`:4437`).
- Each plugin's **isolated background processors** — the workers and sagas runners, the triggers processor — running as separate executables, not threads inside the API.
- The **infrastructure** all of those depend on: a database — Postgres (the recommended engine; or `mysql` / `mssql` / `sqlite` via `--db`) — and a shared cache — `redis` by default, or `garnet` / `deno-kv` via `--cache-backend`.

Standing that up by hand is the integration tax: start each process in dependency order, hand each one the right connection strings, teach each one where its neighbours live, and tear it all down cleanly afterwards. Do it wrong and you get the classic distributed-dev failure modes — a service that races ahead of its database, a processor pointed at the wrong cache, a plugin that cannot find the sibling it calls. Removing exactly that tax is the whole reason the framework adopts an orchestrator.

> The key insight
>
> The unit of a NetScript app is the
>
> resource graph
>
> , not the process. Each plugin brings an HTTP service
>
> and
>
> its own isolated background workers
>
> and
>
> its infrastructure needs.
>
> Aspire
>
> lets you declare that graph once and boot it as a coherent whole, with the wiring between nodes already resolved — that is what an orchestrator buys you that a pile of
>
> deno task
>
> scripts never will.

**Aspire is the conductor.** You describe the desired graph; a single command stands the whole thing up with the wiring resolved. The database URL the `users` service needs, the cache endpoint the workers runtime needs, the cross-reference one plugin holds to another — Aspire computes them and injects them as environment variables, so no process has to discover its neighbours at runtime.

> Aspire is step 2 — before any database command
>
> The canonical workflow is
>
> scaffold → orchestrate → database
>
> . After
>
> netscript init
>
> , you run
>
> cd aspire && aspire restore
>
> once, then
>
> aspire start
>
> . That command provisions your database (Postgres is the recommended engine, or
>
> mysql
>
> /
>
> mssql
>
> /
>
> sqlite
>
> via
>
> --db
>
> at
>
> init
>
> ) and Redis through Docker and brings up every service.
>
> Only then
>
> do
>
> netscript db init
>
> ,
>
> db generate
>
> , and
>
> db seed
>
> work — because those commands provision and migrate the database
>
> through
>
> the running AppHost. Run a db command with no Aspire up and it fails: there is no Postgres for it to talk to. See
>
> Database
>
> and the [CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) for the full sequence.

## The AppHost: a generated TypeScript program

The heart of orchestration is the **AppHost** — a small TypeScript/Node program scaffolded into the `aspire/` subfolder at `aspire/apphost.mts`. It is the entry point `aspire start` executes. It is deliberately tiny: it builds an Aspire builder, hands it your project's `appsettings.json`, and runs the resulting graph.

```ts
// aspire/apphost.mts (generated by `netscript init`)
import { createBuilder } from './.aspire/modules/aspire.mjs';
import { createNetScriptAppHost } from './.helpers/index.mjs';

// 1. Build an Aspire builder (SDK modules restored by `aspire restore`).
const builder = await createBuilder();

// 2. Translate appsettings.json + plugin contributions into a resource
//    graph: db, cache, services, plugin APIs, background processors, apps.
await createNetScriptAppHost(builder, '../appsettings.json');

// 3. Build the graph and run it (dashboard + every resource).
await builder.build().run();
```

```json
{
  "appHost": { "path": "apphost.mts", "language": "typescript/nodejs" },
  "sdk": { "version": "13.4.6" },
  "profiles": {
    "https": {
      "applicationUrl": "https://localhost:0;http://localhost:0",
      "environmentVariables": {
        "ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "http://localhost:0",
        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true",
        "ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS": "true",
        "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:0"
      }
    }
  },
  "packages": {
    "Aspire.Hosting.PostgreSQL": "13.4.6",
    "Aspire.Hosting.Browsers": "13.4.6-preview.1.26319.6"
  }
}
```

> Dashboard and OTLP ports are ephemeral, not pinned
>
> The generated
>
> https
>
> profile asks Kestrel for
>
> ephemeral ports
>
> —
>
> applicationUrl
>
> , the OTLP endpoint, and the resource-service endpoint are all
>
> localhost:0
>
> , so Aspire binds a free port per run instead of hard-pinning the dashboard to
>
> :18888
>
> or the collector to
>
> :4318
>
> . Two consequences: (1)
>
> trust the URL `aspire start` prints
>
> , not a memorized port — the examples in this essay use
>
> :18888
>
> /
>
> :4318
>
> as the conventional Aspire defaults, but your run may differ; (2)
>
> aspire start --isolated
>
> gets its own free infra ports
>
> and
>
> isolated secrets under an isolated run folder, so several apphosts can run side by side without colliding on the base dashboard. Point telemetry backends at the endpoint the run reports, or set
>
> ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL
>
> yourself to fix it.

Two facts about the AppHost are worth internalizing because they contradict assumptions people carry from .NET Aspire:

1. **It uses an isolated TypeScript/Node runtime.** `aspire.config.json` declares `language: "typescript/nodejs"` and `appHost.path: "apphost.mts"`. The AppHost runs on an isolated Node.js runtime inside `aspire/` (with its own `package.json` and `.aspire/` SDK modules) precisely so that the Node dependency graph never leaks into the Deno workspace at the project root. You author NetScript in Deno; Aspire orchestrates it from a sealed-off Node corner.
2. **The graph is derived, not hand-written.** You do not edit `apphost.mts` to add a service. You declare infrastructure, services, plugins, and processors in `appsettings.json`, and each plugin contributes its own resources programmatically. `createNetScriptAppHost` reads the config, runs the contributions, and registers each resulting resource. The next section is the important one: it explains *how* that derivation works.

## How the graph is generated from your plugins

This is the part that makes Aspire feel like *part of the framework* rather than a bolted-on tool: **you never enumerate processes by hand.** A NetScript plugin can declare an Aspire *contribution*, and the AppHost asks every installed plugin to contribute its own slice of the graph. The contract lives in `@netscript/aspire` and is deliberately small.

A plugin's contribution extends `AspireNSPluginContribution`. It names itself and, given a builder and a context, returns the resources it wants in the graph:

```ts
// plugins/<name>/src/aspire-contribution.ts (conceptual shape)
import { AspireNSPluginContribution } from "@netscript/aspire";
import type { AspireBuilder, AspireResource, ContributionContext } from "@netscript/aspire";

class WorkersContribution extends AspireNSPluginContribution {
  readonly pluginName = "@netscript/plugin-workers";

  // Push this plugin's API + background processor into the builder.
  contribute(builder: AspireBuilder, ctx: ContributionContext): readonly AspireResource[] {
    // ... register a deno-service (the API) and a deno-background (the processor)
    return [/* AspireResource[] */];
  }

  // Optional: extra env this contribution needs, and health checks the
  // plugin doctor will probe.
  declareEnv(ctx: ContributionContext) { return {}; }
  declareHealthChecks(ctx: ContributionContext) { return []; }
}
```

The host side composes those contributions. `composeAppHost` walks the plugin manifests, finds the ones that declare an `aspire` contribution, instantiates each, and collects the resources:

```ts
// conceptual: how the AppHost asks plugins for their resources
import { composeAppHost } from "@netscript/aspire";

const { resources, registry } = composeAppHost({
  builder,          // the Aspire builder port
  context,          // ContributionContext (paths, ports, env)
  plugins,          // [{ name, contributions: { aspire: Contribution } }, ...]
});
// `registry` is a ContributionRegistry keyed by pluginName; a duplicate
// plugin name throws DuplicateContributionError — the graph is dedup-checked.
```

The shape of each node the contributions produce is deliberately narrow — every resource is one of a small, closed set of kinds:

**AspireResource — what a plugin contribution returns**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Resource name in the AppHost graph (the label you see in the dashboard). |
| `kind` | `AspireResourceKind` | One of: deno-service, deno-background, container, database, cache. The closed set keeps the graph reasoned-about. |
| `port` | `number?` | TCP port the resource exposes, when applicable (services and plugin APIs; containers and processors may omit it). |
| `metadata` | `Record?` | Adapter-specific extras the builder backend understands. |

So the AppHost is *generated*, but not in a "code-spitting templates" sense. It is generated in the stronger sense that the graph is **assembled at boot from the plugins you installed**. Add the sagas plugin and its `sagas-api` plus its supervisor processor appear; remove it and they vanish — no edit to `apphost.mts` required. The scaffold writes a thin `register-*.mts` helper layer (`register-infrastructure.mts`, `register-services.mts`, `register-plugins.mts`, `register-background.mts`, `register-apps.mts`, `register-tools.mts`) so each resource class lands through the same `builder.addExecutable(...)` path with permissions, working directory, HTTP endpoint, and OTEL environment resolved from config — but the *content* of the graph comes from your plugin set.

> Where this connects
>
> This is the orchestration face of the plugin model. The same plugin that registers routes, a schema slice, and background work (see
>
> the plugin system
>
> ) also declares how it appears in the resource graph. One install, one removal — the whole stack, infrastructure included, follows.

## Service discovery: how resources find each other

Declaring resources is half the job; the other half is *wiring* them. A plugin API may need a sibling plugin's HTTP endpoint; a service may depend on another service; a processor may need the database and the cache. NetScript expresses those needs as **references** on the config entry, and Aspire resolves them into injected environment variables so each process starts with its neighbours' addresses already present.

The reference vocabulary is small and explicit. `@netscript/aspire` extracts three kinds of dependency from each entry:

**Reference fields on a resource entry (resolved at compose time)**

| Name | Type | Description |
| --- | --- | --- |
| `ServiceReferences` | `string[]` | Other services this resource calls. `extractServiceReferences` deduplicates repeated entries. |
| `PluginReferences` | `string[]` | Plugin APIs this resource calls. `extractPluginReferences` returns them for endpoint wiring (e.g. workers-api → sagas-api). |
| `RequiresDb` | `boolean` | Whether the resource needs the Postgres connection. `extractDependencies` normalizes it (default false). |
| `RequiresKv` | `boolean` | Whether the resource needs the Redis/KV connection. Normalized the same way (default false). |

> Services now declare references too
>
> Every resource entry —
>
> ServiceEntry
>
> included — extends the same
>
> ReferenceEntry
>
> , so a
>
> service
>
> is no longer excluded from plugin-reference wiring: it can carry
>
> PluginReferences
>
> and reach a plugin API over the injected
>
> services__<plugin>__http__0
>
> variable, exactly as apps and background processors do. You express this in
>
> netscript.config.ts
>
> on the service's own section, where two fields resolve into the generated
>
> appsettings.json
>
> entry:
>
> - `pluginReferences: string[]` — plugin APIs this service calls (lowers to `PluginReferences`). This is the field that closes the earlier "a Service can't declare `PluginReferences`" gap.
> - `dependsOn: string[]` — sibling services this service waits on (lowers to the resource's `ServiceReferences`, driving both discovery wiring and start ordering).
>
> See
>
> Discover services
>
> for the two-pass resolution these fields feed, and
>
> the config reference
>
> for the full service-section schema.

Because endpoints only exist once resources are created, the wiring happens in **two passes**: first every resource is created, then a second pass resolves each reference against the now-known graph and injects it. In the generated builder that resolution lands as the equivalent of `getEndpoint('http')` plus `withEnvironment(...)` for cross-references, and the database/cache connection strings for the `RequiresDb`/`RequiresKv` flags. By the time a process's entry point runs, the URLs it needs are in `Deno.env` — it never has to "discover" anything at runtime, which is exactly why there is no service-registry client in your handler code.

```text
                          aspire start  (from aspire/)
                                 │
                                 ▼
              ┌──────────────────────────────────────────┐
              │  createNetScriptAppHost(appsettings.json) │
              │  + composeAppHost(plugin contributions)   │
              └──────────────────────────────────────────┘
                                 │  pass 1: create every resource
   ┌─────────────────────────────┼─────────────────────────────────────┐
   ▼                             ▼                                       ▼
(1) dashboard OTLP        (2) infrastructure                   (4) services
    :18888 + :4318            ├─ postgres  (Container)              └─ users  :3001
                              └─ redis     (Container, cache)
                                 │
                                 ▼  pass 2: resolve references → inject env
   ┌──────────────────────────────────────────────────────────────────────────────┐
   │ (5) plugin APIs  workers-api :8091  sagas-api :8092  triggers-api :8093          │
   │     auth-api :8094   streams :4437                                              │
   │ (6) background processors: workers, sagas (bin/combined.ts);                     │
   │     triggers (src/runtime/trigger-processor.ts)                                 │
   │ (7) apps:  dashboard (Fresh)        (8) tools                                   │
   └──────────────────────────────────────────────────────────────────────────────┘
```

The order is not arbitrary. Infrastructure comes up first because everything else depends on it; references are resolved only after the resources they point at exist. The full port map for every runtime resource is consolidated under [the Aspire reference](https://rickylabs.github.io/netscript/netscript/reference/aspire/) — treat that as canonical and this essay as the orientation.

**The resource graph a single `aspire start` brings up**

| Name | Type | Description |
| --- | --- | --- |
| `aspire (dashboard)` | `https://localhost:18888` | The Aspire dashboard. `aspire start` prints a login token. Live resource list, logs, structured traces, and the OTLP collector (:4318) surface here. |
| `postgres` | `Container` | Provisioned via Docker. The recommended engine is Postgres (swap to `mysql` / `mssql` — also Containers — or file-backed `sqlite`, which has no container, via `--db`), persistent (DataPath .data/postgres). The database that `netscript db` commands target — reachable only once Aspire is up. |
| `redis` | `Container (cache)` | Redis cache — the default `--cache-backend`; Redis-compatible. Backs KV/queue workloads for the runtime plugins. Swap to `garnet` (also a Container) or app-level `deno-kv` via `--cache-backend`. |
| `users` | `:3001` | Example oRPC service (defineService). Routes /api/v1/users/* and the RPC surface at /api/rpc/*. |
| `workers-api` | `:8091` | Workers plugin API. /api/v1/workers/{jobs,executions,tasks,seed}; trigger via POST /api/v1/workers/jobs/{id}/trigger. |
| `sagas-api` | `:8092` | Sagas plugin API. /api/v1/sagas/{sagas,instances,publish} plus liveness at /health/live. |
| `triggers-api` | `:8093` | Triggers plugin API (raw Hono, not oRPC). POST /api/v1/webhooks/inbound/generic, GET /api/v1/events. |
| `auth-api` | `:8094` | Auth plugin oRPC service. /api/v1/auth/{signin,callback,signout,session,me} with one active backend (NETSCRIPT_AUTH_BACKEND). |
| `streams` | `:4437` | Durable-streams producer runtime. Served as its own Aspire Deno service; workers/auth/sagas mirror execution state into it. |
| `workers / sagas / triggers` | `background processors` | Separate from the APIs: workers and sagas run from bin/combined.ts; triggers from src/runtime/trigger-processor.ts. Declared under appsettings BackgroundProcessors. |

Each of these capabilities has its own hub: [Services](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) ,

[Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/) , and

[Database](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) are the practical pages behind the graph nodes above.

## Customizing the generated AppHost: restart, regenerate, or hand-edit

Once the graph is running, the recurring question is *which change needs which action*. Because the `register-*.mts` helper layer is **generated from `netscript.config.ts`/`appsettings.json`**, most edits are a config change plus a regenerate, not a hand-edit of the AppHost. The regenerate command is `netscript service generate` — it rewrites only the Aspire helper files, never your service code.

**Which change needs which action**

| Name | Type | Description |
| --- | --- | --- |
| `Handler / service / app code` | `hot or restart resource` | Apps and background processors scaffold with Deno watch mode, so they reload on save. A plain service restarts from the dashboard. No regenerate, no AppHost restart. |
| `Env / Permissions / Port / Workdir on a resource` | `generate + restart AppHost` | Edit the resource's section in netscript.config.ts, run `netscript service generate` to rewrite the register-*.mts layer, then restart `aspire start`. |
| `A reference: ServiceReferences / pluginReferences / dependsOn` | `generate + restart AppHost` | Same flow. Pass 2 only re-resolves and re-injects services____http__0 on the next `aspire start` — a declared-but-not-generated reference does nothing. |
| `Add / remove a plugin, or a new appsettings resource` | `generate + restart AppHost` | `netscript plugin install`/`remove` (or a hand-added resource) changes the graph; the resource only joins on the next generate + `aspire start`. |
| `An injected env value Aspire owns (OTEL_*, a connection string)` | `restart the resource` | Environment is read once at process start, so bounce the affected resource for the new value to take effect. |

> The register-*.mts files are regenerated — express config, don't hand-edit
>
> The scaffolded
>
> register-infrastructure.mts
>
> ,
>
> register-services.mts
>
> ,
>
> register-plugins.mts
>
> ,
>
> register-background.mts
>
> ,
>
> register-apps.mts
>
> , and
>
> register-tools.mts
>
> carry a generated header and are
>
> overwritten by the next `netscript service generate`
>
> . Anything you can express as config survives regen: per resource,
>
> Env
>
> ,
>
> Permissions
>
> ,
>
> Port
>
> , and
>
> Workdir
>
> are all declarable in
>
> netscript.config.ts
>
> /
>
> appsettings.json
>
> — reach for those first. When a wire genuinely is not config-expressible yet (an MCP-over-HTTP endpoint, a bespoke cross-resource reference), there is
>
> no automatic preserve mechanism today
>
> : tag the change
>
> // HAND-EDITED (keep on regen)
>
> and re-apply it after each generate. Prefer moving the need into config so the hand-edit disappears.

### Native database drivers need launch permissions

A resource's permission flags are set **at launch**, and they are separate from the per-task permissions you tighten *inside* a worker (those are covered in

[Restrict worker task permissions](https://rickylabs.github.io/netscript/netscript/background-processing/how-to/restrict-worker-task-permissions/) ). This matters when a plugin loads a **native (FFI) database driver** — for example the native libSQL/Turso client the workers runtime can use for per-channel storage. Without FFI access the process crashes at import with `NotCapable: Requires ffi access`. The workers **background processor** therefore launches with an explicit permission set that includes `--allow-ffi` (and `--allow-sys`):

```ts
// plugins/workers/src/aspire/workers-contribution.ts — the background launch set
const WORKERS_BACKGROUND_PERMISSIONS = [
  '--unstable-kv',
  '--allow-net',
  '--allow-env',
  '--allow-read',
  '--allow-write',
  '--allow-run',
  '--allow-sys',
  '--allow-ffi', // native FFI drivers (e.g. libSQL/Turso) load here
] as const;
```

If you author a plugin or service that pulls in a native driver, give its resource the matching `--allow-ffi` (and any `--allow-sys`) flag through its contribution's launch permissions — a missing flag surfaces only at runtime as an FFI capability crash, not at generate time.

## The dashboard: the local observability surface

When `aspire start` finishes booting, it prints a URL and a one-time login token for the dashboard at `https://localhost:18888`. The dashboard is the single pane of glass over the running graph:

- **Resources** — every container and executable above, with status, endpoints, and environment.
- **Console logs** — stdout/stderr per resource, so a failing background processor is one click away rather than buried in a terminal.
- **Structured logs and traces** — aspire starts an OTLP collector at `http://localhost:4318`, and the spans and structured logs your handlers emit land here, correlated by `traceparent`, so a request that fans out across services is a single trace rather than scattered log lines.

This is where the orchestration story and the [observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

story meet. Aspire already knows the topology — every resource and its OTEL environment — so it can stitch telemetry into that topology for free. Concretely, each resource is started with its `OTEL_SERVICE_NAME` and an `OTEL_EXPORTER_OTLP_ENDPOINT` pointed at the dashboard collector (`http://localhost:4318`, `http/protobuf`), so job dispatch, job execution, scheduler runs, and subprocess task continuation all emit real OpenTelemetry spans that surface here with **no extra wiring** — the trace context propagates into worker subprocesses over W3C `traceparent`.

> Known gap
>
> The scaffold
>
> createJobTools(ctx)
>
> helpers you call
>
> inside
>
> a handler —
>
> trace.addEvent
>
> ,
>
> withChildSpan
>
> ,
>
> progress
>
> — are still no-op stubs. For custom
>
> handler-level
>
> spans, call
>
> @netscript/telemetry
>
> helpers directly. The framework-level spans above are real; see
>
> [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/) for the precise framework-vs-scaffold boundary.

## HTTP/2 and TLS: opt-in today

NetScript service listeners serve **plaintext HTTP/1.1 by default**, and that default is unchanged. HTTP/2 is available but strictly **opt-in via TLS**: `Deno.serve` negotiates h2 over ALPN the moment the listener has a certificate and key, so the way to get HTTP/2 is to hand the service TLS material. There are two ways to do that, and both flip the listener banner from `http` to `https`:

```ts
// Pass cert/key PEM material as ServeOptions.tls. Deno then negotiates HTTP/2
// over ALPN for clients that support it (HTTP/1.1 stays available as fallback).
import { createService } from '@netscript/service';
import type { ServiceTlsOptions } from '@netscript/service';

const tls: ServiceTlsOptions = {
  cert: await Deno.readTextFile('cert.pem'), // PEM certificate chain
  key: await Deno.readTextFile('key.pem'),   // PEM private key
};

await createService(router, { name: 'users' })
  .withHealth()
  .serve({ port: 3001, tls }); // banner now reports https://…
```

```bash
# When ServeOptions.tls is absent, the listener falls back to this env pair.
# BOTH must be set — one alone is ignored and the service stays plaintext.
NETSCRIPT_TLS_CERT_FILE=cert.pem \
NETSCRIPT_TLS_KEY_FILE=key.pem \
  deno run --allow-net --allow-read --allow-env services/users/main.ts

# With both present the service serves HTTPS + HTTP/2 — confirmed with `curl --http2`.
```

> Plaintext HTTP/1.1 is still the default
>
> Opting into TLS does not change the default path: with no
>
> tls
>
> option and no
>
> NETSCRIPT_TLS_CERT_FILE
>
> /
>
> NETSCRIPT_TLS_KEY_FILE
>
> pair, the listener is byte-for-byte the same plain HTTP/1.1 server. That has one consequence worth knowing: browsers cap HTTP/1.1 at roughly
>
> six concurrent connections per origin
>
> , which SSE and durable streams can exhaust — the fix is to adopt HTTP/2 per service by enabling TLS as above. Automatic Aspire dev-certificate provisioning and a default flip to HTTP/2 are still on the roadmap, so today this remains a deliberate opt-in. See
>
> Durable streams
>
> for the connection-cap caveat and [the service reference](https://rickylabs.github.io/netscript/netscript/reference/service/)
>
> for `ServiceTlsOptions` and `ServeOptions.tls`.

## The `--no-aspire` escape hatch

Aspire is the default and the recommended local path, but it is not mandatory. The `init` command takes a `--no-aspire` flag (`netscript init my-app --no-aspire`) that **skips scaffolding the orchestration layer entirely**: no `aspire/` folder, no AppHost to provision infrastructure, no dashboard. You start the generated Deno processes directly and provide your own infrastructure connection strings.

```bash
netscript init my-app --db postgres --service --service-name users --service-port 3001 --yes

# Step 2: orchestration brings up Postgres + Redis + every process.
cd aspire && aspire restore   # once
aspire start                    # dashboard at https://localhost:18888

# Step 3: database commands now work (provisioned through Aspire).
netscript db init --name init
```

```bash
# Scaffold WITHOUT the orchestration layer. No aspire/ folder is created.
netscript init my-app --db postgres --no-aspire --yes

# There is no `aspire start`. Start processes yourself:
deno task --cwd apps/dashboard dev

# You now own infrastructure: bring your own Postgres + cache and supply
# connection strings to each process. `netscript db` has no AppHost to
# provision through, so manage migrations against your own database URL.
```

> What you lose when you opt out
>
> --no-aspire
>
> trades convenience for control. Without the orchestration layer there is
>
> no AppHost
>
> (
>
> aspire/apphost.mts
>
> is not generated),
>
> no automatic Postgres/Redis provisioning
>
> ,
>
> no dashboard
>
> at
>
> :18888
>
> , and
>
> no automatic cross-process wiring
>
> — you become responsible for handing every process its connection strings and its neighbours' endpoints by hand. The
>
> netscript db
>
> commands lose the AppHost they provision through, so the database workflow becomes your responsibility against your own database URL.

**When opting out is the right call:**

- **A deploy target that does its own orchestration.** Kubernetes, Nomad, a managed PaaS, or a Docker Compose file you already maintain — the platform owns process lifecycle and service discovery, so a second orchestrator on top is redundant. This is the primary production case.
- **A constrained or air-gapped environment.** No Docker daemon, or a policy against running the Node AppHost runtime. You run Deno processes directly against externally-managed infrastructure.
- **A single-purpose slice.** You only want the Fresh app, or one service, with no database or cache — the full graph would be overhead.

For local development of a full multi-plugin app, opting out is almost always the wrong trade: you would be hand-rebuilding exactly the wiring the contributions generate for free.

## What Aspire does and does not cover for production

Choosing Aspire as the default is an opinion, and this essay states its boundaries.

**Aspire is the local-development orchestration story.** Its job is to make `git clone` → `aspire start` produce a complete, observable, correctly-wired stack on one machine. It excels at that. What it deliberately does **not** try to be:

- **A production deployment system.** The AppHost provisions Postgres and Redis as local Docker containers for dev convenience. It is not your production database, not your production cache, and not a cluster scheduler. In production you point processes at managed/clustered infrastructure and let your platform own lifecycle and scaling.
- **A replacement for your orchestrator of record.** The same resource model that is a gift on a laptop is redundant under Kubernetes or a PaaS that already does discovery, health, and restarts. That is precisely why `--no-aspire` is a first-class exit, not an afterthought.

The remaining trade-offs of the default path:

- **A second runtime in the tree.** The AppHost is Node/TypeScript while your app is Deno — a deliberate isolation so the two dependency graphs never contaminate each other, at the cost of "what runtime is this?" having two answers in one repo.
- **Docker is a hard dependency of the happy path.** No Docker daemon means the default workflow does not start — which is exactly when `--no-aspire` plus your own infrastructure earns its place.
- **The wiring is implicit.** The two-pass reference resolution is invisible at authoring time, so inspect generated environment variables and the resource graph when debugging service discovery.

## Glossary

- **AppHost** — the program that defines and runs an Aspire resource graph. In NetScript it is the generated TypeScript `aspire/apphost.mts`, configured by `aspire.config.json`.
- **Contribution** — a plugin's declaration of the resources it adds to the graph, expressed by extending `AspireNSPluginContribution` and returning `AspireResource[]` from `contribute(...)`.
- **Resource** — any node Aspire manages: a `container` (Postgres, Redis), a `database`, a `cache`, a `deno-service`, or a `deno-background` processor.
- **OTLP** — the OpenTelemetry protocol endpoint (`http://localhost:4318`) aspire starts so the dashboard can collect the spans and structured logs your handlers emit.

## Where to go next

- **Understand the surrounding model:** [Architecture](https://rickylabs.github.io/netscript/netscript/explanation/architecture/)

  for how the pieces fit, and [The plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/)

  for the contribution model that feeds the graph.
- **Do the practical work:** [Database](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) ,

[Services](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) , and

[Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/) are the hubs behind the graph nodes.

- **Look up exact symbols and the full port map:** [the Aspire reference](https://rickylabs.github.io/netscript/netscript/reference/aspire/)

  and the [CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) .
- **Related:** [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/) explains the spans and logs the dashboard at `:18888` collects.

[Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/) [Capabilities](https://rickylabs.github.io/netscript/netscript/capabilities/)

_Canonical: https://rickylabs.github.io/netscript/explanation/aspire/_

---

# The pure-backend auth model

*This essay is the **why** — the model and its trade-offs. The day-to-day *how* (guides, recipes, API) lives in **Build › [Identity & Access](https://rickylabs.github.io/netscript/identity-access/)**.*

This page explains *what* NetScript authentication actually is, *why* it is designed as a **pure-backend seam** rather than a built-in identity provider, and *how* a single typed port lets you swap GitHub OAuth for WorkOS or better-auth without touching one line of application code. It is understanding-oriented — read it to build the mental model before you wire authentication into a project. When you want the headline API and endpoints, see the [auth capability](https://rickylabs.github.io/netscript/capabilities/auth/); when you want to do the task, follow [Add authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/); when you want exact exported symbols, follow [`reference/service/`](https://rickylabs.github.io/netscript/reference/service/) and the auth adapter references it links to.

> Alpha status
>
> The CLI scaffold pins exact alpha specifiers like
>
> jsr:@netscript/plugin-auth-core@0.0.1-beta.11
>
> . Auth telemetry is real: an opt-in, redacted audit surface ships via
>
> createAuthTelemetry
>
> , enabled when a
>
> subjectHashSalt
>
> is configured. The model below is the authentication seam; for that audit surface and its salt requirement see
>
> [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/) .

## The thesis: NetScript owns the seam, not the identity provider

Most backend frameworks make a choice for you. They either bundle a session store, a password table, and a set of OAuth strategies — and you live inside their opinions forever — or they hand you nothing and you reassemble cookies, token verification, and provider redirects by hand in every project. Both extremes leak the *integration tax* NetScript exists to remove: the first couples your app to one identity vendor; the second makes you the integration.

NetScript takes the same stance on authentication that it takes on [contracts](https://rickylabs.github.io/netscript/explanation/contracts/) and [plugins](https://rickylabs.github.io/netscript/explanation/plugin-system/): the cross-cutting concern belongs to a **typed boundary the framework owns**, and the concrete provider is an adapter that plugs into that boundary. The framework defines *the shape of an authenticator* — a port — and ships several **pure backends** that satisfy it. Your application depends on the port; it never depends on GitHub, WorkOS, or better-auth directly.

The payoff is the one promise this whole design exists to keep: **you swap the provider by changing one environment variable, not your code.**

## The seam: `AuthBackendPort` and its sub-ports

The core package [`@netscript/plugin-auth-core`](https://rickylabs.github.io/netscript/capabilities/auth/) defines a single port, **`AuthBackendPort`**, that every backend must satisfy. It is not a god-interface — it is composed of small, single-responsibility **sub-ports**, so a backend implements exactly the concerns it owns and nothing more.

**AuthBackendPort — the seam every backend satisfies (from `@netscript/plugin-auth-core/ports`)**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | The backend's stable identifier — `kv-oauth`, `workos`, or `better-auth`. Used by the registry to resolve the one active backend. |
| `providers` | `AuthProviderRegistryPort` | The set of identity providers this backend understands (GitHub, Google, Okta, …). Resolves a named provider to its OAuth/OIDC configuration. |
| `sessions` | `AuthSessionStorePort` | Create, read, refresh, and revoke sessions. The mutation surface — and the one non-interactive backends decline. |
| `crypto` | `AuthSessionCryptoPort` | Signs and verifies the opaque session token. The default is a WebCrypto HMAC-SHA256 token (`createHmacSessionTokenCrypto`) — an opaque string, not a JWT you parse. |
| `principalMapper` | `AuthPrincipalMapperPort` | Maps a backend-specific identity into the framework's neutral `Principal` shape, so the rest of the app never sees vendor types. |
| `interactive?` | `InteractiveFlowPort (optional)` | The redirect-based sign-in flow: `signIn`, `handleCallback`, `getSessionId`, `signOut`. OPTIONAL — only a backend that drives its own OAuth redirect implements it. |
| `authenticate(request)` | `(AuthnRequest) => AuthnResult` | The non-interactive verify step inherited from `AuthenticatorPort`: given a request (cookie/header), return a `Principal` or a typed failure. |

Two things make this a *seam* rather than a base class. First, every member is a port — a small interface — so a backend is **composition, not inheritance**: it assembles four required sub-ports (plus one optional one) instead of subclassing framework internals. Second, the optional `interactive` member is where the whole capability matrix below comes from: a backend that owns its redirect flow provides it; a backend that delegates sign-in to a hosted page leaves it out.

> Why a port and not a base class
>
> A base class would force every backend to inherit a session store, a crypto scheme, and a flow it might not have. A
>
> port
>
> lets each backend supply only the sub-ports it owns — WorkOS brings its AuthKit sealed cookie and skips
>
> interactive
>
> entirely, while kv-oauth brings a full KV-backed session store and a real OAuth redirect. Same seam, different fills. This is the doctrine's
>
> composition over inheritance
>
> applied to identity.

## The neutral currency: `Principal` and `AuthnResult` with `scheme: "custom"`

A backend's job is to turn *its* notion of an authenticated user into *NetScript's* notion. That neutral currency lives one layer down, in [`@netscript/service`](https://rickylabs.github.io/netscript/reference/service/) under the `/auth` subpath, and it is the same authentication contract the rest of the framework already speaks — API keys, bearer tokens, trusted headers. Auth backends produce the same `Principal` shape.

```ts
// A backend never returns vendor types to your app. It returns these.

// Who the request is, in framework-neutral terms.
interface Principal {
  readonly subject: string;          // stable user id
  readonly scheme: "api-key" | "bearer" | "trusted-header" | "custom";
  readonly claims: Readonly<Record<string, unknown>>;
  // ...
}

// The result of authenticating a request: success xor typed failure.
type AuthnResult =
  | { ok: true; principal: Principal; readonly setCookies?: readonly string[] }
  | { ok: false; reason: string };
```

```ts
// Every OAuth/OIDC backend stamps its principals with scheme: "custom" —
// distinguishing an interactively-authenticated user from an api-key or
// bearer caller, while still flowing through the SAME AuthnResult seam.

const result: AuthnResult = {
  ok: true,
  principal: {
    subject: "user_01H...",
    scheme: "custom",            // <- auth adapters always use "custom"
    claims: { email: "a@b.dev", provider: "github" },
  },
  setCookies: ["__Host-ns_session=...; HttpOnly; Secure; SameSite=Lax"],
};
```

The discipline here is what makes provider-swapping real. The `principalMapper` sub-port is the *only* place a backend's vendor identity touches NetScript types; everywhere downstream — your service handlers, your contract middleware, your authorization checks — sees a `Principal` with `scheme: "custom"` and never imports a WorkOS or kv-oauth type. Change the backend and the `Principal` your code reads does not change shape.

## Three backends, three different capability matrices

The framework ships three pure backends. They satisfy the **same** `AuthBackendPort`, but they fill the **optional** `interactive` slot differently — and that single difference produces three distinct capability profiles. Only **kv-oauth** is a full interactive backend; WorkOS and better-auth are **non-interactive by design**.

**The three backends and where they diverge**

| Name | Type | Description |
| --- | --- | --- |
| `@netscript/auth-kv-oauth` | `interactive` | Drives its own OAuth/OIDC redirect flow. Full `interactive` port (`signIn`/`handleCallback`/`signOut`), KV-backed sessions with real create/refresh/revoke, refresh-on-read, default cookie `__Host-ns_session`. The default backend. Provider presets: github, google, gitlab, discord, slack, spotify, facebook, twitter, plus tenant-based auth0, okta, awsCognito, azureAd, logto, clerk. |
| `@netscript/auth-workos` | `non-interactive` | Delegates sign-in to WorkOS AuthKit's hosted flow; verifies the sealed `wos-session` cookie. NO `interactive` port. Session mutations throw `AuthBackendOperationUnsupportedError`. |
| `@netscript/auth-better-auth` | `non-interactive` | Wraps a better-auth instance over Prisma; verifies its session. NO `interactive` port. Session mutations throw `AuthBackendOperationUnsupportedError`. |

This is not a missing-feature apology — it is the seam working as intended. A hosted provider like WorkOS *owns* the sign-in page and session lifecycle; asking NetScript to also mutate that session would be wrong, so the backend declines it loudly rather than pretending. The next section explains exactly how it declines.

> What non-interactive means at runtime
>
> On a non-interactive backend (WorkOS or better-auth), the two interactive endpoints behave predictably and visibly:
>
> /api/v1/auth/signin
>
> and
>
> /api/v1/auth/callback
>
> return a typed
>
> AUTH_PROVIDER_ERROR
>
> (HTTP 502, "does not expose an interactive flow"), and any direct session mutation throws
>
> AuthBackendOperationUnsupportedError
>
> . The
>
> session
>
> ,
>
> me
>
> , and
>
> signout
>
> endpoints still work — you verify and read the session the hosted provider established. Choose kv-oauth when you want NetScript to drive the full redirect; choose WorkOS/better-auth when the provider owns sign-in and NetScript only verifies.

## The capability boundary is a typed error, not a silent gap

When a backend cannot do something its sub-port nominally exposes, it does not return `undefined`, log a warning, or no-op. It throws a **typed** `AuthBackendOperationUnsupportedError(name, op, reason)` — naming the backend, the operation, and why. This is the same fail-loud discipline the rest of the framework follows (streams helpers throw `StreamUnsupportedOperationError`; trigger `defer` throws and routes to a DLQ): an unsupported capability is a *visible, typed boundary*, never a quiet surprise in production.

```ts
// A non-interactive backend declining a session mutation. The error names
// the backend, the operation, and the reason — you find out at the call site,
// not three hops later from a malformed cookie.

const revoke = async (sessionId: string): Promise<void> => {
  throw new AuthBackendOperationUnsupportedError(
    "workos",                 // backend name
    "sessions.revoke",        // the operation
    "WorkOS AuthKit owns session lifecycle; revoke via the WorkOS dashboard or API.",
  );
};

// At the service edge, the interactive endpoints translate the same boundary
// into a typed HTTP error rather than a stack trace:
//   POST /api/v1/auth/signin  -> AUTH_PROVIDER_ERROR (502)
//   POST /api/v1/auth/callback -> AUTH_PROVIDER_ERROR (502)
```

Because the boundary is typed, you can *program against it*. A handler that wants to support both interactive and hosted backends can branch on whether `backend.interactive` is present rather than catching errors after the fact — the optionality of the port and the typed error are two views of the same fact: this backend does not own sign-in.

## One active backend — a hard v1 boundary

The unifying plugin [`@netscript/plugin-auth`](https://rickylabs.github.io/netscript/capabilities/auth/) composes **exactly one** active backend. It reads `NETSCRIPT_AUTH_BACKEND` (or `auth.backend` in appsettings), resolves it through a registry — valid values `kv-oauth` | `workos` | `better-auth`, **default `kv-oauth`** — and serves the `auth-api` oRPC service on **:8094** with five endpoints under `/api/v1/auth/`: `signin`, `callback`, `signout`, `session`, `me`.

```text
                    NETSCRIPT_AUTH_BACKEND  (default: kv-oauth)
                                 │
                                 ▼
        ┌──────────────────────────────────────────────┐
        │  @netscript/plugin-auth  (auth-api :8094)     │
        │  resolves ONE active backend from the registry│
        └──────────────────────────────────────────────┘
                                 │  exactly one of:
        ┌────────────────────────┼─────────────────────────┐
        ▼                        ▼                          ▼
  auth-kv-oauth            auth-workos              auth-better-auth
  (interactive)            (non-interactive)        (non-interactive)
  full redirect flow       verify wos-session       verify better-auth
  KV sessions              hosted AuthKit           Prisma-backed
        │                        │                          │
        └────────────── all satisfy AuthBackendPort ────────┘
                                 │
                                 ▼
                 Principal (scheme: "custom")  →  your app
```

**Single-active-backend is a deliberate v1 boundary**, not an incidental limitation. It means there is exactly one authenticator answering at a time. The following are explicitly **out of scope** for v1 — do not design against them yet:

**Out of scope in v1 (single-active-backend boundary)**

| Name | Type | Description |
| --- | --- | --- |
| `Multi-active routing` | `not supported` | You cannot run kv-oauth and WorkOS simultaneously and route requests between them. One backend is active per deployment. |
| `Cross-backend account linking` | `not supported` | There is no linking of a kv-oauth identity to a WorkOS identity. Each backend owns its own identities. |
| `Global logout` | `not supported` | No fan-out logout across backends or across a user's sessions in other backends. |
| `Historical replay / paged session mirror` | `not supported` | No replay of past auth events into a backend, and no paged mirror of every session across backends. |

Choosing one active backend keeps the model coherent: a single `Principal` source, a single session authority, and a single place to reason about who is signed in. Multi-backend identity is a hard problem (consistent logout, link reconciliation, conflicting session lifetimes); v1 declines it on purpose rather than ship a half-correct version.

## Why this seam — the design in one sentence

Everything above serves one outcome: **the provider is an implementation detail your application never imports.** Your handlers read a `Principal`; the framework owns the `AuthBackendPort`; a pure backend fills it; and which backend fills it is a registry decision driven by one environment variable.

- **Capability authors** implement a backend by satisfying sub-ports — they think about OAuth and sessions, never about how a host wires them in.
- **The plugin** composes exactly one backend and exposes a stable five-endpoint service, so the rest of the app sees a fixed surface regardless of provider.
- **Your application** depends on `Principal` / `AuthnResult` with `scheme: "custom"` — so swapping GitHub OAuth for WorkOS is an env-var change and a redeploy, not a refactor.

This is the same shape as the [plugin model](https://rickylabs.github.io/netscript/explanation/plugin-system/) (a thin integration layer over a pure capability) and the [contracts model](https://rickylabs.github.io/netscript/explanation/contracts/) (the framework owns the boundary, you own the logic) — authentication is just the identity-shaped instance of the pattern.

## Glossary

- **`AuthBackendPort`** — the seam every auth backend satisfies; composed of `providers`, `sessions`, `crypto`, `principalMapper` sub-ports plus an optional `interactive` flow. Defined in `@netscript/plugin-auth-core`.
- **`InteractiveFlowPort`** — the optional redirect flow (`signIn`/`handleCallback`/`getSessionId`/ `signOut`). Present only on **kv-oauth**; absent on WorkOS and better-auth.
- **single-active-backend** — the v1 rule that exactly one backend is active per deployment; no multi-active routing, cross-backend linking, global logout, or replay.
- **`Principal` / `scheme: "custom"`** — the framework-neutral identity from [`@netscript/service`](https://rickylabs.github.io/netscript/reference/service/)`/auth`; auth adapters stamp principals with `scheme: "custom"`.
- **`AuthBackendOperationUnsupportedError`** — the typed error a backend throws when an operation is outside its capability matrix (for example session mutation on a non-interactive backend).
- **opaque session token** — the default WebCrypto HMAC-SHA256 token (`createHmacSessionTokenCrypto`); an opaque string you do not parse, not a JWT.

## Where to go next

- **The capability:** [Authentication](https://rickylabs.github.io/netscript/capabilities/auth/) — the headline API, the `auth-api` service on :8094, the five endpoints, and the backend matrix at a glance.
- **Do it:** [Add authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/) — add the `auth` plugin, choose a backend with `NETSCRIPT_AUTH_BACKEND`, run the migration, and wire provider env.
- **Related model:** [The plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/) — why a thin plugin composes a pure capability, the same shape this auth seam follows.
- **Reference:** the neutral authentication contract lives in [`reference/service/`](https://rickylabs.github.io/netscript/reference/service/) (the `/auth` subpath: `Principal`, `AuthnResult`, `AuthenticatorPort`).

[The plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/) [Durability model](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/)

_Canonical: https://rickylabs.github.io/netscript/explanation/auth-model/_

---

# Contracts & type flow

This page explains *why* NetScript is contracts-first and *how* a single type definition travels from a contract, through a service handler, all the way to a typed client and a UI island — with no second source of truth and no code-generation step to drift. It is understanding-oriented: read it to build a mental model. When you want exact signatures, follow the links to [`reference/contracts/`](https://rickylabs.github.io/netscript/reference/contracts/) and [`reference/service/`](https://rickylabs.github.io/netscript/reference/service/); when you want to build the thing, follow the [capability hub for services](https://rickylabs.github.io/netscript/capabilities/services/) or the [Build a service tutorial](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/).

## The thesis: the contract is the product

Most backend stacks have *two* sources of truth for the boundary between a server and its callers: the server's runtime validation, and a separately-maintained client (a generated SDK, a hand-written `fetch` wrapper, an OpenAPI document, a GraphQL schema). The two drift. You change the server, forget the client, and the mismatch surfaces at runtime — in production, as a 500 or a silently-wrong field — instead of at your desk, as a red squiggle.

NetScript removes the second source of truth. A **contract** is one TypeScript value that declares a route's method, its input shape, and its output shape. The server *implements* that exact value; the client is *derived* from that exact value. There is nothing to regenerate and nothing to keep in sync, because there is only ever one definition. The contract is not documentation about the boundary — it **is** the boundary.

> One definition, enforced three ways
>
> The same contract value is consumed by
>
> zod
>
> (runtime input/output validation), by the
>
> TypeScript
>
> type checker (compile-time shape checking on both sides), and by the OpenAPI generator (the published spec). Change the contract and all three move together — there is no path where one lags behind.

## What a contract actually is

A contract is built from [`@orpc/contract`](https://orpc.unnoq.com) plus [`zod`](https://zod.dev). `oc.route({ method })` declares the transport verb; `.input(...)` and `.output(...)` attach zod schemas that describe the request and response. The result is an inert *definition* — it owns no handler, opens no socket, and does no runtime work. It is pure shape. That inertness is the point: because a contract performs no side effects, it can be imported anywhere — by the server, by the client, by a test, by a codegen-free tool — without dragging runtime behavior along with it.

```ts
import { z } from 'zod';
import { oc } from '@orpc/contract';
import { implement } from '@orpc/server';

// 1. zod schemas describe the data — the single shape definition.
export const UsersListItemSchemaV1 = z.object({
  id: z.number().int().positive(),
  name: z.string().min(1),
  summary: z.string().min(1),
  status: UsersStatusSchemaV1,
  createdAt: z.string().datetime(),
});

// 2. The contract binds method + input + output. No handler yet.
export const UsersContractV1 = {
  health: {
    check: oc.route({ method: 'GET' })
      .input(z.object({}).optional())
      .output(UsersHealthSchemaV1),
  },
  list: oc.route({ method: 'POST' })
    .input(UsersListInputSchemaV1)
    .output(UsersListResponseSchemaV1),
  updateStatus: oc.route({ method: 'POST' })
    .input(UsersUpdateStatusInputSchemaV1)
    .output(UsersUpdateStatusResponseSchemaV1),
};

// 3. implement() turns the contract into a .handler()-bindable object.
export const UsersV1 = implement(UsersContractV1);
```

```text
schema  ->  contract  ->  implement()  ->  handler  ->  client
  |          |             |              |          |
 zod      oc.route     binds the      your code    derived,
 shape    (verb +      contract to      runs       not written
          io)         a server obj   the logic     by hand

Everything downstream is TYPED FROM step 1. You define the
shape once; the compiler propagates it to every consumer.
```

The contract version above lives under `contracts/versions/v1/` and is exported through the workspace's `@<project>/contracts` alias (for the scaffolded `users` example, that is `@my-app/contracts`). Versioning the contract directory — `versions/v1/`, later `v2/` — is deliberate: a contract is a long-lived promise, so its breaking changes are an explicit new version rather than an in-place mutation that silently breaks callers.

> zod is the shape; oRPC is the boundary
>
> A useful split to hold in your head:
>
> zod
>
> answers
>
> "what does this data look like, and is a given value valid?"
>
> , while
>
> oRPC
>
> (
>
> @orpc/contract
>
> ) answers
>
> "which route, which verb, what goes in, what comes out?"
>
> . The contract is where the two meet — an
>
> oc.route(...)
>
> wrapping zod schemas in
>
> .input()
>
> /
>
> .output()
>
> . Neither library knows about the other's transport or persistence; together they describe the whole boundary and nothing else.

## `implement()`: from shape to a bindable server object

`implement()` (from `@orpc/server`) is the hinge between the *definition* and the *runtime*. Given a contract, it returns an object whose every route exposes a `.handler(...)` method. The handler you pass in is type-locked to the contract: its argument is the contract's `input` type, and its return value must satisfy the contract's `output` type. You cannot return the wrong shape — it will not compile.

```ts
import { type UsersListItemV1, v1 } from '@my-app/contracts';

// `input` is typed from the contract's .input() schema.
// The returned object is checked against the .output() schema.
export const UsersV1 = {
  list: v1.users.list.handler(async ({ input }) => {
    // `input` is fully typed. The compiler knows its fields.
    // Returns seeded in-memory records at this scaffold step (no DB yet).
    return { items: seededUsers, pagination: { total: seededUsers.length } };
  }),
  updateStatus: v1.users.updateStatus.handler(async ({ input }) => {
    // mutate + return a value the contract's output schema accepts
    return { updated: true, id: input.id, status: input.status };
  }),
};
```

```ts
// The router aggregates versioned handler objects into one tree.
import { UsersV1 } from './routers/v1.ts';
import { health } from './routers/health.ts';

export const v1 = { users: { ...UsersV1, health } };
export const router = { v1 };
```

> The handler is the only place you write logic
>
> Notice what the handler does
>
> not
>
> do: it never parses the request body, never validates input, never serializes the response by hand, never declares a route string. The contract already specified all of that.
>
> implement()
>
> wires zod validation around your function automatically, so the handler body is pure business logic over already-typed, already-validated data.

The router tree mirrors the contract tree. Because the contract is a plain nested object — `{ v1: { users: { list, updateStatus, health } } }` — the handlers nest the same way, and the derived client later walks the *same* path (`client.users.list(...)`). There is no separate routing table to register, no decorator to remember, and no string key that can fall out of sync with the handler it names. The shape of your API *is* the shape of these objects.

## Serving the router: where the contract meets HTTP

A local service hands the router to `defineService(...)`, which wires CORS, request logging, OpenAPI, RPC, and health endpoints in one call and binds a port. The contract's shapes become the service's validation and its published OpenAPI document at the same time — one definition, two artifacts.

```ts
import { defineService } from '@netscript/service';
import { router } from './router.ts';

await defineService(router, {
  name: 'users',
  version: '1.0.0',
  port: parseInt(Deno.env.get('PORT') || '3001'),
  openapi: { title: 'Users API', description: 'users service' },
  debug: true,
});
// Serves /api/v1/users/* (OpenAPI) and /api/rpc/v1/... (typed RPC) on :3001.
```

Aspire injects `PORT` at runtime, so the entrypoint reads it from the environment; the typed source of truth is your `netscript.config.ts` `services.<name>.port` field, which the scaffold wires as the fallback default — set the port there rather than editing this line.

The `users` service listens on **port 3001** and exposes two parallel transports from the same contract: REST-shaped routes under `/api/v1/users/*` (driven by `oc.route({ method, path })` and surfaced in OpenAPI) and a typed RPC channel under `/api/rpc/v1/...` that the derived client speaks. Both are the *same* contract; the difference is only the wire format. The RPC mount point is `/api/rpc/*` — not `/rpc` — and the derived client is configured to target exactly that base, so you rarely type the path yourself; it follows from the contract and the service options.

> Two service-construction APIs in one project
>
> Local services in
>
> services/
>
> use the one-shot
>
> defineService(router, options)
>
> form above. The framework's
>
> plugin
>
> API services (workers, sagas, triggers, auth) use a fluent builder instead —
>
> createService(router, options).withCors().withLogger().withOpenAPI(...).withDocs().withRPC(...).withHealth().serve()
>
> . Same contracts-first model underneath; the builder simply exposes each cross-cutting concern as an explicit, composable step. Reach for
>
> defineService
>
> when the defaults are what you want, and the builder when you need to add, remove, or reorder a concern. See
>
> the services capability
>
> .

## The type pipeline, end to end (a diagram in prose)

Here is the whole journey of a single field — say `status` on a user — from where it is born to where it is consumed, with no manual duplication at any hop:

```text
  zod schema                contract                 server                    client / UI
 ───────────              ───────────              ──────────                ───────────────

 UsersStatusSchemaV1  ──>  oc.route({ POST })  ──>  implement(contract)  ──>  derived RPC client
   z.enum([...])            .input(InputV1)          .handler(({input}) =>     await client.users
                            .output(ResponseV1)        ...)  // typed in        .list(args)
       │                         │                       │     and out             │
       │   defines the shape     │   binds verb + io      │  runs your logic        │  args + result
       ▼                         ▼                       ▼   over typed data        ▼   are TYPED from
   one definition          one boundary            one implementation         the SAME schema —
                                                                              no codegen, no drift
```

Read it left to right. The `status` field is declared once, in a zod schema. The contract references that schema in its `.input()`/`.output()`. `implement()` produces a server object whose handler sees `status` as a typed field on `input` and must return it correctly in the output. The client — derived from the very same contract value — exposes `client.users.list(...)` whose argument type and result type are both projected straight from those schemas. A UI island that calls the client (optionally through `@orpc/tanstack-query`) inherits those types yet again.

Crucially, no arrow in that diagram is a *copy*. Each hop is a *projection* of the previous one — TypeScript reading the contract's types, oRPC reading the contract's routes, zod reading the contract's schemas. Because every consumer reads from the same value rather than from a duplicated declaration, there is no place for the two to disagree. The contract is the only thing anyone authored by hand; everything to its right is inferred.

Change `UsersStatusSchemaV1` and the ripple is immediate and compile-time: the handler that returns the old shape stops compiling, every client call site that reads the removed field stops compiling, and the OpenAPI document regenerates. **The type checker becomes your integration test.** That is the entire payoff of contracts-first: integration bugs that other stacks discover at runtime, NetScript discovers at build time, because there was never a second copy to fall out of step.

**What flows through the pipeline — and what never needs hand-syncing**

| Name | Type | Description |
| --- | --- | --- |
| `input / output shapes` | `zod schema` | Declared once. Validated at runtime by implement(), checked at compile time on both server and client. |
| `route verb + path` | `oc.route({ method, path })` | Declared on the contract. Drives the OpenAPI document and the REST routes; never re-declared in the handler. |
| `handler argument` | `{ input }` | Typed from the contract's .input() schema. The handler body operates on already-validated data. |
| `handler return` | `output type` | Must satisfy the contract's .output() schema or it fails to compile. No hand-written serialization. |
| `typed client` | `derived from contract` | Not generated, not written by hand. Argument and result types are projected from the same contract value. |
| `OpenAPI document` | `emitted by defineService` | Produced from the contract — a published spec that cannot drift from the running server. |

## Why this design, and what it costs

The trade-offs, because contracts-first is an opinion, not a free lunch:

- **You write the schema first.** For a trivial one-off endpoint, declaring a zod schema before writing the handler feels like ceremony. The payoff arrives the moment a *second* consumer exists (a client, a UI, another service) — which for a real backend is immediately.
- **Versioning is explicit, not automatic.** A breaking change to a shape is a new contract version (`versions/v2/`), not an in-place edit. This is deliberate friction: it forces you to decide whether callers can migrate, rather than breaking them silently.
- **The boundary is the contract, not the database.** At the early scaffold step the `users` handlers return seeded in-memory records — the contract is proven end to end *before* a database is wired. Persistence is a later concern that slots in behind an unchanged contract.
- **zod is the runtime price.** Validation runs on every request. That is a deliberate cost: it is also the thing that makes the published OpenAPI document and the compile-time types trustworthy, because the wire is checked against the same shape the types describe.

The oRPC family (`@orpc/contract`, `@orpc/server`, `@orpc/client`, `@orpc/zod`, `@orpc/tanstack-query`) at `^1.14.6` is pinned in the workspace catalog. `zod` (`jsr:@zod/zod@4.4.3`) is pinned per-package in each member's imports section, not in the catalog. So the contract surface stays consistent across every workspace member.

## How contracts-first shows up across the framework

The contract is not just a service idea — it is the *unifying* idea. The same model that types a service's RPC channel also types the plugin boundaries you compose into a NetScript app:

- **Services** are the canonical case on this page — a contract, an `implement()`-bound router, and a `defineService`/`createService` host. See [the services capability](https://rickylabs.github.io/netscript/capabilities/services/).
- **Workers and sagas** expose their own oRPC services built from contracts, served via the fluent `createService(...).serve()` builder, so dispatching a job or driving a saga is a typed client call rather than a hand-rolled `fetch`. See [background jobs](https://rickylabs.github.io/netscript/capabilities/background-jobs/) and [durable sagas](https://rickylabs.github.io/netscript/capabilities/durable-sagas/).
- **Triggers** also serve a typed v1 oRPC contract — for trigger and event introspection plus management (fire, enable/disable, schedule preview, SSE event subscription) — like workers and sagas. Their exception is narrower: the *webhook ingress endpoint* itself (`POST /api/v1/webhooks/:triggerId`) stays a *raw*, signature-verifying route rather than an oRPC procedure, because it verifies an HMAC over the raw request bytes from external senders whose shapes you do not control. That asymmetry is itself instructive — contracts-first is for boundaries you *own*; an inbound webhook is a boundary someone else owns. See [the plugin model](https://rickylabs.github.io/netscript/explanation/plugin-system/).

Holding those together: the contract is how NetScript makes the *internal* surfaces of a system type-safe end to end, and the framework is explicit about where that model stops.

## Glossary

- **Contract** — a single typed value declaring a route's method, input shape, and output shape. The boundary between a server and its callers, and the single source of truth for that boundary. See the [glossary](https://rickylabs.github.io/netscript/glossary/#contract).
- **oRPC** — the contract-and-RPC library NetScript builds the boundary on (`@orpc/*`). It supplies `oc.route(...)`, `implement(...)`, and the derived typed client. See the [glossary](https://rickylabs.github.io/netscript/glossary/#orpc).
- **zod** — the schema library that describes and validates each shape. It is the runtime half of the contract; oRPC is the routing half. See the [glossary](https://rickylabs.github.io/netscript/glossary/#zod).

## Where to go next

- **Do it:** the [Build a service tutorial](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/) walks the contract → service → typed client → island path with this exact `users` example.
- **Hub:** the [services capability](https://rickylabs.github.io/netscript/capabilities/services/) covers `defineService` versus the fluent `createService(...).serve()` builder and the real ports.
- **Architecture:** [the architecture overview](https://rickylabs.github.io/netscript/explanation/architecture/) places contracts in the larger picture, and [the plugin model](https://rickylabs.github.io/netscript/explanation/plugin-system/) shows how plugins reuse the same contracts-first seam.
- **Reference:** the exact exported symbols live in [`reference/contracts/`](https://rickylabs.github.io/netscript/reference/contracts/) and [`reference/service/`](https://rickylabs.github.io/netscript/reference/service/).

[Architecture](https://rickylabs.github.io/netscript/netscript/explanation/architecture/) [The plugin system](https://rickylabs.github.io/netscript/netscript/explanation/plugin-system/)

_Canonical: https://rickylabs.github.io/netscript/explanation/contracts/_

---

# Durability model

*This essay is the **why** — the model and its trade-offs. The day-to-day *how* (guides, recipes, API) lives in **Build › [Durable workflows](https://rickylabs.github.io/netscript/durable-workflows/)**.*

This essay is **understanding-oriented**. It answers one question: *how does NetScript make long-running, message-driven work survive a process restart?* It builds the mental model — what a saga is, how its state is persisted, where that state physically lives, and how compensation and correlation fit — so you can reason about the running system. It is not a step-by-step guide. When you want to build a durable workflow with your own hands, follow the [durable workflow tutorial](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/); for the headline API and ports see

[Durable sagas](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/) ; for the exact exported symbols see

[sagas](https://rickylabs.github.io/netscript/netscript/reference/sagas/) .

![A saga as a persisted state machine: an inbound message is routed by correlation id to the right instance, the runtime loads its state from the durable store, the matching handler advances the state and returns effects, and the new state is written back.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/saga-state-machine.svg)

*A saga is a persisted state machine. Messages drive transitions; the runtime loads state by correlation, applies the matching handler, and writes the new state back to the durable store.*

> What is live today
>
> The saga builder, its persisted state model, the message-handler effects, and the
>
> durable store
>
> behind them are all
>
> implemented and they compile
>
> — the scaffold ships a working
>
> defineSaga(...)
>
> sample, a registry API at
>
> :8092
>
> , and a durable runtime that persists every transition to either
>
> Deno KV
>
> or
>
> Prisma/Postgres
>
> . Two builder methods are reserved:
>
> .onSignal(...)
>
> and
>
> .onQuery(...)
>
> compile and register, but their runtime dispatch is explicitly deferred (the doc comments say so) — do not design around live signal/query routing yet. Neither caveat touches the core saga durability described here.

## What "durable" actually means here

A plain request handler is **ephemeral**: it runs, returns, and forgets. If the process restarts halfway through a multi-step business process — provision an account, charge a card, send a welcome email — everything in memory is gone and there is no record of how far you got. Durability is the property that lets a *logical* workflow outlive any *single* execution: its progress is written down somewhere external to the process, so a restart, a retry, or a later message can pick up exactly where the last one left off.

NetScript draws the durability boundary at the **saga**. A saga is a small, named state machine whose state is persisted and whose transitions are driven by **messages** rather than by a callable returning to its caller. Because the state lives outside the process and the inputs arrive as messages over time, a saga can span minutes, hours, or many process lifetimes — that is what the word *durable* buys you. This is doctrine axiom A12 in practice: *durable workflows are state machines*, not long-lived call stacks. See [Architecture](https://rickylabs.github.io/netscript/netscript/explanation/architecture/) for how that axiom shapes the whole framework.

> Durability is about the state, not the speed
>
> Durability does not mean "slow" or "queued forever". It means the workflow's
>
> position
>
> — which step it is on and what it has accumulated so far — is recorded outside the handler, so the workflow is correct even when the runtime is not continuous. A saga that completes in one message is still durable; it just had one transition.

## The saga builder: a state machine you declare, not wire

A saga is authored with a **fluent builder**. You declare an id, a durability tier, the shape and initial value of its state, and one or more message handlers, then call `.build()` to freeze it into a definition the runtime can register and run.

```ts
// plugins/sagas/<saga>.ts  — the scaffolded shape, verbatim core
import { defineSaga, sagaComplete } from '@netscript/plugin-sagas-core';

type State = Readonly<{ status: string; processedAt?: string }>;
type Message = Readonly<{ type: 'UserSettingsCreated'; payload: { userId: string } }>;

export const userOnboardingSaga = defineSaga('user-onboarding')
  .durability('t1')
  .state<State>({ status: 'pending' })
  .on<Message['type'], Message['payload']>(
    'UserSettingsCreated',
    (saga, message, context) => {
      saga.state = {
        ...saga.state,
        status: 'completed',
        processedAt: context.now.toISOString(),
      };
      return [sagaComplete({ messageType: message.type, processedAt: context.now.toISOString() })];
    },
  )
  .build();

export default userOnboardingSaga;
```

Each call in the chain has a precise job:

**The defineSaga(...) builder chain**

| Name | Type | Description |
| --- | --- | --- |
| `defineSaga(id)` | `(id: string) => SagaBuilder` | Opens the builder and names the saga. The id is the registry key and shows up at GET /api/v1/sagas/sagas. |
| `.durability(tier)` | `(tier: 't1' \| 't2' \| 't3') => SagaBuilder` | Declares the saga-definition durability TIER — how aggressively the runtime should persist this saga. Defaults to t1. This is a property of the definition, distinct from which physical store (kv or prisma) the runtime writes to. |
| `.state(initial)` | `(initial: S) => SagaBuilder` | Declares the persisted state shape and its initial value. This object is what survives across messages and restarts. Must precede any handler. |
| `.on(type, handler)` | `(type, (saga, msg, ctx) => Effect[]) => SagaBuilder` | Registers a transition for one message type. The handler mutates saga.state and returns an array of effects (for example sagaComplete(...)). |
| `.compensate(type, handler)` | `(type, (saga, msg, ctx) => Effect[]) => SagaBuilder` | Registers a compensation handler for a FAILED event type — the first-class rollback hook (see below). Same handler shape as .on(...). |
| `.build()` | `() => SagaDefinition` | Freezes the chain into a SagaDefinition after at least one handler exists. Nothing runs until build() and registration. |

The builder surface is wider than the scaffold sample shows. Alongside the core methods above it also exposes `.correlate(...)` (a custom correlation extractor), `.concurrency(...)` (bounded, optionally per-message-key concurrency), and `.schedule(cron)` (a cron schedule on the definition), plus the two reserved hooks `.onSignal(...)` and `.onQuery(...)`. Reach for the reference unit when you need the full surface — this essay sticks to the load-bearing concepts.

The mental model to hold: **`defineSaga(...).durability(...).state(...).on(...).build()` is a declaration of a persisted state machine.** You are not writing imperative control flow that falls off the end of a callable — you are describing *which messages move the workflow* and *what state each move leaves behind*.

> Why state lives on `saga.state`
>
> The handler receives the live
>
> saga
>
> object and mutates
>
> saga.state
>
> in place, then returns effects. Keeping state on the saga rather than in handler-local variables is exactly what makes it
>
> durable
>
> : the runtime owns that object, persists it to the configured durable store, and rehydrates it before the next matching message. A local variable would vanish;
>
> saga.state
>
> does not.

## Durability tiers: how hard to persist

`.durability(tier)` takes one of three tiers — `t1`, `t2`, `t3` — and defaults to `t1`. The tier is the saga *definition's* contract for how aggressively the runtime should persist it; it is a separate axis from *which* physical store the writes land in. Hold the two apart: the tier travels with the definition, the store backend is chosen once for the whole runtime. The same `t1` saga runs unchanged whether its state is written to Deno KV or to Postgres — you never re-author a saga to change where it persists.

## Where the state physically lives: the durable store

The builder describes *what* to persist. The **durable saga store** is *where* it goes. NetScript ships two interchangeable backends, and the runtime persists every transition to exactly one of them, chosen at startup:

**Durable saga store backends — NETSCRIPT_SAGA_STORE**

| Name | Type | Description |
| --- | --- | --- |
| `kv` | `KvSagaStore` | Persists saga runtime state to Deno KV. The default scaffold backend — zero external dependencies, ideal for local development and KV-native deployments. |
| `prisma` | `PrismaSagaStore` | Persists saga runtime state through a host-owned Prisma client into your scaffolded relational database (Postgres in the recommended setup; mysql / mssql / sqlite all work — the store follows your Prisma client, it is not Postgres-specific), across three saga_runtime_* tables. Choose this when you want saga state in your relational store alongside the rest of your data. Requires a Prisma client at construction. |

You select the backend explicitly — it is **mandatory**, and the runtime throws at startup if neither source provides it (`Saga store backend is required. Set NETSCRIPT_SAGA_STORE=kv|prisma …`). Two equivalent switches:

- **Environment:** `NETSCRIPT_SAGA_STORE=kv` or `NETSCRIPT_SAGA_STORE=prisma`.
- **App settings:** `sagas.store.backend: "kv" | "prisma"`.

The composition root is `createDurableSagaRuntime(...)`, exported from the `@netscript/plugin-sagas/runtime` subpath. When you ask for the Prisma backend you must hand it a client; the KV backend can take a `Deno.Kv` (or open the default):

```ts
// composition root — pick the backend once, at startup
import { createDurableSagaRuntime } from '@netscript/plugin-sagas/runtime';

const { runtime, store, dispose } = await createDurableSagaRuntime({
  backend: 'prisma',     // or 'kv'
  prisma: prismaClient,  // pass when backend === 'prisma'
});
// `runtime` registers SagaDefinitions and applies messages;
// `store` is the KvSagaStore or PrismaSagaStore instance; `dispose` releases it.
```

> Two axes: tier vs store backend
>
> Keep these apart in your head. The
>
> durability tier
>
> —
>
> .durability('t1')
>
> on the builder — is a property of the saga
>
> definition
>
> describing how aggressively the runtime should persist it. The
>
> store backend
>
> —
>
> kv
>
> or
>
> prisma
>
> — is the physical place those persisted writes land, chosen once at the composition root for the whole runtime. Switching stores is a deployment decision, not a code rewrite.

### Choosing kv vs prisma

Both backends implement the same `SagaStorePort`, so the choice is operational, not behavioural:

- **`kv` (default).** Zero external dependencies — state lives in Deno KV. Lowest-friction for local development and for deployments that are already KV-native. This is what the scaffold uses out of the box, so a fresh project is durable with nothing else running.
- **`prisma`.** Routes the durable write path into your relational database — Postgres in the recommended setup, or `mysql` / `mssql` / `sqlite` if that is what you scaffolded with `--db` (the store writes through your Prisma client, so it is not tied to Postgres). Pick it when you already operate that database (the [Database & Prisma](https://rickylabs.github.io/netscript/netscript/data-persistence/database/) stack and Aspire bring one up) and want saga state queryable alongside the rest of your relational data — at the cost of a running database and a Prisma client to hand the store at construction.

### How the Prisma store maps the runtime

The `PrismaSagaStore` is a thin delegate over a host-owned Prisma client. The durable *write path* spans three `saga_runtime_*` tables, each capturing one facet of the persisted machine:

**Prisma durable write-path models**

| Name | Type | Description |
| --- | --- | --- |
| `SagaRuntimeState` | `saga_runtime_state` | The current persisted state object for an instance — the durable 'position' the runtime rehydrates before the next message. |
| `SagaRuntimeTransition` | `saga_runtime_transition` | The applied transitions, keyed by instance and version, so the durable workflow's history is recorded — not just its latest snapshot. |
| `SagaRuntimeCorrelation` | `saga_runtime_correlation` | The correlation index that maps a saga id plus correlation key back to its instance — how the runtime finds the right state to load. |

This is deliberately distinct from the read-model `SagaInstance` table (`saga_instances`) that backs the listing API. The `saga_runtime_*` tables are the **durability mechanism**; `SagaInstance` is a projection used to *display* instances. Choosing the `prisma` backend opts the durable write path into Postgres; the `kv` backend keeps the same logical structure in Deno KV instead.

## Compensation: two shapes

If you have used other orchestration frameworks, you may expect a saga to be a list of forward steps each paired with a rollback. NetScript supports compensation in **two** shapes, and it is worth knowing which one you are looking at.

**Shape 1 — compensation as an effect (what the scaffold ships).** A saga handler **returns an array of effects**. `sagaComplete({...})` is one such effect — it signals the workflow reached a terminal, successful state. In this shape, corrective actions are expressed the same way: as additional effects a message handler returns, interpreted by the runtime, rather than as a separate rollback chain registered up front. The scaffolded sample uses exactly this model, which is why its handler's last line is `return [sagaComplete({...})]`.

**Shape 2 — compensation as a first-class builder hook.** The `SagaBuilder` *also* exposes a `.compensate(eventType, handler)` method — "register a compensation handler for a failed event type". It takes the same `(saga, message, context) => Effect[]` handler shape as `.on(...)`, but the runtime invokes it on the failure path for that event rather than the forward path. So if you want an explicit, named rollback per event type, the hook is there.

> Which shape should you reach for?
>
> Both are real. The
>
> effect-array
>
> shape (Shape 1) is the scaffold's default and the simplest mental model — corrective actions are just more values your handler returns. Reach for
>
> .compensate(...)
>
> (Shape 2) when you want an
>
> explicit
>
> rollback handler bound to a specific failed event type, separate from the forward
>
> .on(...)
>
> transition. They are not mutually exclusive — a saga can use forward effects and register compensations for the events that need them.

## Correlation: how one saga instance finds its messages

A saga *definition* is a template; a running workflow is a saga *instance*. Many onboarding flows can be in flight at once, so the runtime keys instances by a **correlation id** and exposes them through the registry API. The registry stores saga metadata in Deno KV, and the API service lists definitions and live instances:

**Sagas API — registry and instances (port :8092)**

| Name | Type | Description |
| --- | --- | --- |
| `GET /api/v1/sagas/sagas` | `list definitions` | Every registered saga definition and its handled message types — this is where your built saga shows up. |
| `GET /api/v1/sagas/instances` | `list instances` | Live saga instances. Each instance carries its own persisted state. |
| `GET /api/v1/sagas/instances/{sagaName}/{correlationId}` | `single instance` | One instance addressed by saga name plus correlation id — the durable position of one workflow. |
| `POST /api/v1/sagas/publish` | `publish a message` | Hand a message to the saga runtime, which routes it to the matching handler on the correct instance. |
| `GET /health/live` | `liveness` | The sagas service liveness probe. |

The thing to internalize: a saga's identity (`id`, set via the builder) plus a correlation id is what lets the durable state survive being put down and picked back up. The runtime does not keep your workflow in memory; it looks the instance up by correlation, loads its state from the configured store, applies the message, and writes the new state back. By default the correlation key comes from the message; `.correlate(...)` lets a definition extract it differently.

## The worked example: three capabilities, one durable workflow

Durability becomes interesting when capabilities **compose**. The scaffold ships exactly this choreography, and it is the same continuous app the [tutorials](https://rickylabs.github.io/netscript/tutorials/) build rung by rung. Follow one user-onboarding flow through three plugins:

```text
  Inbound HTTP                Background job              Durable saga
  (triggers :8093)            (workers :8091)            (sagas :8092)
  ────────────────           ────────────────           ────────────────
  POST /api/v1/webhooks ───▶  create-user-settings ───▶  user-onboarding
  /inbound/generic            job runs:                  saga handles:
       │                      publishes                  'UserSettingsCreated'
  enqueueJob(jobRef)          UserSettingsCreated         │
       │                           │                      returns
       ▼                           ▼                      [ sagaComplete({...}) ]
  worker job enqueued        saga message published      workflow terminal
                                                          (state persisted to
                                                           kv | prisma store)
```

Step by step, in the real code:

1. **A trigger turns an inbound webhook into a job.** The triggers plugin exposes raw Hono routes (not oRPC). The webhook handler returns an array of `enqueueJob(jobRef, { payload, priority })` effects, so a `POST` to `:8093/api/v1/webhooks/inbound/generic` enqueues a worker job — the *ingress* of the durable flow. (`enqueueJob` is the one live trigger action; the `defer` action is defined but unsupported — it throws and routes to the DLQ, so do not build on deferred replay.) See [Triggers & ingress](https://rickylabs.github.io/netscript/netscript/durable-workflows/triggers/) .
2. **A worker job publishes the saga message.** The workers plugin's `create-user-settings` sample is an ordinary `defineJobHandler(async (ctx) => ...)` that, on success, **publishes the `UserSettingsCreated` message** via a saga publisher. The job is the *unit of work*; publishing the message is how it hands control to the durable layer. See [Background jobs](https://rickylabs.github.io/netscript/netscript/background-processing/workers/) .
3. **A saga consumes the message and emits `sagaComplete`.** The sagas plugin registers `userOnboardingSaga`, whose `.on('UserSettingsCreated', ...)` handler mutates `saga.state` and returns `[ sagaComplete({...}) ]`. That terminal effect is the durable workflow finishing — and the new state is written to whichever store (`kv` or `prisma`) the runtime was configured with.

```ts
// workers/jobs/create-user-settings.ts — the publish step, verbatim core
import { createSagaPublisher } from '@netscript/plugin-sagas/runtime';
import { createSuccessResult, defineJobHandler } from '@netscript/plugin-workers-core';
import { z } from 'zod';

type UserRegistrationMessage = {
  type: 'UserSettingsCreated';
  payload: { userId: string };
};

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

const handler = defineJobHandler(async (ctx) => {
  const { userId } = CreateUserSettingsPayloadSchema.parse(ctx.payload ?? {});
  await sagaPublisher.publish({ type: 'UserSettingsCreated', payload: { userId } });
  return createSuccessResult({ userId, settingsCreated: true, source: 'scaffold-sample' });
});

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

> Why split a job from a saga at all?
>
> The
>
> job
>
> does the discrete, retryable unit of work (parse the payload, write a record, call an API) and reports success or failure. The
>
> saga
>
> owns the
>
> long-lived position
>
> across many such messages. Splitting them means a transient job failure can be retried without losing the workflow's accumulated state, and the same saga can react to messages published by several different jobs. Composition, not a single mega-handler, is what keeps each piece small and durable.

## What a crash actually preserves

Concretely, when the process dies mid-workflow:

- **Persisted (survives):** the instance's `saga.state` (its `SagaRuntimeState` / KV equivalent), the applied transitions, and the correlation index. On restart the runtime can find the instance by correlation and rehydrate its exact position.
- **Not preserved (by design):** anything held only in handler-local variables or in-process memory. That is the whole point of moving state onto `saga.state` — local closures are *expected* to be lost, and the durable store is what stands in for them.
- **Idempotency:** the runtime carries an applied-key boundary (`SagaAppliedKeyStore`) so that a redelivered message does not double-apply a transition — important because at-least-once delivery means the same message can arrive twice across a restart.

## Limitations (alpha)

The durability story is real but young, and a few edges are worth naming so you do not over-trust it:

- **Reserved builder hooks.** `.onSignal(...)` and `.onQuery(...)` compile and register, but their runtime dispatch is explicitly deferred. Treat them as forward-declared surface, not live features.
- **Trigger `defer` is unsupported.** The `defer` trigger action throws and routes to the DLQ — only `enqueueJob` is a live ingress for durable flows today.
- **Two stores, same port, different operational maturity.** `kv` is the path the scaffold and tests exercise most; `prisma` is real and tested but assumes you bring and manage the Postgres + Prisma client yourself.

None of these undermine the core guarantee — a built `defineSaga(...)` survives restarts on either store — but they shape what you should and should not design around right now.

## Why the model looks like this — the design trade-offs

The message-and-state shape is a deliberate set of trade-offs:

- **Persisted state over in-memory closures.** Putting the workflow's position on `saga.state` and persisting it to a durable store is what survives restarts. The cost is that you think in transitions, not in straight-line code; the benefit is correctness across process lifetimes.
- **A pluggable store over a hard-wired backend.** Pulling the persistence behind a single `KvSagaStore` / `PrismaSagaStore` seam — selected by one explicit setting — lets the same saga run on Deno KV in development and on Postgres in production without touching the workflow. The cost is the one mandatory choice at startup; the benefit is that durability is a deployment decision, not a code rewrite.
- **Effects over imperative side-effects.** Returning `sagaComplete({...})` (and other effects) instead of calling out directly keeps handlers replayable. The runtime decides *when* and *how* effects apply, which is what makes retries and compensation tractable.
- **Composition over a workflow monolith.** Trigger → job → saga are three small capabilities wired by messages. Each can be added, tested, and scaled independently, and the

[plugin model](https://rickylabs.github.io/netscript/netscript/explanation/architecture/) is what lets a host assemble them without editing host code.

## How this connects to the rest of NetScript

A durable workflow is not an island. It rides on top of the same primitives you have already met or will meet:

- It is delivered as **plugins** — workers, sagas, triggers — through the plugin model's contribution/registry mechanism.
- Its messages and effects are **observable**: job dispatch and execution emit real OpenTelemetry spans that show up in Aspire automatically. See [observability](https://rickylabs.github.io/netscript/explanation/observability/) for the full picture — including the one known gap (the scaffold `createJobTools(ctx)` handler helpers are no-op stubs, a tracked limitation; call `@netscript/telemetry` helpers directly for custom spans).
- Its API surfaces (`:8091`, `:8092`, `:8093`) and the Postgres/Redis backing store — including the Postgres tables behind the `prisma` saga store — are brought up by Aspire. Remember the ordering: `cd aspire && aspire start` is what makes the durable infrastructure available **before** any `netscript db` command. See [KV, queues & cron](https://rickylabs.github.io/netscript/netscript/data-persistence/kv-queues-cron/) for the KV/queue primitives the runtime leans on, and [Durable streams](https://rickylabs.github.io/netscript/netscript/durable-workflows/streams/) for the streaming counterpart to message-driven sagas.

## Where to go next

- **Do it:** [Build a durable workflow](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/) — the hands-on tutorial that adds the saga and consumes `UserSettingsCreated` end to end.
- **See the capability:** [Durable sagas](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/) — the headline `defineSaga` API, the `:8092` endpoints, the `kv | prisma` store switch, and the Learn / Do / Reference triplet.
- **Look it up:** [sagas](https://rickylabs.github.io/netscript/netscript/reference/sagas/) for the full generated API surface, and

[queue](https://rickylabs.github.io/netscript/netscript/reference/queue/) for the queue layer underneath message delivery.

[Auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) [Observability](https://rickylabs.github.io/netscript/netscript/explanation/observability/)

_Canonical: https://rickylabs.github.io/netscript/explanation/durability-model/_

---

# Observability

*This essay is the **why** — the model and its trade-offs. The day-to-day *how* (guides, recipes, API) lives in **Build › [Observability](https://rickylabs.github.io/netscript/observability/)**.*

This essay answers one question: how does NetScript make a *distributed, multi-process* application observable, so that one logical operation reads as one story even though it crosses HTTP, a queue, a saga, and a worker subprocess? The answer is a single idea applied everywhere — **the trace context travels with the work** — wired into the framework boundaries so you inherit it for free. Read this to build the mental model; to wire spans yourself, follow the [how-to: add OpenTelemetry](https://rickylabs.github.io/netscript/observability/how-to/add-opentelemetry/); for the headline API and ports, see the

[Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/) hub; for exact exported symbols, see

[telemetry](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) .

![A traceparent header entering at an HTTP request, propagating through the service RPC boundary, into a job dispatched onto the queue, and injected into a worker subprocess — every span nesting under one trace id.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/otel-traceparent.svg)

*One traceparent, four processes, one trace. The framework carries the W3C trace context across each boundary so spans born in separate processes still nest under the same root.*

## The thesis: observability is a property of the boundary

Most backends bolt observability on after the fact. You write a handler, ship it, watch it misbehave, and *then* thread a logger, a metrics client, and a tracer through every call site — three libraries, three configuration surfaces, three ways to forget a field. The instrumentation drifts from the code because it was never part of the code's shape.

NetScript takes the same stance on observability that it takes on

[contracts](https://rickylabs.github.io/netscript/netscript/explanation/contracts/)

a cross-cutting concern belongs to the boundary, so the framework owns it and hands you a typed seam. A service built with [`defineService(...)`](https://rickylabs.github.io/netscript/capabilities/services/) wires request logging, health endpoints, and OpenTelemetry context propagation in one call. A worker job is dispatched *inside a span* the framework opens for you. The intent is that the *common* signal — "this operation happened, here is its trace id, here is whether it was healthy" — is free and uniform, and the *specific* signal — a custom child span around an expensive step — is one typed call away.

> Three signals, one context
>
> OpenTelemetry models telemetry as three correlated signal types:
>
> traces
>
> (the causal tree of spans for one logical operation),
>
> logs
>
> (timestamped structured records), and
>
> metrics
>
> (aggregated counters and gauges). NetScript's design goal is that all three share one
>
> trace context
>
> — the
>
> traceparent
>
> that travels with a request — so a log line, a span, and a counter can be stitched back to the same operation in the dashboard. The shared context is what turns three separate streams into one story.

## The core insight: distributed trace propagation

This is the part worth understanding well, because it is where most home-grown observability breaks. In a NetScript app, a single user action — "place an order" — does not run in one process. An HTTP request hits a service; the service dispatches a job onto a queue; a worker picks the job up, often in a *separate subprocess*; that worker may emit a saga step that fans out further. Four processes, one intent. If each process started its own trace, your dashboard would show four disconnected fragments and you would correlate them by hand, by timestamp, badly.

The fix is the **W3C trace context**: a `traceparent` header (and an optional `tracestate`) that carries a trace id and the current span id. The rule is simple — *whoever does the work carries the context forward, and opens their span as a child of the id they received.* When every hop obeys that rule, the spans nest into one tree even though no two of them share a process.

NetScript enforces the rule at each boundary it owns:

**The service boundary.** When you serve a router with `defineService(...).withRPC({ traceContext: true })`, RPC handling on `/api/rpc/*` reads the incoming `traceparent` and continues it, so a downstream call is a child of the caller's span rather than an orphan. You write the business logic; the framework keeps the causal chain intact across the wire.

**The queue / worker boundary.** Before your handler runs, the dispatcher opens a real `traceJobExecution` span carrying job attributes, duration, and status. When that job runs *out-of-process*, the dispatcher serializes the active context and injects the `traceparent` / `tracestate` (and the parent's `OTEL_*` config) into the subprocess environment via `createJobSubprocessEnv`. The child Deno process reads them back on startup and continues the *same* trace — so a span born in a forked subprocess still nests under the HTTP request that triggered it.

**The scheduler and SSE boundaries.** Cron runs emit their own spans rooted at the scheduler tick, and SSE events can be linked back to the job execution that produced them via `extractTraceContextFromRecord` — so a streamed progress event points at its originating trace.

> The key insight, in one line
>
> A trace is one operation only because
>
> every process that touches the work agreed to carry the same `traceparent`
>
> . NetScript makes that agreement automatic at the boundaries it owns (service RPC, job dispatch, subprocess spawn, scheduler). Where
>
> you
>
> open a new boundary — a raw
>
> fetch
>
> to a third party, a process you spawn yourself — the agreement is yours to honor: forward the header, or the child span becomes an orphan and the single-story view breaks.

```text
  HTTP request          service (RPC)          queue / dispatcher         worker subprocess
 ──────────────       ─────────────────       ────────────────────      ──────────────────
 traceparent     ->   continue context   ->   traceJobExecution    ->   createJobSubprocessEnv
 arrives at edge      open child span         opens job span            injects traceparent into
                      (withRPC traceContext)   (REAL OTel today)         env; child joins SAME trace
        │                    │                        │                         │
        └──────────── one trace id, carried forward at every hop ───────────────┘
```

## Structured logging, correlated by trace

Logs in NetScript are structured records, not free-text `console.log`. A handler's `ctx.logger` emits JSON with a level, a message, and an attribute bag, and the logging middleware enriches each record with request metadata. Because logging runs inside the same active span as the work, a log line emitted during a job carries — or can be joined to — the operation's trace id. That correlation is the whole point: in the dashboard you select a slow trace, and the log lines emitted *within* its spans are right there beside it, not in a separate searchable haystack you cross-reference by timestamp.

This is also why the scaffold's `progress(...)` helper is limited: it logs via the worker pool and delegates to `ctx.reportProgress`, but it does *not* by itself emit a `job.progress` OpenTelemetry span event. For an OTel-visible progress event, call `recordJobProgress` from `@netscript/telemetry/instrumentation` directly. The exact logging surface lives in

[logger](https://rickylabs.github.io/netscript/netscript/reference/logger/) .

## Where the signal goes: OTLP to the Aspire dashboard

A span or a log is only useful once something collects it. In the default dev loop that collector is the Aspire dashboard, and the wire between your process and the dashboard is **OTLP** (the OpenTelemetry Protocol). The generated Aspire AppHost configures an OTLP receiver at `http://localhost:4318` and a dashboard UI at `https://localhost:18888`; resources started under Aspire are handed the OTLP endpoint through environment variables, so they export telemetry without per-service configuration. This is why [Aspire is step two](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) of the dev flow, not an afterthought: `cd aspire && aspire start` brings the receiver up — along with Postgres and Redis — *before* the first handler runs, so the very first request has somewhere to land. Without it, handlers still execute; they simply export into the void.

**The observability surface — endpoints, ports, and what each one carries**

| Name | Type | Description |
| --- | --- | --- |
| `Aspire dashboard` | `https://localhost:18888` | The viewing surface. Resource graph, per-resource health, structured logs, and the distributed-trace view. Login token is printed by `aspire start`. |
| `OTLP receiver` | `http://localhost:4318` | Where processes export OpenTelemetry traces, logs, and metrics. Configured by the generated Aspire AppHost and handed to resources via env vars. |
| `Service trace context` | `traceparent` | Continued by defineService RPC handling on /api/rpc/* (withRPC traceContext) so a downstream call is a child span of its caller, not an orphan. |
| `Subprocess env` | `OTEL_* + traceparent` | Injected into a worker subprocess by createJobSubprocessEnv so an out-of-process job continues the SAME trace as the request that dispatched it. |
| `Workers health` | `GET :8091/health` | Liveness for the workers API. The cheapest signal: is this capability up? |
| `Auth health` | `GET :8094/health/live` | Liveness for the auth-api service (also exposes /health/ready). |

## Known gap: scaffold job-tools helpers

Two layers, stated precisely so you never over- or under-claim.

> Real OTel vs. scaffold stubs
>
> Framework / dispatcher layer = real OTel.
>
> traceJobExecution
>
> , scheduler spans, subprocess
>
> traceparent
>
> propagation, and
>
> task.execute
>
> spans are live. A user gets job traces in Aspire
>
> automatically
>
> , with zero handler code.
>
> Scaffold `createJobTools(ctx)` tracing helpers = still no-op stubs.
>
> The
>
> trace.addEvent
>
> and
>
> trace.withChildSpan
>
> helpers the generated sample hands
>
> into your handler
>
> are placeholders — your callback runs and returns normally, but no extra span is exported. This is a
>
> known, tracked limitation with a fix planned
>
> (debt
>
> workers-scaffold-job-tools-noop
>
> ), not a permanent design choice. The workaround today: call
>
> @netscript/telemetry/instrumentation
>
> helpers directly from your handler for custom spans — because the dispatcher already opened the parent job span, your child span nests under it automatically.

```ts
// services/orders/handlers/process-order.ts
import {
  defineJobHandler,
  createSuccessResult,
} from '@netscript/plugin-workers-core';
// For CUSTOM spans inside a handler, import the telemetry helpers directly.
// The dispatcher already opened the parent job span around this handler,
// so this child span nests under it automatically.
import { withChildSpan } from '@netscript/telemetry/instrumentation';

const handler = defineJobHandler(async (ctx) => {
  ctx.logger.info('processing order'); // structured log, joined to the trace

  // Bracket an expensive step in a REAL child span.
  const result = await withChildSpan('order.charge', async (span) => {
    span.setAttribute('order.amount', ctx.payload.amount);
    return { charged: true };
  });

  return createSuccessResult({ charged: result.charged });
});

export default Object.assign(handler, { id: 'process-order' as const });
```

## The auth audit trail: structured, redacted, traced

Authentication is the one place where "just log everything" is actively dangerous — sign-in events carry subjects, tokens, and claims you must *not* persist in the clear. The auth audit surface shipped to solve exactly this: `@netscript/plugin-auth-core/telemetry` is a small, audit-safe instrumentation facade that the auth service composition root wires in with `createAuthTelemetry`. It does three things, all of them on purpose.

**It traces auth operations as first-class spans.** `traceOperation` brackets each auth operation — `auth.signin`, `auth.callback`, `auth.signout`, `auth.session`, `auth.me` — in a child span that joins the incoming request trace, so a failed sign-in is a node in the same trace as the request that triggered it, not a disconnected log line.

**It emits standardized audit events.** Each operation records an `auth.audit.log` span event plus breadcrumbs (`auth.principal.resolved`, `auth.session.issued`, `auth.session.revoked`) with a finite outcome vocabulary — `success`, `unauthenticated`, `failed_bad_credentials`, `failed_session_expired`, `failed_provider_error`, `failed_callback_invalid` — and a machine-readable error code (`AUTH_INVALID_CREDENTIALS`, `AUTH_SESSION_EXPIRED`, …). Outcomes are an enum, not prose, so the audit trail is queryable.

**It redacts by construction.** A raw subject never lands in the trace. `hashSubject` runs the subject through HMAC-SHA-256 with a *deployment-owned salt* (never derived from the subject), so the recorded `auth.subject_hash` is stable for correlation but not reversible. `redactAuthPrincipal` projects a principal down to its hash, scheme, scope/role *counts*, and claims with any token-bearing key (anything matching `token`, `secret`, `credential`, `password`, `apikey`, `authorization`, `sessionid`, …) stripped out entirely. The shape that reaches the dashboard is audit-safe by design, not by a downstream scrubbing pass you might forget.

> Auth audit is gated — and that is deliberate
>
> The redaction is only as strong as its salt, so auth telemetry is
>
> opt-in by configuration
>
> :
>
> createAuthTelemetry
>
> is enabled only when a
>
> subjectHashSalt
>
> is supplied (the auth service resolves it from
>
> NETSCRIPT_AUTH_AUDIT_SALT
>
> ). With no salt configured,
>
> traceOperation
>
> runs your callback through a
>
> no-op recorder
>
> — auth still works, but no subject is hashed and no audit span is emitted, because emitting an un-salted hash would be worse than emitting nothing. A guiding rule runs through the code:
>
> observability must never change auth behavior
>
> — every recorder method swallows its own errors so a telemetry failure can never break a login.

This supersedes the older "auth diagnostics, not an audit trail" caveat: there is now a real, structured, redacted auth audit surface. What it is *not* is a tamper-evident, immutable ledger — the events ride the standard OTel/streams transport. Treat it as a strong, queryable audit trail for operational and security review, not as a compliance-grade write-once log. For how auth itself is shaped, see [Auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) and the

[Authentication](https://rickylabs.github.io/netscript/netscript/identity-access/auth/) hub.

## Why this design, and what it costs

The trade-offs, because instrumentation-at-the-boundary is an opinion.

- **Telemetry follows the framework, not a side library.** Because the trace context rides the service boundary and the dispatcher opens the job span, you cannot accidentally instrument half your code — the lifecycle signal is free. The cost is that you instrument NetScript's *way*: you reach for `@netscript/telemetry` and the catalog-pinned `@opentelemetry/api` (`^1.9`), not whatever tracer you used last job.
- **One viewing surface in dev, your choice in prod.** The dashboard at `:18888` is a developer convenience wired by Aspire. It is an OTLP receiver like any other; in production you point the same OTLP export at your own collector. The model does not lock you to Aspire — it locks you to the protocol.
- **Correlation depends on propagation working end to end.** A dropped `traceparent` — a call that doesn't carry it forward — turns a child span into an orphan and breaks the single-story view. The framework propagates it across the service boundary and into worker subprocesses so you don't have to; custom fan-out (your own `fetch`, your own spawned process) is where you reintroduce the responsibility.
- **The scaffold helpers are a known, bounded gap.** The job lifecycle, scheduler, subprocess, and `task.execute` spans are real — but the scaffolded `createJobTools(ctx)` `trace` helpers are no-op stubs (fix planned). Their shapes are stable, so code you write against them keeps working when the runtime fills them in. Until then, use `@netscript/telemetry/instrumentation` directly.

The OpenTelemetry dependency is pinned in the workspace catalog (`@opentelemetry/api` at `^1.9`) and imported through the catalog, never de-catalogued, so every workspace member shares one telemetry API surface — which is itself why a `traceparent` minted in the service and read in a worker refers to the same span model.

## Glossary

- **OpenTelemetry (OTel)** — the vendor-neutral standard for traces, logs, and metrics that NetScript instruments against (`@opentelemetry/api`). See the [glossary](https://rickylabs.github.io/netscript/glossary/) and the

[Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/) hub.

- **OTLP** — the OpenTelemetry Protocol; the wire your process uses to export telemetry. In dev, the Aspire AppHost receives it at `http://localhost:4318`.
- **Span** — one node in a trace: a named, timed operation with attributes and events. A child span (`withChildSpan`) nests under its parent to form the causal tree.
- **traceparent** — the W3C trace-context header that carries the trace id across a boundary so separate spans stitch into one trace; the framework injects it even into worker subprocesses.

## Where to go next

- **Do it:** the [how-to: add OpenTelemetry](https://rickylabs.github.io/netscript/observability/how-to/add-opentelemetry/) walks adding a custom span, structured logs, and `traceparent` propagation against a running service.
- **Hub:** the [Telemetry & logging](https://rickylabs.github.io/netscript/netscript/observability/telemetry/) hub covers the headline API and the OTel-wired-into-boundaries model with the real endpoints; [Authentication](https://rickylabs.github.io/netscript/netscript/identity-access/auth/)

  covers the auth surface whose audit trail is described above.
- **Related:** [Services & contracts](https://rickylabs.github.io/netscript/netscript/services-sdk/services/) (the boundary that propagates trace context),

[Durable sagas](https://rickylabs.github.io/netscript/netscript/durable-workflows/sagas/) (the multi-step operations a single trace spans), and

[Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/) (the dashboard and OTLP receiver that consume these signals).

- **Reference:** exact exported symbols live in [telemetry](https://rickylabs.github.io/netscript/netscript/reference/telemetry/) , and the logging surface in [logger](https://rickylabs.github.io/netscript/netscript/reference/logger/) .

[Durability model](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) [Orchestration with Aspire](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

_Canonical: https://rickylabs.github.io/netscript/explanation/observability/_

---

# The plugin system

This essay explains the mental model behind a NetScript plugin: how a plugin relates to its sibling **core package**, what it *contributes* to a host through a typed **manifest**, how the host *discovers* it through **generated registries** rather than hand-imports, and why a single plugin's HTTP API and its background work run as **separate processes**. Read it to understand the shape before you extend it.

If you only want to *add* a plugin to a workspace, follow the

[add-a-plugin how-to](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/) ; to *author* a new one, see [author-a-plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/author-a-plugin/) . For the exact symbols a plugin author calls, use the [@netscript/plugin reference](https://rickylabs.github.io/netscript/netscript/reference/plugin/) . The [auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) is the richest worked example of every idea here.

![A single plugin splits into an HTTP API service resource and one or more isolated background-processor resources, each started by the AppHost as a separate Aspire resource with its own permissions.](https://rickylabs.github.io/netscript/netscript/assets/diagrams/plugin-thread-isolation.svg)

*One plugin, many resources: the API service and each background processor run as separate AppHost resources, so a crash or a load spike in one cannot take the others down.*

> Three nouns carry the whole model
>
> A plugin declares a
>
> manifest
>
> ; the manifest names a set of
>
> contributions
>
> against a fixed set of extension axes; a generated
>
> registry
>
> turns those declarations into static modules the host imports. Hold those three nouns and the rest of this page is detail.

## A plugin is a thin layer over a core package

The single most important thing to understand is that a NetScript plugin is usually *two packages, not one*. The real logic lives in a **core** package; the plugin is a thin integration layer that contributes that logic to a host.

**Public plugin packages and their sibling core packages**

| Public plugin | Sibling core package | What lives in core |
| --- | --- | --- |
| `@netscript/plugin-workers` | `@netscript/plugin-workers-core` | Job/scheduler runtime, ports, contracts. |
| `@netscript/plugin-sagas` | `@netscript/plugin-sagas-core` | Saga DSL, durable runtime, durability tiers. |
| `@netscript/plugin-triggers` | `@netscript/plugin-triggers-core` | Trigger definition builders, ingress runtime. |
| `@netscript/plugin-streams` | `@netscript/plugin-streams-core` | Durable stream producer runtime. |
| `@netscript/plugin-auth` | `@netscript/plugin-auth-core` (+ backends) | `AuthBackendPort` seam, domain, contracts. |

The split follows the architecture doctrine's separation of *behavior* from *integration*:

- The **core** package implements the capability itself — the authoring DSL (for example the saga and trigger definition builders), the runtime, the ports it depends on, the adapters, telemetry helpers, and the versioned contract types. This is where the long-running behavior and state live.
- The **plugin** package is a thin integration layer (the doctrine's *Plugin Package* archetype). Its `mod.ts` is small. It re-exports the userland surface from its core sibling rather than redefining it, and it adds the one thing the core cannot supply on its own: a **manifest** that tells a host *what* this plugin contributes and *how* to wire it up.

Because of this split, core packages appear as an **Internals** subsection on each plugin's reference page rather than as separate top-level entries. Application authors normally reach core symbols *through* the public plugin, so the public plugin is the surface users consume.

> One import path, two responsibilities
>
> The saga DSL (
>
> defineSaga
>
> ,
>
> defineQuery
>
> ,
>
> defineSignal
>
> ) is exported from
>
> @netscript/plugin-sagas-core
>
> , where the capability is authored.
>
> @netscript/plugin-sagas/runtime
>
> exports the runtime infrastructure instead — the publisher, the durable runtime, the saga stores, the runner, and the supervisor. The plugin package itself stays thin: its
>
> mod.ts
>
> re-exports only the manifest surface (
>
> sagasPlugin
>
> ,
>
> inspectSagas
>
> ) so the behavior/integration boundary stays intact in source.

This is also why some plugin surfaces are deliberately thin or even fail loud. In `@netscript/plugin-streams`, the manifest-side helpers redirect you to the real producer runtime in `@netscript/plugin-streams-core` (`createDurableStream`) by surfacing a `StreamUnsupportedOperationError` rather than quietly doing nothing. The *behavior* lives in core; the *plugin* only carries the manifest. The boundary is a feature, not an oversight — see

[durable streams](https://rickylabs.github.io/netscript/netscript/durable-workflows/streams/) for the producer-versus-manifest framing.

This two-tier shape is not reserved for the official plugins. When you scaffold a custom plugin with `netscript plugin new <name>`, the generator emits the same pair: a JSR-publishable core engine package under `packages/plugin-<name>-core/` (its domain, ports, application orchestration, `contracts/v1`, and testing doubles) and a thin connector under `plugins/<name>/` (its manifest, adapter, Aspire contribution, CLI/scaffold entrypoints, and service) whose `contracts` subpath simply re-exports the core's `contracts/v1`. So custom plugins inherit the same behavior-versus-integration split — thin, composable, and independently publishable — from the moment they are generated. See

[author-a-plugin](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/author-a-plugin/) for the walkthrough.

## What a plugin contributes: the manifest

A plugin describes itself with a typed **manifest**, assembled through the `definePlugin()` builder in [@netscript/plugin](https://rickylabs.github.io/netscript/netscript/reference/plugin/) . The manifest is a *declaration*, not executable wiring: `definePlugin(name, version)` returns a builder, and each chained `.with*()` call adds a **contribution** along a well-defined **extension axis**.

```ts
// plugins/workers/src/public/mod.ts (abridged)
import { definePlugin } from "@netscript/plugin";

// definePlugin(name, version) returns a builder. No behavior runs here —
// each .with*() call only NAMES a contribution against a fixed axis.
export const workersManifest = definePlugin("@netscript/plugin-workers", "0.0.1-beta.11")
  .withType("background-processor")
  .withService({ name: "workers-api", entrypoint: "./services/src/main.ts", port: 8091 })
  .withBackgroundProcessor({ name: "workers-combined", entrypoint: "./bin/combined.ts", concurrency: 2 })
  .withBackgroundProcessor({ name: "workers-worker", entrypoint: "./bin/worker.ts", concurrency: 2 })
  .withBackgroundProcessor({ name: "workers-scheduler", entrypoint: "./bin/scheduler.ts" })
  .withDbSchemas([{ path: "./database/workers.prisma", engine: "postgres" }])
  .withContractVersions([{ version: "v1", loader: "./contracts/v1/mod.ts" }])
  .withRuntimeConfigTopics([{ name: "workers", schemaPath: "./runtime/workers.schema.json" }])
  .withAspire("./src/aspire/mod.ts")
  .build();
```

The builder exposes a *fixed* set of contribution axes — the vocabulary every host understands. The most load-bearing ones:

**Builder methods, each declaring one kind of contribution**

| Builder method | Contributes | Used for |
| --- | --- | --- |
| `.withService(…)` | An HTTP service: name, entrypoint, port. | The plugin's oRPC API resource. |
| `.withBackgroundProcessor(…)` | A long-running processor: name, entrypoint, concurrency. | Workers, runners, processors — runs apart from the API. |
| `.withDbSchemas(…)` | A Prisma schema fragment + engine. | Owned tables merged into the workspace schema. |
| `.withStreamTopics(…)` | Typed stream topic definitions. | Durable change-data channels. |
| `.withRuntimeConfigTopics(…)` | A named, schema-validated config topic. | Per-plugin runtime configuration. |
| `.withContractVersions(…)` | A versioned contract loader. | Forward/backward contract compatibility. |
| `.withTelemetry(…)` | Telemetry registration. | Spans, metrics, structured logs. |
| `.withAspire(…)` | An Aspire contribution module path. | How the AppHost materializes the plugin's resources. |

Contributions are the vocabulary the host understands. A workers plugin contributes worker job definitions and processors; a sagas plugin contributes saga definitions; a streams plugin contributes stream topics and a service; an auth plugin contributes its oRPC service, contract versions, and a runtime-config topic. The host never needs to know the *internals* of any plugin — it only needs to understand these contribution shapes.

This is the doctrine's principle of **registration over inheritance** for cross-package extension: a plugin *registers* named contributions against open extension axes instead of subclassing host internals. Registration scales because the host can validate a registration at composition time, log it, and reject conflicts — for example, duplicate plugin names are rejected with a structured error that references both contributors.

> Contributions are a closed set; plugins are an open set
>
> The host understands a
>
> fixed
>
> list of contribution shapes, but any number of plugins may contribute against them. That asymmetry is what lets capabilities compose without the host growing new code for each plugin.

## How the host discovers plugins: generated registries

NetScript does **not** auto-discover plugins from `node_modules`, and the host does **not** hand-import each plugin. Plugins live under `plugins/` and are discovered through the file system, but the link between *declaring* a plugin and the *runtime* using it is a generated **registry**.

Rather than scanning the file system at runtime, the scaffold/codegen step emits static registry modules — TypeScript that the runtime imports directly — so that adding a plugin is a *regeneration* step, not a code edit. Two properties of this loader matter for the model:

- **Load order is deterministic.** Plugins must not depend on the order in which other plugins load; the doctrine forbids order-dependence and asserts against it.
- **Each load contributes named registrations** against one or more extension axes, and duplicate names across plugins are rejected with a structured error.

> Compose, don't edit
>
> A host
>
> assembles
>
> plugins; it never edits another boundary's code to accept one. Adding workers, sagas, triggers, streams, or auth means shipping a manifest and regenerating the registry — the host's own source is untouched. This is the discipline that keeps capabilities independently versioned and independently removable.

The practical sequence — `netscript plugin install …` followed by the registry-generation step — is covered in the [add-a-plugin how-to](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/) and the

[CLI reference](https://rickylabs.github.io/netscript/netscript/cli-reference/) . Regenerating the registry is what makes a freshly added plugin visible to the runtime.

## Why background work runs as separate processes

A single plugin almost never runs as one process. Its **HTTP API** and its **background work** are materialized by the AppHost as *distinct* Aspire resources, each with its own entrypoint and its own permission set. The workers plugin is the clearest example: its Aspire contribution registers the API as a Deno *service* and each processor as a Deno *background* resource:

```ts
// plugins/workers/src/aspire/workers-contribution.ts (abridged)
// The API is a service resource; each processor is a SEPARATE background resource.
const api = builder.addDenoService("workers-api", {
  entrypoint: "plugins/workers/services/src/main.ts",
  port: ctx.port("workers-api", 8091),
  permissions: WORKERS_SERVICE_PERMISSIONS, // narrow: serve HTTP
});

const combined = builder.addDenoBackground("workers-combined", {
  entrypoint: "plugins/workers/bin/combined.ts",
  permissions: WORKERS_BACKGROUND_PERMISSIONS, // wider: queues, db
});
// …plus workers-scheduler and workers-worker, each its own resource
return [api, combined, scheduler, worker];
```

The background entrypoints are real files in every scaffolded plugin, and each capability picks the shape it needs:

**Where each plugin's background work runs**

| Plugin | Background entrypoint | AppHost resource |
| --- | --- | --- |
| workers | `bin/combined.ts` (also `worker.ts`, `scheduler.ts`) | Deno background, separate from `workers-api`. |
| sagas | `src/runtime/saga-runner.ts` | Deno background `saga-runner`. |
| triggers | `src/runtime/trigger-processor.ts` | Deno background `trigger-processor`. |

The reason this is structural rather than incidental is three-fold:

1. **Crash containment.** A processor that hits an unrecoverable error takes down only its own resource. The HTTP API keeps serving; other processors keep running.
2. **Independent scaling.** The API and the processors have different load profiles — request latency versus queue depth — so they are tuned and scaled independently (`WORKER_CONCURRENCY` on the background resource never touches the API).
3. **Least privilege.** The API gets a narrow permission set (serve HTTP); background resources get the wider set they need (queues, database, file watching). Splitting the processes lets each one run with only the permissions its job requires.

> The key insight
>
> "One plugin" is a packaging unit, not a runtime unit. At runtime a plugin fans out into one API service and N background resources — that fan-out is exactly what the AppHost reads from the manifest and the plugin's Aspire contribution. See
>
> orchestration with Aspire
>
> for how the AppHost assembles them.

## Auth: the model at its richest

The **auth** plugin is the clearest single exemplar of every idea on this page, because it stretches the core/plugin split across *five* units instead of two:

- `@netscript/plugin-auth-core` defines the **port** — `AuthBackendPort` — and nothing provider-specific. It is the seam.
- Three pure **backend adapters** implement that port for different identity providers: `@netscript/auth-kv-oauth` (the only interactive backend — full OAuth/OIDC redirect flow), `@netscript/auth-workos`, and `@netscript/auth-better-auth` (both non-interactive).
- `@netscript/plugin-auth` is the **composing plugin**: it carries the manifest, runs the `auth-api` oRPC service on `:8094`, and selects exactly **one** active backend via `NETSCRIPT_AUTH_BACKEND` (default `kv-oauth`).

That is the whole model written large: behavior lives in core and adapters, the plugin only composes and declares, and the host sees one service contribution regardless of which backend is active. Where a backend cannot satisfy a capability — for instance, asking a non-interactive backend to run an interactive sign-in — the seam fails loud with a typed `AuthBackendOperationUnsupportedError` rather than silently misbehaving. Read the

[auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/) for the full port-and-adapter walkthrough.

> Package pins & the audit surface
>
> Scaffolded JSR imports use exact
>
> @0.0.1-beta.11
>
> pins for the aligned release train. Auth also ships a structured, redacted audit surface —
>
> createAuthTelemetry
>
> from
>
> @netscript/plugin-auth-core
>
> — which records audit spans only when a
>
> subjectHashSalt
>
> is configured (
>
> NETSCRIPT_AUTH_AUDIT_SALT
>
> ); without a salt it runs as a no-op. See
>
> Observability
>
> for the full audit-trail model.

## Why the model looks like this

The shape exists to keep three concerns from leaking into each other:

1. **Capability authors** work in a core package and think only about behavior, ports, and contracts — never about how a host discovers them.
2. **Plugin packages** stay small: they translate a capability into a manifest of contributions, which is the only thing a host has to understand.
3. **Hosts** depend on a stable, finite set of contribution shapes and a deterministic registry, so adding a plugin never requires editing host code — it requires a manifest and a regenerated registry.

The result is that capabilities **compose**. A host can add workers, sagas, triggers, streams, and auth in any combination, and each plugin contributes its services, background processors, schemas, and topics through the same vocabulary — each running as its own isolated resource.

## Where to go next

[Add a first-party plugin  The task-oriented recipe: scaffold, register, regenerate, verify.](https://rickylabs.github.io/netscript/netscript/orchestration-runtime/how-to/add-a-plugin/)

[The auth model  The five-unit core/adapter/plugin split — the model at its richest.](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/)

[Orchestration with Aspire  How the AppHost turns manifests into running API and background resources.](https://rickylabs.github.io/netscript/netscript/explanation/aspire/)

[Plugin authoring contract  definePlugin(), the contribution axes, and the registry emitter.](https://rickylabs.github.io/netscript/netscript/reference/plugin/)

Each plugin's surface is documented on its own reference page:

[workers](https://rickylabs.github.io/netscript/netscript/reference/workers/) ,

[sagas](https://rickylabs.github.io/netscript/netscript/reference/sagas/) ,

[triggers](https://rickylabs.github.io/netscript/netscript/reference/triggers/) , and

[streams](https://rickylabs.github.io/netscript/netscript/reference/streams/) . For the wider picture, see

[architecture](https://rickylabs.github.io/netscript/netscript/explanation/architecture/) and

[the durability model](https://rickylabs.github.io/netscript/netscript/explanation/durability-model/) .

[Contracts & type flow](https://rickylabs.github.io/netscript/netscript/explanation/contracts/) [Auth model](https://rickylabs.github.io/netscript/netscript/explanation/auth-model/)

_Canonical: https://rickylabs.github.io/netscript/explanation/plugin-system/_