isolationtest

type Control string

type Engine struct {
	Eng   *cypher.Engine
	Close func() error
}

type EngineFactory func() (*Engine, error)

type Observation struct {
	// Permutation is the interleaving in force, and is the exact string
	// [Runner.Only] takes to replay it.
	Permutation string
	// Step is the step's name.
	Step string
	// Cols and Rows are the step's result, as rendered strings. Strings rather
	// than typed values because the transcript is the contract: an invariant
	// must be checking the same thing the golden file records, not a parallel
	// view of it that could disagree.
	Cols []string
	Rows [][]string
	// Err is the step's error, if any.
	Err error
}

type Observer func(Observation) error

type Permutation struct {
	// Steps are the step names in execution order.
	Steps []string
	// Owner[i] is the session index that owns Steps[i].
	Owner []int
}

type Runner struct {
	// NewEngine builds the per-permutation engine. Required.
	NewEngine EngineFactory
	// BlockTimeout overrides [DefaultBlockTimeout] when non-zero.
	BlockTimeout time.Duration
	// PermutationTimeout overrides [DefaultPermutationTimeout] when non-zero.
	PermutationTimeout time.Duration
	// Only, when non-empty, restricts the run to the single permutation with
	// this name — the exact string a golden file prints after "starting
	// permutation: ". This is the re-runnability contract: a failing
	// permutation is named in the diff and can be replayed on its own.
	Only string
	// Observe, when non-nil, is called for every completed step. See [Observer].
	Observe Observer
	// contains filtered or unexported fields
}

type Session struct {
	// Name identifies the session in the rendered output.
	Name string
	// Setup runs once per permutation, on this session, before any of its steps.
	// Typically a single Begin.
	Setup []Step
	// Steps are the session's units of work, in the order this session must run
	// them. Every enumerated permutation preserves this order.
	Steps []Step
	// Teardown runs once per permutation, on this session, after the permutation
	// completes. Errors here are rendered but do not fail the permutation, so a
	// COMMIT of an already-finished transaction is a harmless no-op to script.
	Teardown []Step
}

type Spec struct {
	// Name is the spec's identity; the golden file is testdata/<Name>.golden.
	Name string
	// Doc is prose describing what the scenario is FOR. It is rendered into the
	// golden output, so the file explains itself to whoever reads the diff.
	Doc string
	// Setup runs once per permutation on a control session, before any session
	// setup. Build the fixture here.
	Setup []Step
	// Teardown runs once per permutation on the control session, last.
	Teardown []Step
	// Sessions are the scripted actors. Their declaration order is the tie-break
	// the enumeration uses, so it fixes the order permutations are emitted in.
	Sessions []*Session
	// Permutations, when non-empty, are the ONLY interleavings run, each given
	// as a list of step names. When empty every valid interleaving is
	// enumerated. This mirrors PostgreSQL's rule exactly, and it is the escape
	// hatch for a scenario whose full enumeration is too large for its test
	// layer or whose steps genuinely block.
	Permutations [][]string
}

type Step struct {
	// Name identifies the step and MUST be unique across the whole spec: it is
	// what makes a failing permutation re-runnable by name.
	Name string
	// Query is the Cypher this step executes. Empty when Ctl is set.
	Query string
	// Ctl is the transaction-control verb this step performs. Empty when Query
	// is set.
	Ctl Control
	// Hook is an escape hatch: a step body written in Go rather than in Cypher.
	//
	// It exists for the things a query language cannot express and an isolation
	// harness nevertheless has to script — a rendezvous between two sessions, a
	// deliberate wait, a fault injected at a precise point in an interleaving.
	// PostgreSQL needs no equivalent because SQL has pg_sleep and advisory
	// locks; GoGraph's step vocabulary is Cypher, which has neither.
	//
	// A Hook runs on its session's goroutine exactly where a Query would, so it
	// participates in blocking detection identically: a Hook that does not
	// return within the block timeout is reported as `<waiting …>` and its
	// completion is reported when it is observed. Label is what the transcript
	// prints in place of the query text, so a Hook step renders deterministically
	// (a Go closure has no stable text).
	Hook  func(ctx context.Context) error
	Label string
	// Params are the query parameters, if any. Rendered into the output so a
	// golden file records what was actually run.
	Params map[string]any
}