returnplan

type Applier func(target any, p *Plan) (unmatched []Path, ok bool)

type Companion struct {
	Path Path
	With string
}

type Path struct {
	Segments []Segment
	// Open is set by the schema resolver when the path steps through a
	// map key or an open (`any`) value, whose keys predict cannot know:
	// at runtime such an include may match nothing (the
	// PULSE_RETURN_PATH_UNMATCHED warning). Not part of the canonical
	// form.
	Open bool
}

type Plan struct {
	// Preset is the preset name the block resolved from, PresetCustom
	// for an explicit include / exclude without one.
	Preset string
	// Include, Exclude and Keep are canonical: deduplicated, sorted by
	// spelling, with every path another one already covers removed, an
	// include an exclude covers removed, an exclude that touches no
	// include or keep path removed, and a keep path an include covers
	// removed.
	Include []Path
	Exclude []Path
	Keep    []Path
	// Companions are the CONDITIONAL selections a preset carries: each
	// one keeps a map key beside a kept sibling (Companion). Canonical
	// like Keep: one an include or exclude covers is removed. Answered by
	// VisitIn, never by Visit (which cannot see the parent map).
	Companions []Companion
	// Precision is the wire float significant-digit count, 0 unlimited.
	Precision int
	// Exact lists the REQUEST-DERIVED precision exemptions: nodes (and
	// their subtrees) whose floats carry integer semantics for this
	// request — a count aggregation's data column, a count crosstab
	// cell — written at full precision even when Precision is set. The
	// resolver fills it (internal/descriptor/return_resolve.go); the
	// response-type exemptions that hold for every request live beside
	// the encoder (types/return_shape.go, precisionExempt). Derived from
	// the request, never part of the selection, so outside the digest.
	Exact []Path
	// SelectsAll reports that Include covers every top-level key of the
	// root, so the root itself is selected whole.
	SelectsAll bool
	// Digest identifies the resolved selection (Include, Exclude, Keep,
	// Companions, Precision — not the preset name), so equivalent
	// spellings share it.
	Digest string
}

type RowEncoder func(owner any, row map[string]any) ([]byte, error)

type Segment struct {
	// Name is the JSON key, or the glob PREFIX when Glob is set (so
	// `effect_*` is Name "effect_" with Glob true; `*` alone is Name ""
	// with Glob true). Empty for an Index segment.
	Name string
	// Glob marks a suffix `*` map-key glob.
	Glob bool
	// Index marks the `[*]` array wildcard.
	Index bool
}

type SyntaxError struct {
	Path   string
	Reason string
}

type Verdict struct {
	// Keep is false when the node is absent on the wire.
	Keep bool
	// Whole means the node's whole subtree is emitted untouched: the
	// caller need not descend. Keep && !Whole means descend and ask for
	// each child.
	Whole bool
}