guide

Documentation

Overview

Package guide turns explicit operator answers and reviewed normalized evidence into one deterministic, strictly gated authoring bundle.

Guide is not a browser command language. It accepts only the closed browser.1.5 macro vocabulary and never infers a sequence, mutation, side effect, confirmation policy, or ambiguity decision from evidence.

Index

• Constants
• func MarshalDeterministic(bundle *Bundle) ([]byte, error)
• type ActionIntent
• type AmbiguityResolution
• type Bundle
  • func Author(catalog *Catalog, intent Intent, assessedAt time.Time) (*Bundle, error)
  • func RunWizard(in io.Reader, prompts io.Writer, records []evidence.Record, ...) (*Bundle, error)
• type Catalog
  • func NewCatalog(records []evidence.Record) (*Catalog, error)
• type Intent
• type LocatorCandidate
• type OriginCandidate
• type OutputCandidate
• type OutputDeclaration
• type ParameterIntent
• type RecordCandidate
• type StepIntent
• type WaitIntent

Constants

const (
	// BundleVersion identifies the deterministic guided-authoring envelope.
	BundleVersion = "browsertools.guided-authoring.v1"
)

Functions

func MarshalDeterministic

func MarshalDeterministic(bundle *Bundle) ([]byte, error)

MarshalDeterministic returns stable indented JSON with one trailing newline.

Types

type ActionIntent

type ActionIntent struct {
	ID                   string                     `json:"id"`
	Description          string                     `json:"description,omitempty"`
	EvidenceIDs          []string                   `json:"evidenceIds"`
	Parameters           []ParameterIntent          `json:"parameters"`
	Sequence             []StepIntent               `json:"sequence"`
	OutputIDs            []string                   `json:"outputIds"`
	OutputDeclarations   []OutputDeclaration        `json:"outputDeclarations,omitempty"`
	SideEffects          []profile.SideEffect       `json:"sideEffects"`
	ConfirmationPolicy   profile.ConfirmationPolicy `json:"confirmationPolicy"`
	AmbiguityResolutions []AmbiguityResolution      `json:"ambiguityResolutions"`
}

ActionIntent maps selected evidence to one explicitly named capability.

type AmbiguityResolution

type AmbiguityResolution struct {
	LocatorID string `json:"locatorId"`
	Rationale string `json:"rationale"`
}

AmbiguityResolution records the operator's rationale for one selected ambiguous accessibility candidate.

type Bundle

type Bundle struct {
	Version   string                     `json:"version"`
	Spec      draft.Spec                 `json:"spec"`
	Profile   profile.Profile            `json:"profile"`
	Evidence  []evidence.Record          `json:"evidence"`
	Decisions []evidence.LocatorDecision `json:"decisions"`
	Review    review.Bundle              `json:"review"`
}

Bundle contains every artifact needed by the existing strict handoff gates.

func Author

func Author(catalog *Catalog, intent Intent, assessedAt time.Time) (*Bundle, error)

Author materializes and verifies every guided artifact. It returns only a bundle that passes draft, schema, fixture revalidation, review, expiry, and digest verification at assessedAt.

func RunWizard

func RunWizard(in io.Reader, prompts io.Writer, records []evidence.Record, assessedAt time.Time) (*Bundle, error)

RunWizard presents a deterministic terminal questionnaire and returns only a strictly promotable guided-authoring bundle. Prompts go to prompts so JSON output can remain separate. Answers are read one line at a time; no answer is treated as a browser instruction or executable code.

type Catalog

type Catalog struct {
	Records  []RecordCandidate  `json:"records"`
	Origins  []OriginCandidate  `json:"origins"`
	Locators []LocatorCandidate `json:"locators"`
	Outputs  []OutputCandidate  `json:"outputs"`
	// contains filtered or unexported fields
}

Catalog is a canonical, stable-ID view of reviewed normalized evidence. IDs are local authoring references and never enter a portable profile.

func NewCatalog

func NewCatalog(records []evidence.Record) (*Catalog, error)

NewCatalog validates, canonicalizes, and assigns deterministic local IDs to normalized evidence. The input is never mutated.

type Intent

type Intent struct {
	Info            profile.Info            `json:"info"`
	ObservationKind profile.ObservationKind `json:"observationKind"`
	Confidence      profile.Confidence      `json:"confidence"`
	ExpiresAfter    profile.Duration        `json:"expiresAfter"`
	Actions         []ActionIntent          `json:"actions"`
}

Intent is the complete set of explicit answers accepted from an operator.

type LocatorCandidate

type LocatorCandidate struct {
	ID         string                    `json:"id"`
	RecordID   string                    `json:"recordId"`
	Locator    evidence.CandidateLocator `json:"locator"`
	FromOutput bool                      `json:"fromOutput,omitempty"`
}

LocatorCandidate identifies one accessibility candidate within a record.

type OriginCandidate

type OriginCandidate struct {
	ID     string `json:"id"`
	Origin string `json:"origin"`
}

OriginCandidate identifies one canonical observed origin.

type OutputCandidate

type OutputCandidate struct {
	ID        string                   `json:"id"`
	RecordID  string                   `json:"recordId"`
	Output    evidence.CandidateOutput `json:"output"`
	LocatorID string                   `json:"locatorId,omitempty"`
	Bound     bool                     `json:"bound"`
}

OutputCandidate identifies one output candidate within a record.

type OutputDeclaration

type OutputDeclaration struct {
	HintID         string                 `json:"hintId"`
	Source         profile.OutputSource   `json:"source"`
	LocatorID      string                 `json:"locatorId,omitempty"`
	Property       string                 `json:"property,omitempty"`
	Selector       string                 `json:"selector,omitempty"`
	FallbackReason profile.FallbackReason `json:"fallbackReason,omitempty"`
}

OutputDeclaration binds one unbound extraction hint to an explicit portable source. The hint supplies only key/type; all source semantics are authored.

type ParameterIntent

type ParameterIntent struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Required bool   `json:"required"`
}

ParameterIntent is the deliberately restricted scalar parameter shape used by the wizard. Richer schemas remain available through draft.Spec.

type RecordCandidate

type RecordCandidate struct {
	ID               string `json:"id"`
	Origin           string `json:"origin"`
	ObservedAt       string `json:"observedAt"`
	Tool             string `json:"tool"`
	SourceActionHint string `json:"sourceActionHint,omitempty"`
}

RecordCandidate identifies one normalized observation.

type StepIntent

type StepIntent struct {
	Kind           profile.StepKind `json:"kind"`
	Navigate       string           `json:"navigate,omitempty"`
	LocatorID      string           `json:"locatorId,omitempty"`
	ValueParameter string           `json:"valueParameter,omitempty"`
	Wait           *WaitIntent      `json:"wait,omitempty"`
}

StepIntent is one explicit member of the closed browser.1.5 macro set.

type WaitIntent

type WaitIntent struct {
	LocatorID  string                  `json:"locatorId,omitempty"`
	Navigation *profile.NavigationWait `json:"navigation,omitempty"`
}

WaitIntent is a locator or navigation wait, never an arbitrary predicate.