Glossary

Reference. Short definitions of the terms used throughout the documentation, alphabetically. Each links to the page that treats it in depth.

abandoned — A unit still open when the drain deadline passes. It is aborted through its AbortSignal and counted in DrainReport.abandoned — the field the exit code keys on (2). See ExitReport and DrainReport.

ambient record — The small, fixed UnitRecord — { unitId, traceId, tenantId, signal } — the kernel opens in an AsyncLocalStorage store for a unit's whole extent, and currentUnit() reads. It carries data, never services; signal is the very AbortSignal the unit's work callback is handed, so a middleware-shaped runtime — a Temporal activity, an AMQP delivery — can still honour the drain deadline. See Ambient data, injected capabilities.

composition root — The one module a process boots: it imports the application and a starter, and exports the runtime port. HttpModule("OrderApi")({ router, imports, … }) is one. See Modules and Starters.

context — Context<R> — what a built graph hands out: ctx.get(Port) for any port in R. RuntimeHost.ctx is the application context; unit work receives the forked one. See Entry points.

contract — The transport-neutral description of what a process answers, in a package of its own so a client can take it without the server: an oRPC contract for HTTP, a temporal-contract for a Temporal worker, an amqp-contract for AMQP. The starter's port-and-provider sugar types the application's record from it. See Starters.

defect vs error — An error (Err) is a modeled outcome, visible in a Result's E; a defect is an unmodeled failure — a throw, a bug — invisible to the type and observable only by match/recoverDefect. The kernel passes both through untouched. See Nothing throws.

drain — The signal-driven shutdown, in three beats: readiness flips false, the pre-drain delay elapses, then the runtime stops accepting and in-flight units get drainTimeoutMs. Only a signal drains; stop() and a crash do not. See Draining, in three beats.

exit code — What runMain sets process.exitCode to from an ExitReport: 0, 1, 2, 70 or 78. See runMain and exit codes.

export — A port a module makes visible to whoever imports it. Only exports reach the context; a provided-but-unexported port is private to the module. See Modules and Keep a port private.

fragment — A sub-tree of a contract that is itself a valid contract: contract.orders is one. It is what a piece implements, and what makes a slice liftable — api.OrpcRouter(contract.orders)([…]) serves the fragment alone, with the slice's own piece unchanged. See Split a router into controllers.

fork — Module.forkScope — a scope opened over an existing context for a module's providers, then closed. A starter's own unit option is a fork the runtime opens itself, through UnitHost.fork, around every unit it handles. See Open a per-request scope.

gate — A phantom type that is inert when a composition is sound and refuses the call otherwise. Both shipped gates are the same shape: a marker intersected onto a parameter, unknown when sound. start's is StartGate — one of two sentences (NO RUNTIME — …, UNSATISFIED RUNTIME PORTS — …), plus di's own UNSATISFIED DEPENDENCIES — nothing provides for an unmet need — a bound unit module's own included — checked first and ending on the port's id. di's own is DependencyGate on Module.build/scoped/forkScope — the same one-property object, ending on the missing ports: "UNSATISFIED DEPENDENCIES — nothing provides": Pool. See start and StartOptions and Compile errors, not surprises.

issuer — Whoever mints the tokens a deployment accepts, named by the iss claim it signs them with — an identity provider, or @btravstack/testing/jwt's localIssuer under test. jwtAuthenticator requires iss to match the configured issuer — the issuer option, or HTTP_JWT_ISSUER when it is not pinned — and it is the issuer that decides how a tenant is spelled: tenant in the example, tid on Entra, org_id on Auth0, which is why principal(claims) is the application's. See Protect a procedure.

JWKS — The JSON Web Key Set an issuer publishes its public keys at, and what jwtAuthenticator verifies a signature against: fetched on demand from the configured URL — the jwks option, or HTTP_JWT_JWKS_URI when it is not pinned — cached, and refetched when a token names a kid the cache has not seen. Because it publishes public keys, the accepted algorithms are asymmetric only — an HMAC one beside them is the algorithm-confusion attack. See @btravstack/http-server.

kernel event — One of the nine KernelEvents (building … uncaught) the kernel emits to its EventSink; stderrSink writes one JSON line each. See Kernel events.

kind — The name under which a runtime forks one unit's module: the key a unit: { … } record is indexed by. @btravstack/http-server has one kind per authentication scheme plus anonymous, and forks the kind that authenticated the request — a scheme binding no module of its own falls back to anonymous; the two workers have exactly one each (message, activity). A kind's fork is seeded with what the unit was opened for — the principal, the delivery, the activity input — and a leaf reads that fork's services off context.unit. See Open a per-request scope.

liveness / readiness — The two probes the kernel serves itself. /livez is 200 in every phase before exited; /readyz is 200 only while serving and not forced unready, and once false never returns to true. See Probes.

module — Module(name)({ imports, provides, exports }) — the unit of composition in di: what it brings in, what it builds, what it lets out. Its type carries its exports, its error channel and its unmet needs. See Modules.

need — A dependency a module has not satisfied itself, carried in its type. Scope and Env are the two the kernel discharges. See Modules.

piece — One contract key's implementation as a provider of its own, minted from the contract: api.OrpcController(contract, "orders"), AmqpHandler(contract, "orderAudit"), TemporalWorkflowActivities(contract, "fulfillOrder"). The key rides the piece's own port id, so a piece cannot sit under the wrong key, and an array of them composes into the one provider a runtime takes — every leaf covered, or the call is refused. See Split a router into controllers and Split a worker into slices.

pinned — Of a statement: carrying the tenant setting inside its own transaction, so a row-level-security policy reading current_setting('app.tenant_id', true) can narrow it. tenantScoped(tenant) pins every statement; an unpinned read matches no row rather than erroring, and an unpinned write is refused with 42501. See @btravstack/prisma.

policy — The third layer of authorization: (principal, resource) → decision, decided in the handler because that is the only layer holding the resource. A plain function answering Result<Authorized<T>, Forbidden> — no port, no registry, no framework Forbidden, since a framework cannot invoke a rule that runs after a fetch. See Authorize a request.

port — class Logger extends Port("Logger")<Service> {} — a nominal name for a service, the vocabulary an application defines. RuntimePort is the one the kernel resolves its runtime from. See Ports.

pre-drain delay — Beat 2 of the drain: preDrainDelayMs (default 5_000) between readiness flipping false and the runtime being told to stop accepting — the window Kubernetes' eventually-consistent endpoint removal needs. See Tune the drain for Kubernetes.

provider — Provider(port)({ inject, ...arm }) — how a port's service is built: value, sync, make, class or acquire/release. See Providers.

runtime — The service behind a port declared over RuntimePort: { name, resolves, start }, where start returns a Serving. A process boots exactly one. See The Runtime contract and One process, one runtime.

scope — The lifetime a graph is built and torn down in — Module.scoped opens one, runs a callback, and closes it on every path, running finalisers in reverse. Scope is also the phantom need an acquire/release provider adds. See Scopes and resource safety.

sink — Two of them, and they are not the same thing. An EventSink takes a KernelEvent (stderrSink is the default); a Sink takes a Line (jsonSink is the default, pinoSink the alternative). kernelEvents(logger) is the adapter that makes the first out of the second. Neither may take the process down: a throwing one is swallowed. See Kernel events and @btravstack/observability.

slice — A feature's vertical, as an ordinary module: its piece, whatever private providers that piece needs, and a needs list naming what it expects from the root. It exports only its piece's port; several slices in one root are a modulith, and one lifts into a process of its own without its piece changing. See Split a router into controllers.

starter — A package that brings one concern's defaults for the standard case, in the Spring Boot sense: @btravstack/http-server, @btravstack/temporal-worker and @btravstack/amqp-worker each bring a runtime, a module sugar and a port-and-provider sugar; @btravstack/observability brings implementations of the kernel's Logger, Tracer and Meter ports, and no runtime. See Starters.

structured logging — A line whose message is a constant and whose facts are fields — info("placing an order", { orderId, quantity }), not a rendered sentence — so the receiving system groups by message and filters by field. Attributes is flat and scalar for that reason, and the ambient unit's ids are added by the implementation rather than by the caller. See Log and correlate.

trace id — UnitRecord.traceId — the correlation id, defaulting to UnitMeta.id, which a runtime may supply from outside the process (an x-request-id header, a message id, a workflow id). Why UnitMeta.id must be unique per unit. It is the field @btravstack/observability's logger stamps on every line without the caller naming it. See The Runtime contract.

unit / unit of work — One piece of work a runtime submits through host.run(meta, work): an HTTP request, an activity attempt, a delivery. The kernel counts it towards the drain, hands it an AbortSignal and an ambient record carrying that same signal, and hands its Result straight back. See The Runtime contract.

witness type — A type only one function can mint — Authorized<T> is T intersected with a unique symbol the rule's module declares and never exports — used as the parameter type of the operation a decision protects, so the operation cannot be reached without the decision. What it buys is that a forgotten rule is a compile error; a deliberate as Authorized<T> stays writable, and is a lie in one line a reviewer greps for. See Authorize a request.