templating

type CompilationError struct {
	// TemplateName is the name of the template that failed to compile
	TemplateName string

	// TemplateSnippet contains the first 200 characters of the template
	TemplateSnippet string

	// Cause is the underlying compilation error from the template engine
	Cause error
}

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

type Engine interface {

	// Render executes a template with the given context and returns the output.
	// The ctx parameter is used for cancellation and timeout control.
	// Returns RenderError if template execution fails, RenderTimeoutError if
	// the context deadline is exceeded, or TemplateNotFoundError if the
	// template doesn't exist.
	Render(ctx context.Context, templateName string, templateContext map[string]any) (string, error)

	// RenderWithProfiling renders a template and returns profiling statistics
	// for included templates. Useful for performance debugging.
	//
	// Enable profiling via Options.Profiling at construction time.
	// Returns nil stats when profiling is disabled.
	//
	// Stats are aggregated by template name — multiple renders of the same
	// template are combined into a single IncludeStats entry with count > 1.
	RenderWithProfiling(ctx context.Context, templateName string, templateContext map[string]any) (string, []IncludeStats, error)

	// PostProcess applies a template's configured post-processor chain to
	// text that did not come from that render pass, so a caller assembling
	// output from several pieces can normalise each piece the same way.
	PostProcess(ctx context.Context, templateName string, text string) (string, error)

	BeginPostProcessTransaction(context.Context) (context.Context, PostProcessTransaction)

	// TemplateNames returns the names of all available templates, sorted alphabetically.
	TemplateNames() []string

	// HasTemplate checks if a template with the given name exists.
	HasTemplate(templateName string) bool

	// GetRawTemplate returns the original template string for the given name.
	// Returns TemplateNotFoundError if the template doesn't exist.
	GetRawTemplate(templateName string) (string, error)

	// TemplateCount returns the number of templates in the engine.
	TemplateCount() int

	// EnableTracing enables template execution tracing for debugging.
	EnableTracing()

	// DisableTracing disables template execution tracing.
	DisableTracing()

	// IsTracingEnabled returns whether tracing is currently enabled.
	IsTracingEnabled() bool

	// GetTraceOutput returns accumulated trace output and clears the buffer.
	GetTraceOutput() string

	// AppendTraces appends traces from another engine to this engine's trace buffer.
	// This is useful for aggregating traces from multiple worker engines.
	AppendTraces(other Engine)

	// EnableFilterDebug enables detailed filter operation logging.
	EnableFilterDebug()

	// DisableFilterDebug disables detailed filter operation logging.
	DisableFilterDebug()

	// IsFilterDebugEnabled returns whether filter debug logging is enabled.
	IsFilterDebugEnabled() bool

	// ClearVMPool releases pooled VMs to allow garbage collection.
	// Call after rendering completes to reduce memory from parallel rendering spikes.
	// No-op for engines that don't use VM pooling.
	ClearVMPool()
}

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

type ExactCycleProtocolState interface {
	ValidateExactCycleProtocolState() error
	SameExactCycleProtocolState(ExactCycleProtocolState) (bool, error)
}

type ExactCycleProtocolStateProvider interface {
	ExactCycleProtocolState() (ExactCycleProtocolState, error)
}

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

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

type ExactCycleRootInvocation struct {
	Kind string
	Name string
}

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

type FailError struct {
	Message string
}

type FileRegistrar interface {
	Register(args ...any) (string, error)
}

type FilterFunc func(in any, args ...any) (any, error)

type GlobalFunc func(args ...any) (any, error)

type GlobalUsageIntrospector interface {
	GlobalUsage(name string) (used, known bool)
}

type HTTPFetcher interface {
	// Fetch fetches content from a URL with optional options and authentication.
	// Arguments:
	//   - args[0]: URL (string, required)
	//   - args[1]: options (map, optional) - {"interval": "60s", "timeout": "30s", "retries": 3, "critical": true}
	//   - args[2]: auth (map, optional) - {"type": "bearer"|"basic", "token": "...", ...}
	Fetch(args ...any) (any, error)

	// Pending reports whether this render left the URL out because its new
	// content waits for a render that can accept it: Fetch returned empty
	// content without fetching, and a later render serves the content.
	Pending(url string) bool
}

type IncludeStats struct {
	// Name is the name of the included/rendered template.
	Name string

	// Count is the number of times this template was rendered.
	// Templates rendered multiple times (e.g., in loops) have count > 1.
	Count int

	// TotalMs is the cumulative time spent rendering this template in milliseconds.
	// For templates rendered multiple times, this is the sum of all renders.
	TotalMs float64

	// AvgMs is the average time per render in milliseconds (TotalMs / Count).
	AvgMs float64

	// MaxMs is the maximum time for a single render in milliseconds.
	MaxMs float64
}

type IncrementalBackendPlanRegistrar interface {
	Profile(record map[string]any) (string, error)
	Backend(record map[string]any, text string) (string, error)
	BackendWhenAny(record map[string]any, text, cell string, keys []string) (string, error)
}

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

type IncrementalBindingPlannerExecutor interface {
	RenderIncrementalBindings(context.Context, string, map[string]any) ([]byte, error)
}

type IncrementalBindingSnapshotPlanner interface {
	SnapshotIncrementalBindingInputs([]string, map[string]any) (*IncrementalBindingInputSnapshot, error)
	MatchIncrementalBindingInputs([]string, map[string]any, *IncrementalBindingInputSnapshot) bool
	RenderIncrementalBindingsSnapshot(context.Context, string, *IncrementalBindingInputSnapshot) ([]byte, error)
}

type IncrementalCertifiedValueReader interface {
	IncrementalValuesCertified(
		context.Context,
		string,
		string,
	) (*IncrementalCertifiedValues, error)
}

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

type IncrementalComponentBatchError struct {
	Index int
	Err   error
}

type IncrementalComponentBatchExecutor interface {
	RenderIncrementalComponents(
		context.Context,
		string,
		[]IncrementalComponentBatchItem,
	) ([]string, error)
}

type IncrementalComponentBatchItem struct {
	Context         context.Context
	TemplateContext map[string]any
	Activate        func() error
	Deactivate      func()
}

type IncrementalComponentContextOptions struct {
	ExecutionLease  IncrementalExecutionLease
	ResourceDeriver IncrementalResourceDeriver
	EventRecorder   IncrementalEventRecorder
	StatusRecorder  IncrementalStatusPatchRecorder
	TransitionTime  string
	ContextValueKey any
	ContextValue    any
}

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

type IncrementalComponentContextValues struct {
	Source        string
	Item          map[string]any
	Props         map[string]any
	RenderSubject map[string]any
	RenderMode    string
	Resources     any
	Controller    map[string]ResourceStore
	Shared        SharedContributionContext
	HTTP          HTTPFetcher
	PlanRegistry  IncrementalBackendPlanRegistrar
}

type IncrementalComponentExecutor interface {
	RenderIncrementalComponent(context.Context, string, map[string]any) (string, error)
}

type IncrementalComponentSourceTransaction struct {
	Children []IncrementalComponentSourceTransactionChild
}

type IncrementalComponentSourceTransactionBatch struct {
	Bindings      map[string]any
	Contexts      []context.Context
	ChildContexts []context.Context
}

type IncrementalComponentSourceTransactionChild struct {
	TemplateName string
	Index        int
}

type IncrementalComponentSourceTransactionLifecycle interface {
	IncrementalComponentVectorLifecycle
	LoadSourceTransactionWave(context.Context, int) (IncrementalComponentSourceTransactionBatch, error)
	SealWave(int) error
}

type IncrementalComponentSourceTransactionWave struct {
	Transactions []IncrementalComponentSourceTransaction
}

type IncrementalComponentSourceTransactionsInput struct {
	SharedContext map[string]any
	Waves         []IncrementalComponentSourceTransactionWave
	Lifecycle     IncrementalComponentSourceTransactionLifecycle
}

type IncrementalComponentSourceTransactionsRenderer interface {
	IncrementalComponentSourceTransactionsEligibility() bool
	RenderIncrementalComponentSourceTransactions(
		context.Context,
		IncrementalComponentSourceTransactionsInput,
	) error
}

type IncrementalComponentVectorCarrierEligibility struct {
	TemplateNames []string
	BindingNames  []string
}

type IncrementalComponentVectorCarrierLane struct {
	TemplateName string
	Count        int
	Bindings     map[string]any
	Contexts     []context.Context
}

type IncrementalComponentVectorCarrierWave struct {
	Lanes []IncrementalComponentVectorCarrierWaveLane
	// EntryPoints optionally fixes per-child dispatch; nil preserves lane order.
	EntryPoints []string
}

type IncrementalComponentVectorCarrierWaveLane struct {
	TemplateName string
	Count        int
}

type IncrementalComponentVectorCarrierWaveLifecycle interface {
	IncrementalComponentVectorLifecycle
	LoadWave(context.Context, int) ([]IncrementalComponentVectorCarrierLane, error)
	SealWave(int) error
}

type IncrementalComponentVectorCarrierWavesInput struct {
	SharedContext map[string]any
	Waves         []IncrementalComponentVectorCarrierWave
	Lifecycle     IncrementalComponentVectorCarrierWaveLifecycle
}

type IncrementalComponentVectorCarrierWavesRenderer interface {
	IncrementalComponentVectorCarrierEligibility() (
		IncrementalComponentVectorCarrierEligibility,
		bool,
	)
	RenderIncrementalComponentVectorCarrierWaves(
		context.Context,
		IncrementalComponentVectorCarrierWavesInput,
	) error
}

type IncrementalComponentVectorEligibility struct {
	BindingNames []string
}

type IncrementalComponentVectorInput struct {
	Count         int
	SharedContext map[string]any
	Bindings      map[string]any
	Contexts      []context.Context
	Lifecycle     IncrementalComponentVectorLifecycle
}

type IncrementalComponentVectorLifecycle interface {
	Begin(index int) error
	End(index int, output string) error
	Abort(activeIndex int, cause error)
}

type IncrementalComponentVectorRenderer interface {
	IncrementalComponentVectorEligibility(
		templateName string,
	) (IncrementalComponentVectorEligibility, bool)
	RenderIncrementalComponentVector(
		context.Context,
		string,
		IncrementalComponentVectorInput,
	) error
}

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

type IncrementalEventRecorder interface {
	RecordEvent(namespace, name, apiVersion, kind, eventType, reason, message string) error
}

type IncrementalExecutionLease interface {
	BeginIncrementalExecution(context.Context, string) (func(), error)
	BeforeIncrementalNativeCall(context.Context) error
}

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

type IncrementalRankedFragmentBytesReader interface {
	IncrementalRankedFragmentBytes(ctx context.Context, group, cell string) (int, error)
}

type IncrementalRankedFragmentJoinReader interface {
	IncrementalRankedFragmentsJoin(context.Context, string, string, string) (string, error)
}

type IncrementalRankedFragmentReader interface {
	IncrementalRankedFragments(context.Context, string, string) (string, error)
}

type IncrementalRankedTextFragmentJoinReader interface {
	IncrementalRankedTextFragmentJoin(context.Context, string, string, string) (TextFragment, error)
}

type IncrementalRankedTextFragmentReader interface {
	IncrementalRankedTextFragment(context.Context, string, string) (TextFragment, error)
}

type IncrementalRenderer interface {
	RenderIncremental(context.Context, string) (string, error)
}

type IncrementalResourceBinder interface {
	BindIncrementalResources(string, any, IncrementalResourceInvocationLease) (any, error)
}

type IncrementalResourceBoundFrameFactory func(
	IncrementalResourceInvocationLease,
) (*native.FunctionTrampoline, error)

type IncrementalResourceDeriver interface {
	DeriveResource(resource string, item any, path string, value any) (any, error)
}

type IncrementalResourceFunctionBinding struct {
	Trampoline        *native.FunctionTrampoline
	BoundFrameFactory IncrementalResourceBoundFrameFactory
}

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

type IncrementalResourceInvocationLease interface {
	ValidateIncrementalResourceInvocation(context.Context) error
}

type IncrementalSourceTransactionChildSelector interface {
	ActiveIncrementalSourceTransactionChild() (int, error)
}

type IncrementalSourceTransactionResourceBinder interface {
	BindIncrementalSourceTransactionResources(
		[]string,
		any,
		IncrementalResourceInvocationLease,
		IncrementalSourceTransactionChildSelector,
	) (any, error)
}

type IncrementalSourceTransactionSelectorAuthenticator interface {
	ValidateIncrementalSourceTransactionSelector(IncrementalSourceTransactionChildSelector) error
}

type IncrementalStatusPatchRecorder interface {
	RecordStatusPatch(
		namespace, name, apiVersion, kind, uid, resourceVersion string,
		variants map[string]map[string]any,
		sourceTemplate string,
		sourceLine int,
		listOwnership ...string,
	) error
}

type IncrementalTextFragmentRenderer interface {
	RenderIncrementalTextFragment(context.Context, string) (TextFragment, error)
}

type IncrementalValueCounter interface {
	IncrementalValueCount(ctx context.Context, group, cell string) (int, error)
}

type IncrementalValueReader interface {
	IncrementalValues(context.Context, string, string) ([]any, error)
}

type Options struct {
	// EntryPoints lists template names to compile explicitly; the remaining
	// templates are snippets, discovered and compiled automatically when
	// referenced via render/render_glob statements with inherit_context.
	// nil means every template is an entry point.
	EntryPoints []string
	// IncrementalEntryPoints is the subset of EntryPoints compiled against
	// the deterministic incremental declaration set.
	IncrementalEntryPoints []string
	// IncrementalBindingEntryPoints is the subset compiled as deterministic
	// dynamic binding planners.
	IncrementalBindingEntryPoints []string
	// Filters are custom filters merged over the built-in set (can be nil).
	Filters map[string]FilterFunc
	// Functions are custom global functions merged over the built-in set
	// (can be nil).
	Functions map[string]GlobalFunc
	// PostProcessors configures per-template post-processing (can be nil).
	PostProcessors map[string][]PostProcessorConfig
	// Declarations registers domain-specific types with Scriggo (e.g.
	// currentConfig for slot-aware server assignment). Use this when
	// templates need access to types from other packages (can be nil).
	Declarations map[string]any
	// Profiling enables Scriggo's built-in profiler, which collects timing
	// data for function calls, macros, and includes during execution
	// (see RenderWithProfiling). Profiling adds minimal runtime overhead.
	Profiling bool
}

type PathResolver struct {
	// BaseDir is the absolute base path for HAProxy auxiliary files.
	// This is used with "default-path origin" in HAProxy's global section
	// to resolve relative paths regardless of where the config file is located.
	// Example: "/etc/haproxy"
	BaseDir string

	// MapsDir is the relative path to the HAProxy maps directory.
	// Example: "maps"
	MapsDir string

	// SSLDir is the relative path to the HAProxy SSL certificates directory.
	// Example: "ssl"
	SSLDir string

	// CRTListDir is the relative path to the HAProxy crt-list files directory.
	// Example: "ssl"
	CRTListDir string

	// GeneralDir is the relative path to the HAProxy general files directory.
	// Example: "files"
	GeneralDir string
}

type PlanRegistrar interface {
	// Section registers section text under a kind ("profile" or "backend")
	// and a name, and returns its placeholder line. Registering the same
	// (kind, name) twice is fine while the text is identical.
	Section(kind, name, text string) (string, error)

	// Fragment registers text to splice in at the placeholder it returns,
	// without the text passing through the template writer. Unlike Section it
	// does not partition the config — the fragment lands inside the
	// surrounding core section, so the rendered bytes are identical to
	// emitting the text inline.
	Fragment(name string, fragment TextFragment) (string, error)

	// Profile content-addresses a named `defaults` section from the shape
	// values a backend shares with every backend of the same shape (mode,
	// balance, hash-type, default-server keywords and the profile directive
	// lines), registers it, and returns its name (`haptic-be-<hash>`). Two
	// backends with the same shape get the same name and one section, which is
	// what makes them dynamic-eligible. The name is what Backend() writes after
	// `from` and records as the backend's `profile`.
	Profile(record map[string]any) (string, error)

	// Backend records a backend as data and registers its section text.
	// Unknown keys and a missing name are errors — a typo must not silently
	// under-describe the emitted section.
	Backend(record map[string]any, text string) (string, error)

	// ProfileGroup returns the placeholder line where every registered
	// profile section is spliced, sorted by name. Emit it exactly once.
	ProfileGroup() string

	// MapMeta declares whether entry order matters for a map file. Maps are
	// ordered unless declared otherwise.
	MapMeta(path string, ordered bool) error
}

type PostProcessBatchError struct {
	Index int
	Err   error
}

type PostProcessBatcher interface {
	PostProcessBatch(ctx context.Context, templateName string, inputs []string) ([]string, error)
}

type PostProcessPublication interface {
	Publish()
	Abort()
}

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

type PostProcessReuseProver interface {
	PostProcessReuseProof(templateName string) (*PostProcessReuseProof, error)
}

type PostProcessTransaction interface {
	Stage(context.Context) (PostProcessPublication, error)
	Abort()
}

type PostProcessor interface {
	// Process applies transformation to the input string.
	// Returns the transformed output or an error if processing fails.
	Process(input string) (string, error)
}

type PostProcessorConfig struct {
	// Type specifies which post-processor to use.
	Type PostProcessorType `yaml:"type" json:"type"`

	// Params contains type-specific configuration as key-value pairs.
	// For regex_replace:
	//   - pattern: Regular expression pattern to match (required)
	//   - replace: Replacement string (required)
	Params map[string]string `yaml:"params" json:"params"`
}

type PostProcessorType string

type RawTextRenderer interface {
	RenderRawTo(context.Context, string, map[string]any, io.Writer) ([]IncludeStats, error)
	RawTextRenderInstrumented() bool
}

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

type RenderError struct {
	// TemplateName is the name of the template that failed to render
	TemplateName string

	// Cause is the underlying rendering error from the template engine
	Cause error
}

type RenderTimeoutError struct {
	// TemplateName is the name of the template that timed out
	TemplateName string

	// Cause is the underlying context error
	Cause error
}

type RenderedEvent struct {
	// Namespace of the involved (regarding) resource. Empty for cluster-scoped.
	Namespace string
	// Name of the involved resource.
	Name string
	// APIVersion of the involved resource (e.g. "networking.k8s.io/v1").
	APIVersion string
	// Kind of the involved resource (e.g. "Ingress").
	Kind string
	// Type is the Event type: "Warning" or "Normal".
	Type string
	// Reason is a short, machine-readable, PascalCase reason (e.g. "RouteConflict").
	Reason string
	// Message is the human-readable description.
	Message string
}

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

type RenderedResource struct {
	// APIVersion of the target resource (e.g., "v1", "gateway.networking.k8s.io/v1").
	APIVersion string

	// Kind of the target resource (e.g., "Service", "Secret", "ConfigMap").
	Kind string

	// Namespace of the target resource. Empty for cluster-scoped resources;
	// the applier passes Namespace("") to the dynamic client which handles
	// cluster-scoped types automatically.
	Namespace string

	// Name of the target resource.
	Name string

	// Object is the desired resource shape that will be sent verbatim to the
	// API server via SSA. It must include `apiVersion`, `kind`, and
	// `metadata.name` — the collector validates and injects those at
	// Register time, so callers can omit them and pass only the deltas.
	Object map[string]any

	// CreateOnlyFields are dotted field paths the applier sends when it creates
	// this object and omits from every apply after that, leaving them to
	// whoever runs it.
	CreateOnlyFields []string
}

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

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

type ResourceDeriver interface {
	DeriveResource(resource string, item any, path string, value any) (any, error)
}

type ResourceStore interface {
	// List returns all resources from the store.
	List() []any

	// Fetch returns resources matching the given keys (typically namespace, name).
	Fetch(keys ...any) []any

	// GetSingle returns a single resource matching the keys, or nil if not found.
	GetSingle(keys ...any) any
}

type RuntimeEnvironment struct {
	// GOMAXPROCS is the maximum number of OS threads for parallel execution.
	// Used by sharding logic to calculate optimal shard count.
	GOMAXPROCS int
}

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

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

type SharedContributionContext interface {
	Unique(cell, key, value string) string
	Publish(cell, key string, value any) string
	PublishRanked(cell, key, rank string, value any) string
	Select(group, cell, key string) (any, bool)
	SelectValues(group, cell string) []any
	Count(group, cell string) int
	// contains filtered or unexported methods
}

type SharedContributionRecorder interface {
	Unique(cell, key, value string)
}

type SharedValueSelector interface {
	Select(group, cell, key string) (any, bool, error)
	SelectValues(group, cell string) ([]any, error)
	Count(group, cell string) (int, error)
}

type SourceFrame = scriggo.SourceFrame

type SourceSpan = scriggo.SourceSpan

type StatusPatch struct {
	// Namespace of the target Kubernetes resource.
	Namespace string

	// Name of the target Kubernetes resource.
	Name string

	// APIVersion of the target resource (e.g., "networking.k8s.io/v1").
	APIVersion string

	// Kind of the target resource (e.g., "Service", "ConfigMap", or any watched CRD's Kind).
	Kind string

	// UID identifies the exact source resource incarnation. Empty for offline and legacy inputs.
	UID string

	// ResourceVersion identifies the exact source resource revision. Empty for offline and legacy inputs.
	ResourceVersion string

	// ListOwnership encodes status-relative JSON pointers and entry selectors. Empty replaces complete lists.
	ListOwnership string

	// Variants maps pipeline phase names to desired status payloads.
	// Keys are phase names: "rendered", "deployed", "renderFailed", "deployFailed".
	// Values are the desired .status content for that phase.
	Variants map[string]map[string]any

	// SourceTemplate is the template path that called statusPatch() to register
	// this patch (best-effort, from native.Env.CallPath). Empty when unknown.
	// SourceLine is the 1-based line within that template of the statusPatch()
	// call (from native.Env.CallLine), 0 when unknown. Provenance metadata only —
	// the controller never reads them; they let the playground jump from a
	// rendered status block back to the exact statusPatch() call. Resource-agnostic:
	// a template name and line, not a resource path.
	SourceTemplate string
	SourceLine     int
}

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

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

type StatusPatchProjectionClaim struct {
	Namespace       string
	Name            string
	APIVersion      string
	Kind            string
	UID             string
	ResourceVersion string
	ListOwnership   string
	Phase           string
}

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

type StatusPatchProjectionPlanEntry struct {
	Group      string
	Entry      string
	Projection *StatusPatchProjection
}

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

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

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

type StatusPatchTarget struct {
	Namespace  string
	Name       string
	APIVersion string
	Kind       string
}

type TemplateNotFoundError struct {
	// TemplateName is the name of the requested template
	TemplateName string

	// AvailableTemplates lists all available template names
	AvailableTemplates []string
}

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

type TextFragment = native.TextFragment

type WorkerGate interface {
	// TryAcquire reports whether one more worker may run a chunk now.
	TryAcquire() bool
	// Release returns a worker admitted by TryAcquire.
	Release()
}