playground

type Arrival struct {
	Mode ArrivalMode
	// Interval is the gap for ArrivalEvery.
	Interval time.Duration
	// PerHour is the mean rate for ArrivalPoisson.
	PerHour float64
	// Calendar confines arrivals to business hours: the stream pauses when it
	// closes and resumes when it opens, so a day's worth of cases lands inside the
	// day. The zero value is around the clock.
	Calendar
}

type ArrivalMode int

type ArrivalProfile struct {
	// Scheduled is false for a sequential plan, which has no schedule of its own:
	// its next arrival depends on the run, so there is no shape to draw and saying
	// so is better than drawing a flat line that means something else.
	Scheduled bool
	// Cases is how many the profile is of, and Start and End bound them.
	Cases      int
	Start, End time.Time
	// Buckets holds the arrivals per slice, oldest first. Empty when not Scheduled.
	Buckets []int
}

type Bucket struct {
	// At is when the slice begins; it is Width long.
	At time.Time
	// Started and Completed are the cases that arrived and finished inside it.
	Started, Completed int
	// InFlight is how many cases were still running at its end — arrivals minus
	// completions up to here, which is the work in progress a reader compares
	// against the arrival rate.
	InFlight int
}

type Budget struct {
	// MaxOccurrences caps how many scheduled things a single Run may carry out.
	MaxOccurrences int
	// Horizon caps how far simulated time may travel from where the Run started.
	// A run stops *before* stepping past it, so the horizon is never overshot.
	Horizon time.Duration
	// Stop, when set, is asked before every occurrence whether to give up. It is
	// how a pause reaches a run that is already in flight: the run holds the
	// session's goroutine, so the answer cannot come through the loop. Like the
	// other bounds, stopping this way is not quiescence.
	Stop func() bool
}

type Calendar struct {
	// Open are the windows in a day. Empty means the whole day.
	Open []Window
	// Days selects the weekdays, indexed by time.Weekday. The zero value — no day
	// selected — means every day.
	Days [7]bool
}

type CaseResult struct {
	InstanceKey uint64
	State       model.ProcessInstanceState
	// Path is the BPMN element ids a token activated, in order.
	Path []string
	// Variables are the case's root-scope variables as text.
	Variables map[string]string
	// Incidents is how many of this case's tokens are parked behind an incident.
	Incidents int
}

type CaseRow struct {
	// Index is the row's place in the dataset that produced it.
	Index       int
	InstanceKey uint64
	State       model.ProcessInstanceState
	Started     time.Time
	Ended       time.Time
	Duration    time.Duration
	Incidents   int
	// End is the BPMN id of the last element the case reached — the outcome a
	// reader groups the table by.
	End       string
	Variables map[string]string
}

type Check struct {
	Name   string
	Want   string
	Got    string
	Passed bool
	// Rule marks a check that came from a per-case rule rather than from a bound on
	// the run. Both decide the verdict alike; a reader is shown them differently,
	// because a rule's own breakdown says more than a check line has room for.
	Rule bool
}

type Choice struct {
	// Value is what the case carries. It is used as given, so a choice of numbers
	// arrives as a number and a choice of labels as a string.
	Value any
	// Weight is how often this option comes up relative to the others. Zero on
	// every option means they are equally likely; zero on one of several weighted
	// options means that one never comes up, which is how an option is kept in the
	// list while being switched off.
	Weight int
}

type Comparison struct{ Deltas []Delta }

type Dataset struct {
	// Count is how many cases to produce.
	Count int
	// Fields are the start variables each case carries. None is allowed: that is a
	// run of N cases with no input, which is a load test of the model's own shape.
	Fields []Field
}

type Delta struct {
	Name          string
	Unit          Unit
	Before, After int64
	// HigherIsBetter is the polarity of this measure, not a judgement about this
	// particular pair of runs — Better and Worse apply it to the numbers.
	HigherIsBetter bool
	// Neutral marks a measure that moved without that being good or bad, so it is
	// shown and not coloured. Not every number has a direction, and inventing one
	// for the sake of a green arrow is how a report starts misleading people.
	Neutral bool
}

type Durations struct {
	Count              int
	Min, P50, P90, Max time.Duration
	Mean               time.Duration
}

type ElementStat struct {
	Runs    int
	Work    time.Duration
	Wait    time.Duration
	MaxWait time.Duration
	// Incidents is how many tokens are parked on this element behind a simulated
	// failure. It is counted per element rather than only per run because "five
	// incidents" says a run went wrong and "five incidents, all at the payout" says
	// where — which is the question the run-wide total cannot answer.
	Incidents int
}

type ElementUse struct {
	Id    string
	Count int64
}

type Expectations struct {
	// MinCompleted is how many cases must reach an end event. It counts completions,
	// not starts: a run whose cases are all still parked has not completed them.
	MinCompleted int
	// MaxIncidents is how many tokens may be parked behind a simulated failure.
	// Nil is not checked; a pointer to zero is "none at all".
	MaxIncidents *int
	// MaxP50, MaxP90 and MaxDuration bound how long a case may take: the median for
	// the everyday case, p90 for the tail somebody actually waits through, and the
	// maximum for the promise that nothing takes longer than a day. Zero is not
	// checked — a bound of no time is not a thing anybody means.
	MaxP50, MaxP90, MaxDuration time.Duration
	// MinVisits and MaxVisits bound how many tokens passed through an element.
	// Coverage and outcome are the same statement about the same counter: "the
	// approval branch must be exercised" is a minimum of one, "the error branch must
	// stay rare" is a maximum.
	MinVisits, MaxVisits map[string]int64
	// MaxQueue bounds the longest queue a pool ever had — the capacity question
	// stated as a target rather than read off a table.
	MaxQueue map[string]int
	// Rules are the expectations stated per case rather than per run. They are the
	// statement the fields above cannot make: "the median is under four hours" is
	// true of a run, "an application under 50 000 from a grade-A customer is
	// approved" is true of a case, and a run that holds it nine times in ten is not
	// nine tenths right.
	//
	// They are judged from the cases, not from the report, so [Judge] takes their
	// outcomes rather than computing them: see [Sandbox.JudgeRules].
	Rules []Rule
}

type Field struct {
	// Name is the start variable this field writes.
	Name string
	Kind FieldKind
	// Min and Max bound FieldInt and FieldDecimal, inclusive. They are float64
	// because that is what a JSON number is; FieldInt requires whole ones.
	Min, Max float64
	// Decimals is how many places FieldDecimal draws to.
	Decimals int
	// PercentTrue is how often FieldBool is true.
	PercentTrue int
	// Choices are the options of FieldChoice.
	Choices []Choice
	// Value is what FieldConstant writes.
	Value any
	// Prefix goes in front of FieldSequence's number.
	Prefix string
	// MinOffset and MaxOffset bound FieldTimestamp, as offsets from the run's own
	// simulated start. They are relative because a Playground run happens on a
	// virtual clock: an absolute date typed in once is stale the next time the
	// scenario runs, while "some time in the last thirty days" stays true.
	MinOffset, MaxOffset time.Duration
	// OnlyDate writes a FieldTimestamp as a calendar date rather than an instant.
	OnlyDate bool
}

type FieldKind string

type FlowUse struct {
	From, To string
	Count    int64
}

type HeatMap struct {
	Elements []ElementUse
	Flows    []FlowUse
}

type Occurrence struct {
	Kind OccurrenceKind
	// Element is the BPMN element id the occurrence happened on; empty for a timer
	// tick, which may fire several timers that came due at the same instant.
	Element string
	// At is the simulated instant it happened at.
	At time.Time
}

type OccurrenceKind int

type Options struct {
	// ModelXML is the BPMN to run: a draft's XML, or a deployed definition's.
	ModelXML []byte
	// Root names the process to instantiate by its BPMN id. Empty picks the sole
	// executable process, and is an error if the model has several.
	Root string
	// BaseDir is where the sandbox's temporary directory is created. Empty uses the
	// host's temp dir.
	BaseDir string
	// StartTime is the instant simulated time starts at. The zero value starts at
	// the Unix epoch, which is legal but reads badly in a report; a caller that
	// shows times to a person should set it.
	StartTime time.Time
	// Seed makes the run reproducible: the same dataset, policy and seed replay the
	// same durations and failures.
	Seed int64
	// Stubs is the answering policy. The zero value parks every job, which is what
	// an environment with no workers does.
	Stubs StubSet
}

type Plan struct {
	// Cases are the start variables of each case, in the order they were given.
	// That order is the report's order.
	Cases [][]model.VariableValue
	// Arrival spreads them over simulated time. The zero value starts them all at
	// once.
	Arrival Arrival
}

type Pool struct {
	// Capacity is how many cases the pool works on at once. It must be at least 1.
	Capacity int
	// Calendar is when the pool works. The zero value is always.
	Calendar
}

type PoolStat struct {
	// Served is how many jobs the pool worked on, BusyTime the seat time they took
	// together (nine one-hour cases are nine hours of seat time however many seats
	// shared them), and MaxQueue the longest the queue in front of it ever got.
	Served   int
	BusyTime time.Duration
	MaxQueue int
	// Capacity is the pool's size, and Available the seat time its calendar offered
	// over the run — capacity times the working time, not times the wall clock.
	// Utilisation is BusyTime over Available, and the distinction is the whole
	// point: counting the nights and the weekend as idle capacity reads as "we have
	// room" on a pool with three hundred cases queued.
	Capacity  int
	Available time.Duration
}

type Progress struct {
	// Occurrences is how many scheduled things the run carried out.
	Occurrences int
	// Quiescent is true when the run stopped because nothing was left to do, and
	// false when it stopped on the budget — the difference between "the model is
	// finished" and "we stopped looking".
	Quiescent bool
	// SimTime is where simulated time stands now.
	SimTime time.Time
}

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

type Report struct {
	// Cases is how many were started, Completed how many reached an end event, and
	// Incidents how many tokens are parked behind a simulated failure. A completion
	// rate that quietly excluded the parked ones would be the useful-looking wrong
	// number.
	Cases, Completed, Incidents int
	// SimStart and SimEnd bound the run in simulated time.
	SimStart, SimEnd time.Time
	// MaxInFlight is the most cases that were ever active at the same time — the
	// work in progress a reader compares against the arrival rate.
	MaxInFlight int
	// Duration summarises the finished cases' elapsed time.
	Duration Durations
	// Visits counts every token that passed through an element (the heat map),
	// Elements what the sandbox measured at the jobs it answered (the bottleneck
	// ranking), and Pools what each pool did.
	Visits   map[string]int64
	Elements map[string]ElementStat
	Pools    map[string]PoolStat
	// Timeline is the same run laid out over simulated time, so a reader can see
	// when the work arrived and when it drained rather than only what it summed to.
	Timeline Timeline
}

type Rule struct {
	// Name labels the rule in the verdict. Empty reads the expressions back.
	Name string
	// When selects the cases the rule speaks about. Empty means every case.
	When string
	// Then is what those cases must show: their variables as the run left them,
	// plus "end" — the BPMN id of the last element the case reached — and
	// "durationSeconds", how long it took in simulated time.
	Then string
}

type RuleOutcome struct {
	Rule Rule
	// Cases is how many the run had; Matched how many the When selected.
	Cases, Matched int
	// Satisfied and Violated split the matched, finished cases.
	Satisfied, Violated int
	// Undecided is matched cases that never reached an end, so the Then could not
	// be judged. They are neither: the run has not finished answering for them, and
	// counting them either way would state something the run did not show.
	Undecided int
	// Examples are the first offending cases, by their position in the dataset, so
	// a reader can go and look at one rather than at a number. Bounded; Truncated
	// says the run had more.
	Examples  []int
	Truncated bool
}

type RunState string

type RunStatus struct {
	State RunState
	// Occurrences is how many scheduled things the run has carried out, Cases how
	// many have been created and Completed how many have finished. The last two
	// come from the engine's maintained counters, so asking is O(1) however large
	// the batch is.
	Occurrences      int
	Cases, Completed int
	// SimTime is where simulated time stands.
	SimTime time.Time
	// Err is why a failed run stopped.
	Err string
}

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

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

type Stub struct {
	// Min and Max bound the simulated time the work takes. The draw between them
	// is deterministic in the run's seed and the job's key, so a re-run with the
	// same seed produces the same durations. Max below Min is treated as Min.
	Min, Max time.Duration
	// Outputs are the variables the answer writes, as a worker's completion would.
	Outputs []model.VariableValue
	// FailPerMillion is the failure probability in parts per million (0 never
	// fails, 1_000_000 always). The draw is deterministic like the duration.
	FailPerMillion int32
	// FailMessage is the incident message a simulated failure raises. Empty uses a
	// message naming the element, so an incident is never anonymous.
	FailMessage string
	// ErrorCode, when set, makes a simulated failure throw a BPMN error with this
	// code — caught by a matching boundary or event subprocess — instead of raising
	// an incident. That is how a *business* error path is exercised, not just a
	// technical one.
	ErrorCode string
}

type StubSet struct {
	// Default answers every non-human job that ByElement does not name. Nil parks
	// them.
	Default *Stub
	// Human answers user tasks. Nil — the default — parks them for the person at
	// the keyboard: that is the interactive half of the Playground. A batch run
	// sets it, so 50 000 cases do not wait for anybody.
	Human *Stub
	// ByElement answers one BPMN element by id, ahead of Default and Human alike.
	ByElement map[string]Stub
	// Pools are the sets of workers elements compete for, by name. An element with
	// no pool is worked on the instant it arrives, however many cases are already
	// in flight — which is the right model for a machine and the wrong one for a
	// person.
	Pools map[string]Pool
	// PoolOf assigns a BPMN element to a pool by name. Naming a pool that does not
	// exist is refused at [Open]: a silently ignored assignment would show up only
	// as a waiting time that never appears.
	PoolOf map[string]string
}

type Task struct {
	JobKey      uint64
	InstanceKey uint64
	// Element is the BPMN element id. The name a person reads is not carried here:
	// the Modeler has the diagram, and the compiled graph only knows an element's
	// name where its own detail record happens to keep one.
	Element string
	// Human is true for a user task — modelled human work, as opposed to a job
	// whose worker simply has no stub configured.
	Human bool
}

type Timeline struct {
	Width   time.Duration
	Buckets []Bucket
	// contains filtered or unexported fields
}

type Unit int

type Verdict struct {
	Passed bool
	Checks []Check
}

type Window struct{ From, To time.Duration }