config

type ActionSubscriber struct {
	bus.BaseSubscriber
	Config     *Config
	ActionExpr hcl.Expression
}

type AmbientProvider func(cfg *Config) cty.Value

type Assert struct {
	Name      string `hcl:"name,label"`
	Condition bool   `hcl:"condition"`
}

type AssertBlockHandler struct {
	BlockHandlerBase
}

type AttrMeta struct {
	// Summary is a one-line description, shown as a completion item's detail.
	Summary string

	// Doc is richer Markdown for hover.
	Doc string

	// Hint tells a completion provider what kind of value belongs after `=`.
	Hint Hint

	// Context names the shape of `ctx` this attribute's expression is
	// evaluated against, for attributes evaluated at event time. The shape
	// varies per *attribute*, not per block: a receiver's `action` sees
	// ctx.topic/ctx.msg/ctx.fields, while `on_connect` on the same client sees
	// none of them and `on_decode_error` sees the failure instead.
	//
	// Use a stable kebab-case name shared by every attribute with the same
	// shape (e.g. "message", "http-request", "connection"), and describe the
	// shape itself with RegisterContextSchema. Naming a shape that nothing
	// describes — or describing one nothing names — is a reported problem.
	Context string

	// ContextFields are fields this attribute's `ctx` carries in addition to
	// the ones its shape declares. Only an open shape — one whose OpenFields
	// is set — accepts them: `on_decode_error` has the same five fixed fields
	// everywhere, plus identity fields chosen by the receiver, so the mqtt
	// receiver adds `mqtt_topic` where the rabbitmq one adds `routing_key`.
	//
	// A name that the shape already declares, or that a universal field takes,
	// is a reported problem — it is exactly the collision the runtime resolves
	// by dropping the site's field.
	ContextFields []ContextField

	// Enum is the closed set of legal string values, when there is one.
	Enum []string

	// Default is the value the attribute takes when it is omitted, written as
	// it would be written in a config file: `30s`, `true`, `0`. A computed
	// default may be written as the pattern it follows
	// (`vinculum-<name>-<hostname>`).
	//
	// Leave it empty when there is no default worth stating — a required
	// attribute has none, and neither does an optional one whose absence means
	// "do nothing" rather than "do this instead". It is rendered as a literal,
	// so a default that can only be explained in a sentence ("the vinculum
	// topic, verbatim") belongs in Doc instead; a backticked sentence in a
	// Default column reads as a value and is not one.
	//
	// This is curated, like Summary, because the defaults are applied
	// imperatively while processing a block (`keepAlive := 30 * time.Second`)
	// rather than declared anywhere reflection can reach. Prefer stating it
	// here over burying it in Doc prose: a default is the second thing a reader
	// wants after what the attribute means, and a consumer can only put it in
	// its own column if it arrives as its own field.
	Default string

	// Deprecated, when non-empty, marks the attribute deprecated and explains
	// the replacement.
	Deprecated string
}

type AuthConfig struct {
	Mode string `hcl:"mode,label"` // "basic" | "oidc" | "oauth2" | "custom" | "none"

	// disabled — when true the block is parsed but inert, exactly as if it were
	// absent (server-level auth) or "none" (block-level). Mode-specific required
	// fields are not validated. Typically driven by an env expression so a single
	// var can both supply credentials and toggle auth on/off.
	Disabled bool `hcl:"disabled,optional"`

	// basic — realm shown in WWW-Authenticate header; defaults to server name
	Realm string `hcl:"realm,optional"`
	// basic — map(string) expression; username → plaintext password
	Credentials hcl.Expression `hcl:"credentials,optional"`

	// basic + custom — expression evaluated per request
	Action hcl.Expression `hcl:"action,optional"`

	// oidc + oauth2 — required aud values; token must contain at least one
	Audience hcl.Expression `hcl:"audience,optional"` // list(string)

	// oidc — OIDC issuer URL (used for discovery)
	Issuer string `hcl:"issuer,optional"`
	// oidc — override the JWKS endpoint (disables OIDC discovery)
	JWKSUrl string `hcl:"jwks_url,optional"`
	// oidc — permitted signing algorithms; defaults to ["RS256","ES256"]
	Algorithms hcl.Expression `hcl:"algorithms,optional"` // list(string)
	// oidc — permitted clock skew for exp/nbf; defaults to "30s".
	// Accepts a string ("30s"), a number (seconds), or a duration capsule.
	ClockSkew hcl.Expression `hcl:"clock_skew,optional"`

	// oidc (introspection) + oauth2 — RFC 7662 introspection endpoint
	IntrospectUrl string `hcl:"introspect_url,optional"`

	// oidc introspection — client ID for introspection endpoint
	IntrospectClientID string `hcl:"introspect_client_id,optional"`
	// oidc introspection — client secret for introspection endpoint
	IntrospectClientSecret string `hcl:"introspect_client_secret,optional"`

	// oauth2 — client ID for introspection endpoint (required)
	ClientID string `hcl:"client_id,optional"`
	// oauth2 — client secret (required; use env.VAR)
	ClientSecret string `hcl:"client_secret,optional"`
	// oauth2 — cache TTL for introspection results; defaults to "0s" (no cache).
	// Accepts a string ("60s"), a number (seconds), or a duration capsule.
	CacheTTL hcl.Expression `hcl:"cache_ttl,optional"`

	DefRange hcl.Range `hcl:",def_range"`
}

type BaseBusClient struct {
	BaseClient
	Subscriber bus.Subscriber
	Client     bus.Client
}

type BaseClient struct {
	Name     string
	DefRange hcl.Range
}

type BaseServer struct {
	Name     string
	DefRange hcl.Range
}

type BlockHandler interface {
	Preprocess(block *hcl.Block) hcl.Diagnostics
	FinishPreprocessing(config *Config) hcl.Diagnostics
	GetBlockDependencyId(block *hcl.Block) (string, hcl.Diagnostics)
	GetBlockDependencies(block *hcl.Block) ([]string, hcl.Diagnostics)
	Process(config *Config, block *hcl.Block) hcl.Diagnostics
	FinishProcessing(config *Config) hcl.Diagnostics
}

type BlockHandlerBase struct {
}

type BusBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

type BusClient interface {
	Client
	Build() (bus.Client, error)
	GetClient() bus.Client
	GetSubscriber() bus.Subscriber
	SetSubscriber(subscriber bus.Subscriber)
}

type BusDefinition struct {
	Name      string         `hcl:"name,label"`
	Type      *string        `hcl:"type,optional"`
	QueueSize *int           `hcl:"queue_size,optional"`
	Metrics   hcl.Expression `hcl:"metrics,optional"`
	Tracing   hcl.Expression `hcl:"tracing,optional"`
}

type Client interface {
	GetName() string
	GetDefRange() hcl.Range
}

type ClientBlockHandler struct {
	BlockHandlerBase
}

type ClientDefinition struct {
	Type string `hcl:"type,label"`
	Name string `hcl:"name,label"`

	Disabled      bool      `hcl:"disabled,optional"`
	DefRange      hcl.Range `hcl:",def_range"`
	RemainingBody hcl.Body  `hcl:",remain"`
}

type ClientProcessor func(config *Config, block *hcl.Block, body hcl.Body) (Client, hcl.Diagnostics)

type ConditionBlockHandler struct {
	BlockHandlerBase
}

type ConditionDefinition struct {
	Type          string    `hcl:"type,label"`
	Name          string    `hcl:"name,label"`
	Disabled      bool      `hcl:"disabled,optional"`
	DefRange      hcl.Range `hcl:",def_range"`
	RemainingBody hcl.Body  `hcl:",remain"`
}

type ConditionProcessor func(config *Config, block *hcl.Block, def *ConditionDefinition) hcl.Diagnostics

type ConditionRegistration struct {
	Process         ConditionProcessor
	HasDependencyId bool
}

type ConditionalTriggerTypePlugin func(cfg *Config) map[string]TriggerRegistration

type Config struct {
	Logger *zap.Logger
	// UserLogger is Logger with Go caller and stacktrace suppressed. Use it
	// at sites that report errors caused by user-supplied VCL (expression
	// eval failures, assertion failures, action errors, etc.) where the Go
	// source location and stack are noise rather than signal.
	UserLogger *zap.Logger
	Functions  map[string]function.Function
	Constants  map[string]cty.Value

	Features map[string]string
	BaseDir  string
	WriteDir string
	// Testing is true when the config is built for `vinculum test`. It is
	// projected to VCL as the `sys.testing` ambient bool, so a config can gate
	// real external I/O off under test (e.g. `disabled = sys.testing`).
	Testing bool

	SigActions       *SignalActionHandler
	Startables       []Startable
	PostStartables   []PostStartable
	PreStoppables    []PreStoppable
	Stoppables       []Stoppable
	BusCapsuleType   cty.Type
	CtyBusMap        map[string]cty.Value
	Buses            map[string]bus.EventBus
	CtyClientMap     map[string]cty.Value
	Clients          map[string]map[string]Client
	CtyServerMap     map[string]cty.Value
	Servers          map[string]map[string]Listener
	CtyVarMap        map[string]cty.Value
	CtyTriggerMap    map[string]cty.Value
	TriggerDefRanges map[string]hcl.Range
	CtyConditionMap  map[string]cty.Value
	CtyFsmMap        map[string]cty.Value
	CtyWireFormatMap map[string]cty.Value

	MetricsServers map[string]MetricsRegistrar
	OtlpClients    map[string]OtlpClient
	// contains filtered or unexported fields
}

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

type ConstBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

type Constraint struct {
	Kind       ConstraintKind `json:"kind"`
	Attributes []string       `json:"attributes"`
	Message    string         `json:"message"`
}

type ConstraintKind string

type ContextField struct {
	// Name is the attribute name, read as `ctx.<name>`.
	Name string

	// Type is the coarse value type, from the same vocabulary as an
	// attribute's: string, number, bool, list, map, or object — plus "dynamic"
	// for a value whose type depends on the message, and "capsule" for an
	// opaque handle passed to a function rather than read directly.
	Type string

	// Summary is a one-line description, shown as a completion item's detail.
	Summary string

	// Doc is richer Markdown for hover.
	Doc string

	// Optional marks a field that is absent from some evaluations of this
	// shape, e.g. ctx.fields on a message that carries no metadata.
	Optional bool
}

type ContextSchema struct {
	// Summary is a one-line description of when an expression sees this shape.
	Summary string

	// Doc is richer Markdown for hover.
	Doc string

	// Fields are the shape's own fields, in the order worth reading them.
	Fields []ContextField

	// OpenFields marks a shape whose Fields are a floor rather than the whole
	// list: every site carries them, and a site may carry more. Attributes
	// naming an open shape declare their additions with
	// AttrMeta.ContextFields; only an open shape may.
	//
	// `decode-error` is the case — five fields are fixed by
	// MakeDecodeErrorHook and the receiver adds its own transport identity —
	// and a consumer that treated the list as closed would report a correct
	// `ctx.routing_key` as an unknown field.
	OpenFields bool
}

type CtyValuer interface {
	CtyValue() cty.Value
}

type CtyWireFormat struct {
	Inner wire.WireFormat
}

type EditorDefinition struct {
	Type          string
	Name          string
	Params        []string // parameter names extracted from params expression
	VariadicParam string   // optional variadic parameter name
	Body          hcl.Body // remaining body for type-specific parsing
	DefRange      hcl.Range
}

type EditorProcessor func(
	config *Config,
	evalCtxFn func() *hcl.EvalContext,
	def *EditorDefinition,
) (function.Function, hcl.Diagnostics)

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

type FileKind string

type FsmBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

type FsmTopLevel struct {
	Name          string         `hcl:"name,label"`
	Initial       string         `hcl:"initial"`
	QueueSize     *int           `hcl:"queue_size,optional"`
	ShutdownEvent *string        `hcl:"shutdown_event,optional"`
	Disabled      bool           `hcl:"disabled,optional"`
	Tracing       hcl.Expression `hcl:"tracing,optional"`
	OnChange      hcl.Expression `hcl:"on_change,optional"`
	OnError       hcl.Expression `hcl:"on_error,optional"`
	RemainingBody hcl.Body       `hcl:",remain"`
}

type FuncDoc struct {
	Name string
	// Signatures is one rendered calling convention per form. More than one
	// means an overload set: a host function whose argument shapes differ per
	// arity is not one function with optional parameters, and showing it as one
	// would lie.
	Signatures []string
	// Doc is the prose describing the function, "" when undocumented.
	Doc string
	// Params are the documented parameters, unioned across the forms with the
	// first occurrence of a name winning — matching how functy renders them.
	Params []FuncParam
}

type FuncParam struct {
	// Name is how the parameter is written in a signature: "*rest" for a
	// variadic, "name?" for one that is optional with no default, else the bare
	// name.
	Name string
	// Type is the annotated type, "" when unannotated (dynamic).
	Type string
	// Default is the source text of a default value, "" when there is none.
	Default string
	// Doc describes the parameter, "" when undocumented.
	Doc string
	// Required reports whether a caller must supply it.
	Required bool
}

type FunctionPlugin func(cfg *Config) map[string]function.Function

type GitAuth struct {
	Token                 string    `hcl:"token,optional"`
	Username              string    `hcl:"username,optional"`
	Password              string    `hcl:"password,optional"`
	PrivateKey            string    `hcl:"private_key,optional"`
	PrivateKeyFile        string    `hcl:"private_key_file,optional"`
	Passphrase            string    `hcl:"passphrase,optional"`
	KnownHosts            string    `hcl:"known_hosts,optional"`
	InsecureIgnoreHostKey bool      `hcl:"insecure_ignore_host_key,optional"`
	DefRange              hcl.Range `hcl:",def_range"`
}

type GitDefinition struct {
	Label      string     `hcl:"name,label"`
	Disabled   bool       `hcl:"disabled,optional"`
	Repo       string     `hcl:"repo"`
	Branch     string     `hcl:"branch,optional"`
	Tag        string     `hcl:"tag,optional"`
	Commit     string     `hcl:"commit,optional"`
	Depth      *int       `hcl:"depth,optional"`
	Submodules bool       `hcl:"submodules,optional"`
	Auth       *GitAuth   `hcl:"auth,block"`
	Fetches    []GitFetch `hcl:"fetch,block"`
	DefRange   hcl.Range  `hcl:",def_range"`
}

type GitFetch struct {
	Name      string    `hcl:"name,label"`
	From      string    `hcl:"from,optional"`
	Into      string    `hcl:"into"`
	Overwrite bool      `hcl:"overwrite,optional"`
	DefRange  hcl.Range `hcl:",def_range"`
}

type HandlerServer interface {
	Listener
	GetHandler() http.Handler
}

type HelpTopicResolver interface {
	// HelpKinds returns the kind names this resolver accepts, which are what
	// may appear as a `kind:` prefix — "block:http" to ask for the block when
	// a bare "http" would be ambiguous.
	HelpKinds() []string

	// HelpTopic renders the topic named by path, already formatted for
	// reading. An empty kind searches every kind.
	//
	// The bool distinguishes "nothing is named that" from "here is the answer".
	// An ambiguous path is an answer: the rendered menu of ways to resolve it.
	HelpTopic(kind string, path []string) (string, bool)
}

type Hint string

type InstrumentMetrics interface {
	GetMeterProvider() metric.MeterProvider
	IsDefaultMetricsBackend() bool
}

type Listener interface {
	GetName() string
	GetDefRange() hcl.Range
}

type MemberMeta struct {
	// Summary is a one-line description, shown as a completion item's detail.
	Summary string

	// Doc is richer Markdown for hover.
	Doc string

	// Members describes the members of a member that is itself an object
	// (`sys.functy.version`). An object member must set this or FreeMembers, so
	// that gaining a field is a reported change rather than a silent one.
	Members map[string]MemberMeta

	// FreeMembers marks an object member whose names are not fixed by the
	// language — `sys.signals` carries whichever signals the host OS defines.
	// As on a namespace, Members is then a floor: `sys.signals.bynumber` is
	// described and always present, while the signal names beside it vary with
	// the OS and are neither enumerated nor checked.
	FreeMembers bool
}

type MessageConverter func(cty.Value) (any, error)

type MessageTransformWrapper struct {
	Func vbxform.MessageTransformFunc
}

type MetricBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

type MetricDefinition struct {
	Help             string         `hcl:"help"`
	LabelNames       []string       `hcl:"label_names,optional"`
	Namespace        string         `hcl:"namespace,optional"`
	Buckets          []float64      `hcl:"buckets,optional"`
	Server           hcl.Expression `hcl:"server,optional"`
	Value            hcl.Expression `hcl:"value,optional"`
	ComputedInterval *string        `hcl:"computed_interval,optional"`
	Tracing          hcl.Expression `hcl:"tracing,optional"`
	DefRange         hcl.Range      `hcl:",def_range"`
}

type MetricsRegistrar interface {
	Listener
	InstrumentMetrics
	GetRegistry() *prometheus.Registry
	IsDefaultServer() bool
}

type NamespaceSchema struct {
	// Block names the top-level block type that publishes names into this
	// namespace, for a namespace the config author fills in (`bus.<name>`).
	// Setting it makes the namespace a block namespace, which has no members of
	// its own to enumerate.
	Block string

	// Summary is a one-line description, used as a completion item's detail.
	Summary string

	// Doc is richer Markdown used for hover; may be multi-paragraph.
	Doc string

	// DocPage names the hand-written reference page for this namespace,
	// relative to doc/, as TypeSchema.DocPage does.
	DocPage string

	// Members holds curated per-member metadata, keyed by member name. Every
	// key must name a member the provider's value carries, and every member it
	// carries must have an entry.
	Members map[string]MemberMeta

	// FreeMembers marks a namespace whose member names are not the language's
	// to know: `env` is the environment of whichever process happens to be
	// running, so enumerating it would describe the machine that generated the
	// document rather than the language.
	//
	// Members is then a floor rather than the whole list — whatever is
	// described is described, and anything else is allowed. Nothing undescribed
	// is emitted, which is also what keeps the document from varying with the
	// machine that produced it, and `vinculum check` accepts any name below
	// such a root.
	FreeMembers bool

	// Constant marks a namespace whose values are identical in every process,
	// so the value is part of the language rather than of the environment and
	// is emitted alongside the member. True of `http_status`; false of `sys`,
	// whose hostname and pid describe the machine.
	Constant bool

	// UniformMemberSummary is the summary taken by every member that does not
	// carry its own. It exists for a namespace whose members are a single
	// uniform family — `http_status` is sixty status codes that differ only in
	// which code they are — where sixty hand-written summaries would say the
	// same sentence sixty times and hide the one fact that differs.
	//
	// Only legal together with Constant, because the emitted value is then what
	// distinguishes one member from another. Without it the members would be
	// documented and indistinguishable.
	UniformMemberSummary string
}

type OtlpClient interface {
	Client
	// GetTracerProvider returns the OTel SDK TracerProvider for span extraction
	// (e.g. to call tracer.Start() or trace.SpanFromContext()).
	GetTracerProvider() trace.TracerProvider
	// IsDefaultClient returns true if this client should be used when no
	// explicit tracing = attribute is specified.
	IsDefaultClient() bool
	// GetMeterProvider returns the OTel SDK MeterProvider for creating
	// metric instruments (counters, histograms, gauges).
	GetMeterProvider() metric.MeterProvider
	// IsDefaultMetricsBackend returns true if this client should be used
	// as the default metrics backend when no explicit metrics = is specified.
	IsDefaultMetricsBackend() bool
}

type PluginContext struct {
	// Block is the `plugin "<label>" { ... }` block as parsed from the
	// .vinit file. Block.Labels[0] is the plugin label. Block.Body is the
	// full block body; the plugin decodes its own schema from it. The
	// `disabled` attribute has already been consumed by Vinculum but is
	// still syntactically present in the body.
	Block *hcl.Block

	// EvalContext is the minimal .vinit eval context: env.* and the cty
	// standard library. No const, no user functions, no contributions from
	// other plugins.
	EvalContext *hcl.EvalContext

	// Logger is a zap logger pre-bound with `plugin=<label>` as a
	// structured field. Plugins should use this rather than constructing
	// their own logger so plugin output is consistent with Vinculum's.
	// May be nil if Vinculum was started without a logger.
	Logger *zap.Logger
}

type PluginDefinition struct {
	Label    string   `hcl:"name,label"`
	Disabled bool     `hcl:"disabled,optional"`
	Body     hcl.Body `hcl:",remain"`
}

type PostStartable interface {
	PostStart() error
}

type PreStoppable interface {
	PreStop() error
}

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

type ReconnectDefinition struct {
	InitialDelay  hcl.Expression `hcl:"initial_delay,optional"`
	MaxDelay      hcl.Expression `hcl:"max_delay,optional"`
	BackoffFactor *float64       `hcl:"backoff_factor,optional"`
	MaxRetries    *int           `hcl:"max_retries,optional"`
	DefRange      hcl.Range      `hcl:",def_range"`

	// BackoffFactorRange underlines the attribute itself when its value is
	// rejected. A *float64 carries no range of its own, and pointing at the
	// whole block would leave a reader of a five-attribute block looking for
	// which one was meant.
	BackoffFactorRange hcl.Range `hcl:"backoff_factor,attr_range"`
}

type RegisterOption func(*registerOptions)

type SchemaAttr struct {
	Name     string `json:"name"`
	Required bool   `json:"required"`
	// Type is the coarse value type: expression, string, bool, number, list,
	// or map.
	Type    string `json:"type"`
	Summary string `json:"summary,omitempty"`
	Doc     string `json:"doc,omitempty"`
	Hint    Hint   `json:"hint,omitempty"`
	// Context names the `ctx` shape this attribute's expression sees; look it
	// up in the document's top-level `contexts`.
	Context string `json:"context,omitempty"`
	// ContextFields are fields this site adds to that shape, present only for
	// an open shape. Read them as appended to the shape's own fields.
	ContextFields []*SchemaContextField `json:"contextFields,omitempty"`
	Enum          []string              `json:"enum,omitempty"`
	// Default is the value used when the attribute is omitted, written as it
	// would be written in a config file. Absent when there is no default worth
	// stating rather than when the zero value applies.
	Default    string `json:"default,omitempty"`
	Deprecated string `json:"deprecated,omitempty"`
}

type SchemaBlock struct {
	// File is the kind of configuration file this block belongs in. Always
	// emitted, so a consumer validating one language cannot mistake a block of
	// the other for one of its own.
	File FileKind
	// Labels are the block's label names, from blockSchema.
	Labels []string
	// VariantLabel names the label that selects the variant; empty for plain
	// blocks. Always the first label in v1.
	VariantLabel string
	// Summary and Doc describe the block type as a whole.
	Summary string
	Doc     string
	// DocPage is the hand-written reference page for the block type.
	DocPage string
	// Undocumented is true when no curated schema was registered for the block.
	Undocumented bool
	// Body is the single body of a plain block; nil for typed blocks.
	Body *SchemaBody
	// Variants maps variant key to body; nil for plain blocks.
	Variants map[string]*SchemaBody
}

type SchemaBody struct {
	Summary string `json:"summary,omitempty"`
	Doc     string `json:"doc,omitempty"`
	// DocPage is the hand-written reference page for this type, relative to
	// doc/. A consumer generating an index links to it.
	DocPage string `json:"docPage,omitempty"`
	// Undocumented is true when no curated schema was registered for this body.
	Undocumented bool `json:"undocumented,omitempty"`
	// Conditional is true for a variant whose availability depends on config
	// state (see RegisterConditionalTriggerType).
	Conditional bool `json:"conditional,omitempty"`
	// FreeAttributes is true when attribute names here are chosen by the
	// config author rather than fixed by the parser, so an unknown name is
	// not an error.
	FreeAttributes bool                          `json:"freeAttributes,omitempty"`
	Attributes     []*SchemaAttr                 `json:"attributes"`
	Blocks         map[string]*SchemaNestedBlock `json:"blocks"`
	Constraints    []Constraint                  `json:"constraints"`
}

type SchemaContext struct {
	Summary string `json:"summary,omitempty"`
	Doc     string `json:"doc,omitempty"`
	// Fields are the shape's own fields first, then the universal ones every
	// `ctx` carries.
	Fields []*SchemaContextField `json:"fields"`
	// OpenFields is true when Fields is a floor rather than the whole list: a
	// site may carry more, named by its attribute's `contextFields`. Treat an
	// unlisted field as unknown-but-possible rather than as an error.
	OpenFields bool `json:"openFields,omitempty"`
}

type SchemaContextField struct {
	Name    string `json:"name"`
	Type    string `json:"type"`
	Summary string `json:"summary,omitempty"`
	Doc     string `json:"doc,omitempty"`
	// Optional is true when the field is absent from some evaluations.
	Optional bool `json:"optional,omitempty"`
	// Universal is true for a field every `ctx` carries whatever the site, so
	// a consumer can group or fold them away.
	Universal bool `json:"universal,omitempty"`
}

type SchemaDocument struct {
	// SchemaVersion is the version of the output format itself.
	SchemaVersion string `json:"schemaVersion"`
	// VinculumVersion is the version of the binary that produced the document.
	VinculumVersion string `json:"vinculumVersion"`
	// Contexts maps a `ctx` shape name to its description. An attribute's
	// `context` field names one of these.
	Contexts map[string]*SchemaContext `json:"contexts"`
	// Namespaces maps a top-level name in the evaluation namespace to its
	// description: what `sys.`, `env.`, and `bus.` mean and what may follow
	// them. Where `contexts` says what an expression sees at a particular site,
	// this says what every expression sees everywhere.
	Namespaces map[string]*SchemaNamespace `json:"namespaces"`
	// Plugins lists the registry entries plugins contributed to this document,
	// e.g. "client.acme". Absent when no plugins were loaded, so its presence
	// is what tells a consumer the document describes more than a stock binary.
	// The generator does not load plugins itself; the caller sets this.
	Plugins []string `json:"plugins,omitempty"`
	// Blocks maps top-level block type name to its description.
	Blocks map[string]*SchemaBlock `json:"blocks"`
}

type SchemaGenOptions struct {
	// Strict makes curation problems (metadata referencing an attribute or
	// block that does not exist) fatal for the caller. Problems are always
	// collected; Strict only decides whether they fail the command.
	Strict bool
	// RequireDocs additionally reports every block, variant, nested block, and
	// attribute that carries no Summary.
	RequireDocs bool
}

type SchemaMember struct {
	Name string `json:"name"`
	// Type is the coarse value type: the attribute vocabulary plus `object`,
	// `capsule`, and — for a capsule registered under a name usable in a `.cty`
	// annotation — that name, e.g. `time`.
	Type string `json:"type"`
	// Value is the member's literal value, present only in a namespace whose
	// values are the same in every process.
	Value   string `json:"value,omitempty"`
	Summary string `json:"summary,omitempty"`
	Doc     string `json:"doc,omitempty"`
	// FreeMembers is true for an object member whose own member names are not
	// fixed by the language, such as the host's signal table.
	FreeMembers bool `json:"freeMembers,omitempty"`
	// Members are this member's own members, when it is an object.
	Members []*SchemaMember `json:"members,omitempty"`
}

type SchemaNamespace struct {
	// Kind is "provider" or "block".
	Kind string `json:"kind"`
	// Block names the top-level block type that publishes names here, for a
	// block namespace.
	Block   string `json:"block,omitempty"`
	Summary string `json:"summary,omitempty"`
	Doc     string `json:"doc,omitempty"`
	// DocPage is the hand-written reference page for this namespace, relative
	// to doc/.
	DocPage string `json:"docPage,omitempty"`
	// Undocumented is true when no curated schema was registered for the
	// namespace, as for a block.
	Undocumented bool `json:"undocumented,omitempty"`
	// Constant is true when every member's value is the same in every process,
	// which is what makes a member's `value` meaningful.
	Constant bool `json:"constant,omitempty"`
	// FreeMembers is true when the member names are not fixed by the language,
	// so `members` is empty by design rather than by omission. A block
	// namespace is always free: its names come from the config.
	FreeMembers bool `json:"freeMembers,omitempty"`
	// Members are the namespace's members, sorted by name.
	Members []*SchemaMember `json:"members"`
}

type SchemaNestedBlock struct {
	Labels []string `json:"labels"`
	// Repeatable is true when the block may appear any number of times.
	Repeatable bool `json:"repeatable"`
	// Required is true when exactly one instance must be present.
	Required bool `json:"required"`
	SchemaBody
}

type SchemaProvider interface {
	Schema() TypeSchema
}

type ServerBlockHandler struct {
	BlockHandlerBase
}

type ServerDefinition struct {
	Type string `hcl:"type,label"`
	Name string `hcl:"name,label"`

	Disabled      bool      `hcl:"disabled,optional"`
	DefRange      hcl.Range `hcl:",def_range"`
	RemainingBody hcl.Body  `hcl:",remain"`
}

type ServerProcessor func(config *Config, block *hcl.Block, body hcl.Body) (Listener, hcl.Diagnostics)

type SignalActionHandler struct {
	Ctx            context.Context
	Logger         *zap.Logger
	UserLogger     *zap.Logger
	SignalActions  map[platform.Signal]hcl.Expression
	SignalCtx      map[platform.Signal]*hcl.EvalContext
	SigChannel     chan os.Signal
	AddedStartable bool
	TracerProvider trace.TracerProvider
	// Files is the source file map for rendering a failing signal action against
	// its own line, set from the Config during Build(). Nil for a handler not
	// built that way (the diagnostic writer tolerates a nil map).
	Files map[string]*hcl.File
}

type SignalsDefinition struct {
	SigHup   hcl.Expression `hcl:"SIGHUP,optional"`
	SigInfo  hcl.Expression `hcl:"SIGINFO,optional"`
	SigUsr1  hcl.Expression `hcl:"SIGUSR1,optional"`
	SigUsr2  hcl.Expression `hcl:"SIGUSR2,optional"`
	Disabled bool           `hcl:"disabled,optional"`
	DefRange hcl.Range      `hcl:",def_range"`
}

type Startable interface {
	Start() error
}

type Stoppable interface {
	Stop() error
}

type SubscriberSource struct {
	Subscriber hcl.Expression
	Action     hcl.Expression
	Transforms hcl.Expression
	QueueSize  *int
}

type SubscriptionBlockHandler struct {
	BlockHandlerBase
}

type SubscriptionDefinition struct {
	Name       string         `hcl:"name,label"`
	TargetExpr hcl.Expression `hcl:"target,optional"`
	Topics     []string       `hcl:"topics"`
	QueueSize  *int           `hcl:"queue_size,optional"`
	Transforms hcl.Expression `hcl:"transforms,optional"`
	Subscriber hcl.Expression `hcl:"subscriber,optional"`
	ActionExpr hcl.Expression `hcl:"action,optional"`
	Disabled   bool           `hcl:"disabled,optional"`
}

type TLSConfig struct {
	Enabled            bool      `hcl:"enabled,optional"`
	CACert             string    `hcl:"ca_cert,optional"`
	Cert               string    `hcl:"cert,optional"`
	Key                string    `hcl:"key,optional"`
	InsecureSkipVerify bool      `hcl:"insecure_skip_verify,optional"`
	RequireClientCert  bool      `hcl:"require_client_cert,optional"`
	SelfSigned         bool      `hcl:"self_signed,optional"`
	DefRange           hcl.Range `hcl:",def_range"`
}

type TriggerBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

type TriggerDefinition struct {
	Type          string         `hcl:"type,label"`
	Name          string         `hcl:"name,label"`
	Disabled      bool           `hcl:"disabled,optional"`
	Tracing       hcl.Expression `hcl:"tracing,optional"`
	DefRange      hcl.Range      `hcl:",def_range"`
	RemainingBody hcl.Body       `hcl:",remain"`

	// TracerProvider is resolved from Tracing (or auto-wired) during Process()
	// and is available to trigger-type processors via triggerDef.TracerProvider.
	TracerProvider trace.TracerProvider
}

type TriggerProcessor func(config *Config, block *hcl.Block, def *TriggerDefinition) hcl.Diagnostics

type TriggerRegistration struct {
	Process         TriggerProcessor
	HasDependencyId bool // true if this trigger type produces a cty value at trigger.<name>
}

type TypeSchema struct {
	// Sample is a zero value (normally a pointer to one) of the gohcl decode
	// struct for this body. Required for top-level blocks and typed variants;
	// ignored for nested sub-blocks, whose structure is reflected from the
	// parent's field type.
	Sample any

	// AlsoSamples lists further decode structs whose attributes and blocks
	// belong to the same body. Some bodies are decoded in more than one pass —
	// a sql client's dialect struct captures the rest with `,remain` and hands
	// it to a second struct holding the dialect-agnostic settings — and the
	// schema has to describe the union.
	AlsoSamples []any

	// Summary is a one-line description, used as a completion item's detail.
	Summary string

	// Doc is richer Markdown used for hover; may be multi-paragraph.
	Doc string

	// DocPage names the hand-written reference page for this type, relative to
	// doc/ — "client-mqtt.md", or "server-vws.md#client-vws" for a type
	// documented in a section of another page.
	//
	// It exists because a generated index has to link somewhere, and a link
	// target synthesized by convention is exactly the kind of thing that rots
	// silently: the page gets renamed and the index still points at it. A test
	// checks that every DocPage names a file that exists and, for a fragment,
	// a heading that is in it.
	//
	// Required for a variant of a typed block under --require-docs; those are
	// what the generated per-type indexes link to.
	DocPage string

	// Attrs holds curated per-attribute metadata, keyed by HCL attribute name.
	// Every key must name an attribute that reflection found.
	Attrs map[string]AttrMeta

	// FreeAttributes marks a body whose attribute names are chosen by the
	// config author rather than fixed by the parser (`const`, an fsm
	// `storage` block). Consumers should not flag an unknown attribute here.
	FreeAttributes bool

	// Blocks holds curated metadata for nested sub-blocks, keyed by HCL block
	// type name. Structure is normally reflected and this only adds docs, so
	// every key must name a sub-block reflection found — unless the entry
	// carries its own Sample, which declares a sub-block of a body the parent
	// parses by hand from a `,remain` body (see fsm's state/event/storage).
	Blocks map[string]TypeSchema

	// Repeatable and Required describe the header of a sub-block declared via
	// its own Sample. For a reflected sub-block the field type already says
	// whether the block is a slice, a pointer, or a value, so curating either
	// is a reported problem — with one exception.
	//
	// Required is curatable on a *repeatable* sub-block, where it raises `0..n`
	// to `1..n`. A slice cannot tell "any number, including none" apart from
	// "one or more", so a parser that demands one (a `git` block with no
	// `fetch` clones nothing) has no other way to say so. Together the two
	// booleans read as they always have: required to appear, repeatable to
	// appear again.
	Repeatable bool
	Required   bool

	// Variants declares the variant bodies of a typed block whose variants are
	// not driven by a registry (currently only `metric`). Registry-driven
	// blocks (client, server, trigger, condition, wire_format, editor) leave
	// this nil; their variants come from the registry.
	Variants map[string]TypeSchema

	// Constraints are advisory cross-attribute rules that reflection cannot
	// express. Every attribute they name must exist in the reflected body.
	Constraints []Constraint
}

type VariableBlockHandler struct {
	BlockHandlerBase
	// contains filtered or unexported fields
}

type VinculumPluginInitFunc = func(*PluginContext) hcl.Diagnostics

type WireFormatBlockHandler struct {
	BlockHandlerBase
}

type WireFormatDefinition struct {
	Type          string    `hcl:"type,label"`
	Name          string    `hcl:"name,label"`
	DefRange      hcl.Range `hcl:",def_range"`
	RemainingBody hcl.Body  `hcl:",remain"`
}

type WireFormatProcessor func(config *Config, block *hcl.Block, body hcl.Body) (cty.Value, hcl.Diagnostics)