harness

Documentation

Overview

Package harness is the host-side trigger/render client for the resident pure-M harness (design §3.1, spec §9). The harness's contract is its output *frame*, not its transport: a deterministic line-delimited envelope of verbatim ^STDASSERT per-suite blocks + a verbatim LCOV block + provenance tags (§3.2). This package is a thin frame-splitter — it owns NO test/coverage parsing. Each suite block is handed to the unchanged mtest.ParseOutput and the LCOV block to the unchanged mcov consumers, which is what structurally guarantees G4 cross-engine parity (the resident tier and the file-side tier speak the exact same dialect).

Index

• Constants
• Variables
• func RunResident(ctx context.Context, eng engine.Engine, suites []mtest.TestSuite) ([]mtest.RunResult, error)
• func SplitFrame(frame string) ([]SuiteBlock, string, string, FrameMeta, error)
• func Trigger(ctx context.Context, eng engine.Engine, scope []string) (string, error)
• func TriggerCoverage(ctx context.Context, eng engine.Engine, scope, routines []string) (string, error)
• type FrameMeta
• type Merged
  • func Reconcile(fileSide, resident []mtest.RunResult) Merged
• type Provenanced
• type SuiteBlock

Constants

const (
	SourceFileSide = "file-side"
	SourceResident = "resident"
)

Source names which tier produced a result.

Variables

var (
	// ErrNoFrame means the input had no ##M-HARNESS header — not a frame.
	ErrNoFrame = errors.New("harness: missing ##M-HARNESS header")
	// ErrTruncated means the stream ended before the ##END-HARNESS trailer, or
	// the trailer's suite count disagrees with the blocks parsed — a dropped
	// connection. Partial results are still returned alongside it.
	ErrTruncated = errors.New("harness: truncated frame (missing or mismatched trailer)")
)

Functions

func RunResident

func RunResident(ctx context.Context, eng engine.Engine, suites []mtest.TestSuite) ([]mtest.RunResult, error)

RunResident triggers the resident orchestrator for the given suites and maps the framed result back into the SAME mtest.RunResult shape the file-side runner produces — so the two tiers reconcile (Reconcile) and render through one path. A suite is ok only when its parsed summary is ok AND its ##END exit is 0 (a mid-suite crash reads as a fail), identical to mtest.RunSuite. A structurally bad frame (no header, truncated stream) is an error.

func SplitFrame

func SplitFrame(frame string) ([]SuiteBlock, string, string, FrameMeta, error)

SplitFrame splits the result frame (§3.2) into per-suite ^STDASSERT blocks, the LCOV block, the raw ##MON line-monitor block (both empty when coverage was not requested), and the provenance / summary metadata. It is delimiter- scanning only — no test or coverage parsing happens here. Unrecognized ## directives are skipped (forward-compat). A missing header is ErrNoFrame; a missing/mismatched trailer is ErrTruncated, returned alongside whatever was parsed so a caller can still render it.

func Trigger

func Trigger(ctx context.Context, eng engine.Engine, scope []string) (string, error)

Trigger invokes the resident orchestrator run^STDHARN over the engine adapter and returns the raw result frame (design §3.1, the CLI trigger path). It is pure delegation — the scope (suite routine names) is passed straight to run^STDHARN and the frame comes back on the engine's stdout. The same frame travels over T.1's WebSocket transport unchanged.

It drives run^STDHARN through RunScript (direct mode) rather than RunRoutine so it is engine-portable: the YDB-only RUN^STDHARN entry reads $ZCMDLINE, which IRIS lacks, whereas passing scope as an M argument works on both.

The routines (STDHARN, STDASSERT, the suites) must already be available to the engine — staged/loaded by the caller, exactly as the host-orchestrated path arranges them. Suite names are routine names (no quoting hazard).

func TriggerCoverage

func TriggerCoverage(ctx context.Context, eng engine.Engine, scope, routines []string) (string, error)

TriggerCoverage invokes cov^STDHARN, which runs the scope under the IRIS line monitor over the named routines and adds a raw ##MON block to the frame (the host joins it via mcov.FromMonitor). On YDB the ##MON block is empty by design (YDB coverage stays the host-side view "TRACE" path); resident coverage is the IRIS tier.

Types

type FrameMeta

type FrameMeta struct {
	Frame  int
	Tier   string
	Engine string
	NS     string
	Suites int
	Pass   int
	Fail   int
}

FrameMeta carries the header provenance (render label) and the trailer cross-check totals.

type Merged

type Merged struct {
	Results []Provenanced // one per suite, file-side first then resident-only, in order
	OK      bool          // union: false if ANY suite failed on either tier
}

Merged is the reconciled two-tier verdict (design §3.4, spec §9.1-Q6).

func Reconcile

func Reconcile(fileSide, resident []mtest.RunResult) Merged

Reconcile produces one verdict by provenance. The file-side tier is authoritative for pure-logic suites (the deterministic PR gate); the resident IRIS tier is authoritative for integration suites (the live DD + data). The host runs each suite on exactly one tier, so the two result sets are normally disjoint; on conflict for the same suite the integration (resident) verdict wins — reality beats the file-side approximation. The OK is the UNION: any failure on either tier ⇒ not OK, so `m test`'s exit is non-zero (spec §3.3).

type Provenanced

type Provenanced struct {
	Result mtest.RunResult
	Tier   string // mtest.TierPureLogic | mtest.TierIntegration
	Source string // SourceFileSide | SourceResident
}

Provenanced is one suite's result tagged with the tier it is authoritative for and which tier actually produced it.

type SuiteBlock

type SuiteBlock struct {
	Name string
	Body string
	Exit int
}

SuiteBlock is one per-suite payload: Name is the suite (the ##SUITE token with any leading ^ stripped, so it matches mtest.TestSuite.Name), Body is the verbatim ^STDASSERT text between the ##SUITE and ##END lines (fed unchanged to mtest.ParseOutput), Exit is the engine exit code from the ##END line.