template

type Rendered ¶

type Rendered struct {
	// Target is the template's declared target — the discriminant that
	// says which typed pointer below is populated.
	Target Target

	// JSON is the rendered body exactly as RenderJSON produced it,
	// before strict decode. It is always populated.
	JSON json.RawMessage

	// Request is populated iff Target is TargetRequest.
	Request *types.Request

	// Composed is populated iff Target is TargetComposed.
	Composed *types.ComposedRequest

	// Chain is populated iff Target is TargetChain.
	Chain *types.ChainRequest

	// Facet is populated iff Target is TargetFacet.
	Facet *types.FacetRequest

	// Sample is populated iff Target is TargetSample.
	Sample *types.SampleRequest
}

Rendered is the result of a complete render: the substituted JSON plus the typed request it decoded into.

Exactly one of the five typed pointers is non-nil, and which one is decided solely by Target. There are no generics and no per-target wrapper types — the caller reads the pointer its target names and hands it straight to the matching facade method (Process, Compose, ProcessChain, FacetSchema, SampleWithRequest). A caller that does not know the target ahead of time can switch on Target, or take the interface value from Typed.

JSON is retained alongside the typed value because the two answer different questions. The typed request is what gets executed; the raw JSON is what a caller shows a human, diffs against an expectation, or stores as the record of what a render produced. Re-marshaling the typed value would not reproduce it — every request struct is dense with omitempty, so a slot that rendered to an explicit zero would silently vanish from a round trip.

func Render(t *Template, supplied map[string]any) (*Rendered, error)

func (r *Rendered) Typed() any

type Resolution ¶

type Resolution struct {
	// contains filtered or unexported fields
}

Resolution is a template's declared variables resolved against a caller-supplied map: every declared name mapped either to its concrete JSON value or to Unresolved. It is the sole input to the render walk's substitution and `$when` guard evaluation.

Resolved values are decoded with json.Number in place of float64, so an integer supplied by the caller reaches the rendered request as the exact literal it was written as — a u64 field value never round-trips through float64 and never loses its low bits.

A Resolution is read-only once returned; every accessor is nil-safe.

func Resolve(t *Template, supplied map[string]any) (*Resolution, error)

func (r *Resolution) All() map[string]any

func (r *Resolution) Declared(name string) bool

func (r *Resolution) Get(name string) (any, bool)

func (r *Resolution) IsResolved(name string) bool

func (r *Resolution) Len() int

func (r *Resolution) Names() []string

type Store ¶

type Store struct {
	// contains filtered or unexported fields
}

Store is a name→template lookup built from an ordered list of directory roots. It is what makes a template a file rather than a Go literal.

Discovery ¶

Each configured root is walked with filepath.WalkDir and every *.json file under it becomes a template. Directories and non-.json files are skipped silently. A configured root that does not exist is skipped too — a layered setup routinely names an optional override directory that is simply absent — but a configured path that exists and is NOT a directory is an error, because that is a misconfiguration rather than an absence.

Naming ¶

A template's name is its path relative to its OWN root, minus the .json extension, forward-slash separated regardless of host. A file at templates/finance/revenue.json under the root templates/ is named finance/revenue. Subdirectories therefore namespace for free, and the root's own location never leaks into the name — which is what lets the same relative layout be served from two different roots.

The derived name is authoritative and is stamped onto Template.Name. A document may repeat its own name, but a document claiming a name its path does not give it is a PULSE_TEMPLATE_INVALID: silently renaming an author's template is exactly the class of surprise this surface exists to remove.

Within a single root, two files can never derive the same name — the mapping is invertible, since appending ".json" to a name recovers the relative path exactly. Collisions are therefore always cross-root.

Precedence ¶

Roots are an ordered precedence list and the FIRST root wins. A duplicate name across roots is not an error: the earlier root's entry answers lookups and the later ones are recorded as shadowed, surfacing in Summary.Shadows so a layered setup is visible rather than mysterious.

Precedence is resolved at LOOKUP time, not baked in at construction. That is deliberate: hot reload adds files to the index after the fact, and a file dropped into a lower-precedence root must never be able to displace — or break — a name that already worked.

Validation ¶

Every discovered file is read, parsed, and declaration-validated during construction, so a malformed template fails at startup with the offending path named rather than lying in wait until someone renders it. Parse alone cannot name the file (a document whose bytes do not parse has no knowable name), so the store re-raises every parse fault with the path and the derived name attached, preserving the original code.

Hot reload ¶

The index is a cached snapshot, not a boot-time freeze. A lookup whose snapshot has aged past templateRescanInterval re-walks the configured roots first, so a template file dropped into a scanned directory becomes renderable without restarting the process — and a deleted one stops resolving. Precedence is re-resolved from the fresh index, so a file appearing in a higher-precedence root starts shadowing a lower one and removing it hands the name back.

A rescan is a directory walk plus one os.Stat per candidate file. A file whose size AND modification time both match the parsed copy already held is reused as-is, so a steady-state rescan over a directory of unchanged templates costs syscalls and no JSON parsing at all.

Reload forces the walk immediately, ignoring the interval, for callers who need determinism rather than eventual visibility.

Degradation ¶

Construction and rescan judge a broken document differently, on purpose.

At CONSTRUCTION a malformed file is a deploy error and fails outright: the operator is standing there, and starting a process over a directory the author has not finished is worse than not starting.

After construction a malformed file is almost always a transient edit — a half-written save, a typo mid-keystroke — and the degradation is strictly PER FILE:

• A template that parsed before and no longer does keeps serving its LAST-GOOD parse. A running system keeps running.
• A file that has never parsed has no last-good, so its name resolves to PULSE_TEMPLATE_INVALID naming the path.
• Every other template in the store is untouched, including siblings in the same directory.
• Reload does NOT report a per-file document fault. Returning one would mask an otherwise healthy catalog behind one operator's keystroke. Brokenness is observable through List instead: the affected entry reports Summary.Broken with the fault in Summary.Error.
• Repairing the file clears the broken state on the next rescan.

Root-level faults stay whole-walk errors and Reload still reports them: a configured root that exists but is not a directory is a misconfiguration, not a transient edit, and there is no per-file scope to degrade to.

Concurrency ¶

Every exported method is safe for concurrent use, and the zero-value nil *Store is usable: it lists nothing and reports every lookup as PULSE_TEMPLATE_NOT_FOUND. That keeps "no template directories configured" an ordinary answer rather than a nil check at every call site.

func NewStore(dirs []string) (*Store, error)

func (s *Store) Dirs() []string

func (s *Store) Get(name string) (*Template, error)

func (s *Store) List() []Summary

func (s *Store) Reload() error

type Summary ¶

type Summary struct {
	// Name is the template's lookup identifier.
	Name string `json:"name"`

	// Description mirrors Template.Description.
	Description string `json:"description,omitempty"`

	// Target mirrors Template.Target.
	Target Target `json:"target"`

	// Variables lists the declared variable names in author order. The
	// full declarations are reachable by fetching the template itself.
	Variables []string `json:"variables,omitempty"`

	// Path is the source file the winning entry was loaded from. Empty
	// for a template registered programmatically.
	Path string `json:"path,omitempty"`

	// Shadows lists the source paths of same-named templates this entry
	// takes precedence over. Template directories are an ordered
	// precedence list and the first directory wins; the losing entries
	// are recorded here rather than discarded, so a layered setup is
	// visible instead of mysterious. Empty when nothing is shadowed.
	Shadows []string `json:"shadows,omitempty"`

	// Broken reports that the source file at Path failed to parse or
	// validate on the most recent scan.
	//
	// It is the only place a post-startup breakage is visible. A template
	// that parsed once and has since been broken keeps ANSWERING with its
	// last-good parse — a half-written editor save must not take a running
	// system down — so nothing about fetching it would reveal the fault.
	// This flag is what lets an operator find the bad file without
	// rendering every template in the catalog one at a time.
	//
	// A Broken entry whose Target is empty never parsed at all: the file
	// was already malformed the first time the store saw it, so there is
	// no last-good copy and no declaration to project. That entry is
	// listed to be SEEN, not fetched — asking for it by name returns
	// PULSE_TEMPLATE_INVALID.
	Broken bool `json:"broken,omitempty"`

	// Error is the parse or validation fault behind Broken, already
	// naming the source file. Empty when Broken is false.
	Error string `json:"error,omitempty"`
}

Summary is the lightweight projection of a template used for listing — everything a caller needs to choose a template and build a form for it, without the body. It is what ListTemplates reports.

type Target ¶

type Target string

Target names the public request root a rendered template decodes into. It is a closed enum, spelled lowercase on the wire; the value selects the strict-decode type at render, so it can never be inferred from the body shape. An absent or unrecognised target is PULSE_TEMPLATE_TARGET_UNKNOWN.

const (
	// TargetRequest renders into types.Request — the single-cohort
	// process/predict envelope and the 95% case.
	TargetRequest Target = "request"

	// TargetComposed renders into types.ComposedRequest — a multi-slot
	// Compose batch with optional Compose-host overlays.
	TargetComposed Target = "composed"

	// TargetChain renders into types.ChainRequest — a source-rooted
	// linear ProcessChain.
	TargetChain Target = "chain"

	// TargetFacet renders into types.FacetRequest — the facet endpoints.
	TargetFacet Target = "facet"

	// TargetSample renders into types.SampleRequest — record sampling.
	TargetSample Target = "sample"
)

func AllTargets() []Target

func (t Target) String() string

func (t Target) Valid() bool

type Template ¶

type Template struct {
	// Name is the template's lookup identifier. It is derived by the
	// store from the file's path relative to its directory root (minus
	// the .json extension, forward-slash separated); a document may also
	// carry its own name, and a Template built directly in Go may leave
	// it empty. Declaration validation does not require it — naming is
	// the store's job.
	Name string `json:"name,omitempty"`

	// Description is optional human-facing prose describing what the
	// template produces.
	Description string `json:"description,omitempty"`

	// Target names the request root the rendered body decodes into.
	// Required.
	Target Target `json:"target"`

	// Variables declares every parameter the template accepts, in
	// author order. A template with no variables is legal — it renders
	// to a constant request.
	Variables []*Variable `json:"variables,omitempty"`

	// Body is the parameterised request, held as raw JSON with its
	// variable markers intact. Required, and must be a non-empty JSON
	// object. It is not a valid request until rendered.
	Body json.RawMessage `json:"body"`
}

Template is the parsed template document.

func Parse(data []byte) (*Template, error)

func (t *Template) Summarize(path string, shadows []string) Summary

func (t *Template) Variable(name string) (*Variable, bool)

func (t *Template) VariableNames() []string

type VarType ¶

type VarType string

VarType is the declared type of a template variable. It is a closed enum: an unrecognised type is a declaration error, never a pass-through.

The scalar members (string, number, integer, boolean, field, date) are the only types permitted as a list's element type — see IsScalar.

const (
	// VarString accepts any JSON string.
	VarString VarType = "string"

	// VarNumber accepts any JSON number, integral or fractional.
	VarNumber VarType = "number"

	// VarInteger accepts a JSON number with no fractional part; 1 and 1.0
	// qualify, 1.5 does not.
	VarInteger VarType = "integer"

	// VarBoolean accepts a JSON bool.
	VarBoolean VarType = "boolean"

	// VarField accepts a JSON string naming a cohort field. It is
	// shape-identical to VarString and exists as a distinct type so that
	// cohort-bound field-name constraining can be layered on later
	// without a wire change.
	VarField VarType = "field"

	// VarEnum accepts a JSON string that is a member of the declaration's
	// Values set. A VarEnum declaration without Values is invalid.
	VarEnum VarType = "enum"

	// VarList accepts a JSON array whose every element satisfies the
	// declaration's Items type. A VarList declaration without Items, or
	// with a non-scalar Items, is invalid — lists do not nest.
	VarList VarType = "list"

	// VarDate accepts a JSON string parsing as an ISO date.
	VarDate VarType = "date"

	// VarPeriod accepts a JSON object carrying exactly one of `ranges` or
	// `table`, mirroring the GROUP_DATE_RANGES / FILTER_DATE_RANGES
	// labeled-date-range Params shape.
	VarPeriod VarType = "period"
)

func AllVarTypes() []VarType

func (v VarType) IsScalar() bool

func (v VarType) String() string

func (v VarType) Valid() bool

type Variable ¶

type Variable struct {
	// Name is the variable's identifier — the key a caller supplies it
	// under and the token the body's markers reference. Required,
	// non-empty, unique within a template.
	Name string `json:"name"`

	// Type is the declared type. Required; must be one of AllVarTypes.
	Type VarType `json:"type"`

	// Description is optional human-facing prose. It exists so a caller
	// can build a form (or a prompt) from the declaration alone.
	Description string `json:"description,omitempty"`

	// Required marks a variable that must resolve to a value at render.
	// Required together with a Default is legal, and the pair is not a
	// contradiction: the default resolves the variable, so a required
	// variable carrying a default can never go missing.
	Required bool `json:"required,omitempty"`

	// Default is the value used when the caller supplies none, held as
	// raw JSON so integer fidelity survives to the render walk. An
	// explicit JSON null means "no default", identical to omitting it.
	Default json.RawMessage `json:"default,omitempty"`

	// Values is the permitted member set for a VarEnum variable.
	// Membership is exact and case-sensitive. Required for VarEnum,
	// meaningless for every other type.
	Values []string `json:"values,omitempty"`

	// Items is the element type for a VarList variable. Required for
	// VarList, meaningless for every other type, and must name a scalar
	// type — lists do not nest.
	Items VarType `json:"items,omitempty"`
}

Variable is one declared template parameter. The declaration is the contract a caller's supplied variable map is checked against: it fixes the accepted JSON type, whether a value is mandatory, and what stands in when the caller supplies nothing.