execution

type AttemptState string

type CanarySafety interface {
	// Breach reports that an authoritative whole-Canary breach OCCURRED. code is a
	// canary.AbortConditions() taxonomy code; an unrecognised code fails closed to a
	// whole-Canary latch at the controller, so a typo can only ever stop the experiment, never
	// silently continue it.
	Breach(capability string, gen uint64, code string)

	// AttemptSettled reports ONE settled post-admission attempt so the composition layer's
	// population detectors (elevated error rate, latency pathology) can judge. failed is an
	// ordinary execution failure; latency is the observed attempt duration.
	//
	// The engine reports only ADMITTED attempts that settled. It does NOT report request-scoped
	// denials — a policy deny, a scope refusal, an allowance already consumed — because those are
	// what a healthy Canary does all day, and counting them would let a Canary abort itself for
	// correctly refusing requests. Conditions carrying their own immediate whole-Canary
	// classification are likewise not laundered through a rate: they trip directly.
	AttemptSettled(capability string, gen uint64, failed bool, latency time.Duration)
}

type Config struct {
	// State is the capability-local rollout state (Gateway). Required.
	State *rollout.State
	// Broker materializes the approved-server credential (nil ⇒ no credential is
	// attached; the upstream call carries no Authorization).
	Broker *broker.Broker
	// Events is the PR-8 durable-event manager. Required for the commit-before-
	// side-effect guarantee; a nil Events fails every execution closed.
	Events *events.Manager
	// Upstream is the bounded upstream MCP client. Required.
	Upstream UpstreamCaller
	// ResponseProfile is the PR-7 inspection profile used to inspect + DLP the
	// upstream response before returning it to the client.
	ResponseProfile inspection.Profile
	// Metrics is the optional rollout telemetry sink.
	Metrics Metrics
	// Clock is injected for tests; nil ⇒ time.Now.
	Clock func() time.Time
	// Actor labels events emitted by this executor.
	Actor string
	// LiveGate is the OPTIONAL composition-layer side-effect gate consulted at the boundary
	// BEFORE the executor's own tool-freshness + emergency-kill re-check, so the kill re-read
	// stays the LAST authoritative check before Upstream.Call (PREREQ-MCP-KILL-1). It owns the
	// gates that live OUTSIDE this package — Canary blast-radius budget reservation, runtime
	// live-execution trust revalidation, and read-first enforcement. nil ⇒ the executor is
	// byte-identical to the pre-gate path (the ShadowEvaluator and any non-live composition
	// never set it). See livegate.go.
	LiveGate LiveExecutionGate
	// Safety is the OPTIONAL narrow whole-Canary breach seam (blocker #7). Nil means no Canary is
	// composed; it is replaced by a no-op so call sites never branch. It is deliberately separate
	// from Metrics — see safety.go for why observability and control must not share a sink.
	Safety CanarySafety
}

type CredentialPlanner interface {
	Plan(broker.PlanInput) (broker.CredentialPlan, error)
}

type Discovery struct {
	Registry *registry.Registry
	Catalog  *catalog.Catalog
	Upstream UpstreamCaller
	// OnIngest, when set, is invoked after a SUCCESSFUL catalog ingest (a new snapshot was
	// published). Ingestion can only ever land a tool Quarantined/ReviewRequired — it never
	// produces catalog.Usable — so a re-discovered tool that exactly matches an active trust
	// approval would otherwise stay non-Usable until the next inventory read, Shadow
	// preflight, or the periodic 30s reconcile tick, contaminating an in-flight Shadow
	// experiment. The composition root wires this to the tool-trust reconcile hook so the
	// approval's projection is re-materialized immediately. Optional and nil-safe; it must
	// only WITHDRAW-or-re-affirm trust (it can never widen usability), so calling it here is
	// safe even though this package holds no trust authority.
	OnIngest func()
	// IngestGuard, when set, runs the catalog ingest (its snapshot PUBLISH) inside the
	// tool-trust reconcile critical section so a catalog revision advance is MUTUALLY
	// EXCLUSIVE with an in-flight trust approval. Without it, ingestion advances the live
	// catalog revision without holding the coordinator's derive lock, so an approval that
	// captured the pre-advance revision between its target load and its durable commit would
	// validate a stale copy — an identical rediscovery (same fingerprint, bumped revision) or
	// an F1→F2→F1 flap in that window would be approved instead of returning the required
	// stale-target conflict (ADR-0034 optimistic concurrency, PR round-15). Optional and
	// nil-safe; when nil the ingest runs directly. Like OnIngest it only ever gates WHEN a
	// publish lands, never what a publish produces, so carrying it grants this package no
	// trust authority.
	IngestGuard func(ingest func() error) error
}

type EvidenceReader interface {
	CommittedForExport(part model.Partition, afterSeq uint64, maxRecords int) ([]model.Event, []uint64, uint64, error)
}

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

type LiveExecutionGate interface {
	// AdmitSideEffect decides whether this request may cross the irreversible upstream
	// boundary. It performs NO upstream call and NO credential materialization.
	AdmitSideEffect(in LiveGateInput) LiveGateDecision

	// AdmitAuxiliary decides whether a NON-side-effect-bearing invocation — MCP
	// lifecycle and discovery traffic — may cross the same upstream boundary.
	//
	// It is a SEPARATE admission because the two questions are genuinely different,
	// and collapsing them in either direction is a defect this interface has already
	// suffered once in each direction:
	//
	//   - Routing auxiliary traffic through AdmitSideEffect spends a Canary execution
	//     reservation on a call that can cause no side effect (so MaxTotalExecutions
	//     stops measuring physical invocations) and refuses it on a tool-trust
	//     revalidation that has no tool to bind (so an armed node cannot complete a
	//     session handshake or list tools).
	//   - Skipping the gate ENTIRELY for auxiliary traffic — the first fix for the
	//     above — also discards the questions that DO apply to it: whether the live
	//     tier is armed at all, and whether it has begun quiescing. Those are the
	//     operator's disarm and wind-down controls, and after a restart the tier is
	//     deliberately left composed-but-unarmed while the persisted rollout mode may
	//     still resolve EffectExecute. Auxiliary traffic reaching a third-party
	//     upstream — establishing a session, reading its catalog, and carrying a
	//     materialized credential when the decision obliges one — on a tier the
	//     operator has disarmed or is winding down is the fail-closed restart posture
	//     (§17) being lost for every method except tools/call.
	//
	// So this admission runs the LIFECYCLE half and nothing else: no budget
	// reservation, no read-first, no live-trust revalidation. A denial fails the
	// invocation closed with the gate's bounded reason and Upstream.Call is never
	// reached; an admit returns a Release the executor runs exactly once after the
	// upstream leg, exactly as AdmitSideEffect does.
	//
	// It is part of the REQUIRED interface rather than an optional one on purpose: a
	// gate that does not answer this question must not be able to answer it by
	// omission, because omission is the permissive direction.
	AdmitAuxiliary(in LiveGateInput) LiveGateDecision
}

type LiveGateDecision struct {
	Admit  bool
	Reason mcperr.Reason
	// Revalidate (non-nil only when Admit) is a FINAL-BOUNDARY re-check the executor runs inside
	// preCallGuard, immediately before the emergency-kill re-read. It returns false when the
	// activation this request was admitted under is no longer current — e.g. a concurrent Canary
	// demotion invalidated the reserved generation AFTER admission but BEFORE the irreversible call.
	// Because the admission-time reservation cannot see a later demotion, and preCallGuard's kill
	// re-read does not consult the Canary generation, WITHOUT this an already-admitted request could
	// still reach the upstream after a leaving-live transition returned success (Codex P1 round-8,
	// PR #1290). It is a composition-layer concern (the generation lives in the canary runtime), so it
	// enters this package only as an injected predicate — the executor stays generic and byte-identical
	// when the gate (or Revalidate) is nil.
	Revalidate func() bool
	Release    func()
	// ReservationID (set only when Admit) names the budget slot this side effect was
	// authorized against. It binds a physical attempt to the reservation that paid
	// for it, so an effect can never be attributed to an unauthorized slot and an
	// orphan can be traced back to the exact grant. An empty value is tolerated:
	// gates that do not meter (nil/legacy) keep the executor byte-identical.
	ReservationID string
	// ActivationGeneration (set only when Admit) is the Canary activation generation
	// in force at admission. It is recorded on the attempt so an orphan from a
	// superseded generation stays recognizable after a restart and can never be
	// mistaken for fresh execution allowance. Zero when the gate does not meter.
	ActivationGeneration uint64
}

type LiveGateInput struct {
	Capability protocol.Capability
	// Operation is the policy-engine operation class (read-first is decided from THIS, never
	// the server-provided readOnlyHint).
	Operation policy.OperationClass
	// Tenant / Principal identify the authenticated subject for the blast-radius ceilings.
	Tenant    string
	Principal string
	// ServerID / ToolName / Fingerprint are the exact reviewed target the live-trust
	// revalidation binds against (Fingerprint is the hex composite fingerprint the decision
	// was computed against; tool freshness separately proves it still matches the live tool).
	ServerID    string
	ToolName    string
	Fingerprint string
	Now         time.Time
}

type Metrics interface {
	ObserveResolution(capability string, res rollout.Resolution)
	ObserveBlock(capability string, reason mcperr.Reason)
	ObserveExecution(capability string, ok bool)
	ObserveUpstream(capability string, outcome string)
	ObserveDLPBlock(capability string, response bool)
	// ObserveOutcomeEvidenceLoss records that a post-execution outcome event could
	// not be committed. The side effect already happened, so this is the archive
	// losing its record of it — best-effort must mean "does not block the response",
	// never "fails invisibly".
	ObserveOutcomeEvidenceLoss(capability string)
	// ObserveShadowOutcome records ONE non-executing Shadow evaluation and its formal
	// Model-1 verdict. outcome is a ShadowOutcome value (a bounded, low-cardinality enum:
	// would_execute / would_block / would_require_* / would_fail_*) — never a tenant,
	// subject, tool, or argument. It is emitted only by the ShadowEvaluator; the live
	// executor never calls it.
	ObserveShadowOutcome(capability string, outcome string)
}

type RecoveredAttempt struct {
	AttemptID            string
	ReservationID        string
	ActivationGeneration uint64
	State                AttemptState
	// TerminalSendState is the committed physical-send state when State is
	// AttemptSettled, and the zero value otherwise. It is never synthesized for an
	// orphan.
	TerminalSendState model.PhysicalSendState
	// Reconciliation is the DERIVED knowledge from append-only witness evidence. It
	// is ReconRequired when no witness has answered — for an orphan AND for a settled
	// attempt, since a settled attempt whose send state is may_have_been_sent still
	// has an open question. It never changes execution authority — only what is known.
	Reconciliation model.ReconciliationResult
}

type RecoveryReport struct {
	// Orphans require reconciliation. They consume their original allowance
	// permanently and are never re-executed.
	Orphans []RecoveredAttempt
	// Settled attempts reached a valid terminal outcome.
	Settled []RecoveredAttempt
	// ReservationBreaches names every slot bound to more than one attempt. A
	// non-empty slice means N accepted reservations produced more than N potential
	// physical invocations.
	//
	// Surfacing this was a red-team finding. Recovery previously listed such
	// attempts individually — VISIBLE, but not the same as DETECTED: nothing
	// distinguished "two attempts" from "two attempts that one slot paid for".
	ReservationBreaches []ReservationBreach
}

type ReservationBreach struct {
	ReservationID string
	AttemptIDs    []string
}

type ShadowConfig struct {
	// State is the capability-local rollout state (Gateway). Required.
	State *rollout.State
	// Planner is the OPTIONAL plan-only credential capability. nil ⇒ credential
	// readiness is reported as not-evaluated (a Shadow evaluator is constructible with
	// no credential capability at all).
	Planner CredentialPlanner
	// Events is the durable-event manager. Required: evidence-before-report is
	// mandatory, so a nil Events fails every evaluation closed.
	Events *events.Manager
	// Metrics is the optional rollout telemetry sink.
	Metrics Metrics
	// Clock is injected for tests; nil ⇒ time.Now.
	Clock func() time.Time
	// Actor labels events emitted by this evaluator.
	Actor string
}

type ShadowDecision struct {
	EvaluatedAction    string        // the raw policy action (never softened)
	Outcome            ShadowOutcome // Model-1 enforcement prediction
	ShadowOverride     bool          // policy itself is restrictive (non-allow-class)
	CredentialPlan     string        // credential_plan_valid / _invalid / no_credential_profile
	MaterializeReady   string        // always not_evaluated (§12 — Shadow never materializes)
	RequestInspection  string        // would_pass / would_fail (from the pre-executor hard-fail source)
	ResponseInspection string        // always not_evaluated (§13 — no upstream response exists)
}

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

type ShadowOutcome string

type UpstreamCaller interface {
	Call(ctx context.Context, target upstreamclient.Target, method string, params json.RawMessage, opts upstreamclient.CallOptions) (*upstreamclient.Response, error)
}

type Witness interface {
	LookupAttempt(ctx context.Context, attemptID string) (WitnessObservation, error)
}

type WitnessObservation struct {
	// Count is the number of physical invocations the witness recorded for this
	// AttemptID. Retained verbatim: >1 is a physical-effect breach, not a duplicate
	// to be normalized away.
	Count int
	// Complete reports whether the witness can PROVE its observation set is complete
	// for the relevant interval. Absence from an incomplete log proves nothing.
	Complete bool
	// CompletenessWatermark is the evidence backing Complete — a durable monotonic
	// watermark, closed window, or authoritative sequence boundary. Required for a
	// definitive "not received".
	CompletenessWatermark string
	// Binding metadata the witness observed, used to confirm the observation really
	// belongs to this attempt rather than merely sharing its id.
	ServerID      string
	Method        string
	ReservationID string
	// Source identifies the witness, so an audit can tell whose evidence this was.
	Source string
	// WindowStartUnixNano / WindowEndUnixNano bound the observed interval.
	WindowStartUnixNano int64
	WindowEndUnixNano   int64
	ObservedAtUnixNano  int64
	// EvidenceDigest is a bounded, non-reversible reference to the underlying record.
	EvidenceDigest string
}