wireoracle

type Anchor struct {
	// Scenario is the name of the Scenarios() entry this anchor checks.
	Scenario string
	// Name describes what this anchor asserts, for -v test output and
	// failure messages.
	Name string
	// Assert decodes only the one field this anchor names out of the raw
	// captured stdout — never by unmarshalling into an SDK type — and
	// fails the test if it does not hold.
	Assert func(t *testing.T, stdout []byte)
}

type Rule struct {
	Name        string
	Placeholder string
	ExpectFires bool
	Why         string
}

type Scenario struct {
	// Name identifies the scenario and its frozen transcript file
	// (testdata/wireoracle/transcripts/<Name>.golden).
	Name string
	// Env holds extra "KEY=VALUE" entries appended to the subprocess's
	// environment, alongside the always-on CODEGRAPH_NO_WATCH=1.
	Env []string
	// Index, when true, runs `codegraph init <workDir>` to completion
	// before starting `serve --mcp`.
	Index bool
	// Requests is the ordered list of JSON-RPC requests written to the
	// subprocess's stdin, one per line.
	Requests []map[string]any
	// ExpectTools is the tool count this scenario's session is expected
	// to advertise via VRFY-03's stderr session line.
	ExpectTools int
	// NoInitialize, when true, means this scenario's session never sends an
	// "initialize" request at all — request id 1 is some other method
	// entirely (used by edge-call-before-initialize, the statelessness
	// edge, RESEARCH Pitfall 2: mark3labs v0.56.0 never gates
	// tools/list/tools/call on Initialized()). Two invariants that only
	// make sense downstream of a real initialize handshake are skipped for
	// a NoInitialize scenario — via this field, not a scenario-name
	// special case (01-04-PLAN Task 2): the VRFY-03 stderr session line
	// (its AddAfterInitialize hook never fires with no initialize call to
	// hook) and the D-02 protocolVersion spec anchor (there is no
	// initialize result.protocolVersion field to assert against).
	NoInitialize bool
	// EraScenario, when true, marks this as one of the six-era Legacy
	// handshake baseline scenarios (01-05-PLAN Task 1 checkpoint:
	// six-era). Every OTHER scenario in this package offers the same
	// literal protocol version as internal/mcp.ProtocolVersion
	// (handshakeExploreProtocolVersion), so oracle_test.go's default D-02
	// spec-anchor comparison hardcodes that one shared literal; an era
	// scenario deliberately offers a DIFFERENT revision, so it carries its
	// own expected offered/negotiated pair instead via
	// EraOfferedVersion/EraNegotiatedVersion.
	EraScenario bool
	// EraOfferedVersion is the literal protocolVersion this era
	// scenario's initialize request offers — "" for legacy-omitted-version,
	// whose params carry no protocolVersion key at all (a plain Go string
	// field defaults to "" whether the key is omitted or sent empty; this
	// package always sends the true omitted-key wire shape, never an
	// empty-string literal — see initializeRequestOmittingVersion).
	EraOfferedVersion string
	// EraNegotiatedVersion is what mark3labs v0.56.0 is expected to
	// negotiate for EraOfferedVersion: itself, for the four supported
	// revisions; the server's own latest, for the unsupported revision
	// (silent coercion); or the server's older backwards-compat default,
	// for the omitted-version case. Three structurally distinct outcomes,
	// never assumed equal to EraOfferedVersion except for the four
	// supported revisions (RESEARCH Pitfall 1).
	EraNegotiatedVersion string
	// InitAfterRequest is the 1-based index into Requests after whose
	// RESPONSE HAS BEEN OBSERVED the harness runs `binPath init workDir`
	// against the already-running server's working directory — SPEC-05's
	// index-appears-mid-session proof (03-04-PLAN.md Task 2). Zero (the
	// field's Go zero value) means "never run init mid-session," so every
	// scenario that predates this field is completely unaffected.
	//
	// "Response has been observed" is load-bearing, not a nicety: writing
	// every request up front and running init partway through would be
	// non-deterministic — the later requests would already sit in the
	// subprocess's stdin pipe, and a pre-init tools/list could be
	// serviced by the server before or after init completes depending on
	// scheduling, flipping the frozen bytes run to run. Capture instead
	// blocks, after writing the InitAfterRequest'th request, until THAT
	// request's own response id has been read from stdout (bounded by
	// Capture's existing runCtx deadline) before running init and before
	// writing any further request. Determinism comes from observing the
	// response, never from a sleep.
	InitAfterRequest int
	// AwaitAfterRequest maps a 1-based index into Requests to a JSON-RPC
	// "method" value. After writing that request, Capture blocks until a
	// frame carrying that method has been observed on stdout — before
	// writing the next request, or, when the index names the LAST request,
	// before closing stdin. A nil map (every scenario predating this field)
	// waits for nothing and takes the identical code path it took before
	// this field existed.
	//
	// Two entries are load-bearing for two DIFFERENT reasons (05-01-PLAN,
	// SPEC-09), and both matter for a subscriptions/listen scenario:
	//
	//  1. An entry on the LAST request is what makes a long-lived
	//     notification stream's transcript deterministic rather than
	//     quietly weaker. go-sdk's changeAndNotify debounces a list-changed
	//     notification through a 10ms time.AfterFunc; if Capture closed
	//     stdin immediately after the mutating request instead of waiting
	//     for the notification to actually arrive, process shutdown would
	//     race that timer and could drop the notification from the
	//     transcript entirely — not a loud failure, a silently thinner one.
	//  2. An entry on a request whose response the harness does NOT wait
	//     for via InitAfterRequest exists because go-sdk calls
	//     jsonrpc2.Async for every call except "initialize" — so the
	//     acknowledgment frame a request like subscriptions/listen produces
	//     races the response to whatever request is written after it.
	//     Waiting for the acknowledgment's own method before writing the
	//     next request is what keeps the captured line order deterministic.
	AwaitAfterRequest map[int]string
	// NoResponseRequests holds 1-based indices into Requests whose JSON-RPC
	// id never carries a response line on this transport, at all, when the
	// session ends at stdin EOF.
	//
	// MEASURED (05-01-PLAN, 5/5 isolated runs against a freshly built
	// binary): a subscriptions/listen request's own id-bearing
	// SubscriptionsListenResult is sent ONLY when the server tears the
	// subscription down gracefully — go-sdk's own doc comment on that type
	// says so verbatim — and an abrupt stdio close (stdin EOF) is not that
	// path. This is go-sdk's own documented design, not a codegraph defect
	// and not something to work around: a scenario with a live
	// subscriptions/listen stream must name that request's index here, or
	// Capture's completion condition (and assertFramingInvariant's
	// exactly-one check) would wait forever for a response frame that is
	// never coming.
	//
	// Capture's own completion condition and assertFramingInvariant
	// (oracle_test.go) both read the ONE seam this field feeds —
	// Scenario.expectedResponseIDs() — so the two can never drift apart on
	// what a scenario owes, mirroring the one-seam rule Phase 3 applied to
	// registerTools/unregisterTools.
	NoResponseRequests []int
}

type Substitutions struct {
	// RepoDir is the capture-time absolute path of the copied fixture
	// tree (Transcript.RepoDir) — the value the repoDir rule replaces.
	RepoDir string
}

type Transcript struct {
	// Stdout is every captured stdout line, newline-joined, RAW (not yet
	// normalized).
	Stdout []byte
	// Stderr is the subprocess's complete captured stderr output.
	Stderr string
	// RepoDir is the workDir the fixture was copied into and the
	// subprocess ran against — callers use it to build Substitutions
	// without recomputing the path.
	RepoDir string
}