reflowthroughput

type ArmPressureInputs struct {
	Admissions           int64
	AdmissionBlocked     int64
	QueueDepthPeak       int64
	MaxBatch             int
	BarrierWaitNanos     int64
	E2EWallNanos         int64
	EffectiveConcurrency int
	// StatsOK is true when admission (exactly-one post-summary + structure) passed.
	StatsOK bool
}

type BYOS3Config struct {
	Bucket         string
	Endpoint       string
	Region         string
	Profile        string
	RootPrefix     string
	ForcePathStyle bool
	// Optional static keys for moto only (cloudtest.TestAccessKeyID pattern).
	// Never used for real BYO — real-cloud uses ambient/profile chain only.
	AccessKeyID     string
	SecretAccessKey string
}

type BindDisposition string

type Budgets struct {
	Run   time.Duration
	Point time.Duration
}

type CleanupLedger struct {
	// Keep suppresses removal entirely. It is an operator choice to retain
	// artifacts, not a failure, so residue under Keep is expected.
	Keep bool
	// DeletePrefix is nil when the run has no object-store residue.
	DeletePrefix PrefixDeleter
	// contains filtered or unexported fields
}

type CompactManifest struct {
	RecipeVersion string         `json:"recipe_version"`
	Seed          int64          `json:"seed"`
	ObjectCount   int            `json:"object_count"`
	SizeBytes     int            `json:"size_bytes"`
	Partitions    int            `json:"partitions"`
	TotalBytes    int64          `json:"total_bytes"`
	SizeHistogram map[string]int `json:"size_histogram"`
	Digest        string         `json:"digest"`
}

type FullPipeOpts struct {
	Binary         string
	SourcePrefix   string
	ProbeConfig    string
	DestURI        string
	ProbeConc      int
	ReflowParallel int
	CheckpointPath string
	GOMEMLIMIT     string
	// MemoryBudget is the operator --memory-budget size string; empty omits
	// the flag so the product derives the budget from the detected limit.
	MemoryBudget string
	StdoutPath   string

	// ProviderClass labels the point in the report. Carried rather than
	// assumed, so a cloud run is not reported as a local one.
	ProviderClass string
	// ProbeExtraArgs are provider flags for the probe child only. Kept separate
	// from ReflowExtraArgs because the two commands do not accept the same
	// flags: probe takes --region/--profile/--endpoint, transfer takes the
	// paired --src-*/--dest-* set. One shared slice would hand each child flags
	// the other needs and the command would refuse them.
	ProbeExtraArgs []string
	// ReflowExtraArgs are provider flags for the reflow child only.
	ReflowExtraArgs []string
	// ChildExtraEnv is appended to both children's environment. Static
	// credentials belong here only for a backend that requires them; a real BYO
	// backend stays ambient or profile-based.
	ChildExtraEnv []string
	// RewriteFrom/RewriteTo map probe output, which carries no dest_rel_key,
	// onto destination keys. They are caller-supplied because the source key
	// shape is not the same on every backend: a local corpus root yields the
	// bare hive key, while an object store prefixes it with the minted run
	// prefix, so a fixed template matches on one and rejects every record on
	// the other. Empty falls back to the bare four-segment identity.
	RewriteFrom string
	RewriteTo   string
}

type GenerateOptions struct {
	Recipe Recipe
	// RunRoot is the external run directory (ownership ledger lives here).
	RunRoot string
	// SourceDirName is the relative name under RunRoot for the immutable source.
	SourceDirName string
}

type GeneratedCorpus struct {
	Recipe          Recipe
	Root            string // absolute source root (operator-supplied test root subdir)
	Manifest        Manifest
	ManifestPath    string
	ReflowInputPath string
	ProbeConfigPath string
	ObjectCount     int
}

type HonestyResult struct {
	OK      bool
	Message string
}

type LandedObjectID struct {
	RelKey string `json:"rel_key"`
	Size   int64  `json:"size_bytes"`
	Digest string `json:"content_digest"`
}

type Manifest struct {
	RecipeVersion string `json:"recipe_version"`
	Seed          int64  `json:"seed"`
	ObjectCount   int    `json:"object_count"`
	// SizeBytes and Partitions are the resolved recipe knobs, recorded so a
	// reader can name the exact corpus shape that produced the evidence.
	// Partitions in particular cannot be reconstructed from the entry digest.
	SizeBytes     int             `json:"size_bytes"`
	Partitions    int             `json:"partitions"`
	TotalBytes    int64           `json:"total_bytes"`
	SizeHistogram map[string]int  `json:"size_histogram"`
	Entries       []ManifestEntry `json:"entries"`
	// Digest is SHA-256 over ordered (relative_key, size, content_digest) lines.
	Digest string `json:"digest"`
}

type ManifestEntry struct {
	RelativeKey   string `json:"relative_key"`
	SizeBytes     int64  `json:"size_bytes"`
	ContentDigest string `json:"content_digest"`
}

type MemoryArm struct {
	// Label is the reported memory_envelope value.
	Label string
	// UseGOMEMLIMIT sources the arm's GOMEMLIMIT from operator options.
	UseGOMEMLIMIT bool
	// UseMemoryBudget sources the arm's --memory-budget from operator options.
	UseMemoryBudget bool
}

type MemoryResolution struct {
	LimitBytes           int64
	LimitSource          string
	BudgetRequestedBytes int64
	BudgetEffectiveBytes int64
	BudgetSource         string
	RetryBufferCapBytes  int64
}

type MintedPoint struct {
	DestDir        string
	CheckpointPath string
}

type OccupancyResult struct {
	OK           bool
	Samples      []int
	Floor        int
	PassedNeeded int
	Passed       int
	Message      string
}

type Options struct {
	// Binary is the absolute path to the built gonimbus binary.
	Binary string
	// Profile name (empty → smoke).
	Profile string
	// Provider is file (default), moto, s3-compatible, or gcs.
	// BYO cloud uses the same GONIMBUS_S3_TEST_* / GONIMBUS_GCS_TEST_* env
	// conventions as test/cloudtest and make test-cloud-real (opt-in; skip/fail
	// clearly when unset for a non-file provider).
	Provider string
	// RunRoot is the operator-supplied external test root (created if needed).
	RunRoot string
	// GOMEMLIMIT is operator-supplied only; never auto-set by the harness.
	// Under the product's minimum-selection limit chain a GOMEMLIMIT binds
	// only when it is the lowest candidate, so this constrains an envelope
	// rather than raising one.
	GOMEMLIMIT string
	// MemoryBudget is the operator --memory-budget value for arms that set the
	// budget directly. Operator-supplied only; never invented by the harness.
	MemoryBudget string
	// TmpfsCheckpointRoot when set is used for checkpoint_class=tmpfs points.
	// The path itself is never written into the report.
	// Also accepted via env TMPFS_CHECKPOINT_ROOT / GONIMBUS_THROUGHPUT_TMPFS_CHECKPOINT_ROOT.
	TmpfsCheckpointRoot string
	// Keep retains minted roots (report only retained invocation id).
	Keep bool
	// PointTimeout bounds each measured point.
	PointTimeout time.Duration
	// ConstrainedGOMEMLIMIT is the GOMEMLIMIT used by constrained-envelope arms
	// of the ceiling-lift and checkpoint profiles. When empty it falls back to
	// GOMEMLIMIT. Accepted via CONSTRAINED_GOMEMLIMIT, or the older
	// CEILING_LIFT_GOMEMLIMIT spelling.
	ConstrainedGOMEMLIMIT string
	// WorktreeCommit is optional instrument commit override (harness identity).
	// It is NEVER applied to measured BinaryCommit (retained-measure provenance).
	WorktreeCommit string
	// ScheduleID selects checkpoint-scale counterbalancing plan
	// (disk_first_odd default; tmpfs_first_odd reverse). Ignored for other profiles.
	ScheduleID string

	// Recipe overrides scale the profile's synthetic corpus at invocation. Zero
	// means keep the profile default. Accepted via OBJECT_COUNT / SIZE_BYTES /
	// PARTITIONS (GONIMBUS_THROUGHPUT_OBJECT_COUNT / _SIZE_BYTES / _PARTITIONS).
	// Absurd values fail closed in Recipe.Validate; the effective corpus is
	// recorded in the report's corpus block so evidence names what was measured.
	RecipeObjectCount int
	RecipeSizeBytes   int
	RecipePartitions  int
}

type PairInputs struct {
	// Invalid marks failed/honesty/missing-stats/non-comparable pairs.
	Invalid bool
	// DiskPressure is true when the disk arm shows writer pressure.
	DiskPressure bool
	// TmpfsPressure is true when the tmpfs arm shows writer pressure.
	TmpfsPressure bool
	// DeltaE2E is (T_disk - T_tmpfs) / max(T_disk, T_tmpfs).
	DeltaE2E float64
}

type ParsedReflowOutput struct {
	RunCount          int
	SummaryCount      int
	WarningClampCount int
	ObjectComplete    int64

	ObjectError   int64
	InvalidInputs int64
	SummaryErrors int64

	// Run-record concurrency (required agreement with summary).
	RunRequested int
	RunEffective int
	RunReason    string
	RunMaxActive int
	RunFinal     int
	RunAdaptive  bool

	// Summary-record concurrency.
	SummaryRequested int
	SummaryEffective int
	SummaryReason    string
	SummaryMaxActive int
	SummaryFinal     int
	SummaryAdaptive  bool

	// Dest-domain policy (GON-067 PR2): static for the run; run and summary must
	// agree. Used by CheckHonesty so the gate asserts resolved output, not an
	// assumed default multiplier.
	RunDestDomainMultiplier           int
	RunDestDomainCeilingEffective     int
	SummaryDestDomainMultiplier       int
	SummaryDestDomainCeilingEffective int

	// Memory resolution as the product reported it. The whole tuple is fixed at
	// startup, so run and summary must agree on every field — comparing only
	// the source labels would let a differing limit, budget, or retry cap
	// through and publish the run's values as if both records agreed. Values
	// stay aggregate (bytes and source labels) — no host identity is retained.
	RunMemory     MemoryResolution
	SummaryMemory MemoryResolution

	// Consensus memory resolution after the agreement check.
	MemoryLimitBytes           int64
	MemoryLimitSource          string
	MemoryBudgetRequestedBytes int64
	MemoryBudgetEffectiveBytes int64
	MemoryBudgetSource         string
	RetryBufferCapBytes        int64
	// SummaryTimeAvgActive is the completed-run occupancy diagnostic. The run
	// record's startup sample is always zero by contract and is not retained.
	SummaryTimeAvgActive float64

	// CheckpointWriterStats is the sterile end-of-run checkpoint writer
	// diagnostic snapshot when the child emitted
	// gonimbus.reflow.checkpoint_writer_stats.v1 (checkpoint measure). Nil when absent.
	// Measure-first only — not product throughput evidence.
	CheckpointWriterStats *reflow.CheckpointWriterStatsRecord
	// CheckpointWriterStatsCount is how many stats records appeared (exactly
	// one is required for retained checkpoint-scale arms).
	CheckpointWriterStatsCount int
	// CheckpointWriterStatsBeforeSummary counts stats records observed before
	// the single summary (must be zero for retained arms).
	CheckpointWriterStatsBeforeSummary int

	// ObjectPathStageStats is the sterile object-path stage attribution snapshot
	// when the child emitted gonimbus.reflow.object_path_stage_stats.v1.
	// Optional; measure-first only — not product throughput marketing.
	ObjectPathStageStats *reflow.ObjectPathStageStatsRecord
	// ObjectPathStageStatsCount is how many stage-stats records appeared.
	ObjectPathStageStatsCount int

	// Consensus fields after agreement check (filled by Finalize).
	Requested       int
	Effective       int
	Reason          string
	MaxActive       int
	Final           int
	AdaptiveEnabled bool
	Initial         int
	Floor           int

	// Consensus dest-domain policy after run/summary agreement.
	DestDomainMultiplier       int
	DestDomainCeilingEffective int

	ThrottleBackoffs  int64
	AdditiveIncreases int64
	ConnectionFreezes int64
	ClampWarningOK    bool
	// Clamp warning details for three-way agreement with run/summary.
	ClampWarnRequested int
	ClampWarnEffective int
	ClampWarnReason    string
	ClampWarnAdaptive  *bool
	ParseErrors        []string

	UnknownTypes []string
	// contains filtered or unexported fields
}

type PointReport struct {
	PointID          string `json:"point_id"`
	ExecutionShape   string `json:"execution_shape"` // reflow_only|full_pipe|probe_drain
	Parallel         int    `json:"reflow_parallel_requested,omitempty"`
	ProbeConcurrency int    `json:"probe_concurrency,omitempty"`
	// AdaptiveMode is reflow adaptive/fixed when reflow ran; empty for probe_drain.
	AdaptiveMode    string `json:"adaptive_mode,omitempty"`
	GOMEMLIMITSet   bool   `json:"gomemlimit_set"`
	GOMEMLIMITValue string `json:"gomemlimit_value,omitempty"`
	// MemoryBudgetRequested is the operator --memory-budget passed to the child
	// (empty when the arm let the product derive the budget).
	MemoryBudgetRequested string `json:"memory_budget_requested,omitempty"`
	// MemoryLimitSource is product memory-limit provenance when reflow ran; omit for probe_drain.
	MemoryLimitSource string `json:"memory_limit_source,omitempty"`
	// MemoryBudgetSource is product budget provenance: derived|operator|operator_clamped_to_limit.
	MemoryBudgetSource string `json:"memory_budget_source,omitempty"`
	// Resolved memory arithmetic as the product reported it (aggregate bytes only).
	MemoryLimitBytes           int64 `json:"memory_limit_bytes,omitempty"`
	MemoryBudgetEffectiveBytes int64 `json:"memory_budget_effective_bytes,omitempty"`
	RetryBufferCapBytes        int64 `json:"retry_buffer_cap_bytes,omitempty"`
	// MemoryEnvelope names which lever bound this arm's memory:
	// gomemlimit_constrained | probe_bound | operator_budget | "".
	MemoryEnvelope string `json:"memory_envelope,omitempty"`
	// ConcurrencyTimeAvgActive is the completed-run occupancy diagnostic.
	ConcurrencyTimeAvgActive float64 `json:"concurrency_time_avg_active,omitempty"`
	CheckpointClass          string  `json:"checkpoint_class,omitempty"`

	// Product reflow concurrency telemetry (omit when not applicable).
	ConcurrencyRequested *int    `json:"concurrency_ceiling_requested,omitempty"`
	ConcurrencyEffective *int    `json:"concurrency_ceiling_effective,omitempty"`
	ConcurrencyReason    *string `json:"concurrency_ceiling_reason,omitempty"`
	ConcurrencyMaxActive *int    `json:"concurrency_max_active,omitempty"`
	ConcurrencyFinal     *int    `json:"concurrency_final,omitempty"`
	AdaptiveEnabled      *bool   `json:"adaptive_enabled,omitempty"`

	// CheckpointWriterStats is sterile checkpoint-writer diagnostics from the
	// child when emitted (checkpoint measure). Measure-first only — not product
	// throughput marketing. Omitted when the child did not emit the record.
	CheckpointWriterStats *reflow.CheckpointWriterStatsRecord `json:"checkpoint_writer_stats,omitempty"`

	ElapsedSeconds      float64 `json:"elapsed_seconds"`
	CompletedObjects    int64   `json:"completed_objects"`
	EndToEndRate        float64 `json:"end_to_end_rate_objects_per_s,omitempty"`
	ProbeDeliveredRate  float64 `json:"probe_delivered_rate_objects_per_s,omitempty"`
	ProbeSaturationRate float64 `json:"probe_saturation_rate_objects_per_s,omitempty"`
	TapValidRows        int64   `json:"tap_valid_reflow_input_rows,omitempty"`
	// TapCopyIntervalSeconds is the wall time of the tap Copy loop (includes
	// producer pacing and downstream backpressure). Not calibrated overhead.
	TapCopyIntervalSeconds float64 `json:"tap_copy_interval_seconds,omitempty"`

	// HonestyOK is nil when honesty is not applicable (e.g. probe_drain).
	HonestyOK      *bool  `json:"honesty_ok,omitempty"`
	HonestyMessage string `json:"honesty_message,omitempty"`

	OccupancySamples []int  `json:"occupancy_samples,omitempty"`
	OccupancyOK      *bool  `json:"occupancy_ok,omitempty"`
	OccupancyMessage string `json:"occupancy_message,omitempty"`

	// ContentParityOK is true when landed key+size+content-digest multisets match.
	ContentParityOK *bool `json:"content_parity_ok,omitempty"`

	StageExitCodes map[string]int `json:"stage_exit_codes"`
}

type PointResult struct {
	Profile          string
	PointID          string
	Parallel         int
	ProbeConcurrency int
	GOMEMLIMIT       string
	// MemoryBudget is the operator --memory-budget value passed to the child
	// (empty when the arm let the product derive the budget).
	MemoryBudget    string
	CheckpointClass string // disk | tmpfs — never the path
	ProviderClass   string // file | moto | s3-compatible | gcs
	Stages          map[string]StageResult
	Tap             TapStats
	Stdout          []byte // small in-memory only; prefer StdoutPath for scale
	StdoutPath      string // external run artifact for reflow JSONL
	Elapsed         time.Duration
	// CompletedObjects is derived from summary/object counts when available.
	CompletedObjects int64
	WallRate         float64 // objects / elapsed seconds (0 if incomplete)
}

type PrefixDeleter func(ctx context.Context, prefix string) error

type ProbeDrainOpts struct {
	Binary         string
	SourcePrefix   string
	ProbeConfig    string
	ProbeConc      int
	GOMEMLIMIT     string
	ProviderClass  string
	ProbeExtraArgs []string
	ChildExtraEnv  []string
}

type ProfileSpec struct {
	Name   string
	Recipe Recipe
	// ExecutionShape: reflow_only | full_pipe
	ExecutionShape string
	// ParallelPoints for reflow --parallel sweeps.
	ParallelPoints []int
	// ProbeConcurrencyPoints for probe sweeps / full-pipe pairs.
	ProbeConcurrencyPoints []int
	// FullPipePairs is (probe, reflow) pairs for full-pipe profiles.
	FullPipePairs [][2]int
	// RequireOccupancy enables fixed-mode saturation occupancy sampling.
	RequireOccupancy bool
	// NoAdaptive forces --no-adaptive.
	NoAdaptive bool
	// MemoryArms declares the memory envelopes each parallel point is run
	// under. Empty means a single arm with no memory override. See MemoryArm.
	MemoryArms []MemoryArm
	// CheckpointClasses lists disk and/or tmpfs discriminators.
	CheckpointClasses []string
	// Description is operator-facing sterile help.
	Description string
}

type Recipe struct {
	Version     string `json:"recipe_version"`
	Seed        int64  `json:"seed"`
	ObjectCount int    `json:"object_count"`
	SizeBytes   int    `json:"size_bytes"`
	Partitions  int    `json:"partitions"`
	// FixedDate is a sterile calendar token embedded in keys (not a field identity).
	FixedDate string `json:"fixed_date"`
}

type Report struct {
	SchemaVersion string `json:"schema_version"`

	BinaryVersion string `json:"binary_version,omitempty"`
	BinaryCommit  string `json:"binary_commit,omitempty"`
	BinarySHA256  string `json:"binary_sha256"`

	// Instrument identity is the harness (test binary / worktree), distinct from
	// the measured child Binary* fields (checkpoint measure / provenance gate). Never backfill
	// BinaryCommit from instrument HEAD.
	InstrumentCommit string `json:"instrument_commit,omitempty"`
	InstrumentSHA256 string `json:"instrument_sha256,omitempty"`
	InstrumentDirty  bool   `json:"instrument_dirty"` // always present: false=clean, true=dirty (probe fail aborts run)

	// Checkpoint-scale schedule provenance (empty for other profiles).
	ScheduleID    string   `json:"schedule_id,omitempty"`
	ScheduleOrder []string `json:"schedule_order,omitempty"` // e.g. "warm:disk:64", "p1:disk:64"

	Corpus CompactManifest `json:"corpus"`

	Profile                 string `json:"profile"`
	ProviderClass           string `json:"provider_class"`
	ThroughputEvidenceClass string `json:"throughput_evidence_class"`
	// MeasurementScope declares this cut's intent (small-scale honesty/relative).
	MeasurementScope string `json:"measurement_scope"`
	// AbsoluteEnvelopeValidation is not_evaluated until an opt-in BYO-cloud
	// scale lane is used; avoids presenting local/moto as a throughput oracle.
	AbsoluteEnvelopeValidation string `json:"absolute_envelope_validation"`

	OS   string `json:"os"`
	Arch string `json:"arch"`

	InvocationID string    `json:"invocation_id"`
	StartedAt    time.Time `json:"started_at"`

	Keep bool `json:"keep"`

	Points []PointReport `json:"points"`
}

type ScheduleStep struct {
	// PairIndex is 0 for warmups; 1..N for retained matched pairs.
	PairIndex int
	// Warmup marks discarded arms (not retained in report / Δe2e).
	Warmup          bool
	Parallel        int
	CheckpointClass string // disk | tmpfs
	MemoryEnvelope  string
	// Ordinal is 0-based position in the full execution order (including warmups).
	Ordinal int
}

type ServiceDemandArmConfig struct {
	// StorePath is the APFS (or other quorum medium) checkpoint path.
	StorePath string
	// Submitters is fixed concurrent mutation callers.
	Submitters int
	// Units is the number of terminal units (each = 3 admissions). 0 → formal quantum.
	Units int
	// MinAdmissions overrides the formal work quantum when > 0 (tests only).
	MinAdmissions int64
	// ElideRawExecSavepoints enables experimental Phase A elision for this arm.
	ElideRawExecSavepoints bool
}

type ServiceDemandArmReport struct {
	Submitters           int                                `json:"submitters"`
	Units                int                                `json:"units"`
	AdmissionsTarget     int64                              `json:"admissions_target"`
	WallSeconds          float64                            `json:"wall_seconds"`
	MutationsPerSec      float64                            `json:"mutations_per_sec"`
	TransactionsPerSec   float64                            `json:"transactions_per_sec"`
	WriterUtilization    float64                            `json:"writer_utilization"`
	BarrierWaitLoad      float64                            `json:"barrier_wait_load"`
	BarrierWaitMeanNanos float64                            `json:"barrier_wait_mean_nanos"`
	BarrierWaitMaxNanos  int64                              `json:"barrier_wait_max_nanos"`
	AdmissionsPerBatch   float64                            `json:"admissions_per_batch"`
	ReachableOccupancy   float64                            `json:"reachable_occupancy"`
	AdmissionWaitMaxNs   int64                              `json:"admission_wait_max_nanos"`
	AdmissionBlocked     int64                              `json:"admission_blocked"`
	Honest               bool                               `json:"honest"`
	HonestyMessage       string                             `json:"honesty_message,omitempty"`
	WriterStats          reflow.CheckpointWriterStatsRecord `json:"writer_stats"`
}

type ServiceDemandCell struct {
	Rep        int                     `json:"rep"`
	Ordinal    int                     `json:"ordinal"`
	ScheduleID ServiceDemandScheduleID `json:"schedule_id"`
	Submitters int                     `json:"submitters"`
	ServiceDemandArmReport
}

type ServiceDemandDisposition string

type ServiceDemandScheduleID string

type ServiceDemandSetConfig struct {
	// RootDir holds per-arm SQLite files (fresh unique DB per arm).
	RootDir string
	// FormalReps is the list of formal rep indices (default 1,2,3). Pilot 0 excluded.
	FormalReps []int
	// Units overrides formal quantum for tests (0 → formal 100k units).
	Units int
	// MinAdmissions overrides formal quantum for tests.
	MinAdmissions int64
	// WorktreeCommitOverride is optional instrument commit override (tests).
	// When set, the set report is always non-formal (test-only identity).
	WorktreeCommitOverride string
	// MediumOverride labels reduced/non-formal structural runs (e.g. "test_tmp").
	// Empty + formal path → verified APFS medium (or set fails formal admission).
	MediumOverride string
	// SkipAPFSCheck allows structural tests on non-APFS roots; forces non-formal.
	SkipAPFSCheck bool
	// ElideRawExecSavepoints enables Phase A elision for every arm in the set.
	// Sets with elision are never formal baseline authority (wantFormalShape false).
	ElideRawExecSavepoints bool
}

type ServiceDemandSetReport struct {
	SchemaVersion    string `json:"schema_version"`
	Medium           string `json:"medium"`
	MixID            string `json:"mix_id"`
	AdmissionsPerArm int64  `json:"admissions_per_arm"`
	// Formal is true only for the default Day-0 shape: reps {1,2,3}, full
	// submitter grid, exact ServiceDemandAdmissionsPerArm on every cell.
	// Reduced Units/MinAdmissions/FormalReps sets are non-formal (structure only).
	Formal                 bool                     `json:"formal"`
	InstrumentSHABefore    string                   `json:"instrument_sha_before"`
	InstrumentCommitBefore string                   `json:"instrument_commit_before"`
	InstrumentDirtyBefore  bool                     `json:"instrument_dirty_before"`
	InstrumentSHAAfter     string                   `json:"instrument_sha_after"`
	InstrumentCommitAfter  string                   `json:"instrument_commit_after"`
	InstrumentDirtyAfter   bool                     `json:"instrument_dirty_after"`
	Cells                  []ServiceDemandCell      `json:"cells"`
	Disposition            ServiceDemandDisposition `json:"disposition"`
	DispositionMessage     string                   `json:"disposition_message,omitempty"`
}

type StageResult struct {
	Name       string        `json:"name"`
	ExitCode   int           `json:"exit_code"`
	Err        string        `json:"error,omitempty"`
	Stderr     string        `json:"stderr_excerpt,omitempty"`
	Duration   time.Duration `json:"duration_ns"`
	StartedAt  time.Time     `json:"-"`
	FinishedAt time.Time     `json:"-"`
}

type StageRunOpts struct {
	Binary         string
	InputPath      string
	DestURI        string
	Parallel       int
	CheckpointPath string
	GOMEMLIMIT     string
	// MemoryBudget is the operator --memory-budget size string. Empty omits the
	// flag entirely, so the product derives the budget from the detected limit.
	MemoryBudget  string
	NoAdaptive    bool
	ProviderClass string
	ExtraArgs     []string
	ChildExtraEnv []string
	// StdoutPath streams reflow JSONL to a file (bounded memory). Required for scale.
	StdoutPath string
	// RewriteFrom/To map probe output without dest_rel_key onto destinations.
	RewriteFrom string
	RewriteTo   string
}

type Tap struct {
	MaxRecordBytes        int
	AcceptReflowInputOnly bool
	// contains filtered or unexported fields
}

type TapStats struct {
	ValidReflowInputRows int64
	UnexpectedRows       int64
	BytesForwarded       int64
	FirstForward         time.Time
	LastForward          time.Time
	// CopyDuration is wall time of the tap Copy loop (includes producer pacing
	// and downstream backpressure). Not calibrated isolated overhead.
	CopyDuration time.Duration
}