rules package reference

Package path: github.com/cpcf/gess/rules

Constants

const (
  FieldConstraintOpUnknown        FieldConstraintOperator = ""
  FieldConstraintOpExists         FieldConstraintOperator = "exists"
  FieldConstraintOpEqual          FieldConstraintOperator = "eq"
  FieldConstraintOpNotEqual       FieldConstraintOperator = "neq"
  FieldConstraintOpLessThan       FieldConstraintOperator = "lt"
  FieldConstraintOpLessOrEqual    FieldConstraintOperator = "lte"
  FieldConstraintOpGreaterThan    FieldConstraintOperator = "gt"
  FieldConstraintOpGreaterOrEqual FieldConstraintOperator = "gte"

  FieldConstraintExists         = FieldConstraintOpExists
  FieldConstraintEqual          = FieldConstraintOpEqual
  FieldConstraintNotEqual       = FieldConstraintOpNotEqual
  FieldConstraintLessThan       = FieldConstraintOpLessThan
  FieldConstraintLessOrEqual    = FieldConstraintOpLessOrEqual
  FieldConstraintGreaterThan    = FieldConstraintOpGreaterThan
  FieldConstraintGreaterOrEqual = FieldConstraintOpGreaterOrEqual
)

Variables

var (
  ErrInvalidRuleset                = errors.New("gess: invalid ruleset")
  ErrIncompatibleRuleset           = errors.New("gess: incompatible ruleset")
  ErrClosedSession                 = errors.New("gess: closed session")
  ErrConcurrencyMisuse             = errors.New("gess: concurrency misuse")
  ErrActionFailed                  = errors.New("gess: action failed")
  ErrValidation                    = errors.New("gess: validation failed")
  ErrFactNotFound                  = errors.New("gess: fact not found")
  ErrStaleFactID                   = errors.New("gess: stale fact id")
  ErrDuplicateFact                 = errors.New("gess: duplicate fact")
  ErrMatcher                       = errors.New("gess: matcher error")
  ErrUnsupportedRuntime            = errors.New("gess: unsupported runtime")
  ErrInvalidPath                   = errors.New("gess: invalid path")
  ErrInvalidListPattern            = errors.New("gess: invalid list pattern")
  ErrInvalidHigherOrderCondition   = errors.New("gess: invalid higher-order condition")
  ErrAggregateValidation           = errors.New("gess: aggregate validation failed")
  ErrAggregateEvaluation           = errors.New("gess: aggregate evaluation failed")
  ErrFunctionValidation            = errors.New("gess: function validation failed")
  ErrFunctionEvaluation            = errors.New("gess: function evaluation failed")
  ErrQueryNotFound                 = errors.New("gess: query not found")
  ErrQueryArgument                 = errors.New("gess: query argument failed")
  ErrQueryValidation               = errors.New("gess: query validation failed")
  ErrQueryExecution                = errors.New("gess: query execution failed")
  ErrLogicalSupportUnavailable     = errors.New("gess: logical support unavailable")
  ErrLogicalOnlyRetract            = errors.New("gess: cannot retract logical-only fact")
  ErrLogicalFactModify             = errors.New("gess: cannot modify fact with logical support")
  ErrDivideByZero                  = errors.New("gess: divide by zero")
  ErrBuiltinArgument               = errors.New("gess: built-in function argument error")
  ErrExplainLogUnavailable         = errors.New("gess: explain log unavailable")
  ErrRuleNotFound                  = errors.New("gess: rule not found")
  ErrDemandCascadeLimit            = errors.New("gess: backchain demand cascade limit exceeded")
  ErrFactLimit                     = errors.New("gess: session fact limit exceeded")
  ErrUnsupportedValue              = errors.New("gess: unsupported value")
  ErrInvalidCheckpoint             = errors.New("gess: invalid checkpoint")
  ErrUnsupportedCheckpointVersion  = errors.New("gess: unsupported checkpoint version")
  ErrInvalidMutationLog            = errors.New("gess: invalid mutation log")
  ErrUnsupportedMutationLogVersion = errors.New("gess: unsupported mutation log version")
)

Types

AccumulateCondition

AccumulateCondition maintains aggregate results over matching input facts.

type AccumulateCondition struct {
  Input  ConditionSpec
  Specs  []AggregateSpec
  Source SourceSpan
}

Accumulate

Accumulate builds an AccumulateCondition.

func Accumulate(input ConditionSpec, specs ...AggregateSpec) AccumulateCondition

CloneAccumulateCondition

CloneAccumulateCondition returns a defensive copy of s.

func CloneAccumulateCondition(s AccumulateCondition) AccumulateCondition

Action

Action is a compiled, inspectable action reference on a rule or query.

type Action struct {
  NameValue                  string
  Order                      int
  GessSourceText             string
  AssertTemplateValuesAction *AssertTemplateValuesActionSpec
}

CloneAction

CloneAction returns a defensive copy of a.

func CloneAction(a Action) Action

Action.AssertTemplateValues

func (a Action) AssertTemplateValues() (*AssertTemplateValuesActionSpec, bool)

Action.DeclarationOrder

func (a Action) DeclarationOrder() int

Action.GessSource

func (a Action) GessSource() string

Action.Name

func (a Action) Name() string

ActionBindingReadSetSpec

ActionBindingReadSetSpec declares which bindings an action reads.

type ActionBindingReadSetSpec struct {
  Reads []ActionBindingReadSpec
}

CloneActionBindingReadSetSpec

CloneActionBindingReadSetSpec returns a defensive copy of s.

func CloneActionBindingReadSetSpec(s *ActionBindingReadSetSpec) *ActionBindingReadSetSpec

ActionBindingReadSpec

ActionBindingReadSpec declares one binding an action reads.

type ActionBindingReadSpec struct {
  Binding string
  Field   string
  Path    PathSpec
}

CloneActionBindingReadSpec

CloneActionBindingReadSpec returns a defensive copy of s.

func CloneActionBindingReadSpec(s ActionBindingReadSpec) ActionBindingReadSpec

ActionCallSpec

ActionCallSpec is a host-function call action.

type ActionCallSpec struct {
  Name string
  Fn   DSLCallFunc
  Args []ExpressionSpec
}

CloneActionCallSpec

CloneActionCallSpec returns a defensive copy of s.

func CloneActionCallSpec(s *ActionCallSpec) *ActionCallSpec

ActionContext

ActionContext is passed to an ActionFunc. It exposes the activation’s identity and generation, read access to bound facts and values, and the mutation API.

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

NewActionContext

NewActionContext returns an ActionContext backed by handle.

func NewActionContext(handle ActionContextHandle) ActionContext

ActionContext.ActivationID

func (c ActionContext) ActivationID() ActivationID

ActionContext.Assert

func (c ActionContext) Assert(templateKey TemplateKey, fields Fields) (AssertResult, error)

ActionContext.AssertLogical

func (c ActionContext) AssertLogical(templateKey TemplateKey, fields Fields) (AssertResult, error)

ActionContext.AssertTemplateValues

func (c ActionContext) AssertTemplateValues(templateKey TemplateKey, values ...Value) error

ActionContext.Binding

func (c ActionContext) Binding(name string) (FactSnapshot, bool)

ActionContext.BindingID

func (c ActionContext) BindingID(name string) (FactID, bool)

ActionContext.BindingScalarValue

func (c ActionContext) BindingScalarValue(name, field string) (Value, bool)

ActionContext.BindingValue

func (c ActionContext) BindingValue(name string) (Value, bool)

ActionContext.BoundFacts

func (c ActionContext) BoundFacts() []FactSnapshot

ActionContext.ClearFocusStack

func (c ActionContext) ClearFocusStack() error

ActionContext.Context

func (c ActionContext) Context() context.Context

ActionContext.Emit

func (c ActionContext) Emit(values ...Value) error

ActionContext.Generation

func (c ActionContext) Generation() Generation

ActionContext.Global

func (c ActionContext) Global(name string) (Value, bool)

ActionContext.Halt

func (c ActionContext) Halt() error

ActionContext.Modify

func (c ActionContext) Modify(id FactID, patch FactPatch) (ModifyResult, error)

ActionContext.PopFocus

func (c ActionContext) PopFocus() (ModuleName, error)

ActionContext.PushFocus

func (c ActionContext) PushFocus(module ModuleName) error

ActionContext.RHSBind

func (c ActionContext) RHSBind(name string) (Value, bool)

ActionContext.Retract

func (c ActionContext) Retract(id FactID) (RetractResult, error)

ActionContext.RuleID

func (c ActionContext) RuleID() RuleID

ActionContext.RuleRevisionID

func (c ActionContext) RuleRevisionID() RuleRevisionID

ActionContext.RulesetID

func (c ActionContext) RulesetID() RulesetID

ActionContext.SessionID

func (c ActionContext) SessionID() SessionID

ActionContext.SetFocus

func (c ActionContext) SetFocus(module ModuleName) error

ActionContext.SetRHSBind

func (c ActionContext) SetRHSBind(name string, value Value)

ActionContextHandle

ActionContextHandle is the runtime implementation behind ActionContext.

type ActionContextHandle interface {
  SetRHSBind(name string, value Value)
  RHSBind(name string) (Value, bool)
  Context() context.Context
  SessionID() SessionID
  RulesetID() RulesetID
  ActivationID() ActivationID
  RuleID() RuleID
  RuleRevisionID() RuleRevisionID
  Generation() Generation
  BoundFacts() []FactSnapshot
  Binding(name string) (FactSnapshot, bool)
  BindingID(name string) (FactID, bool)
  BindingValue(name string) (Value, bool)
  BindingScalarValue(name, field string) (Value, bool)
  Global(name string) (Value, bool)
  Assert(templateKey TemplateKey, fields Fields) (AssertResult, error)
  AssertLogical(templateKey TemplateKey, fields Fields) (AssertResult, error)
  AssertTemplateValues(templateKey TemplateKey, values ...Value) error
  Modify(id FactID, patch FactPatch) (ModifyResult, error)
  Retract(id FactID) (RetractResult, error)
  Halt() error
  Emit(values ...Value) error
  PushFocus(module ModuleName) error
  SetFocus(module ModuleName) error
  PopFocus() (ModuleName, error)
  ClearFocusStack() error
}

ActionContextHandleOf

ActionContextHandleOf returns the engine-owned implementation behind c.

func ActionContextHandleOf(c ActionContext) ActionContextHandle

ActionEffectKind

ActionEffectKind identifies the mutation an ActionEffectSpec performs.

type ActionEffectKind uint8

ActionEffectAssert, ActionEffectAssertLogical, ActionEffectModify, ActionEffectRetract, ActionEffectEmit, ActionEffectBind, ActionEffectPushFocus, ActionEffectPopFocus, ActionEffectClearFocus, ActionEffectHalt

const (
  ActionEffectAssert ActionEffectKind = iota
  ActionEffectAssertLogical
  ActionEffectModify
  ActionEffectRetract
  ActionEffectEmit
  ActionEffectBind
  ActionEffectPushFocus
  ActionEffectPopFocus
  ActionEffectClearFocus
  ActionEffectHalt
)

ActionEffectSpec

ActionEffectSpec is a declarative, expression-backed rule action.

type ActionEffectSpec struct {
  Kind ActionEffectKind
  // Target is the fact-binding name for modify/retract, or the local name
  // for bind. Unused by emit.
  Target string
  // TemplateKey/FactName identify the asserted template for assert/-logical.
  TemplateKey TemplateKey
  FactName    string
  // Fields names the slots set by assert/modify, parallel to Values.
  Fields []string
  // Unset names the slots cleared by modify.
  Unset []string
  // Values are the expression-valued operands.
  Values []ExpressionSpec
}

CloneActionEffectSpec

CloneActionEffectSpec returns a defensive copy of s.

func CloneActionEffectSpec(s *ActionEffectSpec) *ActionEffectSpec

ActionFunc

ActionFunc is the Go implementation of a rule or query action.

type ActionFunc func(ActionContext) error

ActionSpec

ActionSpec names one action implementation registered on a workspace.

type ActionSpec struct {
  Name                 string
  Fn                   ActionFunc
  AssertTemplateValues *AssertTemplateValuesActionSpec
  Effect               *ActionEffectSpec
  Call                 *ActionCallSpec
  BindingReads         *ActionBindingReadSetSpec
  GessSource           string
  // NonEscaping allows the engine to skip freezing unread bindings after a
  // rule fires. Set it only when Fn does not retain ActionContext or any
  // binding-derived data that depends on post-return defensive snapshots.
  NonEscaping bool
}

CloneActionSpec

CloneActionSpec returns a defensive copy of s.

func CloneActionSpec(s ActionSpec) ActionSpec

ActivationID

ActivationID identifies one activation: a rule paired with the specific facts that matched it.

type ActivationID string

ActivationID.IsZero

func (id ActivationID) IsZero() bool

ActivationID.String

func (id ActivationID) String() string

AggregateKind

AggregateKind identifies which aggregate an AggregateSpec computes.

type AggregateKind string

AggregateCount, AggregateSum, AggregateMin, AggregateMax, AggregateCollect

const (
  AggregateCount   AggregateKind = "count"
  AggregateSum     AggregateKind = "sum"
  AggregateMin     AggregateKind = "min"
  AggregateMax     AggregateKind = "max"
  AggregateCollect AggregateKind = "collect"
)

AggregateSpec

AggregateSpec is one aggregate computed over facts matching an accumulate input.

type AggregateSpec struct {
  KindValue      AggregateKind
  ExpressionSpec ExpressionSpec
  BindingName    string
}

CloneAggregateSpec

CloneAggregateSpec returns a defensive copy of s.

func CloneAggregateSpec(s AggregateSpec) AggregateSpec

Collect

Collect aggregates expression’s value from every matching fact into a list.

func Collect(expression ExpressionSpec) AggregateSpec

Count

Count aggregates to the number of matching facts.

func Count() AggregateSpec

Max

Max aggregates to the running maximum of expression over the group.

func Max(expression ExpressionSpec) AggregateSpec

Min

Min aggregates to the running minimum of expression over the group.

func Min(expression ExpressionSpec) AggregateSpec

Sum

Sum aggregates to the running sum of expression over the group.

func Sum(expression ExpressionSpec) AggregateSpec

AggregateSpec.As

func (s AggregateSpec) As(binding string) AggregateSpec

AggregateSpec.Binding

func (s AggregateSpec) Binding() string

AggregateSpec.Expression

func (s AggregateSpec) Expression() ExpressionSpec

AggregateSpec.Kind

func (s AggregateSpec) Kind() AggregateKind

And

And groups condition tree nodes into a conjunction.

type And struct {
  Conditions []ConditionSpec
  Source     SourceSpan
}

ApplyRulesetStatus

ApplyRulesetStatus is the outcome of applying a ruleset to a session.

type ApplyRulesetStatus string

ApplyRulesetApplied, ApplyRulesetUnchanged, ApplyRulesetIncompatible, ApplyRulesetClosed, ApplyRulesetConcurrencyMisuse

const (
  ApplyRulesetApplied           ApplyRulesetStatus = "applied"
  ApplyRulesetUnchanged         ApplyRulesetStatus = "unchanged"
  ApplyRulesetIncompatible      ApplyRulesetStatus = "incompatible"
  ApplyRulesetClosed            ApplyRulesetStatus = "closed"
  ApplyRulesetConcurrencyMisuse ApplyRulesetStatus = "concurrency_misuse"
)

AssertResult

AssertResult reports the outcome of an assert.

type AssertResult struct {
  Status       AssertStatus
  Fact         FactSnapshot
  DuplicateKey DuplicateKey
  Delta        *MutationDelta
}

CloneAssertResult

CloneAssertResult returns a defensive copy of result.

func CloneAssertResult(result AssertResult) AssertResult

AssertResult.Inserted

Inserted reports whether the assert inserted a new fact.

func (r AssertResult) Inserted() bool

AssertStatus

AssertStatus is the outcome of an assert.

type AssertStatus string

AssertInserted, AssertExisting, AssertReplaced, AssertValidationFailure, AssertClosed, AssertConcurrencyMisuse

const (
  AssertInserted          AssertStatus = "inserted"
  AssertExisting          AssertStatus = "existing"
  AssertReplaced          AssertStatus = "replaced"
  AssertValidationFailure AssertStatus = "validation_failure"
  AssertClosed            AssertStatus = "closed"
  AssertConcurrencyMisuse AssertStatus = "concurrency_misuse"
)

AssertTemplateValuesActionSpec

AssertTemplateValuesActionSpec describes a generated rule action that emits values in template field order.

type AssertTemplateValuesActionSpec struct {
  TemplateKey TemplateKey
  Values      []ExpressionSpec
}

CloneAssertTemplateValuesActionSpec

CloneAssertTemplateValuesActionSpec returns a defensive copy of s.

func CloneAssertTemplateValuesActionSpec(s *AssertTemplateValuesActionSpec) *AssertTemplateValuesActionSpec

BindingFieldExpr

BindingFieldExpr references a field, or nested path, of an earlier condition’s binding.

type BindingFieldExpr struct {
  Binding string
  Field   string
  Path    PathSpec
}

BindingPath

BindingPath builds a BindingFieldExpr referencing an earlier condition’s binding through path.

func BindingPath(binding string, path PathSpec) BindingFieldExpr

BindingValueExpr

BindingValueExpr references a value binding, such as an aggregate result, from an earlier condition.

type BindingValueExpr struct {
  Binding string
}

BooleanExpr

BooleanExpr combines Operands with Operator.

type BooleanExpr struct {
  Operator ExpressionBooleanOperator
  Operands []ExpressionSpec
}

CallExpr

CallExpr invokes a registered pure function by name with Args.

type CallExpr struct {
  Name string
  Args []ExpressionSpec
}

Call

Call builds a CallExpr invoking the registered pure function name with args.

func Call(name string, args ...ExpressionSpec) CallExpr

CompareExpr

CompareExpr compares Left and Right with Operator.

type CompareExpr struct {
  Operator ExpressionComparisonOperator
  Left     ExpressionSpec
  Right    ExpressionSpec
}

ConditionID

ConditionID is a compiled rule or query condition’s stable identity.

type ConditionID string

ConditionID.IsZero

func (id ConditionID) IsZero() bool

ConditionID.String

func (id ConditionID) String() string

ConditionSpec

ConditionSpec is a rule or query left-hand-side condition tree node.

type ConditionSpec interface {
  // contains filtered or unexported methods
}

CloneConditionSpec

CloneConditionSpec returns a defensive copy of spec.

func CloneConditionSpec(spec ConditionSpec) ConditionSpec

ConditionTreeKind

ConditionTreeKind identifies the shape of a RuleConditionTree node.

type ConditionTreeKind string

ConditionTreeKindUnknown, ConditionTreeKindAnd, ConditionTreeKindMatch, ConditionTreeKindTest, ConditionTreeKindNot, ConditionTreeKindOr, ConditionTreeKindExists, ConditionTreeKindForall, ConditionTreeKindAccumulate

const (
  ConditionTreeKindUnknown    ConditionTreeKind = ""
  ConditionTreeKindAnd        ConditionTreeKind = "and"
  ConditionTreeKindMatch      ConditionTreeKind = "match"
  ConditionTreeKindTest       ConditionTreeKind = "test"
  ConditionTreeKindNot        ConditionTreeKind = "not"
  ConditionTreeKindOr         ConditionTreeKind = "or"
  ConditionTreeKindExists     ConditionTreeKind = "exists"
  ConditionTreeKindForall     ConditionTreeKind = "forall"
  ConditionTreeKindAccumulate ConditionTreeKind = "accumulate"
)

ConstExpr

ConstExpr is a literal value in an expression tree.

type ConstExpr struct {
  Value any
}

CurrentFieldExpr

CurrentFieldExpr references a field, or nested path, of the fact matched by the current condition.

type CurrentFieldExpr struct {
  Field string
  Path  PathSpec
}

CurrentPath

CurrentPath builds a CurrentFieldExpr referencing the current condition’s fact through path.

func CurrentPath(path PathSpec) CurrentFieldExpr

DSLCallFunc

DSLCallFunc is a host-provided action call implementation.

type DSLCallFunc func(ActionContext, []Value) error

DemandCascadeLimitError

DemandCascadeLimitError reports that a session stopped a backward-chaining demand cascade before processing another demand request.

type DemandCascadeLimitError struct {
  Limit int
  Steps int
}

*DemandCascadeLimitError.Error

func (e *DemandCascadeLimitError) Error() string

*DemandCascadeLimitError.Is

func (e *DemandCascadeLimitError) Is(target error) bool

*DemandCascadeLimitError.Unwrap

func (e *DemandCascadeLimitError) Unwrap() error

DuplicateKey

DuplicateKey is the computed duplicate-detection key for a fact.

type DuplicateKey string

DuplicatePolicy

DuplicatePolicy controls how a template deduplicates facts.

type DuplicatePolicy int

DuplicateStructural, DuplicateAllow, DuplicateUniqueKey

const (
  DuplicateStructural DuplicatePolicy = iota
  DuplicateAllow
  DuplicateUniqueKey
)

ExistsCondition

ExistsCondition tests whether at least one tuple matching Condition exists.

type ExistsCondition struct {
  Condition ConditionSpec
  Source    SourceSpan
}

Exists

Exists builds an ExistsCondition.

func Exists(condition ConditionSpec) ExistsCondition

Explicit

Explicit marks a positive match as ineligible for backward-chaining demand generation while keeping ordinary match behavior unchanged.

type Explicit struct {
  Condition ConditionSpec
  Source    SourceSpan
}

ExpressionBooleanOperator

ExpressionBooleanOperator is the operator in a BooleanExpr.

type ExpressionBooleanOperator string

ExpressionBoolUnknown, ExpressionBoolAnd, ExpressionBoolOr, ExpressionBoolNot

const (
  ExpressionBoolUnknown ExpressionBooleanOperator = ""
  ExpressionBoolAnd     ExpressionBooleanOperator = "and"
  ExpressionBoolOr      ExpressionBooleanOperator = "or"
  ExpressionBoolNot     ExpressionBooleanOperator = "not"
)

ExpressionComparisonOperator

ExpressionComparisonOperator is the operator in a CompareExpr.

type ExpressionComparisonOperator string

ExpressionCompareUnknown, ExpressionCompareEqual, ExpressionCompareNotEqual, ExpressionCompareLessThan, ExpressionCompareLessOrEqual, ExpressionCompareGreaterThan, ExpressionCompareGreaterOrEqual

const (
  ExpressionCompareUnknown        ExpressionComparisonOperator = ""
  ExpressionCompareEqual          ExpressionComparisonOperator = "eq"
  ExpressionCompareNotEqual       ExpressionComparisonOperator = "neq"
  ExpressionCompareLessThan       ExpressionComparisonOperator = "lt"
  ExpressionCompareLessOrEqual    ExpressionComparisonOperator = "lte"
  ExpressionCompareGreaterThan    ExpressionComparisonOperator = "gt"
  ExpressionCompareGreaterOrEqual ExpressionComparisonOperator = "gte"
)

ExpressionFunctionParamSpec

ExpressionFunctionParamSpec declares one named, typed parameter of an expression-backed function.

type ExpressionFunctionParamSpec struct {
  Name string
  Kind ValueKind
}

ExpressionFunctionSpec

ExpressionFunctionSpec defines a pure function whose body is an expression.

type ExpressionFunctionSpec struct {
  Name        string
  Params      []ExpressionFunctionParamSpec
  Return      ValueKind
  Expression  ExpressionSpec
  Description string
  Source      SourceSpan
}

CloneExpressionFunctionSpec

CloneExpressionFunctionSpec returns a defensive copy of s.

func CloneExpressionFunctionSpec(s ExpressionFunctionSpec) ExpressionFunctionSpec

ExpressionPredicate

ExpressionPredicate wraps a compiled predicate for inspection.

type ExpressionPredicate struct {
  ExpressionSpec ExpressionSpec
  PlacementValue ExpressionPredicatePlacement
  Order          int
  SourceSpan     SourceSpan
}

CloneExpressionPredicate

CloneExpressionPredicate returns a defensive copy of p.

func CloneExpressionPredicate(p ExpressionPredicate) ExpressionPredicate

CloneExpressionPredicates

CloneExpressionPredicates returns a defensive copy of predicates.

func CloneExpressionPredicates(predicates []ExpressionPredicate) []ExpressionPredicate

ExpressionPredicate.DeclarationOrder

func (p ExpressionPredicate) DeclarationOrder() int

ExpressionPredicate.Expression

func (p ExpressionPredicate) Expression() ExpressionSpec

ExpressionPredicate.Placement

func (p ExpressionPredicate) Placement() ExpressionPredicatePlacement

ExpressionPredicate.Source

func (p ExpressionPredicate) Source() SourceSpan

ExpressionPredicatePlacement

ExpressionPredicatePlacement reports where the compiler placed a predicate.

type ExpressionPredicatePlacement string

ExpressionPredicatePlacementUnknown, ExpressionPredicatePlacementAlpha, ExpressionPredicatePlacementBetaResidual, ExpressionPredicatePlacementUnsupported

const (
  ExpressionPredicatePlacementUnknown      ExpressionPredicatePlacement = ""
  ExpressionPredicatePlacementAlpha        ExpressionPredicatePlacement = "alpha"
  ExpressionPredicatePlacementBetaResidual ExpressionPredicatePlacement = "beta-residual"
  ExpressionPredicatePlacementUnsupported  ExpressionPredicatePlacement = "unsupported"
)

ExpressionSpec

ExpressionSpec is a deterministic rule predicate expression tree node.

type ExpressionSpec interface {
  // contains filtered or unexported methods
}

CloneExpressionSpec

CloneExpressionSpec returns a defensive copy of spec when it is one of the built-in expression spec nodes.

func CloneExpressionSpec(spec ExpressionSpec) ExpressionSpec

FactID

FactID identifies a fact, stable across modifies within a generation.

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

NewFactID

NewFactID constructs a FactID for engine-owned fact allocation and tests.

func NewFactID(generation Generation, sequence uint64) FactID

FactID.Generation

func (id FactID) Generation() Generation

FactID.IsZero

func (id FactID) IsZero() bool

FactID.Sequence

func (id FactID) Sequence() uint64

FactID.String

func (id FactID) String() string

FactLimitError

FactLimitError reports that a session refused to retain another fact.

type FactLimitError struct {
  Limit int
  Facts int
}

*FactLimitError.Error

func (e *FactLimitError) Error() string

*FactLimitError.Is

func (e *FactLimitError) Is(target error) bool

*FactLimitError.Unwrap

func (e *FactLimitError) Unwrap() error

FactPatch

FactPatch describes a fact modification: Set overwrites the named fields and Unset clears the named fields, restoring their template defaults.

type FactPatch struct {
  Set   Fields
  Unset []string
}

FactSnapshot

FactSnapshot is an immutable, detached view of one fact’s identity, fields, and support state.

type FactSnapshot struct {
  IDValue             FactID
  NameValue           string
  TemplateKeyValue    TemplateKey
  VersionValue        FactVersion
  RecencyValue        Recency
  GenerationValue     Generation
  FieldValues         Fields
  FieldPresenceValues map[string]FieldPresence
  SupportValue        FactSupportProvenance
}

CloneFactSnapshot

CloneFactSnapshot returns a defensive copy of f.

func CloneFactSnapshot(f FactSnapshot) FactSnapshot

CloneFactSnapshotPtr

CloneFactSnapshotPtr returns a defensive copy of f when non-nil.

func CloneFactSnapshotPtr(f *FactSnapshot) *FactSnapshot

CloneFactSnapshots

CloneFactSnapshots returns a defensive copy of facts.

func CloneFactSnapshots(facts []FactSnapshot) []FactSnapshot

FactSnapshot.Field

Field returns one field value by name.

func (f FactSnapshot) Field(name string) (Value, bool)

FactSnapshot.FieldPresence

FieldPresence returns whether a template field was defaulted, explicit, or omitted.

func (f FactSnapshot) FieldPresence(field string) (FieldPresence, bool)

FactSnapshot.FieldPresenceMap

FieldPresenceMap returns template field-presence metadata keyed by field name.

func (f FactSnapshot) FieldPresenceMap() map[string]FieldPresence

FactSnapshot.Fields

Fields returns a copy of the fact’s field values.

func (f FactSnapshot) Fields() Fields

FactSnapshot.Generation

Generation returns the working-memory generation that owns this fact.

func (f FactSnapshot) Generation() Generation

FactSnapshot.ID

ID returns the fact identity.

func (f FactSnapshot) ID() FactID

FactSnapshot.Name

Name returns the dynamic fact name, if the fact is not template-backed.

func (f FactSnapshot) Name() string

FactSnapshot.Path

Path returns the value at path, if present.

func (f FactSnapshot) Path(path PathSpec) (Value, bool, error)

FactSnapshot.Recency

Recency returns the mutation recency that ordered this fact.

func (f FactSnapshot) Recency() Recency

FactSnapshot.String

func (f FactSnapshot) String() string

FactSnapshot.Support

Support returns the fact’s logical support classification.

func (f FactSnapshot) Support() FactSupportProvenance

FactSnapshot.TemplateKey

TemplateKey returns the template identity, if the fact is template-backed.

func (f FactSnapshot) TemplateKey() TemplateKey

FactSnapshot.Version

Version returns the fact version.

func (f FactSnapshot) Version() FactVersion

FactSupportProvenance

FactSupportProvenance is a fact’s support classification.

type FactSupportProvenance struct {
  State FactSupportState
}

FactSupportState

FactSupportState classifies how a fact is supported.

type FactSupportState string

FactSupportStated, FactSupportLogical, FactSupportStatedAndLogical, FactSupportMetadataOnly

const (
  FactSupportStated           FactSupportState = "stated"
  FactSupportLogical          FactSupportState = "logical"
  FactSupportStatedAndLogical FactSupportState = "stated_and_logical"
  FactSupportMetadataOnly     FactSupportState = "metadata_only"
)

FactTarget

FactTarget names the facts a condition matches.

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

DynamicFact

DynamicFact builds a target matching dynamic facts with name.

func DynamicFact(name string) FactTarget

DynamicFactIn

DynamicFactIn builds a target matching dynamic facts in module.

func DynamicFactIn(module ModuleName, name string) FactTarget

TemplateFact

TemplateFact builds a target matching facts of the named template.

func TemplateFact(name string) FactTarget

TemplateFactIn

TemplateFactIn builds a target matching facts of the named template in module.

func TemplateFactIn(module ModuleName, name string) FactTarget

TemplateKeyFact

TemplateKeyFact builds a target matching facts of the template key.

func TemplateKeyFact(key TemplateKey) FactTarget

FactTarget.Kind

func (t FactTarget) Kind() FactTargetKind

FactTarget.Normalized

Normalized returns t with trimmed names and inferred kind where possible.

func (t FactTarget) Normalized() FactTarget

FactTarget.Ref

func (t FactTarget) Ref() NameRef

FactTarget.TemplateKey

func (t FactTarget) TemplateKey() TemplateKey

FactTargetKind

FactTargetKind identifies what kind of fact a FactTarget matches.

type FactTargetKind uint8

FactTargetUnknown, FactTargetDynamic, FactTargetTemplate, FactTargetTemplateKey

const (
  FactTargetUnknown FactTargetKind = iota
  FactTargetDynamic
  FactTargetTemplate
  FactTargetTemplateKey
)

FactVersion

FactVersion advances each time a fact is modified; a fact’s FactID stays stable across modifies within a generation.

type FactVersion uint32

FieldChange

FieldChange describes one field’s before and after value.

type FieldChange struct {
  Field string
  Old   Value
  New   Value
}

CloneFieldChange

CloneFieldChange returns a defensive copy of change.

func CloneFieldChange(change FieldChange) FieldChange

CloneFieldChanges

CloneFieldChanges returns a defensive copy of changes.

func CloneFieldChanges(changes []FieldChange) []FieldChange

FieldConstraint

FieldConstraint is the compiled, inspectable form of a FieldConstraintSpec.

type FieldConstraint struct {
  Field    string
  Path     PathSpec
  Operator FieldConstraintOperator
  Value    Value
}

CloneFieldConstraint

CloneFieldConstraint returns a defensive copy of c.

func CloneFieldConstraint(c FieldConstraint) FieldConstraint

FieldConstraintOperator

FieldConstraintOperator is the comparison a FieldConstraintSpec applies.

type FieldConstraintOperator string

FieldConstraintSpec

FieldConstraintSpec constrains one field, or nested path, of a matched fact.

type FieldConstraintSpec struct {
  Field    string
  Path     PathSpec
  Operator FieldConstraintOperator
  Value    any
}

CloneFieldConstraintSpec

CloneFieldConstraintSpec returns a defensive copy of s.

func CloneFieldConstraintSpec(s FieldConstraintSpec) FieldConstraintSpec

FieldPresence

FieldPresence reports how a field came to have its value.

type FieldPresence string

FieldPresenceOmitted, FieldPresenceDefault, FieldPresenceExplicit

const (
  FieldPresenceOmitted  FieldPresence = "omitted"
  FieldPresenceDefault  FieldPresence = "default"
  FieldPresenceExplicit FieldPresence = "explicit"
)

FieldRef

FieldRef names a field, or nested path, of an earlier binding.

type FieldRef struct {
  Binding string
  Field   string
  Path    PathSpec
}

CloneFieldRef

CloneFieldRef returns a defensive copy of r.

func CloneFieldRef(r FieldRef) FieldRef

FieldSpec

FieldSpec declares one template field: its name, kind, whether it’s required, an optional default, and an optional closed set of allowed values.

type FieldSpec struct {
  Name          string
  Kind          ValueKind
  Required      bool
  Default       any
  HasDefault    bool
  AllowedValues []any
}

CloneFieldSpec

CloneFieldSpec returns a defensive copy of field.

func CloneFieldSpec(field FieldSpec) FieldSpec

CloneFieldSpecs

CloneFieldSpecs returns a defensive copy of fields.

func CloneFieldSpecs(fields []FieldSpec) []FieldSpec

Fields

type Fields map[string]Value

CloneFields

CloneFields returns a defensive copy of fields.

func CloneFields(in Fields) Fields

MustFields

MustFields builds fields from alternating string keys and raw values, panicking when the inputs cannot be converted.

func MustFields(pairs ...any) Fields

NewFields

func NewFields(raw map[string]any) (Fields, error)

NewFieldsFromPairs

NewFieldsFromPairs builds fields from alternating string keys and raw values.

func NewFieldsFromPairs(pairs ...any) (Fields, error)

NormalizeFields

NormalizeFields returns fields in canonical immutable form.

func NormalizeFields(fields Fields) Fields

Fields.DuplicateKey

DuplicateKey returns a deterministic duplicate key for fields.

func (f Fields) DuplicateKey() string

Fields.Equal

func (f Fields) Equal(other Fields) bool

ForallCondition

ForallCondition tests whether every tuple matching Domain also satisfies Requirement.

type ForallCondition struct {
  Domain      ConditionSpec
  Requirement ConditionSpec
  Source      SourceSpan
}

Forall

Forall builds a ForallCondition.

func Forall(domain ConditionSpec, requirement ConditionSpec) ForallCondition

FunctionEvaluationError

FunctionEvaluationError reports a pure function that panicked, returned an error, or returned a value of the wrong kind.

type FunctionEvaluationError struct {
  RuleName       string
  QueryName      string
  ConditionIndex int
  PredicateIndex int
  FunctionName   string
  Source         SourceSpan
  Err            error
}

*FunctionEvaluationError.Error

func (e *FunctionEvaluationError) Error() string

*FunctionEvaluationError.Is

func (e *FunctionEvaluationError) Is(target error) bool

*FunctionEvaluationError.Unwrap

func (e *FunctionEvaluationError) Unwrap() error

Generation

Generation is the working-memory reset epoch.

type Generation uint64

Global

Global is the compiled, inspectable form of a GlobalSpec.

type Global struct {
  NameValue       string
  KindValue       ValueKind
  DefaultValue    Value
  HasDefaultValue bool
  DescriptionText string
  Order           int
}

CloneGlobal

CloneGlobal returns a defensive copy of g.

func CloneGlobal(g Global) Global

Global.DeclarationOrder

func (g Global) DeclarationOrder() int

Global.Default

func (g Global) Default() (Value, bool)

Global.Description

func (g Global) Description() string

Global.Kind

func (g Global) Kind() ValueKind

Global.Name

func (g Global) Name() string

GlobalExpr

GlobalExpr references a declared session global.

type GlobalExpr struct {
  Name string
}

GlobalValue

GlobalValue builds an expression reading the named session global.

func GlobalValue(name string) GlobalExpr

GlobalSpec

GlobalSpec declares a named, typed global with an optional default value.

type GlobalSpec struct {
  Name        string
  Kind        ValueKind
  Default     any
  HasDefault  bool
  Description string
}

CloneGlobalSpec

CloneGlobalSpec returns a defensive copy of s.

func CloneGlobalSpec(s GlobalSpec) GlobalSpec

HasPathExpr

HasPathExpr evaluates to true when Path resolves to a present value on the current fact.

type HasPathExpr struct {
  Path PathSpec
}

HasPath

HasPath builds a HasPathExpr testing whether path resolves to a present value on the current fact.

func HasPath(path PathSpec) HasPathExpr

JoinConstraint

JoinConstraint is the compiled, inspectable form of a JoinConstraintSpec.

type JoinConstraint struct {
  Field    string
  Path     PathSpec
  Operator FieldConstraintOperator
  Ref      FieldRef
}

CloneJoinConstraint

CloneJoinConstraint returns a defensive copy of c.

func CloneJoinConstraint(c JoinConstraint) JoinConstraint

JoinConstraintSpec

JoinConstraintSpec compares a field of the matched fact against a field of an earlier binding named by Ref.

type JoinConstraintSpec struct {
  Field    string
  Path     PathSpec
  Operator FieldConstraintOperator
  Ref      FieldRef
}

CloneJoinConstraintSpec

CloneJoinConstraintSpec returns a defensive copy of s.

func CloneJoinConstraintSpec(s JoinConstraintSpec) JoinConstraintSpec

ListPatternElement

ListPatternElement is the compiled, inspectable form of a ListPatternElementSpec.

type ListPatternElement struct {
  KindValue      ListPatternElementKind
  ExpressionSpec ExpressionSpec
  BindingName    string
  Order          int
}

CloneListPatternElement

CloneListPatternElement returns a defensive copy of e.

func CloneListPatternElement(e ListPatternElement) ListPatternElement

ListPatternElement.Binding

func (e ListPatternElement) Binding() string

ListPatternElement.DeclarationOrder

func (e ListPatternElement) DeclarationOrder() int

ListPatternElement.Expression

func (e ListPatternElement) Expression() ExpressionSpec

ListPatternElement.Kind

func (e ListPatternElement) Kind() ListPatternElementKind

ListPatternElementKind

ListPatternElementKind identifies one element of a ListPatternSpec.

type ListPatternElementKind string

ListPatternElementUnknown, ListPatternElementValue, ListPatternElementWildcard, ListPatternElementSegment, ListPatternElementRestWildcard

const (
  ListPatternElementUnknown      ListPatternElementKind = ""
  ListPatternElementValue        ListPatternElementKind = "value"
  ListPatternElementWildcard     ListPatternElementKind = "wildcard"
  ListPatternElementSegment      ListPatternElementKind = "segment"
  ListPatternElementRestWildcard ListPatternElementKind = "rest-wildcard"
)

ListPatternElementSpec

ListPatternElementSpec is one element of a ListPatternSpec.

type ListPatternElementSpec struct {
  Kind       ListPatternElementKind
  Expression ExpressionSpec
  Binding    string
}

CloneListPatternElementSpec

CloneListPatternElementSpec returns a defensive copy of s.

func CloneListPatternElementSpec(s ListPatternElementSpec) ListPatternElementSpec

ListElem

ListElem builds a fixed-position list pattern element.

func ListElem(expression ExpressionSpec) ListPatternElementSpec

ListRestWildcard

ListRestWildcard builds a list pattern element matching a variable-length run without capturing it.

func ListRestWildcard() ListPatternElementSpec

ListSegment

ListSegment builds a list pattern element matching a variable-length run.

func ListSegment(binding string) ListPatternElementSpec

ListWildcard

ListWildcard builds a list pattern element matching any one element.

func ListWildcard() ListPatternElementSpec

ListPatternSpec

ListPatternSpec is a structural pattern over a LIST-typed field.

type ListPatternSpec struct {
  Path     PathSpec
  Elements []ListPatternElementSpec
}

CloneListPatternSpec

CloneListPatternSpec returns a defensive copy of s.

func CloneListPatternSpec(s ListPatternSpec) ListPatternSpec

ListPattern

ListPattern builds a ListPatternSpec matching elements positionally against the LIST-typed field at path.

func ListPattern(path PathSpec, elements ...ListPatternElementSpec) ListPatternSpec

Match

Match is a positive fact match condition tree node.

type Match RuleConditionSpec

CloneMatch

CloneMatch returns a defensive copy of s.

func CloneMatch(s Match) Match

ModifyResult

ModifyResult reports the outcome of a modify.

type ModifyResult struct {
  Status ModifyStatus
  Fact   FactSnapshot
  Delta  *MutationDelta
}

CloneModifyResult

CloneModifyResult returns a defensive copy of result.

func CloneModifyResult(result ModifyResult) ModifyResult

ModifyResult.Changed

Changed reports whether the modify changed the fact.

func (r ModifyResult) Changed() bool

ModifyStatus

ModifyStatus is the outcome of a modify call.

type ModifyStatus string

ModifyChanged, ModifyNoOp, ModifyMissing, ModifyStale, ModifyValidationFailure, ModifyDuplicate, ModifyLogicalSupport, ModifyClosed, ModifyConcurrencyMisuse

const (
  ModifyChanged           ModifyStatus = "changed"
  ModifyNoOp              ModifyStatus = "no_op"
  ModifyMissing           ModifyStatus = "missing"
  ModifyStale             ModifyStatus = "stale"
  ModifyValidationFailure ModifyStatus = "validation_failure"
  ModifyDuplicate         ModifyStatus = "duplicate"
  ModifyLogicalSupport    ModifyStatus = "logical_support"
  ModifyClosed            ModifyStatus = "closed"
  ModifyConcurrencyMisuse ModifyStatus = "concurrency_misuse"
)

Module

Module is the compiled, inspectable form of a ModuleSpec.

type Module struct {
  NameValue       ModuleName
  DescriptionText string
  AutoFocusValue  *bool
}

CloneModule

CloneModule returns a defensive copy of m.

func CloneModule(m Module) Module

Module.AutoFocusDefault

func (m Module) AutoFocusDefault() (bool, bool)

Module.Description

func (m Module) Description() string

Module.Name

func (m Module) Name() ModuleName

ModuleName

ModuleName identifies a module. The zero value renders as MAIN, the default module.

type ModuleName string

MainModule

const MainModule ModuleName = "MAIN"

ModuleName.IsZero

func (name ModuleName) IsZero() bool

ModuleName.String

func (name ModuleName) String() string

ModuleSpec

ModuleSpec declares a module: its Name and optional default focus behavior.

type ModuleSpec struct {
  Name        ModuleName
  Description string
  AutoFocus   *bool
}

CloneModuleSpec

CloneModuleSpec returns a defensive copy of s.

func CloneModuleSpec(s ModuleSpec) ModuleSpec

ModuleSpecFromModule

ModuleSpecFromModule returns a ModuleSpec equivalent to m.

func ModuleSpecFromModule(m Module) ModuleSpec

MutationDelta

MutationDelta describes one mutation’s effect.

type MutationDelta struct {
  Kind           MutationKind
  Generation     Generation
  OldGeneration  Generation
  ActivationID   ActivationID
  RuleID         RuleID
  RuleRevisionID RuleRevisionID
  SupportBefore  FactSupportProvenance
  SupportAfter   FactSupportProvenance
  Recency        Recency
  FactID         FactID
  OldVersion     FactVersion
  NewVersion     FactVersion
  Before         *FactSnapshot
  After          *FactSnapshot
  OldDuplicate   DuplicateKey
  NewDuplicate   DuplicateKey
  ChangedFields  []FieldChange
}

CloneMutationDelta

CloneMutationDelta returns a defensive copy of delta.

func CloneMutationDelta(delta MutationDelta) MutationDelta

CloneMutationDeltaPtr

CloneMutationDeltaPtr returns a defensive copy of delta when non-nil.

func CloneMutationDeltaPtr(delta *MutationDelta) *MutationDelta

MutationDelta.FieldChanges

FieldChanges returns a cloned copy of changed fields.

func (d MutationDelta) FieldChanges() []FieldChange

MutationKind

MutationKind is the kind of change recorded in a MutationDelta.

type MutationKind string

MutationAssert, MutationModify, MutationRetract, MutationReset

const (
  MutationAssert  MutationKind = "assert"
  MutationModify  MutationKind = "modify"
  MutationRetract MutationKind = "retract"
  MutationReset   MutationKind = "reset"
)

NameRef

NameRef is an unresolved reference to a named definition.

type NameRef struct {
  Module ModuleName
  Name   string
}

ModuleRef

ModuleRef builds a NameRef explicitly qualified to module.

func ModuleRef(module ModuleName, name string) NameRef

Ref

Ref builds an unqualified NameRef.

func Ref(name string) NameRef

Not

Not negates a condition tree node.

type Not struct {
  Condition ConditionSpec
  Source    SourceSpan
}

Or

Or groups condition tree branches into a disjunction.

type Or struct {
  Conditions []ConditionSpec
  Source     SourceSpan
}

ParamExpr

ParamExpr references a named query parameter.

type ParamExpr struct {
  Name string
}

PathSegment

PathSegment is one step of a PathSpec.

type PathSegment struct {
  Kind  PathSegmentKind
  Key   string
  Index int
}

ListIndex

ListIndex builds a list-index path segment.

func ListIndex(index int) PathSegment

MapKey

MapKey builds a map-key path segment.

func MapKey(key string) PathSegment

PathSegmentKind

PathSegmentKind identifies one step of a PathSpec.

type PathSegmentKind string

PathSegmentRoot, PathSegmentMap, PathSegmentIndex

const (
  PathSegmentRoot  PathSegmentKind = "root"
  PathSegmentMap   PathSegmentKind = "map"
  PathSegmentIndex PathSegmentKind = "index"
)

PathSpec

PathSpec describes a path into a structured value.

type PathSpec struct {
  Segments []PathSegment
}

Path

Path builds a PathSpec rooted at the field root, followed by segments.

func Path(root string, segments ...PathSegment) PathSpec

PathSpec.String

func (p PathSpec) String() string

PureFunction

PureFunction is a deterministic, side-effect-free function implementation available to condition and query expressions.

type PureFunction func(context.Context, []Value) (Value, error)

PureFunction0

PureFunction0 is a fixed-arity PureFunction taking no arguments.

type PureFunction0 func(context.Context) (Value, error)

PureFunction1

PureFunction1 is a fixed-arity PureFunction taking one argument.

type PureFunction1 func(context.Context, Value) (Value, error)

PureFunction2

PureFunction2 is a fixed-arity PureFunction taking two arguments.

type PureFunction2 func(context.Context, Value, Value) (Value, error)

PureFunction3

PureFunction3 is a fixed-arity PureFunction taking three arguments.

type PureFunction3 func(context.Context, Value, Value, Value) (Value, error)

PureFunctionDefinition

PureFunctionDefinition is the compiled, inspectable form of a PureFunctionSpec or ExpressionFunctionSpec.

type PureFunctionDefinition struct {
  NameValue               string
  ParamNamesValue         []string
  ArgsValue               []ValueKind
  ReturnKind              ValueKind
  DescriptionText         string
  ExpressionSpec          ExpressionSpec
  ExpressionBackedValue   bool
  Order                   int
  EqualityComparatorValue bool
  IndexKeyExtractorValue  bool
}

ClonePureFunctionDefinition

ClonePureFunctionDefinition returns a defensive copy of f.

func ClonePureFunctionDefinition(f PureFunctionDefinition) PureFunctionDefinition

PureFunctionDefinition.Args

func (f PureFunctionDefinition) Args() []ValueKind

PureFunctionDefinition.DeclarationOrder

func (f PureFunctionDefinition) DeclarationOrder() int

PureFunctionDefinition.Description

func (f PureFunctionDefinition) Description() string

PureFunctionDefinition.EqualityComparator

func (f PureFunctionDefinition) EqualityComparator() bool

PureFunctionDefinition.Expression

func (f PureFunctionDefinition) Expression() (ExpressionSpec, bool)

PureFunctionDefinition.ExpressionBacked

func (f PureFunctionDefinition) ExpressionBacked() bool

PureFunctionDefinition.IndexKeyExtractor

func (f PureFunctionDefinition) IndexKeyExtractor() bool

PureFunctionDefinition.Name

func (f PureFunctionDefinition) Name() string

PureFunctionDefinition.ParamNames

func (f PureFunctionDefinition) ParamNames() []string

PureFunctionDefinition.Return

func (f PureFunctionDefinition) Return() ValueKind

PureFunctionSpec

PureFunctionSpec registers a pure function by Name, its Args and Return value kinds, and exactly one implementation function.

type PureFunctionSpec struct {
  Name               string
  Args               []ValueKind
  Return             ValueKind
  Func               PureFunction
  Func0              PureFunction0
  Func1              PureFunction1
  Func2              PureFunction2
  Func3              PureFunction3
  EqualityComparator bool
  IndexKeyExtractor  bool
}

ClonePureFunctionSpec

ClonePureFunctionSpec returns a defensive copy of s.

func ClonePureFunctionSpec(s PureFunctionSpec) PureFunctionSpec

QualifiedName

QualifiedName is a module-qualified name, rendered as “MODULE.Name”.

type QualifiedName struct {
  Module ModuleName
  Name   string
}

QualifiedName.String

func (n QualifiedName) String() string

Query

Query is the compiled, inspectable form of a QuerySpec.

type Query struct {
  NameValue                      string
  ModuleValue                    ModuleName
  DescriptionText                string
  SourceSpan                     SourceSpan
  GessSourceText                 string
  ParameterValues                []QueryParameter
  ConditionValues                []RuleCondition
  ConditionTreeValue             RuleConditionTree
  ConditionBranchValues          []RuleConditionBranch
  ConditionBranchesTruncatedFlag bool
  ReturnValues                   []QueryReturn
}

CloneQuery

CloneQuery returns a defensive copy of q.

func CloneQuery(q Query) Query

Query.ConditionBranches

func (q Query) ConditionBranches() []RuleConditionBranch

Query.ConditionBranchesTruncated

ConditionBranchesTruncated reports whether ConditionBranches is a bounded inspection prefix rather than the complete Cartesian expansion.

func (q Query) ConditionBranchesTruncated() bool

Query.ConditionTree

func (q Query) ConditionTree() RuleConditionTree

Query.Conditions

func (q Query) Conditions() []RuleCondition

Query.Description

func (q Query) Description() string

Query.GessSource

func (q Query) GessSource() string

Query.Module

func (q Query) Module() ModuleName

Query.Name

func (q Query) Name() string

Query.Parameters

func (q Query) Parameters() []QueryParameter

Query.Returns

func (q Query) Returns() []QueryReturn

Query.Source

func (q Query) Source() SourceSpan

QueryParameter

QueryParameter is the compiled, inspectable form of a QueryParameterSpec.

type QueryParameter struct {
  NameValue string
  KindValue ValueKind
  Order     int
}

CloneQueryParameters

CloneQueryParameters returns a defensive copy of parameters.

func CloneQueryParameters(parameters []QueryParameter) []QueryParameter

QueryParameter.DeclarationOrder

func (p QueryParameter) DeclarationOrder() int

QueryParameter.Kind

func (p QueryParameter) Kind() ValueKind

QueryParameter.Name

func (p QueryParameter) Name() string

QueryParameterSpec

QueryParameterSpec declares one named, typed query parameter.

type QueryParameterSpec struct {
  Name string
  Kind ValueKind
}

CloneQueryParameterSpec

CloneQueryParameterSpec returns a defensive copy of s.

func CloneQueryParameterSpec(s QueryParameterSpec) QueryParameterSpec

QueryReturn

QueryReturn is the compiled, inspectable form of a QueryReturnSpec.

type QueryReturn struct {
  AliasValue     string
  BindingName    string
  ExpressionSpec ExpressionSpec
  FactValue      bool
  Order          int
  SourceSpan     SourceSpan
}

CloneQueryReturn

CloneQueryReturn returns a defensive copy of r.

func CloneQueryReturn(r QueryReturn) QueryReturn

CloneQueryReturns

CloneQueryReturns returns a defensive copy of returns.

func CloneQueryReturns(returns []QueryReturn) []QueryReturn

QueryReturn.Alias

func (r QueryReturn) Alias() string

QueryReturn.Binding

func (r QueryReturn) Binding() string

QueryReturn.DeclarationOrder

func (r QueryReturn) DeclarationOrder() int

QueryReturn.Expression

func (r QueryReturn) Expression() ExpressionSpec

QueryReturn.Fact

func (r QueryReturn) Fact() bool

QueryReturn.Source

func (r QueryReturn) Source() SourceSpan

QueryReturnSpec

QueryReturnSpec declares one named query result column.

type QueryReturnSpec struct {
  Alias      string
  Binding    string
  Expression ExpressionSpec
  Source     SourceSpan
}

CloneQueryReturnSpec

CloneQueryReturnSpec returns a defensive copy of s.

func CloneQueryReturnSpec(s QueryReturnSpec) QueryReturnSpec

ReturnFact

ReturnFact builds a QueryReturnSpec returning the whole fact bound to binding under alias.

func ReturnFact(alias, binding string) QueryReturnSpec

ReturnValue

ReturnValue builds a QueryReturnSpec returning expression under alias.

func ReturnValue(alias string, expression ExpressionSpec) QueryReturnSpec

QuerySpec

QuerySpec defines a named query.

type QuerySpec struct {
  Name          string
  Module        ModuleName
  Description   string
  Source        SourceSpan
  GessSource    string
  Parameters    []QueryParameterSpec
  Conditions    []RuleConditionSpec
  ConditionTree ConditionSpec
  Returns       []QueryReturnSpec
}

CloneQuerySpec

CloneQuerySpec returns a defensive copy of s.

func CloneQuerySpec(s QuerySpec) QuerySpec

RHSBindExpr

RHSBindExpr references a right-hand-side local variable created by a bind action earlier in the same rule firing.

type RHSBindExpr struct {
  Name string
}

Recency

Recency is a session-wide counter that advances on every fact mutation.

type Recency uint32

ResetStatus

ResetStatus is the outcome of a reset.

type ResetStatus string

ResetApplied, ResetValidationFailure, ResetClosed, ResetConcurrencyMisuse

const (
  ResetApplied           ResetStatus = "applied"
  ResetValidationFailure ResetStatus = "validation_failure"
  ResetClosed            ResetStatus = "closed"
  ResetConcurrencyMisuse ResetStatus = "concurrency_misuse"
)

RetractResult

RetractResult reports the outcome of a retract.

type RetractResult struct {
  Status RetractStatus
  Fact   FactSnapshot
  Delta  *MutationDelta
}

CloneRetractResult

CloneRetractResult returns a defensive copy of result.

func CloneRetractResult(result RetractResult) RetractResult

RetractResult.Removed

Removed reports whether the retract removed the fact.

func (r RetractResult) Removed() bool

RetractStatus

RetractStatus is the outcome of a retract call.

type RetractStatus string

RetractRemoved, RetractStatedSupportRemoved, RetractLogicalOnly, RetractMissing, RetractStale, RetractClosed, RetractValidationFailure, RetractConcurrencyMisuse

const (
  RetractRemoved              RetractStatus = "removed"
  RetractStatedSupportRemoved RetractStatus = "stated_support_removed"
  RetractLogicalOnly          RetractStatus = "logical_only"
  RetractMissing              RetractStatus = "missing"
  RetractStale                RetractStatus = "stale"
  RetractClosed               RetractStatus = "closed"
  RetractValidationFailure    RetractStatus = "validation_failure"
  RetractConcurrencyMisuse    RetractStatus = "concurrency_misuse"
)

Rule

Rule is the compiled, inspectable form of a RuleSpec.

type Rule struct {
  IDValue                        RuleID
  RevisionIDValue                RuleRevisionID
  NameValue                      string
  ModuleValue                    ModuleName
  DescriptionText                string
  TagValues                      []string
  SalienceValue                  int
  AutoFocusValue                 bool
  HasAutoFocus                   bool
  EffectiveAutoFocusFlag         bool
  Order                          int
  SourceSpan                     SourceSpan
  GessSourceText                 string
  ConditionValues                []RuleCondition
  ConditionTreeValue             RuleConditionTree
  ConditionBranchValues          []RuleConditionBranch
  ConditionBranchesTruncatedFlag bool
  ActionValues                   []RuleAction
}

CloneRule

CloneRule returns a defensive copy of r.

func CloneRule(r Rule) Rule

CloneRules

CloneRules returns a defensive copy of rules.

func CloneRules(rules []Rule) []Rule

Rule.Actions

func (r Rule) Actions() []RuleAction

Rule.AutoFocus

func (r Rule) AutoFocus() (bool, bool)

Rule.ConditionBranches

func (r Rule) ConditionBranches() []RuleConditionBranch

Rule.ConditionBranchesTruncated

ConditionBranchesTruncated reports whether ConditionBranches is a bounded inspection prefix rather than the complete Cartesian expansion.

func (r Rule) ConditionBranchesTruncated() bool

Rule.ConditionTree

func (r Rule) ConditionTree() RuleConditionTree

Rule.Conditions

func (r Rule) Conditions() []RuleCondition

Rule.DeclarationOrder

func (r Rule) DeclarationOrder() int

Rule.Description

func (r Rule) Description() string

Rule.EffectiveAutoFocus

func (r Rule) EffectiveAutoFocus() bool

Rule.GessSource

func (r Rule) GessSource() string

Rule.ID

func (r Rule) ID() RuleID

Rule.Module

func (r Rule) Module() ModuleName

Rule.Name

func (r Rule) Name() string

Rule.RevisionID

func (r Rule) RevisionID() RuleRevisionID

Rule.Salience

func (r Rule) Salience() int

Rule.Source

func (r Rule) Source() SourceSpan

Rule.Tags

func (r Rule) Tags() []string

RuleAction

RuleAction is a compiled, inspectable action reference on a rule.

type RuleAction struct {
  NameValue  string
  Order      int
  SourceSpan SourceSpan
}

CloneRuleAction

CloneRuleAction returns a defensive copy of a.

func CloneRuleAction(a RuleAction) RuleAction

CloneRuleActions

CloneRuleActions returns a defensive copy of actions.

func CloneRuleActions(actions []RuleAction) []RuleAction

RuleAction.DeclarationOrder

func (a RuleAction) DeclarationOrder() int

RuleAction.Name

func (a RuleAction) Name() string

RuleAction.Source

func (a RuleAction) Source() SourceSpan

RuleActionSpec

RuleActionSpec references, by Name, an action registered on the workspace.

type RuleActionSpec struct {
  Name   string
  Source SourceSpan
}

CloneRuleActionSpec

CloneRuleActionSpec returns a defensive copy of s.

func CloneRuleActionSpec(s RuleActionSpec) RuleActionSpec

RuleCondition

RuleCondition is the compiled, inspectable form of a fact match condition.

type RuleCondition struct {
  IDValue               ConditionID
  BindingName           string
  NameValue             string
  TemplateKeyValue      TemplateKey
  FieldConstraintValues []FieldConstraint
  ListPatternValues     []RuleListPattern
  JoinConstraintValues  []JoinConstraint
  PredicateValues       []ExpressionPredicate
  ExplicitValue         bool
  Order                 int
  SourceSpan            SourceSpan
}

CloneRuleCondition

CloneRuleCondition returns a defensive copy of c.

func CloneRuleCondition(c RuleCondition) RuleCondition

CloneRuleConditions

CloneRuleConditions returns a defensive copy of conditions.

func CloneRuleConditions(conditions []RuleCondition) []RuleCondition

RuleCondition.Binding

func (c RuleCondition) Binding() string

RuleCondition.DeclarationOrder

func (c RuleCondition) DeclarationOrder() int

RuleCondition.Explicit

func (c RuleCondition) Explicit() bool

RuleCondition.FieldConstraints

func (c RuleCondition) FieldConstraints() []FieldConstraint

RuleCondition.ID

func (c RuleCondition) ID() ConditionID

RuleCondition.JoinConstraints

func (c RuleCondition) JoinConstraints() []JoinConstraint

RuleCondition.ListPatterns

func (c RuleCondition) ListPatterns() []RuleListPattern

RuleCondition.Name

func (c RuleCondition) Name() string

RuleCondition.Predicates

func (c RuleCondition) Predicates() []ExpressionPredicate

RuleCondition.Source

func (c RuleCondition) Source() SourceSpan

RuleCondition.Target

func (c RuleCondition) Target() FactTarget

RuleCondition.TemplateKey

func (c RuleCondition) TemplateKey() TemplateKey

RuleConditionBranch

RuleConditionBranch is one compiled branch in a condition tree. Flat rules and tree rules without disjunction expose one branch. Disjunctive trees expose expanded alternatives in source order, bounded for structurally compiled programs; Rule.ConditionBranchesTruncated and Query.ConditionBranchesTruncated report whether the returned inspection is incomplete.

type RuleConditionBranch struct {
  IDValue         int
  ConditionValues []RuleConditionBranchCondition
}

CloneRuleConditionBranch

CloneRuleConditionBranch returns a defensive copy of b.

func CloneRuleConditionBranch(b RuleConditionBranch) RuleConditionBranch

CloneRuleConditionBranches

CloneRuleConditionBranches returns a defensive copy of branches.

func CloneRuleConditionBranches(branches []RuleConditionBranch) []RuleConditionBranch

RuleConditionBranch.Conditions

func (b RuleConditionBranch) Conditions() []RuleConditionBranchCondition

RuleConditionBranch.ID

func (b RuleConditionBranch) ID() int

RuleConditionBranchCondition

RuleConditionBranchCondition describes a condition within an expanded branch. Path is the authored condition-tree path, while Visible indicates whether the binding is exposed to actions. Negated conditions are local and not visible.

type RuleConditionBranchCondition struct {
  ConditionValue RuleCondition
  PathValue      []int
  VisibleValue   bool
  NegatedValue   bool
  ExplicitValue  bool
}

CloneRuleConditionBranchCondition

CloneRuleConditionBranchCondition returns a defensive copy of c.

func CloneRuleConditionBranchCondition(c RuleConditionBranchCondition) RuleConditionBranchCondition

CloneRuleConditionBranchConditions

CloneRuleConditionBranchConditions returns a defensive copy of conditions.

func CloneRuleConditionBranchConditions(conditions []RuleConditionBranchCondition) []RuleConditionBranchCondition

RuleConditionBranchCondition.Condition

func (c RuleConditionBranchCondition) Condition() RuleCondition

RuleConditionBranchCondition.Explicit

func (c RuleConditionBranchCondition) Explicit() bool

RuleConditionBranchCondition.Negated

func (c RuleConditionBranchCondition) Negated() bool

RuleConditionBranchCondition.Path

func (c RuleConditionBranchCondition) Path() []int

RuleConditionBranchCondition.Visible

func (c RuleConditionBranchCondition) Visible() bool

RuleConditionSpec

RuleConditionSpec is the field set behind a positive fact match condition.

type RuleConditionSpec struct {
  Binding string
  // SyntheticBinding marks a binding generated by a source loader rather
  // than authored by the user. User-facing diagnostics may omit its name.
  SyntheticBinding bool
  // Volatile is a compile-time planning hint that the matched fact is
  // expected to be modified frequently. The planner may place an otherwise
  // independent volatile match later in a branch to reduce propagation
  // churn. It does not change match semantics or revision identity.
  Volatile         bool
  Target           FactTarget
  FieldConstraints []FieldConstraintSpec
  ListPatterns     []ListPatternSpec
  JoinConstraints  []JoinConstraintSpec
  Predicates       []ExpressionSpec
  Source           SourceSpan
}

CloneRuleConditionSpec

CloneRuleConditionSpec returns a defensive copy of s.

func CloneRuleConditionSpec(s RuleConditionSpec) RuleConditionSpec

RuleConditionTree

RuleConditionTree is the compiled, inspectable condition tree for a rule or query.

type RuleConditionTree struct {
  KindValue      ConditionTreeKind
  ChildrenValue  []RuleConditionTree
  MatchCondition RuleCondition
  HasMatch       bool
  TestExpression ExpressionSpec
  HasTest        bool
  AggregateValue AccumulateCondition
  HasAggregate   bool
  SourceSpan     SourceSpan
}

CloneRuleConditionTree

CloneRuleConditionTree returns a defensive copy of t.

func CloneRuleConditionTree(t RuleConditionTree) RuleConditionTree

CloneRuleConditionTrees

CloneRuleConditionTrees returns a defensive copy of trees.

func CloneRuleConditionTrees(trees []RuleConditionTree) []RuleConditionTree

RuleConditionTree.Aggregate

func (t RuleConditionTree) Aggregate() (AccumulateCondition, bool)

RuleConditionTree.Children

func (t RuleConditionTree) Children() []RuleConditionTree

RuleConditionTree.Kind

func (t RuleConditionTree) Kind() ConditionTreeKind

RuleConditionTree.Match

func (t RuleConditionTree) Match() (RuleCondition, bool)

RuleConditionTree.Source

func (t RuleConditionTree) Source() SourceSpan

RuleConditionTree.Test

func (t RuleConditionTree) Test() (ExpressionSpec, bool)

RuleFieldConstraint

RuleFieldConstraint is an alias of FieldConstraint.

type RuleFieldConstraint = FieldConstraint

RuleFieldConstraintSpec

RuleFieldConstraintSpec is an alias of FieldConstraintSpec, used in rule-condition contexts.

type RuleFieldConstraintSpec = FieldConstraintSpec

RuleID

RuleID is a rule’s stable identity, surviving ReplaceRule.

type RuleID string

RuleID.IsZero

func (id RuleID) IsZero() bool

RuleID.String

func (id RuleID) String() string

RuleListPattern

RuleListPattern is the compiled, inspectable list pattern attached to a rule condition.

type RuleListPattern struct {
  PathSpec      PathSpec
  ElementsValue []ListPatternElement
  Order         int
}

CloneRuleListPattern

CloneRuleListPattern returns a defensive copy of p.

func CloneRuleListPattern(p RuleListPattern) RuleListPattern

CloneRuleListPatterns

CloneRuleListPatterns returns a defensive copy of patterns.

func CloneRuleListPatterns(patterns []RuleListPattern) []RuleListPattern

RuleListPattern.DeclarationOrder

func (p RuleListPattern) DeclarationOrder() int

RuleListPattern.Elements

func (p RuleListPattern) Elements() []ListPatternElement

RuleListPattern.Path

func (p RuleListPattern) Path() PathSpec

RuleRevisionID

RuleRevisionID identifies one compiled revision of a rule.

type RuleRevisionID string

RuleRevisionID.IsZero

func (id RuleRevisionID) IsZero() bool

RuleRevisionID.String

func (id RuleRevisionID) String() string

RuleSpec

RuleSpec defines a rule.

type RuleSpec struct {
  Name        string
  Module      ModuleName
  ID          RuleID
  Description string
  Source      SourceSpan
  GessSource  string
  Tags        []string
  Salience    int
  AutoFocus   *bool
  // Conditions is the flat positive conjunction form. When ConditionTree is
  // nil, compile normalizes Conditions to And(Match...) without changing
  // condition ordering, condition identity, graph topology, or agenda behavior.
  Conditions []RuleConditionSpec
  // ConditionTree is the structured left-hand side form. It is mutually
  // exclusive with Conditions in one RuleSpec.
  ConditionTree ConditionSpec
  Actions       []RuleActionSpec
}

CloneRuleSpec

CloneRuleSpec returns a defensive copy of s.

func CloneRuleSpec(s RuleSpec) RuleSpec

Ruleset

Ruleset is an immutable compiled ruleset facade. Its implementation is owned by the engine through a RulesetHandle.

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

Compile

Compile compiles workspace into an immutable Ruleset, equivalent to calling workspace.Compile directly.

func Compile(ctx context.Context, workspace *Workspace) (*Ruleset, error)

NewRuleset

NewRuleset returns a public Ruleset backed by handle.

func NewRuleset(handle RulesetHandle) *Ruleset

*Ruleset.Action

func (r *Ruleset) Action(name string) (Action, bool)

*Ruleset.Actions

func (r *Ruleset) Actions() []Action

*Ruleset.Function

func (r *Ruleset) Function(name string) (PureFunctionDefinition, bool)

*Ruleset.Functions

func (r *Ruleset) Functions() []PureFunctionDefinition

*Ruleset.Global

func (r *Ruleset) Global(name string) (Global, bool)

*Ruleset.Globals

func (r *Ruleset) Globals() []Global

*Ruleset.ID

func (r *Ruleset) ID() RulesetID

*Ruleset.Module

func (r *Ruleset) Module(name ModuleName) (Module, bool)

*Ruleset.Modules

func (r *Ruleset) Modules() []Module

*Ruleset.Queries

func (r *Ruleset) Queries() []Query

*Ruleset.Query

func (r *Ruleset) Query(name string) (Query, bool)

*Ruleset.Rule

func (r *Ruleset) Rule(name string) (Rule, bool)

*Ruleset.RuleByID

func (r *Ruleset) RuleByID(id RuleID) (Rule, bool)

*Ruleset.RuleByRevisionID

func (r *Ruleset) RuleByRevisionID(id RuleRevisionID) (Rule, bool)

*Ruleset.Rules

func (r *Ruleset) Rules() []Rule

*Ruleset.Template

func (r *Ruleset) Template(name string) (Template, bool)

*Ruleset.TemplateByKey

func (r *Ruleset) TemplateByKey(key TemplateKey) (Template, bool)

*Ruleset.Templates

func (r *Ruleset) Templates() []Template

RulesetHandle

RulesetHandle is the engine-owned implementation behind a public Ruleset. Implementations must return detached inspection values.

type RulesetHandle interface {
  ID() RulesetID
  Module(ModuleName) (Module, bool)
  Modules() []Module
  Template(string) (Template, bool)
  TemplateByKey(TemplateKey) (Template, bool)
  Templates() []Template
  Action(string) (Action, bool)
  Actions() []Action
  Function(string) (PureFunctionDefinition, bool)
  Functions() []PureFunctionDefinition
  Global(string) (Global, bool)
  Globals() []Global
  Rule(string) (Rule, bool)
  RuleByID(RuleID) (Rule, bool)
  RuleByRevisionID(RuleRevisionID) (Rule, bool)
  Rules() []Rule
  Query(string) (Query, bool)
  Queries() []Query
}

RulesetHandleOf

RulesetHandleOf returns the engine-owned implementation behind r.

func RulesetHandleOf(r *Ruleset) RulesetHandle

RulesetID

RulesetID identifies one compiled ruleset revision. It is derived from the ruleset’s declared shape: templates, rules, queries, globals, and the declared signatures of Go host functions and actions. Host function and action implementations do not contribute, so two rulesets differing only in their Go closures share the same RulesetID.

type RulesetID string

RulesetID.String

func (id RulesetID) String() string

RunID

RunID identifies one session Run call.

type RunID uint64

RunID.IsZero

func (id RunID) IsZero() bool

RunID.String

func (id RunID) String() string

RunStatus

RunStatus is the outcome of a Run.

type RunStatus string

RunCompleted, RunHalted, RunFireLimit, RunCanceled, RunActionFailed, RunClosed, RunConcurrencyMisuse, RunFailed

const (
  RunCompleted         RunStatus = "completed"
  RunHalted            RunStatus = "halted"
  RunFireLimit         RunStatus = "fire_limit"
  RunCanceled          RunStatus = "canceled"
  RunActionFailed      RunStatus = "action_failed"
  RunClosed            RunStatus = "closed"
  RunConcurrencyMisuse RunStatus = "concurrency_misuse"
  RunFailed            RunStatus = "failed"
)

SessionID

SessionID identifies a session.

type SessionID string

SessionID.String

func (id SessionID) String() string

SourceSpan

SourceSpan is a source location range within a .gess file, carried into compiled definitions and runtime errors for rulesets loaded from .gess source.

type SourceSpan struct {
  Name        string
  StartLine   int
  StartColumn int
  EndLine     int
  EndColumn   int
}

SourceSpan.String

String returns the source name and starting line/column.

func (s SourceSpan) String() string

SupportID

SupportID identifies one logical support edge.

type SupportID string

SupportID.IsZero

func (id SupportID) IsZero() bool

SupportID.String

func (id SupportID) String() string

Template

Template is the compiled, inspectable form of a TemplateSpec.

type Template struct {
  NameValue              string
  ModuleValue            ModuleName
  KeyValue               TemplateKey
  CompatibilityKeyValue  TemplateKey
  FieldValues            []FieldSpec
  DuplicatePolicyValue   DuplicatePolicy
  DuplicateKeyValues     []string
  BackchainReactiveValue bool
  BackchainDemandKey     TemplateKey
  BackchainDemandValue   bool
  BackchainSourceKey     TemplateKey
  SourceSpan             SourceSpan
  GessSourceText         string
}

CloneTemplate

CloneTemplate returns a defensive copy of t.

func CloneTemplate(t Template) Template

CloneTemplates

CloneTemplates returns a defensive copy of templates.

func CloneTemplates(templates []Template) []Template

Template.BackchainDemandTemplateKey

func (t Template) BackchainDemandTemplateKey() (TemplateKey, bool)

Template.BackchainReactive

func (t Template) BackchainReactive() bool

Template.BackchainSourceTemplateKey

func (t Template) BackchainSourceTemplateKey() (TemplateKey, bool)

Template.CompatibilityKey

func (t Template) CompatibilityKey() TemplateKey

Template.DuplicateKeys

func (t Template) DuplicateKeys() []string

Template.DuplicatePolicy

func (t Template) DuplicatePolicy() DuplicatePolicy

Template.Fields

func (t Template) Fields() []FieldSpec

Template.GessSource

func (t Template) GessSource() string

Template.IsBackchainDemandTemplate

func (t Template) IsBackchainDemandTemplate() bool

Template.Key

func (t Template) Key() TemplateKey

Template.Module

func (t Template) Module() ModuleName

Template.Name

func (t Template) Name() string

Template.QualifiedName

func (t Template) QualifiedName() QualifiedName

Template.Source

func (t Template) Source() SourceSpan

TemplateKey

TemplateKey identifies a compiled template within a ruleset.

type TemplateKey string

TemplateKey.String

func (key TemplateKey) String() string

TemplateSpec

TemplateSpec declares a fact template: its name, module, key, fields, duplicate policy, and whether it’s backward-chaining reactive.

type TemplateSpec struct {
  Name              string
  Module            ModuleName
  Key               TemplateKey
  CompatibilityKey  TemplateKey
  Source            SourceSpan
  GessSource        string
  Fields            []FieldSpec
  DuplicatePolicy   DuplicatePolicy
  DuplicateKeyNames []string
  BackchainReactive bool
}

Test

Test evaluates a standalone boolean expression over earlier local bindings.

type Test struct {
  Expression ExpressionSpec
  Source     SourceSpan
}

ValidationError

ValidationError reports a definition that failed structural or compile-time validation.

type ValidationError struct {
  TemplateName       string
  RuleName           string
  FunctionName       string
  GlobalName         string
  Source             SourceSpan
  FieldName          string
  ConditionIndex     int
  HasConditionIndex  bool
  ConstraintIndex    int
  HasConstraintIndex bool
  PredicateIndex     int
  HasPredicateIndex  bool
  JoinIndex          int
  HasJoinIndex       bool
  ActionIndex        int
  HasActionIndex     bool
  Reason             string
  Err                error
}

*ValidationError.Error

func (e *ValidationError) Error() string

*ValidationError.Is

func (e *ValidationError) Is(target error) bool

*ValidationError.Unwrap

func (e *ValidationError) Unwrap() error

Value

Value is an immutable, typed field or expression value.

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

BoolValue

BoolValue returns a bool value.

func BoolValue(value bool) Value

CanonicalValue

CanonicalValue converts raw into a Value.

func CanonicalValue(raw any) (Value, error)

CloneValue

CloneValue returns a defensive copy of v.

func CloneValue(v Value) Value

CloneValueSlice

CloneValueSlice returns a defensive copy of in.

func CloneValueSlice(in []Value) []Value

FloatValue

FloatValue returns a float value.

func FloatValue(value float64) Value

IntValue

IntValue returns an integer value.

func IntValue(value int64) Value

NewValue

func NewValue(raw any) (Value, error)

NullValue

func NullValue() Value

StringValue

StringValue returns a string value.

func StringValue(value string) Value

Value.AsBool

AsBool returns the stored bool when the value kind is ValueBool.

func (v Value) AsBool() (bool, bool)

Value.AsFloat64

AsFloat64 returns the stored float when the value kind is ValueFloat.

func (v Value) AsFloat64() (float64, bool)

Value.AsInt64

AsInt64 returns the stored integer when the value kind is ValueInt.

func (v Value) AsInt64() (int64, bool)

Value.AsList

AsList returns a defensive copy of the stored list when the value kind is ValueList.

func (v Value) AsList() ([]Value, bool)

Value.AsListShared

AsListShared returns the value’s backing list without copying when the kind is ValueList. The returned slice aliases internal storage and must not be modified; use AsList for a defensive copy.

func (v Value) AsListShared() ([]Value, bool)

Value.AsMap

AsMap returns a defensive copy of the stored map when the value kind is ValueMap.

func (v Value) AsMap() (map[string]Value, bool)

Value.AsMapShared

AsMapShared returns the value’s backing map without copying when the kind is ValueMap. The returned map aliases internal storage and must not be modified; use AsMap for a defensive copy.

func (v Value) AsMapShared() (map[string]Value, bool)

Value.AsString

AsString returns the stored string when the value kind is ValueString.

func (v Value) AsString() (string, bool)

Value.CanonicalKey

CanonicalKey returns a deterministic key for duplicate detection and stable ordering.

func (v Value) CanonicalKey() string

Value.Equal

func (v Value) Equal(other Value) bool

Value.Kind

func (v Value) Kind() ValueKind

Value.ListAt

ListAt returns one list item when the value kind is ValueList.

func (v Value) ListAt(index int) (Value, bool)

Value.ListLen

ListLen returns the list length when the value kind is ValueList.

func (v Value) ListLen() (int, bool)

Value.MapGet

MapGet returns one map value when the value kind is ValueMap.

func (v Value) MapGet(key string) (Value, bool)

Value.RangeList

RangeList visits list items when the value kind is ValueList.

func (v Value) RangeList(fn func(int, Value) bool) bool

Value.RangeMap

RangeMap visits map entries when the value kind is ValueMap.

func (v Value) RangeMap(fn func(string, Value) bool) bool

Value.String

func (v Value) String() string

ValueKind

ValueKind is a Value’s type tag.

type ValueKind uint8

ValueAny, ValueNull, ValueBool, ValueInt, ValueFloat, ValueString, ValueList, ValueMap

const (
  ValueAny ValueKind
  ValueNull
  ValueBool
  ValueInt
  ValueFloat
  ValueString
  ValueList
  ValueMap
)

ValueKind.String

func (k ValueKind) String() string

WhyNotConditionReason

WhyNotConditionReason classifies why one condition did not extend a partial match.

type WhyNotConditionReason string

WhyNotReasonNone, WhyNotReasonNoAlphaMatches, WhyNotReasonJoinMismatch, WhyNotReasonPredicate, WhyNotReasonNegationBlocked

const (
  WhyNotReasonNone            WhyNotConditionReason = ""
  WhyNotReasonNoAlphaMatches  WhyNotConditionReason = "no_alpha_matches"
  WhyNotReasonJoinMismatch    WhyNotConditionReason = "join_mismatch"
  WhyNotReasonPredicate       WhyNotConditionReason = "predicate_rejected"
  WhyNotReasonNegationBlocked WhyNotConditionReason = "negation_blocked"
)

WhyNotOutcome

WhyNotOutcome is the top-level answer to “why has this rule not fired?”.

type WhyNotOutcome string

WhyNotActivated, WhyNotAlreadyFired, WhyNotNeverMatched, WhyNotBlocked

const (
  WhyNotActivated    WhyNotOutcome = "activated"
  WhyNotAlreadyFired WhyNotOutcome = "already_fired"
  WhyNotNeverMatched WhyNotOutcome = "never_matched"
  WhyNotBlocked      WhyNotOutcome = "blocked"
)

Workspace

Workspace is a mutable collection of module, template, action, function, rule, and query definitions. Definitions are validated as they’re added; Compile produces an immutable Ruleset.

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

NewWorkspaceWithHandle

NewWorkspaceWithHandle returns a Workspace backed by handle. Runtime packages use this constructor to make workspace ownership explicit while keeping rules independent of a concrete engine implementation.

func NewWorkspaceWithHandle(handle WorkspaceHandle) *Workspace

*Workspace.AddAction

func (w *Workspace) AddAction(spec ActionSpec) error

*Workspace.AddExpressionFunction

AddExpressionFunction registers a pure function whose body is a single expression over its declared parameters.

func (w *Workspace) AddExpressionFunction(spec ExpressionFunctionSpec) error

*Workspace.AddFunction

func (w *Workspace) AddFunction(spec PureFunctionSpec) error

*Workspace.AddGlobal

AddGlobal declares a typed global constant readable from rule, query, and aggregate expressions and from ActionContext.Global. Values bind per session via WithGlobals; a declaration without a default requires every session to supply a value. In .gess sources the equivalent form is (defglobal *name* (type KIND) (default value)).

func (w *Workspace) AddGlobal(spec GlobalSpec) error

*Workspace.AddModule

AddModule records a module declaration. Compile treats identical repeated declarations as idempotent and rejects conflicting metadata.

func (w *Workspace) AddModule(spec ModuleSpec) error

*Workspace.AddQuery

func (w *Workspace) AddQuery(spec QuerySpec) error

*Workspace.AddRule

func (w *Workspace) AddRule(spec RuleSpec) error

*Workspace.AddTemplate

func (w *Workspace) AddTemplate(spec TemplateSpec) error

*Workspace.Compile

Compile compiles workspace into an immutable Ruleset.

func (w *Workspace) Compile(ctx context.Context) (*Ruleset, error)

*Workspace.RemoveAction

func (w *Workspace) RemoveAction(name string) error

*Workspace.RemoveFunction

func (w *Workspace) RemoveFunction(name string) error

*Workspace.RemoveGlobal

func (w *Workspace) RemoveGlobal(name string) error

*Workspace.RemoveQuery

func (w *Workspace) RemoveQuery(name string) error

*Workspace.RemoveRule

func (w *Workspace) RemoveRule(name string) error

*Workspace.ReplaceAction

func (w *Workspace) ReplaceAction(spec ActionSpec) error

*Workspace.ReplaceFunction

func (w *Workspace) ReplaceFunction(spec PureFunctionSpec) error

*Workspace.ReplaceGlobal

func (w *Workspace) ReplaceGlobal(spec GlobalSpec) error

*Workspace.ReplaceQuery

func (w *Workspace) ReplaceQuery(spec QuerySpec) error

*Workspace.ReplaceRule

func (w *Workspace) ReplaceRule(spec RuleSpec) error

WorkspaceHandle

WorkspaceHandle is the engine-owned implementation behind a public Workspace.

type WorkspaceHandle interface {
  AddModule(ModuleSpec) error
  AddTemplate(TemplateSpec) error
  AddGlobal(GlobalSpec) error
  ReplaceGlobal(GlobalSpec) error
  RemoveGlobal(string) error
  AddAction(ActionSpec) error
  ReplaceAction(ActionSpec) error
  RemoveAction(string) error
  AddFunction(PureFunctionSpec) error
  AddExpressionFunction(ExpressionFunctionSpec) error
  ReplaceFunction(PureFunctionSpec) error
  RemoveFunction(string) error
  AddRule(RuleSpec) error
  ReplaceRule(RuleSpec) error
  RemoveRule(string) error
  AddQuery(QuerySpec) error
  ReplaceQuery(QuerySpec) error
  RemoveQuery(string) error
  Compile(context.Context) (*Ruleset, error)
}

WorkspaceHandleOf

WorkspaceHandleOf returns the engine-owned implementation behind w.

func WorkspaceHandleOf(w *Workspace) WorkspaceHandle

Functions

CompareValues

CompareValues compares string or numeric values.

func CompareValues(left, right Value) (int, bool)

DuplicateKeyValueCapacity

DuplicateKeyValueCapacity returns the expected encoded capacity for value.

func DuplicateKeyValueCapacity(value Value) int

EncodeValueForDuplicateKey

EncodeValueForDuplicateKey appends value’s deterministic duplicate-key representation.

func EncodeValueForDuplicateKey(b *strings.Builder, value Value)

FieldsShareable

FieldsShareable reports whether all field values can be shared without defensive cloning.

func FieldsShareable(fields Fields) bool

Int64Len

Int64Len returns the decimal byte length of value.

func Int64Len(value int64) int

ValueShareable

ValueShareable reports whether v can be shared without defensive cloning.

func ValueShareable(v Value) bool