runtime

type Action struct {
	Ref           string
	TrustContract TrustContract
}

type ActionDispatcher interface {
	Dispatch(ctx context.Context, ref string, args map[string]any) (DispatchResult, error)
}

type ApprovalRequest struct {
	// ActionRef is the action awaiting a decision.
	ActionRef string
	// Effect is the operation effect that routed this action to approval.
	Effect Effect
	// Args is a redacted summary of the resolved args presented to the
	// approver. Never secrets (bindings are references).
	Args map[string]any
}

type Approver interface {
	Approve(ctx context.Context, req ApprovalRequest) (Decision, error)
}

type Artifact struct {
	Name     string
	Path     string
	MimeType string
	// Content is the materialized utf-8 bytes. Empty for a target:none
	// artifact (recorded but not written).
	Content []byte
	// Digest is the sha256 of Content, formatted `sha256:<hex>`. It is computed
	// at construction over the exact bytes writeArtifacts lands on disk, so an
	// operator can independently verify a loose output file against the digest
	// recorded in the per-launch audit (ADR-0027 snapshot identifier). Empty
	// content hashes deterministically to the sha256 of zero bytes, so the
	// digest is always recordable — including for a target:none artifact that
	// is retained but never written.
	Digest string
	// Written reports whether the artifact should be written to disk
	// (publish target `file`) vs retained in the run record only (`none`).
	Written bool
}

type AuditRecord struct {
	// Kind is the record's kind, the explicit discriminator the CLI sink maps
	// to a model.EventType (RecordKindAction → flightplan.launch.action,
	// RecordKindLaunch → flightplan.launch, RecordKindOutput →
	// output.materialized, RecordKindReach → flightplan.launch.reach,
	// RecordKindSeam → flightplan.launch.seam).
	Kind AuditRecordKind
	// ActionRef is the action the record describes, or "" for a per-launch
	// summary or per-output record.
	ActionRef string
	// Fields holds the declared audit field values. For a RecordKindOutput
	// record it holds the flat `aileron.*` attribute map the sink surfaces as
	// the top-level event payload.
	Fields map[string]any
	// Sink is the customer-owned sink reference from the trust contract.
	Sink string
}

type AuditRecordKind int

type AuditSink interface {
	Record(ctx context.Context, rec AuditRecord) string
}

type AuditStructure struct {
	Fields []string
	Sink   string
}

type Binding struct {
	Kind BindingKind
	// Raw is the original binding string, retained for error messages and
	// audit summaries.
	Raw string
	// Name is the input name for BindInput.
	Name string
	// StepID and Output identify a prior step output for BindStep.
	StepID string
	Output string
}

type BindingKind int

type Clock interface {
	Now() time.Time
}

type Constraint struct {
	Enum    []string
	Pattern *regexp.Regexp
}

type Decision struct {
	Approved bool
	// Pending reports that no decision has landed yet, so the run suspends at
	// this action-call instead of blocking. Mutually exclusive with Approved.
	Pending bool
	// Reason carries an optional human reason recorded in the audit on deny.
	Reason string
}

type DecodeError struct {
	Reason string
}

type DenyError struct {
	ActionRef string
	Reason    string
}

type DispatchResult struct {
	// Output is the action's result payload, a JSON-shaped map the runtime
	// binds downstream steps against and redacts before surfacing.
	Output map[string]any

	// ConnectorVersion is the pinned semantic version of the connector that
	// produced the result.
	ConnectorVersion string
	// ConnectorHash is the connector's content hash (`sha256:<hex>`).
	ConnectorHash string
	// IdentityLabel is the non-secret identity label of the credential
	// binding the action used, or "" when none resolved.
	IdentityLabel string
	// CredentialBinding is the name of the credential binding the action
	// used (a reference, never the secret), or "" when none resolved.
	CredentialBinding string
	// ConsentDecision is the consent posture the action ran under
	// (`unattended` on the synchronous read path), or "" when unset.
	ConsentDecision string
}

type Effect string

type Encoding string

type FixedClock struct{ T time.Time }

type Idempotency struct {
	SafeToRetry    bool
	IdempotencyKey bool
}

type ImageRunResult struct {
	// ContentHash is the verified content hash of the frozen unit that ran.
	ContentHash string
	// ResolvedInputs is the frozen resolved-input set.
	ResolvedInputs map[string]any
	// StepOutputs maps steps.<id> → its named outputs.
	StepOutputs map[string]map[string]any
	// Artifacts are the materialized output artifacts.
	Artifacts []Artifact
	// AuditIDs are the audit record ids emitted to the sink.
	AuditIDs []string
}

type ImageRunSpec struct {
	// Image is the exact `ref@sha256:<hex>` the verified lock pinned. It is the
	// load-bearing security value: the runner MUST boot this image verbatim so
	// the environment entered corresponds to the lock's signed assertion.
	Image string
	// Name is the frozen skill name (the store selector).
	Name string
	// Version is the frozen version id (the store directory id).
	Version string
	// Inputs are the literal input overrides supplied at launch.
	Inputs LaunchArgs
	// OutDir is the directory file-target artifacts are written to. Empty skips
	// writing (artifacts are still recorded in the result).
	OutDir string
}

type ImageRunner interface {
	Run(ctx context.Context, spec ImageRunSpec) (ImageRunResult, error)
}

type Input struct {
	Name        string
	Type        InputType
	Description string
	Resolution  Resolution
	// Constraint bounds the resolved value. Nil means unconstrained (today's
	// behavior). When non-nil it holds exactly one of an Enum allow-set or a
	// compiled Pattern; the launch/resolution boundary rejects a resolved
	// value that falls outside it.
	Constraint *Constraint
	// HasExample records whether the manifest declared an example value. It
	// mirrors the Resolution.HasDefault/Default pair so a declared example of a
	// zero-ish value (empty string, false, 0) is still distinguishable from an
	// absent one.
	HasExample bool
	// Example is the declared first-class example value the guided launch walk
	// displays on the prompt line. It is deliberately untyped so an example may
	// be a string, number, object, or array. Meaningful only when HasExample is
	// true; it never affects resolution or required-ness.
	Example any
	// NoPrompt marks an advanced or non-interactive input the guided launch walk
	// skips (the manifest's `prompt: false`). The zero value is promptable, so an
	// input with no `prompt` key walks as usual. A skipped input's declared
	// default applies silently and it stays overridable via --input.
	NoPrompt bool
}

type InputPrompter interface {
	PromptInput(in Input) (string, error)
}

type InputType string

type InputWalker interface {
	Walk(inputs []Input, args LaunchArgs) (LaunchArgs, error)
}

type LLMSeam interface {
	Run(ctx context.Context, req SeamRequest) (map[string]any, error)
}

type LaunchArgs map[string]any

type LoadError struct {
	Reason string
}

type LoadedPlan struct {
	Plan        *Plan
	ContentHash string
	// ResolvedImages carries the verified image digest pins from the frozen
	// lock. When non-empty, Run boots the pinned image and
	// runs the plan inside it; when empty, Run stays on the in-process path.
	// The pins come from the verified manifest lock block, so the digest booted
	// is exactly the one the author signature attested.
	ResolvedImages []freeze.ImagePin
	// StepTrust is the verified lock's sealed per-step reach
	// (lock.stepTrust), keyed by tool step id (#1829). It is the ONLY source
	// of the network reach the runtime enforces for a tool step: the
	// frontmatter trust-contract copy is audit context, never the enforcement
	// input, so a reach can never be re-supplied at launch. Populated only on
	// the verified path. Nil when the frozen unit seals no tool-step reach.
	StepTrust map[string]freeze.StepReach
	// SignerFingerprint is the `sha256:<hex>` fingerprint of the verified
	// author public key (from freeze.VerifyFrozen). It is threaded into the
	// launch audit as the plan's signer identity (#1752). Populated only on the
	// verified path, so it names the key that actually attested this unit.
	SignerFingerprint string
	// Publisher is the connector-style publisher authority the frozen plan
	// declares in its verified lock (`github://owner/repo` or bare
	// `github://owner`), or "" when the plan declares no publisher. The
	// host-side publisher-trust gate (#1900) enforces trust only when this is
	// non-empty. Populated only on the verified path from freeze.VerifyFrozen,
	// so a tampered publisher refuses at verification before it is read here.
	Publisher string
	// SignerKey is the raw ed25519 public key the plan's signature verified
	// against (from freeze.VerifyFrozen). The publisher-trust gate checks its
	// membership in the keyring for the declared Publisher. Populated only on
	// the verified path.
	SignerKey ed25519.PublicKey
	// ImageOrigin is the recorded install source for a plan installed by OCI
	// reference (#1902/#1903), read from the store's non-signed origin sidecar.
	// Present is true only when the version directory carries the sidecar (an
	// OCI install); a locally-frozen plan leaves it zero, which is exactly the
	// signal runInImage uses to stay on the local-tag boot path. The origin is
	// a fetch coordinate, NOT a verification trust anchor: the pulled image is
	// still verified against the signature-covered ResolvedImages pin.
	ImageOrigin RegistryImageOrigin
}

type LocalImageDigestResolver interface {
	Resolve(ctx context.Context, image string) (string, error)
}

type Options struct {
	// Store is the canonical skill store the frozen unit loads from.
	Store *store.Store
	// Name is the frozen skill name.
	Name string
	// Version is the frozen version id (the store directory id).
	Version string

	// Inputs are the literal input overrides supplied at launch.
	Inputs LaunchArgs

	// Dispatcher is the action boundary seam (required to run any action-call
	// or source input).
	Dispatcher ActionDispatcher
	// Approver routes effect-gated actions (required when any non-read action
	// runs).
	Approver Approver
	// Audit receives the customer-owned audit records. Nil emits no audit.
	Audit AuditSink
	// Seam is a marked LLM seam. Nil (the v1 default) makes any llm-seam step
	// error on the non-suspendable path, so a default launch reaches no LLM. A
	// plan may declare more than one seam (#2100); each is served by this one
	// provider.
	Seam LLMSeam

	// Suspendable opts this run into the generic suspend/resume path (#2100).
	// When true, the runtime SUSPENDS (returns a nil error with
	// RunResult.Pending set) at the first step it cannot complete in-band: an
	// unfulfilled llm-seam (no memo entry, no wired Seam value) or a gated
	// action-call whose Approver returned Decision.Pending. When false (the
	// default), behavior is exactly as before: a nil Seam is a hard error and a
	// pending Approver decision is impossible (a synchronous approver never
	// returns pending). A non-nil ResumeOutputs also implies a suspendable run,
	// so a resume never needs both flags set.
	Suspendable bool
	// ResumeOutputs is the caller-supplied memo (stepId → its named outputs) from
	// a prior suspend, replayed on resume. Every step whose id is present here is
	// injected WITHOUT re-execution (exactly-once for effects) and re-audits
	// nothing. Nil on a fresh launch. A non-nil value implies Suspendable.
	ResumeOutputs map[string]map[string]any
	// RunID is stable across a suspend/resume sequence. The runtime mints one
	// when empty and echoes it on the suspend result, so every call in a sequence
	// shares the same id.
	RunID string
	// ImageRunner boots the verified pinned environment image and runs the
	// plan inside it. When the loaded plan carries a resolved image pin and this
	// seam is wired, Run delegates to it; when the plan pins no image, Run stays
	// on the in-process path and never touches this seam. A plan that pins an
	// image with no ImageRunner configured is an explicit error, never a silent
	// in-process fallback (a declared environment must be entered to honor the
	// attestation).
	ImageRunner ImageRunner
	// ImageDigestResolver re-checks, at boot time, that a composed-tools pin's
	// LocalTag still resolves in the local daemon to the host platform's attested
	// config content digest (#1863). It is consulted ONLY on the composed boot
	// path (pin.LocalTag != ""): a composed image is booted by its mutable local
	// tag (its recorded content digest is a locally-built image Id, not a registry
	// digest, so `ref@digest` would not resolve), and nothing else re-checks that
	// the daemon image behind that tag is still the attested one. When this seam is
	// wired and the pin is composed, the resolved digest MUST equal the host
	// platform's entry from the pin's per-arch configDigests set or the boot fails
	// closed (no ImageRunner.Run call); a plan not built for this host's platform is
	// likewise fail-closed, as is a resolve error (the
	// attested image is absent). Nil (the zero value) skips the guard and boots as
	// before (backward-compatible), mirroring the ImageRunner nil-guard discipline.
	ImageDigestResolver LocalImageDigestResolver
	// RegistryImageResolver pulls and verifies the published image for a plan
	// installed by OCI reference (#1903). It is consulted ONLY when the loaded
	// plan carries a registry origin (LoadedPlan.ImageOrigin.Present): such a
	// plan has no local build, so runInImage pulls the published image from the
	// recorded registry, verifies it against the signed lock pin per the pin's
	// binding kind, and boots the returned reference. When the plan needs this
	// seam (a registry origin) but it is nil, the boot is a fail-closed error,
	// never a silent fall-through to the local-tag path (a plan installed from a
	// registry has no local tag to boot). A locally-frozen plan (no origin)
	// never touches this seam and boots by its local tag as before. The CLI
	// wires the production impl over pull.PullImage and nils it on the image-boot
	// re-entry (the sentinel routes in-process before any boot).
	RegistryImageResolver RegistryImageResolver
	// ToolRunner executes a `kind: tool` step as a deterministic subprocess in
	// the current pinned environment (#1829). Unlike ImageRunner, the plan
	// orchestration stays in-process (runPlan); the tool step never dispatches
	// a sibling container. When a loaded plan carries a tool step and this
	// seam is unset, that step is an explicit error, never a silent skip
	// (mirrors the ImageRunner nil-guard discipline).
	ToolRunner ToolStepRunner
	// PublisherVerifier is the host-side publisher-trust gate (#1900). When it
	// is wired and the loaded plan declares a publisher in its verified lock,
	// Run resolves the plan's verified signing key against the operator's
	// keyring for that publisher and refuses to run when the publisher is not
	// trusted (fail-closed), before any boot or step. Nil skips the gate; a
	// plan that declares no publisher also skips it. The CLI wires the
	// keyring-backed impl for a host launch and wires nil on the image-boot
	// re-entry (the host already gated before boot, and no keyring is mounted
	// into the sealed container).
	PublisherVerifier PublisherVerifier
	// InPinnedImage marks this run as already executing INSIDE the verified
	// pinned environment image, the image-boot re-entry (#1731). It routes
	// a whole-plan-pinned unit onto the in-process path instead of booting the
	// pin again: inside the container, in-process IS the certified
	// environment, and re-booting would recurse (the image carries no nested
	// container runtime, and with one it would never terminate). The CLI sets
	// this from the AILERON_SKILL_IMAGE_BOOTED sentinel the image runner
	// injects into the boot env.
	InPinnedImage bool

	// Clock supplies the single launch-time read for dynamic inputs. Nil uses
	// SystemClock.
	Clock Clock
	// Transforms is the deterministic transform registry. Nil uses the
	// default registry.
	Transforms *TransformRegistry

	// InputPrompter resolves a missing required literal input interactively at
	// the launch boundary (a literal input with no `--input` override and no
	// declared default). When it is wired, resolveInputs asks it for the value
	// instead of failing; when it is nil (the default), the runtime keeps
	// today's fail-fast error, so a piped or CI launch never blocks on input.
	// The CLI wires it only when stdin is a TTY. A prompted value is a string
	// treated identically to a `--input name=value` override: it is deep-copied
	// into the frozen resolved set and validated by the same final constraint
	// pass.
	//
	// On the interactive path the InputWalker (below) resolves every literal into
	// Inputs before either branch runs, so a still-wired InputPrompter is never
	// consulted there; the seam is retained for the non-walk path and its own
	// tests.
	InputPrompter InputPrompter

	// InputWalker runs a host-side interactive pass over every declared literal
	// input BEFORE the image-boot / in-process branch (#2063), collecting a value
	// for each into Inputs. It is the only interactive seam that reaches the
	// sealed-image mainline: the in-container prompter is never consulted for a
	// whole-plan-pinned unit (Run short-circuits to the boot before resolveInputs
	// runs), so wiring only InputPrompter would ship the guided walk inert on the
	// primary path. Run consults it only when it is non-nil AND this run is NOT
	// the in-container image-boot re-entry (InPinnedImage): the re-entry runs
	// non-TTY and must never re-walk, so gating on InPinnedImage makes
	// no-recursion structural rather than dependent on the container's TTY state.
	// Nil (the default) skips the walk and keeps today's silent-default one-shot
	// launch. The CLI wires it only on an interactive TTY without
	// `--accept-defaults`.
	InputWalker InputWalker

	// OutDir is the directory file-target artifacts are written to. Empty
	// skips writing (artifacts are still recorded in the result).
	OutDir string
}

type Output struct {
	Name     string
	MimeType string
	Encoding Encoding
	Target   PublishTarget
	Path     string
}

type PendingApprovalError struct {
	// ActionRef is the action awaiting a decision.
	ActionRef string
	// Effect is the operation effect that routed this action to approval.
	Effect Effect
	// Args is the redacted args summary the approver was shown, carried through
	// so the suspend result presents the same request without re-deriving it.
	Args map[string]any
}

type Plan struct {
	// Name is the skill name from the manifest frontmatter.
	Name string
	// Actions are the declared action requirements indexed by ref. The
	// trust contract drives approval routing, idempotency, redaction, and
	// audit for each action-call.
	Actions map[string]Action
	// Inputs are the declared inputs in declaration order. Each resolves
	// once at the launch boundary.
	Inputs []Input
	// Outputs are the declared output artifacts indexed by name.
	Outputs map[string]Output
	// Steps are the step-graph steps in declaration order. The executor
	// walks them in a topologically-sorted order (see Order).
	Steps []Step
	// Order is the deterministic topological order of step indices the
	// executor walks, computed from `steps.*` edges only.
	Order []int
}

type PublishTarget string

type PublisherVerifier interface {
	VerifyPublisher(publisher string, signingKey ed25519.PublicKey) error
}

type RedactionKind string

type RedactionRule struct {
	Field string
	Rule  RedactionKind
}

type RegistryImageOrigin struct {
	// Registry is the registry+repository the published image lives in (e.g.
	// "ghcr.io/acme/plan"), without tag or digest.
	Registry string
	// VersionTag is the store version id (freeze slug) the artifact was published
	// under; the composed image was published under a tag derived from it.
	VersionTag string
	// Present reports whether the loaded plan carries a registry origin. When
	// false, the runtime stays on the local-tag boot path; when true, the runtime
	// pulls and verifies the published image via RegistryImageResolver.
	Present bool
}

type RegistryImageResolver interface {
	Resolve(ctx context.Context, origin RegistryImageOrigin, pin freeze.ImagePin) (bootRef string, err error)
}

type Resolution struct {
	Rule ResolutionRule
	// Literal fields.
	HasDefault bool
	Default    any
	// Dynamic field: "now" or "today".
	DynamicValue string
	// Source fields.
	SourceActionRef string
	SourceSelect    string
}

type ResolutionRule string

type ResolvedInputs struct {
	// Values maps input name → resolved value.
	Values map[string]any
	// SourceBindings records, per source input, the resolved binding the read
	// was recorded by (action ref + select), never the dataset inline. This
	// is what the audit references (ADR-0027 audit boundary).
	SourceBindings map[string]SourceBinding
}

type RunResult struct {
	// ContentHash is the verified content hash of the frozen unit that ran.
	ContentHash string
	// ResolvedInputs is the frozen resolved-input set (Phase A output).
	ResolvedInputs map[string]any
	// StepOutputs maps steps.<id> → its named outputs.
	StepOutputs map[string]map[string]any
	// Artifacts are the materialized output artifacts.
	Artifacts []Artifact
	// AuditIDs are the audit record ids emitted to the sink.
	AuditIDs []string
	// Pending is set (non-nil) when the run SUSPENDED instead of completing
	// (#2100): a suspendable run hit an unfulfilled seam or a pending approval.
	// A completed run has Pending == nil. When Pending is set, StepOutputs /
	// Artifacts / AuditIDs reflect only what completed THIS call, and the caller
	// fulfills the pending step (SuspendResult) and resumes with the carried
	// memo. Run returns a nil error alongside a non-nil Pending: a suspend is not
	// a failure.
	Pending *SuspendResult
}

type SeamRequest struct {
	StepID   string
	Bindings map[string]any
	// Outputs are the named results the seam must produce.
	Outputs []string
	// Prompt is the seam's sealed instruction template (#2105), carried so a
	// suspend/resume caller (#2101) can present it to the agent that fulfills the
	// seam. Empty when the seam declares no prompt. It is the frozen template
	// verbatim; a caller that wants the bindings rendered in resolves them from
	// Bindings.
	Prompt string
	// Model is the seam's recorded model target hint (#2105), for example
	// anthropic:claude-haiku-4-5. A request/hint, never a pin. Empty when the
	// seam declares no model.
	Model string
}

type SourceBinding struct {
	ActionRef string
	Select    string
}

type Step struct {
	ID        string
	Kind      StepKind
	ActionRef string
	// Transform names the deterministic transform to apply, selected from the
	// runtime's closed TransformRegistry. Meaningful only for KindTransform;
	// empty means the identity passthrough (the v1 default). Never carries an
	// LLM-backed transform: that is what KindLLMSeam is for.
	Transform string
	// Args binds action-call argument names to binding references.
	Args map[string]Binding
	// Bindings binds transform / tool / llm-seam input names to binding
	// references.
	Bindings map[string]Binding
	// Outputs are the named results this step produces, referenced by a
	// later step as steps.<id>.<output>.
	Outputs []string
	// MaterializesOutput names a declared output this step's result
	// materializes into. Empty when the step materializes nothing.
	MaterializesOutput string

	// Command is the argv the tool step executes: the first element is the
	// program, the rest its arguments. Always exec'd directly (no shell), so
	// the signed invocation carries no injection surface.
	Command []string
	// MountPath is the in-environment path the resolved step input is
	// written to (as input.json), or empty when the step declares no mount.
	MountPath string
	// CollectPath is the in-environment path whose contents are collected
	// as the step's single declared output, or empty when the step declares
	// no collect.
	CollectPath string
	// TrustContract, when non-nil, is the tool step's declared per-step
	// trust contract: its Hosts declare the step's network reach and Effect
	// the operation effect, validated at decode exactly like an action's
	// contract. The reach the runtime ENFORCES comes from the verified
	// lock's sealed stepTrust section (LoadedPlan.StepTrust), never from
	// this frontmatter copy; a contracted tool step with no sealed entry is
	// a load refusal. Nil when the step declares no reach.
	TrustContract *TrustContract

	// Prompt is the seam's sealed instruction template, using the plan's
	// `{{ inputs.<name> }}` / `{{ steps.<id>.<output> }}` binding grammar. Empty
	// when the seam declares no prompt. Audit-only; unconsumed in v1.
	Prompt string
	// Model is the seam's recorded model target (for example
	// anthropic:claude-haiku-4-5). It is a request/hint recorded not enforced,
	// never a pin. Empty when the seam declares no model. Audit-only;
	// unconsumed in v1.
	Model string
}

type StepKind string

type SuspendKind int

type SuspendResult struct {
	// RunID is stable across the whole suspend/resume sequence. The runtime mints
	// one when Options.RunID is empty and echoes the provided one on resume, so
	// every call in a sequence shares the same id.
	RunID string
	// Kind discriminates the suspend reason (seam vs approval).
	Kind SuspendKind
	// StepID is the id of the step the run suspended at.
	StepID string

	// Seam is populated for a SuspendKindSeam suspend: the SeamRequest-shaped
	// payload the caller's provider (#2101) needs to produce the seam's outputs.
	// Nil for a SuspendKindApproval suspend.
	Seam *SeamRequest
	// Approval is populated for a SuspendKindApproval suspend: the
	// ApprovalRequest-shaped payload the caller's approval surface (#2101)
	// presents. Nil for a SuspendKindSeam suspend.
	Approval *ApprovalRequest

	// StepOutputs is the accumulated memo AT THE POINT OF SUSPENSION: every step
	// whose output was already memoized (injected this call) plus every step that
	// actually executed this call, keyed by step id. On resume the caller passes
	// this back as Options.ResumeOutputs (with the newly-fulfilled step's output
	// added, for a seam) so the runtime replays the completed prefix without
	// re-executing it.
	StepOutputs map[string]map[string]any
	// AuditIDs are the audit record ids emitted DURING THIS CALL only. Steps
	// injected from the memo re-audit nothing, so a multi-resume sequence records
	// each real execution exactly once. A suspend emits no per-launch summary
	// record; the terminal (completing) resume emits it.
	AuditIDs []string
}

type SystemClock struct{}

type ToolStepResult struct {
	// Output is the value read back from CollectPath. It becomes the step's
	// named output; a step that declared no collect returns a nil Output.
	//
	// The production runner returns the collect file's RAW BYTES as a
	// string, never a decoded structure. That is the same contract the
	// materialize path already speaks: a string carrier is parsed as the
	// JSON it emitted (decodeCarrier), so a tool that wants its collected
	// output to materialize as a file artifact writes a file-map JSON
	// document ({path, mimeType, encoding, content}) or a JSON data
	// object/array to its collect path. A non-JSON collect file still flows
	// to downstream bindings as a plain string; it only refuses at the
	// materialize boundary if a step tries to materialize it directly.
	Output any
}

type ToolStepRunner interface {
	Run(ctx context.Context, spec ToolStepSpec) (ToolStepResult, error)
}

type ToolStepSpec struct {
	// StepID is the executing step's id, for scope addressing and error
	// context.
	StepID string
	// Command is the argv to exec: Command[0] is the program, the rest its
	// arguments. It comes from the verified manifest, is exec'd with no
	// shell interpretation, and is the executed-command identity the audit
	// records.
	Command []string
	// MountPath is the in-environment directory the resolved Input is
	// written to before the exec (the read side of the mount boundary).
	// Empty means the step declared no mount and no input file is written.
	MountPath string
	// Input is the step's resolved binding input, written under MountPath.
	// It is a binding-resolved value only, never a credential (credentials
	// are injected host-side at the network boundary, not here).
	Input any
	// CollectPath is the in-environment path whose contents are read back as
	// the step's output (the run-and-collect boundary). Empty means the step
	// declared no collect and the step produces no collected output.
	CollectPath string
	// Hosts is the step's SEALED network reach from the verified lock's
	// stepTrust section, never the re-read frontmatter. Non-empty means the
	// runner MUST run the subprocess under a step-scoped proxy credential
	// registered for exactly these hosts, and MUST fail closed (never run
	// unscoped) when it cannot obtain one. Empty means the step declared no
	// reach and runs under the plan-boot proxy environment unchanged.
	Hosts []string
	// CredentialKind and IdentityLabel carry the step's declared credential
	// identity (its kind and non-secret identity label from the trust
	// contract), threaded to the runner so the step-scope mint tells the
	// daemon which credential identity the step's outbound requests belong
	// to (#1980). They are the declared identity, never credential material
	// (credentials are injected host-side at the network boundary). Both are
	// "" when the step declares no trust contract or no credential identity;
	// the mint then sends no credential block and the scope stays
	// unconstrained, exactly as before. Carried, not yet consumed for egress
	// selection (the umbrella's next sub-issue).
	CredentialKind string
	IdentityLabel  string
}

type Transform func(bindings map[string]any, outputs []string) (map[string]any, error)

type TransformRegistry struct {
	// contains filtered or unexported fields
}

type TrustContract struct {
	CredentialKind string
	Hosts          []string
	Paths          []string
	Effect         Effect
	Idempotency    Idempotency
	Redaction      []RedactionRule
	IdentityLabel  string
	Audit          AuditStructure
}