Module types 

Core data model for Kranz missions (plan §4.2).

CONTRACT FILE — do not modify in implementation phases. If a change seems necessary, report it instead of editing.

All types serialize camelCase to match the plan document’s JSON shapes. plan.json, state.json, and event payloads are built from these types.

Structs

Assertion

BlockContext

Typed source and cause of a milestone block or its resolution. A present context is authoritative; unknown values never inherit legacy prose meaning.

CandidateLink

Sibling-candidate linkage for one stream of a heterogeneous dispatch pool (ticket heterogeneous-dispatch-pool, KRZ-303; the positioning ADR’s 2026-07-31 boundary gloss): one unit of work (a feature) fanned out to N configured backends concurrently, every output recorded as a CANDIDATE FOR JUDGEMENT tied to the same unit — never auto-merged into a winner.

CandidateSpec

One backend+model pairing in the heterogeneous dispatch pool (MissionConfig::worker_candidates, ticket heterogeneous-dispatch-pool / KRZ-303). Structured rather than a "backend/model" string so config::validate can apply the exact same backend/model pair checks as a role selection.

ConsideredAlternatives

DivergenceCandidate

One compared candidate stream on a divergence.noted event (ticket divergence-first-class-event, KRZ-304): the reference to the candidate DIFF the judgement act inspects — the run that produced it, the branch that carries it (KEPT: kranz/pool/<mission>/<unit>-c<index> is the deliverable), the backend that ran it, and the tree hash of the branch HEAD at record time. The hash pins the exact bytes the diverged verdict was computed from, so replay (provenance, the training corpus) re-reads the record without git; only streams that produced a run record appear (a stream that never started has no diff to compare).

ExecutorRoute

The effective executor route of one worker session (ticket routing-rules-config), recorded additively on worker.spawned: routing is provenance, not a hidden implementation detail. Derived once at fold time from mission.created’s original folded goal and routed config (crate::routing::seed_executor_route) — the determinism contract guarantees the recomputation equals the seed-time decision, so no new event payload is needed — then replayed onto each worker spawn.

Feature

Finding

A finding emitted by a validator (scrutiny or functional).

HookStatusConfig

Hook-derived status-signal lane config (ticket agent-hooks-status-signals, crate::hook_status): an OPTIONAL, off-by-default observability lane for backends with a lifecycle-hook surface (BackendKind::supports_hook_status_signals — cursor only today). When enabled, worker sessions on hook-capable backends get a per-run capability token + hook install that reports coarse signals (“running” / “needs input” / “interrupted” / “turn finished”) to endpoint; the signals land ONLY in the ephemeral .kranz/hook-status/ projection, never in mission state. When disabled (the default) every session is byte-identical to today — no hook config anywhere.

Milestone

Mission

MissionConfig

MissionState

PatternRoute

One PATTERN routing rule (ticket routing-rules-config): a task-class pattern routed to an executor capability class. The pattern language is deliberately tiny and deterministic — * matches any (possibly empty) run of characters, every other character is literal, comparison happens after the floor’s normalization (trim + ASCII-lowercase). Must be non-empty and unique within the pattern list after normalization — config::validate fails closed otherwise (a duplicate is dead config under first-match-wins).

PendingGrantRequest

A parked capability-grant request (see MissionState::pending_grant_request). Names the exact target a grant would unblock and the milestone whose validation hit the boundary, so the operator’s approve/deny decision — and the reducer’s cross-check on grant.approved/grant.denied — key off the same target that was requested.

PendingQuestion

An open structured human question (ticket structured-human-question-events), one entry of the pending-decision projection folded from question.opened (see MissionState::pending_questions). Carries the full context the dashboard and Slack need to render the decision without a join: the ask, its structured choices (empty = free text), and who/where it came from. Unlike PendingGrantRequest this parks NOTHING — the run loop does not gate on it; the question rides alongside the mission until the operator answers (question.answered) or it stops being actionable (question.cleared).

PendingRevision

PinnedGate

One pack gate declaration copied into the approval pin. Flight Rules checker execution consumes this snapshot, never a later mission-worktree lookup, so changing pack.toml on the mission branch cannot rewrite the command that judges that same mission.

PinnedRule

One rule’s approval-pinned snapshot inside StandardsPin — the consent surface (D-E): what the operator accepted, verbatim. Strings carry the pack contract’s canonical spellings (must/should, approved/enforced, stage names, the rendered checker binding) so an old log folds even if the pack vocabulary later grows additively.

Plan

The approved plan as emitted by the orchestrator and committed by the engine as the first commit on the mission branch (plan §4.4).

PlanFeature

PlanMilestone

ProvisionedPreview

A preview as provisioned by a remote workspace provider (ticket workspace-remote-coder-provider), recorded on workspace.provisioned: the URL the SUBSTRATE reported for a contract previews[] entry (name-matched — never fabricated), plus whether the substrate reports the URL is fronted with auth (design D-E: previews authenticated by default — recorded, never disabled by the adapter).

PtyScript

One scripted terminal session against an interactive target — the contract-side declaration a pty-script assertion carries (ticket pty-functional-validation). This is VALIDATOR tooling: the script judges what the delivered software DOES on a terminal, it never feeds work back into the mission (positioning ADR’s retained list).

RejectedAlternative

RemoteWorkspaceConfig

Remote substrate (Coder-shaped) connection config (ticket workspace-remote-coder-provider). Additive and serde-defaulted like the rest of the config contract. The substrate token comes from the environment variable NAMED by tokenEnv, read lazily at provision — never a value in config, logs, or events. VPN/SSH reachability of the substrate is an operator/network concern: no public IP is required, and the adapter never opens one.

ReportQuestion

One structured human question inside a WorkerReport (ticket structured-human-question-events). Deliberately id-less: the engine mints the question id at emit time (q-<n>, per-mission monotonic from the folded count), so a model-supplied id can never collide with or shadow another question’s.

ReviewerIndependence

Require a known model family different from every recorded worker attempt. Dispatch identity does not prove statistically independent mistakes.

RoleConfig

RoutingConfig

The backend routing table (ticket backend-routing-abstraction, KRZ-331): the declarative form of “task class → executor route”, making local endpoints, hosted frontier models, and hosted fine-tunes peers behind one routing interface. Resolved deterministically by crate::routing: the FIRST matching rule wins, no match falls through to ExecutorTier::Frontier, and an EMPTY table keeps the hardcoded literal floor (crate::config::task_class_to_tier) byte-for-byte.

RuleCitation

The standards rule a Finding cites (KRZ-343, design D-H): the join key that makes a checker verdict answerable to the approved manifest pin without parsing prose. Every field is the PINNED spelling (the consent snapshot StandardsPin carries), so a citation joins the mission’s approved policy even after the live pack moves on.

SandboxConfig

Per-role OS sandbox config.

StandardsPin

The approval-pinned standards manifest (KRZ-342, design D-E), carried on the plan contract as standardsManifest: pack identity + content digest, the selection inputs resolution ran with, and the applicable rule snapshots. The engine resolves and writes it at approval from the trusted source; every later mission stage consumes THIS snapshot — a mission branch edit or an external pack edit cannot reshape it.

StandardsRuleRef

One rule reference on a standards.resolved event (D-H): the compact, queryable form of a selection. The full snapshots ride in the plan’s StandardsPin; the event stays replay-cheap.

TaskClassRoute

One routing rule: a task class routed to an executor capability class.

TokenUsage

ValidatorReport

WorkerReport

WorkerRun

WorkspaceConfig

Workspace provider seam config (design D-B, ticket workspace-provider-seam): which crate::workspace_provider::WorkspaceProvider supplies the mission’s runnable environment. A DIFFERENT config surface from SandboxConfig — sandbox = process containment, workspace = the runnable environment — and the two stay separate even where runtime code could later be shared.

WorkspaceLifecycle

The last known workspace lifecycle transition (ticket workspace-idle-hibernate), folded from workspace.teardown events carrying a state: "kept" (mode keep), "stopped" (hibernate), "destroyed" (destroy), or "failed" (the provider call failed — the workspace may still be live). state is free-form on purpose so a future substrate-reported transition (e.g. an idle hibernate the substrate owns) folds into the same field without a schema change. ts is the transition event’s own timestamp — the workspace-hours anchor for cost tooling.

WorkspacePin

The workspace provider identity pinned at plan approval (design D-B, ticket workspace-provider-pin-at-approval) — the consent artifact naming the environment the operator approved running against. Free-form strings on purpose: the shape must not assume a provider kind. Per-kind meanings:

Enums

AssertionCheck

BackendKind

Which AgentBackend drives a role’s sessions.

BlockCause

BlockOwner

ControlCommand

ExecutorTier

Which inference tier executes a ticket, derived deterministically from its task-class frontmatter via crate::config::task_class_to_tier.

FeatureOrigin

FeatureStatus

GrantKind

What a grant would extend on approval. All kinds park through the SAME operator approve/deny gate (and reuse its timeout + per-milestone cap); they differ only in the boundary that triggered them and what the reducer extends. #[default] = Command so pre-kind events (and the wire default) fold as the original command-grant behaviour.

MilestoneStatus

MissionStatus

PtyStep

One step of a PtyScript, serde-tagged on op: {"op":"send","text":"…"} / {"op":"expect","pattern":"…",…}.

Role

RunResult

SandboxEnforce

OS sandbox enforcement level for a role’s sessions.

SandboxProvider

Which sandbox mechanism wraps a role’s sessions when enforce is on.

StandardsPinSource

Where the pinned standards bytes came from (KRZ-342 D-A/D-E) — the trust posture approval resolved under, recorded so later stages know whether a live-base re-read exists at all.

WorkerIsolation

How worker/validator sessions are isolated from the primary checkout.

Constants

DEFAULT_RUBBER_STAMP_THRESHOLD_MS

Default for MissionConfig::rubber_stamp_threshold_ms (ticket rubber-stamp-grant-flag): the docs/metrics.md §2 sub-ten-second bucket, made configurable. A grant APPROVED in under this latency is flagged as a rubber-stamp signal in the outcomes report — a flag, never an enforcement.