flowtest

type AutoFlowStart struct {
	Script []byte
	// ChannelArgs names the channel-typed arguments passed with the start
	// request. Only these channels are externally sendable: channel tokens
	// are minted for channels the caller passes in, never for channels the
	// flow creates itself.
	ChannelArgs []string
	// SessionIDKwarg, when non-empty, names a string kwarg the target injects
	// into the start request carrying the session UUID. AutoFlow scripts reject
	// undeclared kwargs, so injection is opt-in per unit; the script uses the
	// kwarg to mint session-unique side-effect tokens.
	SessionIDKwarg string
}

type AutocoreStart struct {
	Workflow string
	Input    proto.Message
}

type AutocoreTarget struct {
	Client              autocore.Client
	ExternalNamespaceID autocore.ExternalNamespaceID
}

type CancelOp struct{}

type CompositeTarget struct {
	Autocore Target
	AutoFlow Target
}

type DriveOp struct {
	At     time.Duration
	Send   *SendOp
	Cancel *CancelOp
	// ExpectError turns the op into an assertion about the engine's error
	// surface: the op must fail with an error whose text contains this
	// substring, and only then counts as behaved. Send ops only; empty means
	// the op is expected to succeed.
	//
	// Only sound for a refusal the engine decides without I/O, such as a
	// channel token it cannot parse or a payload it cannot marshal. A refusal
	// that could instead race an infrastructure fault would let chaos turn
	// environment noise into a safety violation, because a timeout or a
	// dropped connection is indistinguishable from the engine declining. The
	// assertion also cannot tell a harness-side failure from an engine one:
	// the target's own error for a channel it has no token for reads exactly
	// like a refusal, so the substring must name something only the engine says.
	ExpectError string
}

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

type DriverConfig struct {
	Log     *slog.Logger
	Target  Target
	Sources []WeightedSource
	Rate    RateModel
	// RNG drives source picking and unit generation. Seeded per replica so
	// replicas produce independent unit streams.
	RNG *rand.Rand
	// MaxInFlightSessions bounds concurrently running sessions. New arrivals
	// are skipped at the bound: the driver stays open-loop, so a saturated
	// target surfaces as skipped sessions rather than as silently stretched
	// arrival gaps. 0 means DefaultMaxInFlightSessions.
	MaxInFlightSessions int
	// InjectionDuration bounds how long Run produces new sessions. Zero means
	// unbounded. In-flight sessions finish their drive scripts before Run
	// returns; external cancellation aborts them.
	InjectionDuration time.Duration
	// Ledger records session intents and op outcomes. Nil disables recording.
	Ledger SessionLedger
	// Meter instruments the driver. Required when Ledger is set so skipped
	// sessions stay visible; a noop meter is used when nil otherwise.
	Meter otelmetric.Meter
	// SessionDeadline is the verification deadline margin recorded per session:
	// the session's ledger deadline is its start time plus its last drive
	// offset plus this. 0 means DefaultSessionDeadline.
	SessionDeadline time.Duration
}

type Expectation struct {
	// TerminalStates are the allowed outcomes. A set rather than a single
	// state, to absorb legitimate races such as cancel vs. completion.
	TerminalStates []TerminalState
	// Tokens are session-agnostic suffixes of the side-effect tokens the
	// workflow must record via the testkit module, exactly once each: the
	// driver prefixes each with "<session-uuid>:" per session, and the script
	// builds the full token the same way from its session-id kwarg.
	// Order-irrelevant; empty means the unit expects none.
	Tokens []string
}

type FlowcoreEngine interface {
	RunWorkflow(ctx context.Context, namespaceID int64, idempotencyKey string, opts *flowcore.RunWorkflowOptions) (*flowcore.RunWorkflowResult, error)
	CancelWorkflow(ctx context.Context, workflowKey, workflowToken string) error
	SendToWorkflowChannel(ctx context.Context, idempotencyKey, channelToken, workflowToken string, value *pkg_autoflow.Value) error
}

type FlowcoreTarget struct {
	Engine      FlowcoreEngine
	NamespaceID int64
}

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

type ObserverConfig struct {
	Log    *slog.Logger
	Store  *ledger.Store
	Client WorkflowInfoClient
	// Meter instruments the observer. Optional; nil means no metrics.
	Meter otelmetric.Meter
	// Interval is the pause between ticks. 0 means DefaultObserveInterval.
	Interval time.Duration
	// BatchSize caps sessions resolved per tick. 0 means DefaultObserveBatchSize.
	BatchSize int
	// MinAge excludes sessions younger than this. 0 means DefaultObserveMinAge.
	MinAge time.Duration
	// MaxAge excludes sessions older than this. 0 means DefaultObserveMaxAge.
	MaxAge time.Duration
}

type Provenance struct {
	Seed             *int64
	GeneratorVersion string
	// GeneratorConfig is the generator's own canonical form of the effective
	// config it drew under: the input a re-render needs beyond the seed, recorded
	// per unit so it survives a retuned or swarmed generator.
	GeneratorConfig string
}

type RateModel struct {
	Min    int
	Max    int
	Period time.Duration
	Seed   uint64
}

type SendOp struct {
	Channel string
	// RawToken addresses the send with this literal channel token instead of
	// the token the start minted for a channel, which is how a unit addresses
	// a channel the engine never handed it. AutoFlow units only.
	RawToken string
	Payload  proto.Message
}

type SessionHandle interface {
	// WorkflowKey identifies the started workflow in its engine's format.
	WorkflowKey() string
	Send(ctx context.Context, idempotencyKey string, op *SendOp) error
	Cancel(ctx context.Context) error
}

type SessionInfo struct {
	ID             uuid.UUID
	IdempotencyKey string
}

type SessionLedger interface {
	SessionStarted(ctx context.Context, rec *ledger.SessionRecord) error
	WorkflowKeyKnown(sessionID uuid.UUID, key string)
	OpDone(sessionID uuid.UUID, opIndex int32, err error)
}

type Source interface {
	Name() string
	// NextUnit returns the next Unit. All randomness must come from rng so a
	// run is reproducible from its seed.
	NextUnit(rng *rand.Rand) (*Unit, error)
}

type StartSpec struct {
	AutoFlow *AutoFlowStart
	Autocore *AutocoreStart
}

type Target interface {
	Start(ctx context.Context, session SessionInfo, start StartSpec) (SessionHandle, error)
}

type TerminalState int

type Unit struct {
	Name        string
	Description string
	Start       StartSpec
	// Drive holds the timed external operations performed against the
	// running workflow, ordered by offset.
	Drive      []DriveOp
	Expect     Expectation
	Provenance Provenance
}

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

type WeightedSource struct {
	Source Source
	Weight int
}

type WorkflowInfoClient interface {
	GetWorkflowInfo(ctx context.Context, key autocore.WorkflowKey) (*autocore.WorkflowInfo, error)
}