#typescript/src/context

#typescript/src/context

Structured output context for command handlers, mirroring Go's Context (context.go) with Python's Context as the divergence ground truth. Always injected as the second argument to every handler ((args, ctx) signature). app.ts builds the InfraAccess view (infra.ts buildInfraAccess) per dispatch; it is null when the app declares no roots or handshakes, so every infraValue() call throws the not-declared error.

#Writer

export interface Writer

Minimal sink for output streams (process.stdout/stderr or test captures).

#InfraAccess

export interface InfraAccess

A Context's view of infrastructure env vars: root values resolved eagerly at app construction, the set of declared handshake vars (read live), and the set of declared connection vars (read live, but suppressed under --hermetic).

#ConnectionEnvReader

export interface ConnectionEnvReader

OPTIONAL capability a check context may expose: the value of a declared connection env, read live -- EXCEPT under --hermetic, where it resolves as absent [undefined, false] so a check can skip visibly instead of connecting. The check command wraps the tool-supplied check context in a value that satisfies this interface, backed by the app's declared connection envs and the invocation's hermetic state.

isHermetic() reports whether the invocation ran under --hermetic. It exists so a check can DISTINGUISH the two cases that connectionEnvValue's present === false otherwise conflates: "--hermetic suppressed the connection env" vs "the env var is simply unset". A check that layers config fallbacks below the env must honor hermetic even when the env is unset -- otherwise it falls through to a config URL and connects, violating the hermetic guarantee:

const [dsn, present] = r.connectionEnvValue("DATABASE_URL"); if (!present) { if (r.isHermetic()) return rep.skipped("hermetic: connection suppressed"); // env unset but not hermetic -- config fallback is allowed here }

#ReservedFlags

export interface ReservedFlags

The effects-regime reserved flag quartet, extracted by the position-aware pre-scan and delivered on the Context (never as handler kwargs).

#NO_RESERVED_FLAGS

export const NO_RESERVED_FLAGS: ReservedFlags =

The quartet's all-false value: the programmatic dispatch paths' state.

#ReadOnlyContext

export interface ReadOnlyContext extends ContextBase

The context a read_only command's handler receives: its effects handle exposes only run, so a .write() inside a read-only command is a COMPILE error. The runtime seal fires regardless, because plain-JS consumers bypass the type system entirely.

#MutatingContext

export interface MutatingContext extends ContextBase

The context a mutating command's handler receives: the full handle.

#Context

export class Context implements MutatingContext

#contextIsHermetic

export function contextIsHermetic(ctx: Context): boolean

Package-internal accessor (NOT re-exported from index.ts, so not part of the public API): reports whether a framework Context ran under --hermetic. Used by the check-side ConnectionEnvReader wrapper so a check can distinguish "--hermetic suppressed the connection env" from "env var simply unset". Mirrors Go's wrapper reading frameworkCtx.infra directly and Python's _last_hermetic; the cast reaches the private infra snapshot without widening the handler-side Context surface.