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 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"`
}

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
}

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 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 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"`
}