Documentation
¶
Overview ¶
Package promote turns a real session directory into a deterministic eval case. It copies the journal verbatim, reconstructs scripted user inputs from journaled io.input events, and synthesizes a starter assertions.yaml the case author can tighten by hand.
The promote package owns no engine state — it is a pure-disk transform — so it can be exercised from tests without a running bus.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractInputs ¶
ExtractInputs returns the user-typed strings carried by io.input envelopes in the order they appear in the journal. Non-io.input envelopes are ignored. Empty input list yields an empty slice (not nil) so the YAML always serializes a deterministic shape.
The journal stores io.input payloads as either typed events.UserInput (when the writer ran with the live bus) or as map[string]any (post-reload from disk, since journal.Reader unmarshals payloads to interface{}). Both shapes are honored.
func SynthesizeAssertions ¶
SynthesizeAssertions returns the YAML body for assertions.yaml derived from the journal observations. The output is pure data + comments; the caller is expected to launch $EDITOR and tighten the bounds.
The scaffold uses exact-count event_count_bounds (min=max=count) so the case is initially a strict regression-replay. The user loosens bounds as they pull the case into a broader test scenario. Token and latency budgets get 10% / 50% slack respectively.
Types ¶
type PromoteOptions ¶
type PromoteOptions struct {
// SessionDir is the absolute path to ~/.nexus/sessions/<id>. The CLI is
// responsible for resolving an ID to a path via engine.ExpandPath; this
// package treats the value as already-resolved.
SessionDir string
// CaseID is the new case's identifier; becomes the basename of the
// resulting case directory under CasesDir.
CaseID string
// CasesDir is the absolute path to tests/eval/cases (or the user's
// chosen alternative).
CasesDir string
// Owner is recorded into case.yaml. If empty, falls back to $USER, then
// "unknown".
Owner string
// Tags is recorded into case.yaml as the case's tag list.
Tags []string
// Description is recorded into case.yaml. If empty, a synthesized
// default referencing the source session ID is used.
Description string
// OpenEditor, when true, exec's $EDITOR (fallback chain: $VISUAL, nano,
// vi) on the assertions.yaml after Promote returns. The CLI surface
// owns this — library callers typically leave it false.
OpenEditor bool
// Force, when true, overwrites an existing case directory at the
// destination path. Without Force, an existing directory is an error.
Force bool
// Now, when non-zero, overrides time.Now() for recorded_at. Tests use
// it to land deterministic timestamps.
Now time.Time
}
PromoteOptions controls a single Promote call.
type PromoteResult ¶
type PromoteResult struct {
// CaseDir is the absolute path of the new case directory.
CaseDir string
// InputCount is the number of io.input events the journal carried.
InputCount int
// EventCount is the total number of envelopes copied from the journal.
EventCount int
// Warnings are non-fatal advisories surfaced to the user — failed
// session statuses, non-replayable event types, missing config
// snapshot, etc.
Warnings []string
}
PromoteResult is what Promote returns to its caller. CLI prints fields from it; tests assert on them.
func Promote ¶
func Promote(ctx context.Context, opts PromoteOptions) (*PromoteResult, error)
Promote turns a real session directory into a deterministic eval case.
Steps:
- Validate the session dir, journal, and metadata exist.
- Validate / handle the destination case dir per opts.Force.
- Copy the journal byte-for-byte (header + active segment + rotated).
- Copy metadata/config-snapshot.yaml verbatim to input/config.yaml.
- Project journaled io.input events to input/inputs.yaml.
- Synthesize a starter assertions.yaml.
- Write case.yaml metadata.
- Optionally launch $EDITOR on assertions.yaml.
On failure after the case dir was created, Promote attempts to remove the partial directory so a retry isn't blocked by a stale shell.