# 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 the workers plugin's assigned port). 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 the sagas plugin's assigned port). 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 its assigned port), 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 its assigned port. 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 its assigned port 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 effects that either `enqueueJob(jobRef, { payload, priority })` immediately or `defer({ until })` a durable one-shot replay. Like workers and sagas, the triggers service serves a **typed v1 oRPC contract** for trigger and event introspection plus management on its assigned port; 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/). |
| `zod` | `z.object({...})` | The schema declaration and validation library NetScript uses for type-safe inputs, outputs, and runtime verification. It provides the runtime half of contracts. See [Explanation → Contracts](https://rickylabs.github.io/netscript/explanation/contracts/). |

## 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 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). Scaffold `createJobTools(ctx)` handler helpers add custom events, progress, and child spans to the active job trace; their `log.*` surface remains console-backed. 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/)