promote

package
v0.32.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 15 Imported by: 0

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

func ExtractInputs(envs []journal.Envelope) []string

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

func SynthesizeAssertions(envs []journal.Envelope) ([]byte, error)

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:

  1. Validate the session dir, journal, and metadata exist.
  2. Validate / handle the destination case dir per opts.Force.
  3. Copy the journal byte-for-byte (header + active segment + rotated).
  4. Copy metadata/config-snapshot.yaml verbatim to input/config.yaml.
  5. Project journaled io.input events to input/inputs.yaml.
  6. Synthesize a starter assertions.yaml.
  7. Write case.yaml metadata.
  8. 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL