// Package synthetic implements a DataSource that computes signals from
// existing upstream signals by running them through configurable DSP pipelines.
package synthetic

// SignalDef describes one synthetic signal.
type SignalDef struct {
	Name     string        `json:"name"`
	DS       string        `json:"ds"`      // upstream data source name
	Signal   string        `json:"signal"`  // upstream signal name (or "" for constant)
	Inputs   []InputRef    `json:"inputs"`  // alternative multi-input format
	Pipeline []NodeDef     `json:"pipeline"` // ordered list of DSP nodes
	Meta     MetaOverride  `json:"meta"`    // optional metadata overrides

	// Visibility controls who sees this signal in the signal tree:
	//   "global"      — listed in every panel's edit mode
	//   "user"        — listed in every panel owned by Owner
	//   "panel"       — listed only when editing the bound Panel
	// An empty value is treated as "global" for backward compatibility with
	// definitions created before this field existed.
	Visibility string `json:"visibility,omitempty"`
	Owner      string `json:"owner,omitempty"` // creator identity (stamped server-side)
	Panel      string `json:"panel,omitempty"` // bound interface id for "panel" visibility
}

// InputRef names one upstream signal used as input to the pipeline.
type InputRef struct {
	DS     string `json:"ds"`
	Signal string `json:"signal"`
}

// NodeDef is a single node in the pipeline.
type NodeDef struct {
	Type   string         `json:"type"`
	Params map[string]any `json:"params,omitempty"`
}

// MetaOverride allows the synthetic signal to override display metadata.
type MetaOverride struct {
	Unit        string  `json:"unit,omitempty"`
	Description string  `json:"description,omitempty"`
	DisplayLow  float64 `json:"displayLow,omitempty"`
	DisplayHigh float64 `json:"displayHigh,omitempty"`
	Writable    bool    `json:"writable,omitempty"`
}