runner

type App interface {
	// ReadyToBuild tells the block builder that a round started and how
	// long to wait before building; done is closed when the core leaves the
	// height. It must not block.
	ReadyToBuild(req consensus.RequestBuild, wait time.Duration, done <-chan struct{})
	// FinalizeBlock imports a decided block with its seals. It is called
	// from the commit goroutine, one block at a time in height order, and
	// is idempotent for a block that is already the head.
	FinalizeBlock(b *types.Block, round types.Round) error
}

type AppQueueSourceObserver interface{ ObserveAppQueueSource(journal.AppQueueRec) }

type Chain interface {
	// Head returns the application's canonical head.
	Head() *types.Header
	// ValidatorsAt returns the validator set of block number whose parent
	// has hash parent.
	ValidatorsAt(number types.Height, parent types.Hash) (*validator.Set, error)
	// ValidateProposal verifies a proposal (header.VerifyProposal); a
	// proposal from the future fails with header.ErrFutureBlock and the time
	// to wait.
	ValidateProposal(b *types.Block) (time.Duration, error)
	// IsBadBlock reports whether the block is recorded as bad.
	IsBadBlock(h types.Hash) bool
}

type Clock interface {
	Now() time.Time
	Mono() time.Duration
	AfterFunc(d time.Duration, f func()) Timer
}

type CommitRequest struct {
	Block *types.Block
	Round types.Round
}

type Config struct {
	// ValidatorHistory overrides the finite history cap of DeferValidatorStart.
	// Nil takes that explicitly selected profile's supported defaults.
	ValidatorHistory *ValidatorHistoryLimits `json:",omitempty"`
	// ReceiveCache registers a received key only after a successful direct
	// core ACCEPT. Nil preserves legacy precheck caching. This staged runtime
	// API requires explicit limits and currently refuses message journals
	// until a compatible cache-policy profile is available.
	ReceiveCache *transport.ReceiveLedgerOptions `json:",omitempty"`
	// ReceiveFailureCache separately memoizes classified failures within one
	// immutable publication. Nil preserves the original receive path.
	ReceiveFailureCache *transport.ReceiveFailureOptions `json:",omitempty"`
	// Core configures the consensus core. Core.Self must be the signer's
	// address, or zero for a node that never signs.
	Core consensus.Options
	// ReplayWAL replays the write-ahead log on Start to restore the lock,
	// the prepared certificate, the sent votes and the round of the height
	// being decided (a restart-safety rule).
	ReplayWAL bool
	// Manual runs no goroutine: the caller drives the runner with Pump.
	// The deterministic simulator uses it.
	Manual bool

	// InboxMessages and InboxBytes bound the receive queue of one peer
	// (defaults 256 and 32 MiB).
	InboxMessages int
	InboxBytes    int64
	// OverflowLimit is the number of dropped messages of one peer within
	// OverflowWindow above which the peer is disconnected (defaults 1000
	// and 10 s), unless every peer overflows.
	OverflowLimit  int
	OverflowWindow time.Duration
	// Workers is the number of receive-check workers (default GOMAXPROCS).
	Workers int
	// NextHeight is an opt-in next-sequence receive lane. It requires WAL
	// replay and explicit positive limits; nil preserves the original path.
	NextHeight *NextHeightLimits
}

type CoreEnvObservation = journal.CoreEnvObservation

type CoreStepMoment = journal.CoreStepMoment

type CoreStepObservation = journal.CoreStepRec

type CoreStepObserver interface{ ObserveCoreStep(CoreStepObservation) }

type Deps struct {
	// ObservationSeals receives detached verified extra-seal entries after an
	// ordinary core step. It is a separately enabled functional witness sink,
	// independent of diagnostic metadata and replay authority.
	ObservationSeals func(prepared, committed []consensus.ExtraSealEntry)
	// ReceiveCacheRecorded observes a direct core ACCEPT retained in the
	// received cache. It runs after the cache mutex is released and must not
	// block. Nil changes no functional cache ownership or state.
	ReceiveCacheRecorded func(code uint64)
	// ReceiveRecoveryChecked observes an actual complete Recover invocation,
	// never a cache hit. It grants no signer or acceptance authority.
	ReceiveRecoveryChecked func(code codec.Code, failure consensus.RecoveryFailure)
	// ReceiveFailureHit observes reuse of an earlier failed check, not a new
	// Recover, signing operation, or core acceptance. Callbacks must not block.
	ReceiveFailureHit func(code uint64, class transport.ReceiveFailureClass)
	Chain             Chain
	App               App
	// Transport sends and deduplicates; nil sends nothing.
	Transport *transport.Dedup
	// Net is the transport under Transport, used to disconnect peers; nil
	// disconnects nothing.
	Net transport.Transport
	// Signer signs own messages; nil never signs.
	Signer privval.Signer
	// WAL is the write-ahead log; nil keeps none.
	WAL   *wal.Log
	Clock Clock
	// Events receives the event records; nil drops them.
	Events EventSink
	// Journal receives step and outcome records; nil keeps no journal.
	Journal journal.Writer
	// CoreSteps observes detached actual live core execution for diagnostics.
	// It is independent of Journal and does not enable unsupported replay.
	CoreSteps CoreStepObserver
	// TimerSources observes detached scheduler operations after its mutex is
	// released. Nil preserves the original journal and timer behavior.
	TimerSources TimerSourceObserver
	// AppQueueSources observes detached application-input queue mutations.
	AppQueueSources AppQueueSourceObserver
	// FinalizeSources observes detached commit-queue and application-call boundaries.
	FinalizeSources FinalizeSourceObserver
	// InboxSources observes detached receive queue and slot boundaries.
	InboxSources InboxSourceObserver
	// ReceiveFailureDiagnostics explicitly binds one declared source writer to
	// core, inbox, accepted receive and separate failure observations.
	ReceiveFailureDiagnostics ReceiveFailureDiagnosticObserver
	// InboxFailureSources separately observes reuse of earlier failed checks.
	// It does not declare a diagnostic profile or enable functional replay.
	InboxFailureSources InboxFailureSourceObserver
	// InternalSources observes original internal queue output/selection boundaries.
	InternalSources InternalSourceObserver
	// SelectionSources observes original conditional next probes and actual dispatch.
	SelectionSources SelectionSourceObserver
	// ReceiveDispatchSources observes original lookup ownership and actual completion.
	ReceiveDispatchSources ReceiveDispatchSourceObserver
	// WALReadSources observes original restore reads with explicit copy bounds.
	SignerCalls         SignerCallObserver
	WALReadSources      WALReadSourceObserver
	WALReadSourceLimits wal.ReadSourceLimits
	// Synchronising reports whether the application is synchronising the
	// chain; consensus messages that arrive while the engine is stopped are
	// then dropped instead of closing the connection.
	Synchronising func() bool
	// Rand draws the choice between the timer queue and the peer queues and
	// the order of receive checks in manual mode; nil uses math/rand/v2.
	Rand func(n int) int
	// Faults is called at the crash points (builds with wbft_faults).
	Faults faultpoint.Handler
	// Logger logs; nil discards.
	Logger *slog.Logger
	// ModuleLogger, when set, gives the loggers of the log modules: the
	// runner writes a line of the logcat catalog for each event record,
	// under consensus.round or consensus.msg, when that module's level
	// lets it through (observe.md 7.1).
	ModuleLogger func(logcat.Module) *slog.Logger
	// Refused, when set, is called for every signature privval refuses,
	// with the code of the message (sign floor skips included; the HEALTH
	// record of a skip is written once per height).
	Refused func(code uint64)
	// ManualProcessing is an optional deterministic service model. It is
	// accepted only in manual mode and never changes the production loop.
	ManualProcessing *ManualProcessing
}

type EventSink interface {
	Write(r event.Record, at event.Stamp) error
}

type FinalizeSourceObserver interface{ ObserveFinalizeSource(journal.FinalizeRec) }

type HandshakeAction uint8

type InboxFailureSourceObserver interface {
	ObserveInboxFailureHit(journal.InboxFailureHitRec)
}

type InboxSourceObserver interface{ ObserveInboxSource(journal.InboxRec) }

type InternalSourceObserver interface{ ObserveInternalSource(journal.InternalRec) }

type ManualFinalizer interface {
	FinalizeBlockManual(b *types.Block, round types.Round, complete func(error))
}

type ManualProcessing struct {
	Delay    func(ProcessingWork) time.Duration
	Schedule func(time.Duration, func())
}

type NextHeightLimits struct {
	Entries   uint64 `json:"entries,string"`
	Bytes     uint64 `json:"bytes,string"`
	PerPeer   uint64 `json:"per_peer,string"`
	PerSource uint64 `json:"per_source,string"`
}

type ProcessingWork struct {
	Phase string
	Kind  string
	Code  uint64
}

type ReceiveDispatchSourceObserver interface {
	ObserveReceiveDispatch(journal.ReceiveDispatchRec)
}

type ReceiveFailureDiagnosticObserver interface {
	CaptureRun() string
	CoreDeclaration() journal.CoreOptions
	CoreStepObserver
	InboxSourceObserver
	InboxFailureSourceObserver
	transport.ReceiveTransitionObserver
	transport.ReceiveFailureObserver
}

type ReplayInfo struct {
	Records  int    // input records fed to the core
	Stopped  string // why the replay stopped early; "" if it did not
	Replayed bool   // the core continues from the replayed state
}

type RestoreSourceObserver interface{ ObserveRestore(journal.RestoreRec) }

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

type SelectionSourceObserver interface{ ObserveInputSelection(journal.SelectionRec) }

type SignerCallObserver interface{ ObserveSignerCall(journal.SignerCallRec) }

type SourceFinalizer interface {
	FinalizeBlockWithSource(*types.Block, types.Round, app.FinalizeSource) error
}

type Timer interface {
	// Stop prevents the timer from firing; it reports false if the timer
	// already fired or was stopped.
	Stop() bool
}

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

type TimerQueueStatus struct{ Armed, Queued int }

type TimerSourceObserver interface{ ObserveTimerSource(journal.TimerRec) }

type ValidatorHistoryLimits struct {
	Bytes   uint64 `json:"bytes,string"`
	Records uint64 `json:"records,string"`
}

type WALReadSourceObserver interface{ ObserveWALRead(journal.WALReadRec) }

type WALState struct {
	// LastEnd is the height of the last end-of-height record: the highest
	// height the core left after a new head; nil when there is none.
	LastEnd *types.Height
	// Commits are the commit requests in the log, in order, including those
	// of heights the core has already left.
	Commits []CommitRequest
	// contains filtered or unexported fields
}