runtime

type AccountingRuntime struct {
	Preflight                    *accountingpreflight.Checker
	StreamUsage                  *accountingstream.Reconstructor
	TokenAccountingObservability *accountingobs.Stats
	AdminCountService            *accountingapp.Service
	UsageAuthority               UsageAuthorityService
	UsageAuthorityCleanupTimeout time.Duration
	// ConcurrencyProvider is the optional Phase 8 logical-request lease authority.
	ConcurrencyProvider authority.ConcurrencyProvider
	// ConcurrencyLeaseTTL / ConcurrencyRenewBefore are defaults used by heartbeat
	// when the admit decision omits rule-level values.
	ConcurrencyLeaseTTL    time.Duration
	ConcurrencyRenewBefore time.Duration
	// ConcurrencyAuxiliaryLeasePolicy is inherit (default) or acquire_own (10.10).
	ConcurrencyAuxiliaryLeasePolicy string
	// MeteringRecorder is the optional Phase 3 metering journal port. Nil means
	// checkpoints are retained in-request only (no durable append until Phase 5).
	MeteringRecorder metering.Recorder
	// MeteringObservationSink is the optional V2 evidence journal port. It is
	// deliberately separate from MeteringRecorder because pre-terminal economic
	// checkpoints persist immutable observations only; they never rate or mutate
	// money from a receive callback. Runtime checkpoint flushing requires the
	// sink to also implement metering.AtomicObservationSink; a plain
	// ObservationSink is retained for source compatibility but is not retried or
	// invoked by that path.
	MeteringObservationSink metering.ObservationSink
	// RequestCoordinator admits customer/logical-request authority once per request (Phase 6).
	RequestCoordinator *authoritycoord.RequestCoordinator
	// AttemptCoordinator admits operator/attempt authority per B-leg (Phase 6).
	AttemptCoordinator *authoritycoord.AttemptCoordinator
	// SnapshotGeneration is the atomic policy/rating generation publisher (Phase 9.3).
	// Admit binds Current() usage/concurrency/rating refs when present.
	SnapshotGeneration *snapshotgen.Publisher
	// TerminalWork accepts durable settle/release intents on post-output failures
	// (Phase 4.5; requirements 7.7, 8.3; design D9).
	TerminalWork *terminalworkapp.IntentService
}

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

type BillingAdmissionInput = BillingRoutePlanInput

type BillingCreditGate interface {
	Check(context.Context, string) error
}

type BillingExposureAdmission interface {
	Admit(context.Context, BillingExposureAdmissionInput) (billing.CallExposure, error)
}

type BillingExposureAdmissionInput struct {
	BillingAdmissionInput
	CallID string
}

type BillingIdentity struct {
	AccountID func(context.Context, lipapi.Call) string
	// StoreID resolves the trusted durable billing/metering store identity for a
	// request. It is captured with the terminal billing facts and is intentionally
	// absent from public runtime options.
	StoreID            func(context.Context) string
	CustomerPricingRef func(context.Context, lipapi.Call) billing.VersionRef
	ChargePolicyRef    func(context.Context, lipapi.Call) billing.VersionRef
	OperatorRateRef    func(context.Context, string, string) billing.VersionRef

	// WireBounded indicates whether this identity bundle is backed by stock/bounded
	// facts (such as PrincipalSessionIdentity) rather than custom Call-inspecting callbacks.
	// Custom callbacks without an explicit bounded contract remain wire blockers (Requirements 15.6, 19).
	WireBounded bool

	// WireAccountID optionally resolves an account identity directly from bounded scope
	// without constructing or inspecting a lipapi.Call.
	WireAccountID func(context.Context, scope.PrincipalScopeView) string

	// WireCustomerPricingRef optionally resolves the customer pricing snapshot ref from bounded facts.
	WireCustomerPricingRef func(context.Context) billing.VersionRef

	// WireChargePolicyRef optionally resolves the charge policy snapshot ref from bounded facts.
	WireChargePolicyRef func(context.Context) billing.VersionRef
}

type BillingLegObserver interface {
	ObserveBillingLeg(context.Context, billing.CallLegUsageRecord)
}

type BillingLegObserverFunc func(context.Context, billing.CallLegUsageRecord)

type BillingRoutePlanInput struct {
	Call            lipapi.Call
	TraceID         string
	ALegID          string
	BillingCallID   string
	Route           *routing.Selector
	RequestSize     routing.RequestSizeEstimate
	Scope           scope.PrincipalScopeView
	SessionID       string
	MaxOutputTokens *int
	AccountID       string
}

type BillingRuntime struct {
	// BillingCreditGate is the cheap settled-credit screen. Authoritative
	// billing requires it; when wired, runtime invokes it after identity
	// preparation and before route expansion.
	BillingCreditGate BillingCreditGate
	// BillingExposureAdmission is the authoritative operational-exposure seam.
	// When set, it replaces hold admission for this executor generation.
	BillingExposureAdmission BillingExposureAdmission
	// BillingLegObserver receives one recorded current call-leg usage record at terminal ownership.
	// It is observational only and never participates in authorization,
	// settlement, retry, cancellation, or client-visible output.
	BillingLegObserver BillingLegObserver
	TerminalUsageSink  billing.TerminalUsageSink
	// BillingIdentity is the composition identity bundle for exposure admission
	// and terminal call-closure stamping. It contains no hold/authorization identity.
	BillingIdentity BillingIdentity
}

type CancellationCauseClass string // explicit | client_gone | context_done | race_loser | none | other

type CancellationFallback string // negotiated | legacy | none | other

type CancellationModeClass string // none | provider | transport | close_only | other

type CancellationObservation struct {
	CauseClass CancellationCauseClass
	Mode       CancellationModeClass
	Phase      CancellationPhase
	Fallback   CancellationFallback
}

type CancellationPhase string // requested | outcome | forced | terminal | none | other

type CatalogResolver interface {
	Resolve(
		ctx context.Context,
		candidate routing.AttemptCandidate,
		call lipapi.Call,
		backend lipapi.BackendCaps,
	) modelcatalog.EffectiveFacts
}

type CompactionDetector interface {
	PreviewRequest(compaction.PreservationMeta, lipapi.Call) compaction.RequestPreview
	RequestOpened(compaction.PreservationMeta, lipapi.Call) []compaction.Event
	PreviewResponse(compaction.PreservationMeta, lipapi.Event) compaction.ResponsePreview
	ResponseReleased(compaction.PreservationMeta, lipapi.Event) []compaction.Event
}

type CompactionRuntime struct {
	Detector CompactionDetector
	// BackgroundAux is the generation-bound process scheduler client. The
	// scheduler itself remains process-owned; this interface lets callbacks
	// submit work against the executor's frozen generation binding.
	BackgroundAux auxiliary.BackgroundClient
}

type CompactionWireDetector interface {
	CompactionDetector
	RequestOpenedFacts(compaction.PreservationMeta, compactionfacts.RequestFacts) []compaction.Event
}

type ConversationViewObserver interface {
	OnProjection(stage string, summary conversationprojection.ProjectionSummary)
	OnProjectionFailure(stage string)
	OnAnchorFallback(stage string, policy conversationprojection.AnchorMissingPolicy)
	OnAnchorFailure(policy conversationprojection.AnchorMissingPolicy)
}

type ConversationViewTagger interface {
	TagNeverBackend(ctx context.Context, aLegID string, tags []TagRequest) (TagResult, error)
}

type CoreRuntime struct {
	Store                b2bua.Store
	Backends             map[string]execbackend.Backend
	ALegLifecycle        *leglifecycle.Coordinator
	Rand                 routing.Rng
	Now                  func() time.Time
	MaxPendingWireEvents int
	StreamRecovery       streamrecovery.Config
	// PromptCacheMaintenance is the optional generation-owned provider-neutral maintenance port.
	PromptCacheMaintenance PromptCacheMaintenance
	// ConversationViewReader is an optional narrow snapshot port. When set,
	// runtime preserves the single-snapshot per-turn invariant (task 3.2).
	ConversationViewReader conversationprojection.Reader
	// ConversationViewTagger is the optional narrow tagger port for local-turn
	// tag-before-release.
	ConversationViewTagger ConversationViewTagger
	// SteeringWriterFactory constructs an authoritative steering writer for a given A-leg.
	SteeringWriterFactory SteeringWriterFactory
	// LargeBodyAssessor evaluates frontend proof for candidate fast-path execution.
	LargeBodyAssessor largebody.LargeBodyAssessor
	// LargeBodyGenerationID is the optional generation identity for largebody execution validation.
	LargeBodyGenerationID string
	// LargeBodyCandidateDomainGeneration is the optional generation identity for late-route proof validation.
	LargeBodyCandidateDomainGeneration string
}

type EligibilityResolver interface {
	Check(
		ctx context.Context,
		candidate routing.AttemptCandidate,
		call lipapi.Call,
		facts modelcatalog.EffectiveFacts,
	) modelcatalog.EligibilityDecision
}

type Executor struct {
	CoreRuntime
	BillingRuntime
	RoutingRuntime
	SecurityRuntime
	AccountingRuntime
	ObservabilityRuntime
	ExtensionRuntime
	InterleavedRuntime
	CompactionRuntime
	// contains filtered or unexported fields
}

type ExecutorConfig struct {
	Core          CoreRuntime
	Billing       BillingRuntime
	Routing       RoutingRuntime
	Security      SecurityRuntime
	Accounting    AccountingRuntime
	Observability ObservabilityRuntime
	Extension     ExtensionRuntime
	Interleaved   InterleavedRuntime
	Compaction    CompactionRuntime
}

type ExtensionRuntime struct {
	Bus             *hooks.Bus
	RuntimeSnapshot *extensions.RequestRuntimeSnapshot

	// TerminalPolicyReader resolves session-scoped terminal decision policy overrides
	// at request admission (Task 7.2).
	TerminalPolicyReader TerminalPolicyReader

	// ToolCallFinalizationMaxArgsBytes is the assembler buffer cap from merged
	// feature bundles (0 means default at assembler construction).
	ToolCallFinalizationMaxArgsBytes int
	// contains filtered or unexported fields
}

type InterleavedMemo struct {
	Text       string
	Reference  string
	Version    int64
	HadContent bool
}

type InterleavedProcessor interface {
	BeginTurn(ctx context.Context, in InterleavedTurnInput) (InterleavedTurn, error)
	IsMemoVisibleToClient(ctx context.Context, aLegID string) bool
	// MemoSteeringPutRequest builds the feature-owned steering mutation that
	// persists a captured memo.
	MemoSteeringPutRequest(memo string) steering.PutRequest
	// MemoSteeringOverlayID returns the feature-owned stable overlay identity
	// for the thinker memo.
	MemoSteeringOverlayID() steering.OverlayID
	// IsMemoSteeringOverlay reports whether overlayID carries the thinker memo.
	IsMemoSteeringOverlay(overlayID string) bool
}

type InterleavedRuntime struct {
	Processor InterleavedProcessor
}

type InterleavedTurn interface {
	ShapeThinker(call lipapi.Call) (lipapi.Call, error)
	ObserveThinkerEvent(ev lipapi.Event) ([]lipapi.Event, error)
	FinalizeThinker(ctx context.Context) (InterleavedMemo, error)
	FinalizeThinkerStatus(ctx context.Context, interrupted bool, visibleCommitted bool) (InterleavedMemo, error)
	ShapeExecutor(ctx context.Context, call lipapi.Call, memo InterleavedMemo) (lipapi.Call, error)
	Visible() bool
	CanContinue() bool
	ShapeDiagnostics() (outcome string, turnsRemaining int)
	CommitExecutor(ctx context.Context) (remaining int, err error)
	FlushVisible() []lipapi.Event
}

type InterleavedTurnInput struct {
	ALegID              string
	Selector            string
	Backend             string
	Model               string
	RequestID           string
	StreamToClient      string
	SuppressVisibleMemo bool
}

type LaneDomainPolicy struct {
	// UniversalOnly requires backend universal model certification (AnyAcceptedModel: true)
	// and evaluates universal late-route domain proof (e.g. Lane 3 OpenResponses).
	UniversalOnly bool
	// CandidateModels lists finite candidate models certified for the lane when not UniversalOnly.
	CandidateModels []string
}

type MetricsSink interface {
	OnAttemptRecorded(outcome lipapi.AttemptOutcome, backend string)
	OnBackendOpenDuration(backend string, seconds float64)
	OnTransportNegotiation(operation lipapi.Operation, mode lipapi.TransportMode, outcome string)
	OnCancellation(obs CancellationObservation)
}

type ObservabilityRuntime struct {
	Log                        *slog.Logger
	Metrics                    MetricsSink
	ExtensionMetrics           extensions.StageMetrics
	SecretGuardDecisionMetrics extensions.SecretGuardDecisionMetrics
	RouteTrace                 *diag.RouteTraceBuffer
	PolicyDiagnosticsEnabled   bool
	CompletionBufferLimits     completion.BufferLimits
	// ConversationViewObserver is optional narrow diagnostics for bounded conversation-view
	// projection/anchor/steering metrics. Nil is no-op. Labels are bounded enums only (placement, operation, policy, stage).
	ConversationViewObserver ConversationViewObserver
}

type Options struct {
	Config *coreconfig.Config
	Logger *slog.Logger

	// Registrations enumerates configured plugins at bootstrap. When non-empty or Mandatory
	// is set, duplicates and mandatory coverage are validated in New.
	Registrations []lipsdk.Registration
	Mandatory     []lipsdk.Requirement

	// Hooks configures submit, part, and tool-reactor chains (zero value means empty chains).
	Hooks hooks.Config

	// Lifecycles are started after validation and stopped on shutdown (reverse order).
	Lifecycles []lipplugin.Lifecycle
}

type OrchestrationScenarioSpec struct {
	ID               string
	InvariantSummary string
	TestName         string // existing *_test.go function name in package runtime_test
}

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

type ProductionLargeBodyAssessor struct {
	GenerationID              string
	CandidateDomainGeneration string
	AuthorityGate             *largebody.AuthorityAssessmentGate
	WireProofGate             *largebody.BackendWireProofGate
	LaneDomainPolicies        map[string]LaneDomainPolicy
}

type PromptCacheCommittedTurn struct {
	ALegID              string
	BLegID              string
	CommittedSuccessful bool
	ToolEvents          []lipapi.ToolEvent
	Observations        []promptcache.Observation
	BackendInstanceID   string
	CanonicalModelID    string
	Controller          promptcache.Controller
}

type PromptCacheMaintenance interface {
	BeginRealTurn(aLegID string)
	EndSession(aLegID string)
	ArmCommittedTurn(turn PromptCacheCommittedTurn)
}

type RequestTokenEstimator interface {
	EstimateRequestTokens(ctx context.Context, call lipapi.Call) modelcatalog.SizeEstimate
}

type RoutingRuntime struct {
	MaxAttempts             int
	DefaultBackend          string
	SelectorAliases         *routing.AliasResolver
	CapsResolver            capabilities.Resolver
	CatalogResolver         CatalogResolver
	EligibilityResolver     EligibilityResolver
	RequestTokenEstimator   RequestTokenEstimator
	CandidateHealth         policy.CandidateHealth
	RouteObserver           lipsdk.RouteObserver
	AffinityStore           affinity.Store
	AffinityMissingIdentity affinity.MissingIdentityPolicy
	TransportFallbackPolicy lipapi.TransportFallbackPolicy
	RouteOverrideReader     routeoverride.Reader

	ExecutionCompositionPolicy config.ExecutionCompositionPolicy
	BackendExecutionResolver   routing.BackendExecutionResolver
}

type SecureSessionMetrics interface {
	ObserveBeginTurnNew()
	ObserveBeginTurnResume()
	// ObserveBeginTurnDenied increments when BeginTurn fails (code is lipapi SessionDenialCode string or "unknown").
	ObserveBeginTurnDenied(code string)
	ObserveStorageUnavailable()
	ObserveActivityTouch(seconds float64)
	ObserveRecorderClientTurnFailed(mandatory bool)
	ObserveRecorderStreamEventFailed(committed bool, mandatory bool)
}

type SecureSessionPrepInput struct {
	TraceID       string
	Session       largebody.SessionInput
	ContinuityKey string
}

type SecureSessionRecorder = app.GateRecording

type SecurityRuntime struct {
	SecureSession                           *app.Manager
	SyntheticLocalPrincipal                 bool
	SecureSessionRecorder                   app.GateRecording
	SecureSessionRecordingMandatory         bool
	SessionDenialMapper                     func(error) error
	SecureSessionMetrics                    SecureSessionMetrics
	SecureSessionRequireWorkspaceID         bool
	SecureSessionWorkspaceResolveFailClosed bool
	AuthEvents                              *auth.EventDispatcher
	SessionAuditPolicy                      auth.SessionAuditPolicy
}

type SteeringWriterFactory func(ctx context.Context, aLegID string, resolver SteeringWriterResolver) (steering.Writer, error)

type SteeringWriterResolver func(ctx context.Context) (lipapi.Call, conversationprojection.Snapshot, error)

type TagRequest struct {
	Identity conversationprojection.MessageIdentity `json:"identity"`
	Reason   conversationprojection.ReasonCode      `json:"reason"`
}

type TagResult struct {
	StateRevision uint64                       `json:"state_revision"`
	Tags          []conversationprojection.Tag `json:"tags"`
}

type TerminalPolicyQuery struct {
	SecureSessionIncarnation string
	ALegID                   string
	FeatureID                string
	GenerationDefault        bool
}

type TerminalPolicyReader interface {
	Effective(ctx context.Context, in TerminalPolicyQuery) (TerminalPolicySnapshot, error)
}

type TerminalPolicySnapshot struct {
	EffectiveEnabled bool
	Revision         uint64
}

type UsageAuthorityService interface {
	Admit(ctx context.Context, in authorityapp.AdmissionInput) (authorityapp.AdmissionResult, error)
	Settle(ctx context.Context, in authorityapp.SettleInput) (authorityapp.SettleResult, error)
	Release(ctx context.Context, in authorityapp.ReleaseInput) (authorityapp.ReleaseResult, error)
	ApplyUsage(ctx context.Context, cmd authorityapp.ApplyUsageCommand) (authorityapp.ApplyUsageResult, error)
}

type WireBackendIngressArgs struct {
	RequestID       string
	TraceID         string
	AttemptID       string
	BLegID          string
	ALegID          string
	SessionID       string
	Scope           scope.PrincipalScopeView
	BackendID       string
	Model           string
	MaxOutputTokens *int
	Now             time.Time

	SourceDigest  [32]byte
	RewriteDigest [32]byte
	AttemptDigest [32]byte
}

type WireBillingAssessmentArgs struct {
	Scope scope.PrincipalScopeView
}

type WireBillingCreditArgs struct {
	Scope     scope.PrincipalScopeView
	AccountID string // optional explicit account ID override
}

type WireBillingExposureArgs struct {
	BillingCallID   billing.BillingCallID
	TraceID         string
	ALegID          string
	SessionID       string
	Scope           scope.PrincipalScopeView
	AccountID       string
	Route           *routing.Selector
	RequestSize     routing.RequestSizeEstimate
	MaxOutputTokens *int
}

type WireExposureAbortArgs struct {
	BillingCallID   billing.BillingCallID
	SubmissionID    string
	Exposure        billing.CallExposure
	ALegID          string
	SessionID       string
	ExpectedBLegIDs []string
	Now             time.Time
}

type WireFrontendIngressArgs struct {
	RequestID       string
	TraceID         string
	Scope           scope.PrincipalScopeView
	ALegID          string
	SessionID       string
	MaxOutputTokens *int
	Now             time.Time
}

type WirePreflightAssessmentArgs struct {
	Backend                  string
	Model                    string
	CallID                   string
	ProfileID                string
	Source                   largebody.Source
	RequestedMaxOutputTokens *int
	Facts                    modelcatalog.ModelFacts
	Semantics                largebody.ExactTokenizerSemantics
	MaxScanBytes             int64
	MaxPermitHoldCPU         time.Duration
}