rule

type Action struct {
	// Type specifies the action type (publish, add_triple, remove_triple, update_triple, publish_agent)
	Type string `json:"type"`

	// Subject is the NATS subject for publish actions
	Subject string `json:"subject,omitempty"`

	// Predicate is the relationship type for triple actions
	Predicate string `json:"predicate,omitempty"`

	// Object is the target entity or value for triple actions
	Object string `json:"object,omitempty"`

	// TTL specifies optional expiration time for triples (e.g., "5m", "1h")
	TTL string `json:"ttl,omitempty"`

	// Properties contains additional metadata for the action
	Properties map[string]any `json:"properties,omitempty"`

	// Role is the agent role for publish_agent actions (e.g., "general", "architect", "editor")
	Role string `json:"role,omitempty"`

	// Model is the model endpoint name for publish_agent actions
	Model string `json:"model,omitempty"`

	// Prompt is the task prompt template for publish_agent actions
	// Supports variable substitution: $entity.id, $related.id
	Prompt string `json:"prompt,omitempty"`

	// Tools is the per-spawned-agent tool allowlist for publish_agent actions.
	// Tool names are resolved to agentic.ToolDefinition against the global
	// tool registry at dispatch time; unknown names are logged and dropped.
	// Empty/nil leaves TaskMessage.Tools unset, which makes the spawned loop
	// fall back to global tool discovery (existing behaviour).
	//
	// This is the product-layer hook for scoping which tools a given role
	// can see. Putting it on the rule — not in agentic-tools Config — keeps
	// role→tools decisions in the workflow config that already owns the
	// role name, model, and prompt for the spawned agent.
	Tools []string `json:"tools,omitempty"`

	// WorkflowID is the workflow identifier for trigger_workflow actions
	WorkflowID string `json:"workflow_id,omitempty"`

	// ContextData provides additional context passed to the workflow
	ContextData map[string]any `json:"context_data,omitempty"`

	// BoidSignalType specifies the type of boid signal: separation, cohesion, or alignment
	BoidSignalType string `json:"boid_signal_type,omitempty"`

	// BoidStrength specifies the steering strength for boid signals (0.0-1.0)
	BoidStrength float64 `json:"boid_strength,omitempty"`

	// WorkflowSlug identifies the workflow for publish_agent actions (e.g., "github-issue-to-pr")
	WorkflowSlug string `json:"workflow_slug,omitempty"`

	// WorkflowStep identifies the step within the workflow (e.g., "qualify", "develop", "review")
	WorkflowStep string `json:"workflow_step,omitempty"`

	// When is an optional guard clause for conditional action execution.
	// If present, all conditions must match (AND logic) against the entity's current
	// state and $state.* fields for the action to execute. Actions without When always execute.
	When []expression.ConditionExpression `json:"when,omitempty"`

	// Bucket is the KV bucket name for update_kv actions (e.g., "PLAN_STATES").
	// Supports variable substitution.
	Bucket string `json:"bucket,omitempty"`

	// Key is the KV key for update_kv actions. Supports variable substitution.
	Key string `json:"key,omitempty"`

	// Payload is the data to write for update_kv actions.
	// Supports variable substitution in string values (including nested maps).
	Payload map[string]any `json:"payload,omitempty"`

	// Merge controls write semantics for update_kv:
	// true = CAS read-modify-write (merge payload into existing document)
	// false = overwrite entire document (last writer wins)
	Merge bool `json:"merge,omitempty"`
}

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

type ActionExecutorInterface interface {
	Execute(ctx context.Context, action Action, ec *ExecutionContext) error
}

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

type Config struct {
	// Port configuration for inputs and outputs
	Ports *component.PortConfig `` /* 168-byte string literal not displayed */

	// Rule configuration sources
	RulesFiles  []string     `json:"rules_files" schema:"type:array,description:Paths to JSON rule definition files,default:[],category:basic"`
	InlineRules []Definition `json:"inline_rules,omitempty" schema:"type:array,description:Inline rule definitions (alternative to files),category:basic"`

	// Message cache configuration (not exposed in schema - internal config)
	MessageCache cache.Config `json:"message_cache"`

	// Buffer window size for time-window analysis
	BufferWindowSize string `` /* 135-byte string literal not displayed */

	// Alert cooldown period to prevent spam
	AlertCooldownPeriod string `` /* 139-byte string literal not displayed */

	// Graph processor integration
	EnableGraphIntegration bool `` /* 130-byte string literal not displayed */

	// NATS KV patterns to watch for entity changes (e.g., 'telemetry.robotics.>')
	// DEPRECATED: Use EntityWatchBuckets for multi-bucket support. This field is still
	// supported for backwards compatibility and applies to ENTITY_STATES bucket.
	EntityWatchPatterns []string `` /* 153-byte string literal not displayed */

	// EntityWatchBuckets maps bucket names to watch patterns.
	// This enables rules to observe operational results from multiple components.
	// Example: {"ENTITY_STATES": ["telemetry.>"], "WORKFLOW_EXECUTIONS": ["COMPLETE_*"]}
	// If not specified, falls back to EntityWatchPatterns for ENTITY_STATES bucket.
	EntityWatchBuckets map[string][]string `` /* 147-byte string literal not displayed */

	// Debounce delay for rule evaluation (settling time for entity state)
	// Default is 0 (disabled) to ensure rules evaluate against each state change.
	// Set to a positive value (e.g., 100) to batch rapid updates and evaluate final state only.
	DebounceDelayMs time.Duration `` /* 146-byte string literal not displayed */

	// JetStream consumer configuration (not exposed in schema - internal config)
	Consumer struct {
		Enabled        bool   `json:"enabled"`          // Enable JetStream consumer
		AckWaitSeconds int    `json:"ack_wait_seconds"` // Acknowledgment timeout
		MaxDeliver     int    `json:"max_deliver"`      // Max delivery attempts
		ReplayPolicy   string `json:"replay_policy"`    // "instant" or "original"
	} `json:"consumer"`
}

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

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

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

type CronSchedulerConfig struct {
	// Executor is required. A nil executor is rejected because every
	// fire would silently no-op, hiding misconfiguration.
	Executor ActionExecutorInterface

	// Tracker is optional. Pass nil to run without persistence — no
	// cross-restart missed-fire detection, no cooldown hydration on
	// startup. Tests typically pass nil; the production processor
	// wires in a tracker bound to the RULE_SCHEDULES bucket.
	Tracker *ScheduleTracker

	// Metrics is optional. Pass nil to run without Prometheus
	// observability — every recordX call short-circuits on the nil
	// receiver. Tests that don't assert on metrics pass nil; the
	// production processor wires in metrics scoped to its registry.
	Metrics *cronMetrics

	// Logger is optional. Defaults to slog.Default() when nil so the
	// scheduler always has something to log to.
	Logger *slog.Logger
}

type Definition struct {
	ID              string                           `json:"id"`
	Type            string                           `json:"type"`
	Name            string                           `json:"name"`
	Description     string                           `json:"description"`
	Enabled         bool                             `json:"enabled"`
	Conditions      []expression.ConditionExpression `json:"conditions"`
	Logic           string                           `json:"logic"`
	Cooldown        string                           `json:"cooldown,omitempty"`
	Entity          EntityConfig                     `json:"entity,omitempty"`
	Metadata        map[string]interface{}           `json:"metadata,omitempty"`
	OnEnter         []Action                         `json:"on_enter,omitempty"`         // Fires on false→true transition
	OnExit          []Action                         `json:"on_exit,omitempty"`          // Fires on true→false transition
	WhileTrue       []Action                         `json:"while_true,omitempty"`       // Fires on every update while true
	OnRecovery      []Action                         `json:"on_recovery,omitempty"`      // Fires once on restart if still matching; falls back to OnEnter
	RelatedPatterns []string                         `json:"related_patterns,omitempty"` // For pair rules

	// RerunOnRecovery opts rules with only OnEnter/WhileTrue defined into the
	// bootstrap recovery path. When false (default), such rules must declare
	// OnRecovery explicitly to re-fire on restart. Rules that already declare
	// OnRecovery always participate regardless of this flag.
	RerunOnRecovery bool `json:"rerun_on_recovery,omitempty"`

	// MaxIterations limits how many times a rule can enter the matching state for an entity.
	// 0 means no limit. Use $state.iteration and $state.max_iterations in When clauses
	// for retry budgets (e.g., retry up to 3 times then escalate).
	MaxIterations int `json:"max_iterations,omitempty"`

	// FireEveryNEvents makes the rule fire its action only every Nth matching
	// event. N=0 and N=1 both mean "fire on every match" (backward-compatible
	// default). N=2 fires on the 2nd, 4th, 6th matching events; N=10 fires on
	// the 10th, 20th, 30th, etc.
	//
	// The MATCH check still runs on every event — only the action is gated.
	// Counter state is per-rule (not per-entity) and resets when the rule
	// definition is replaced via applyRuleChanges, so a policy change begins
	// with a fresh rhythm.
	//
	// This is a parallel dimension to time-based AlertCooldownPeriod; neither
	// replaces the other.
	FireEveryNEvents int `json:"fire_every_n_events,omitempty"`

	// Schedule is the cron expression for `type: "cron"` rules. Required
	// when Type == "cron"; ignored otherwise. Supports POSIX 5-field
	// (`min hour dom mon dow`) and the descriptors @hourly / @daily /
	// @weekly / @monthly / @yearly. Parsed via robfig/cron/v3 at config
	// load time; bad expressions fail rule construction.
	Schedule string `json:"schedule,omitempty"`

	// Actions is the action list for `type: "cron"` rules. Cron rules use
	// this field instead of OnEnter/OnExit/WhileTrue because they have no
	// state-transition semantics — every scheduled tick fires every Action
	// here. Required when Type == "cron"; ignored otherwise.
	Actions []Action `json:"actions,omitempty"`
}

type Dependencies struct {
	NATSClient *natsclient.Client
	Logger     *slog.Logger
}

type EntityConfig struct {
	Pattern      string   `json:"pattern"`       // Entity ID pattern to match
	WatchBuckets []string `json:"watch_buckets"` // KV buckets to watch
}

type EntityStateEvaluator interface {
	// EvaluateEntityState evaluates the rule directly against EntityState triples.
	// Rule conditions should use full predicate paths (e.g., "sensor.measurement.fahrenheit").
	EvaluateEntityState(entityState *gtypes.EntityState) bool
}

type Evaluation struct {
	Rule              Definition
	EntityID          string
	RelatedID         string // "" for single-entity rules
	CurrentlyMatching bool
	Entity            *gtypes.EntityState // nil for message-path rules
	Related           *gtypes.EntityState // nil for single-entity or message-path
	Revision          uint64              // KV revision that triggered this evaluation; 0 if unknown
	Bootstrap         bool                // true during watcher initial-state replay
}

type Event interface {
	// EventType returns the type identifier for this event
	EventType() string

	// Subject returns the NATS subject for publishing this event
	Subject() string

	// Payload returns the event data as a generic map
	Payload() map[string]any

	// Validate checks if the event is valid and ready to publish
	Validate() error
}

type Example struct {
	Name        string     `json:"name"`
	Description string     `json:"description"`
	Config      Definition `json:"config"`
}

type ExecutionContext struct {
	// EntityID is the primary entity identifier.
	EntityID string

	// RelatedID is the related entity identifier (empty for single-entity rules).
	RelatedID string

	// Entity is the full entity state with triples (nil for message-path rules).
	Entity *gtypes.EntityState

	// Related is the related entity state (nil for single-entity rules or message-path).
	Related *gtypes.EntityState

	// State is the current match state including iteration tracking.
	// May be nil for first evaluation before state is persisted.
	State *MatchState

	// Schedule carries cron-rule context (rule ID, spec, prior fire
	// timestamp). Populated by CronScheduler.fire on time-driven
	// dispatches; nil for message-path and KV-watch rules. The
	// `$schedule.*` substitution layer reads this; see
	// cron_substitution.go for the namespace contract.
	Schedule *ScheduleContext
}

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

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

type Factory interface {
	// Create creates a rule instance from configuration
	Create(id string, config Definition, deps Dependencies) (Rule, error)

	// Type returns the rule type this factory creates
	Type() string

	// Schema returns the configuration schema for UI discovery
	Schema() Schema

	// Validate validates a rule configuration
	Validate(config Definition) error
}

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

type KVWriter interface {
	// UpdateJSON performs a CAS read-modify-write on a JSON document in the named bucket.
	// The updateFn receives the current value (empty map if key doesn't exist) and mutates it.
	// Uses exponential backoff retry on CAS conflicts (via natsclient.KVStore.UpdateJSON).
	UpdateJSON(ctx context.Context, bucket, key string, updateFn func(current map[string]any) error) error

	// PutJSON writes a JSON value to the named bucket (last writer wins, no CAS).
	PutJSON(ctx context.Context, bucket, key string, value map[string]any) error
}

type LastFireRecord struct {
	// RuleID is the cron rule's stable identifier. Duplicates the KV key
	// so that List() consumers can decode a record without re-threading
	// the key alongside it.
	RuleID string `json:"rule_id"`

	// ScheduleSpec is the rule's cron expression at the time of the
	// recorded fire. Useful for operators reading the bucket directly
	// and for missed-fire detection that wants to compute the expected
	// fire interval without re-loading rule definitions.
	ScheduleSpec string `json:"schedule_spec"`

	// LastFiredAt is the wallclock at which the most recent fire began
	// dispatching actions. UTC; serialised RFC3339Nano via Go's default
	// time.Time JSON encoder. Nanosecond precision is preserved best-
	// effort across platforms — callers that depend on exact equality
	// (e.g. round-trip tests) should truncate to a known resolution
	// before write rather than relying on the encoder.
	LastFiredAt time.Time `json:"last_fired_at"`
}

type MatchState struct {
	RuleID         string    `json:"rule_id"`
	EntityKey      string    `json:"entity_key"`
	IsMatching     bool      `json:"is_matching"`
	LastTransition string    `json:"last_transition"` // ""|"entered"|"exited"
	TransitionAt   time.Time `json:"transition_at,omitempty"`
	SourceRevision uint64    `json:"source_revision"`
	LastChecked    time.Time `json:"last_checked"`

	// Iteration tracks how many times this rule has entered the matching state
	// for this entity. Incremented on each TransitionEntered, preserved through exits.
	Iteration int `json:"iteration"`

	// MaxIterations is the configured limit from the rule Definition.
	// 0 means no limit. Used with $state.iteration in When clauses for retry budgets.
	MaxIterations int `json:"max_iterations,omitempty"`

	// FieldValues tracks the last-seen values of fields used in transition conditions.
	// Keys are field names (e.g., "workflow.plan.status"), values are the string
	// representation of the last observed value. Used by the transition operator
	// to detect field-level state changes across evaluations.
	FieldValues map[string]string `json:"field_values,omitempty"`
}

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

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

type Publisher interface {
	// Publish sends a message to a NATS subject.
	// The implementation determines whether to use core NATS or JetStream
	// based on port configuration.
	Publish(ctx context.Context, subject string, data []byte) error
}

type Rule interface {
	// Name returns the human-readable name of this rule
	Name() string

	// Subscribe returns the NATS subjects this rule should listen to
	Subscribe() []string

	// Evaluate checks if the rule conditions are met for the given messages
	Evaluate(messages []message.Message) bool

	// ExecuteEvents generates events when rule conditions are satisfied
	ExecuteEvents(messages []message.Message) ([]Event, error)
}

type ScheduleContext struct {
	// ID is the firing rule's stable identifier — same value as
	// Definition.ID and CronRule.ID. Always non-empty for a cron fire.
	ID string

	// Spec is the cron expression as the rule was registered with it.
	// Captured at fire time so a hot-reload that changes the schedule
	// doesn't retroactively alter substitution output for in-flight
	// dispatches. Always non-empty for a cron fire.
	Spec string

	// LastFiredAt is the wallclock of the most recent successful fire
	// before this one. Zero value (time.IsZero) on the first fire of
	// a freshly-registered rule, before any persisted record exists.
	// The substitution renders zero as the empty string so authors can
	// detect first-fire via `len("$schedule.last_fired_at") == 0` in
	// downstream conditional templates.
	LastFiredAt time.Time
}

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

type Schema struct {
	Type        string                              `json:"type"`
	DisplayName string                              `json:"display_name"`
	Description string                              `json:"description"`
	Category    string                              `json:"category"`
	Icon        string                              `json:"icon,omitempty"`
	Properties  map[string]component.PropertySchema `json:"properties"`
	Required    []string                            `json:"required"`
	Examples    []Example                           `json:"examples,omitempty"`
}

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

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

type Status struct {
	DebounceDelayMs    int       `json:"debounce_delay_ms"`
	PendingEvaluations int       `json:"pending_evaluations"`
	TotalEvaluations   int       `json:"total_evaluations"`
	TotalTriggers      int       `json:"total_triggers"`
	DebouncedCount     int       `json:"debounced_count"` // Matches Tester's test expectations
	RulesLoaded        int       `json:"rules_loaded"`
	LastEvaluationTime time.Time `json:"last_evaluation_time,omitempty"`

	// TrackedRevisions is the total number of (rule,entity,revision) tuples
	// currently in the feedback-loop-prevention map. Monitor this to detect
	// leaks from writes that the watcher never delivers — a healthy
	// processor's count should stay roughly proportional to in-flight rule
	// actions, bounded by the sweeper.
	TrackedRevisions int `json:"tracked_revisions"`
}

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

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

type Transition string

type TripleMutator interface {
	// AddTriple adds a triple via NATS request/response and returns the KV revision.
	AddTriple(ctx context.Context, ruleID string, triple message.Triple) (uint64, error)
	// RemoveTriple removes a triple via NATS request/response and returns the KV revision.
	RemoveTriple(ctx context.Context, ruleID, subject, predicate string) (uint64, error)
}

type ValidationError struct {
	Field   string
	Message string
}

type WorkflowTriggerPayload struct {
	WorkflowID  string         `json:"workflow_id"`
	EntityID    string         `json:"entity_id"`
	TriggeredAt time.Time      `json:"triggered_at"`
	RelatedID   string         `json:"related_id,omitempty"`
	Context     map[string]any `json:"context,omitempty"`
}