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 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.
Core vocabulary
These are the words you will meet first — in the Quickstart, the tutorials ladder, and the architecture overview.
| 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 http://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 and 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. |
Aspire |
aspire start |
The .NET Aspire orchestration layer NetScript uses for local development. It provisions your database (Postgres by default; 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 and 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 and 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 and the 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 and Capabilities → Authentication. |
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 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 the list of plugins (./plugins/<name>/mod.ts). It is the wiring manifest the runtime reads to know what your app is made of. See Explanation → Architecture and reference/config/. |
contract |
oc.route().input().output() |
The versioned, schema-first definition of an API — built with @orpc/contract plus zod 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 and 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. |
| 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. |
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 and 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. |
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. |
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 and Capabilities → Background jobs. |
| Name | Type | Description |
|---|---|---|
manifest |
plugins/ |
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. |
oRPC |
@orpc/contract · @orpc/server |
The contract-and-RPC toolkit (@orpc/*, 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, and the auth service expose oRPC (mounted under /api/rpc/*); triggers are the exception — they mount raw Hono routes. See 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 and Capabilities → Auth. |
plugin |
plugins/ |
An installable, thread-isolated capability. Public workspaces use package dispatch such as netscript plugin add @netscript/plugin-workers; local-source contributor samples use deno run -A packages/cli/bin/netscript-dev.ts plugin add worker --name workers --samples. It lands canonically under plugins/<name>/ with its own mod.ts manifest, contracts, services, and (optionally) Prisma schema; background processors run from entry points like bin/combined.ts or src/runtime/trigger-processor.ts. See Explanation → Plugin system and 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. |
| 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/jobs.registry.ts, keyed by job id). Registries are derived artifacts — regenerate them, do not hand-edit. See 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 and 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 and 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 and 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 and 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 and reference/streams/. |
| 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. Unlike workers and sagas, the triggers service is built on raw Hono routes, not oRPC; POST /api/v1/webhooks/inbound/generic on port 8093 resolves the inbound/generic trigger. See Tutorial → Ingest a webhook and 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.
| Name | Type | Description |
|---|---|---|
appsettings.json |
infra config |
The root infrastructure manifest the Aspire AppHost actually reads — declaring NetScript.Databases (the database engine — Postgres by default, 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 Workdirs. 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. |
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 and 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. |
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 and 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 and 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 adds auth_users / auth_sessions / auth_accounts / auth_verifications). The typed client is generated with netscript db generate after Aspire is up. See Capabilities → Database and 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 and 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.