#typescript/src/effects

#typescript/src/effects

The effects regime: the ctx.effects handle, Unsettled carriers, dry mode's would-do log, and the runtime seal that makes a preview honest.

Two rules govern the whole module and override any local convenience:

• FAIL CLOSED. When the framework cannot prove an operation is safe to

preview, it stops with a precise error instead of guessing.

• ZERO INFERENCE. Nothing is inferred -- not classification, not whether an

argument is a path, not whether a resource is current.

The method set is CLOSED at eight (run, spawn, write, mkdir, remove, rename, chmod, http). CACHE_WRITE has no public method: it is minted only by framework-internal code (schema dump, coverage shards and manifest) and is unreachable from application code.

Every effect method's declared return type is its SETTLED shape and nothing else -- there is no | Unsettled union anywhere in the surface and no narrowing predicate. In dry mode the runtime value at those positions is the Unsettled Proxy, which the static type deliberately does not mention: a handler that only forwards it never notices, and a handler that extracts from it or branches on it trips the runtime seal and truncates the preview. One handler body, both modes.

Parity source: python/strictcli/__init__.py (the reference implementation).

#EffectKind

export type EffectKind =

The coarse taxonomy of an effect, and the set a Grant may be declared for. cache_write is deliberately absent: it is unreachable from application code, so nothing could ever use such a grant.

#CACHE_WRITE

export const CACHE_WRITE = "cache_write"

Framework-blessed cache writes. No public method mints one.

#isGrantableKind

export function isGrantableKind(kind: unknown): kind is EffectKind

True when kind names one of the four grantable effect kinds.

#Effect

export type Effect = "read_only" | "mutating"

The two legal command classifications. There is no default.

#Grant

export interface Grant

A per-command, per-effect-kind authorization with a mandatory reason.

A grant is not permission to do something otherwise forbidden; it is a LABELLED reason that surfaces in the preview so a reviewer reading a dry run sees why a dangerous step is there.

#Forwarding

export interface Forwarding

Declares that a handler deliberately accepts and forwards its arguments. Inert in TypeScript beyond the schema emission (guard v2's enforcement is Python-only -- a TS handler takes a typed args object, which cannot be introspected for a var-keyword parameter), but declared in all three implementations so the API surface stays in parity.

#Completed

export interface Completed

The result of a subprocess that ran to completion.

stdout/stderr are the child's output decoded as UTF-8 strictly, with a single trailing newline removed if present -- the form that can be forwarded straight into a later effect's argv.

#Response

export interface Response

The result of an HTTP request. Header names are lower-cased.

#Spawned

export interface Spawned

A handle for a started-but-not-awaited child process.

#EffectRecord

export interface EffectRecord

One entry in the structured effect log (the conformance surface's shape).

#DRY_RUN_HEADER

export const DRY_RUN_HEADER = "DRY RUN — no changes were made. Would do:"

The would-do log's header line. The dash is U+2014 EM DASH.

#EffectLog

export class EffectLog

The ordered effect records produced by one dispatch.

#effectTypeName

export function effectTypeName(v: unknown): string

Runtime type name for the effect argument type-guard messages.

#EffectsCommandView

export interface EffectsCommandView

What the effects handle needs to know about the running command.

#ReadOnlyEffects

export interface ReadOnlyEffects

The read-only slice of the effects handle: observes and nothing else.

#MutatingEffects

export interface MutatingEffects extends ReadOnlyEffects

The full effects handle: exactly eight methods, and the set is CLOSED.

#Effects

export class Effects implements MutatingEffects