README
¶
Checked execution IR
The ir package defines the production execution representation for Effectus.
The representation uses effectus/v1/ir.proto and contains no Go callbacks.
ir.Check validates a protobuf artifact against an immutable declaration environment.
ir.Parse treats stored or received protobuf bytes as untrusted input.
Both functions return an opaque ir.Checked value.
The checker validates these properties:
- Plan order follows list priority order, then flow priority order.
- Plan IDs and step IDs are unique.
- Step ordinals start at zero and have no gaps.
- Result slots start at zero and have no gaps.
- A result reference only uses a slot from an earlier step.
- Argument names are unique and use lexical order.
- Required and optional arguments follow the verb contract.
- Fact paths, verb contracts, functions, and types match the environment.
- Predicate functions are declared pure and total.
- Predicate results have the
booltype. - Literal, fact, and result values keep distinct protobuf variants.
- Structural and value limits apply before execution.
- Unknown protobuf fields cause rejection.
Use EnvironmentDigest for RuleArtifact.environment_digest.
Use ContractHash for each Step.contract_hash.
The checker recalculates both values and rejects a mismatch.
Use Checked.Marshal to store deterministic protobuf bytes.
Use Checked.Digest as the artifact content digest.
Checked.CloneArtifact returns an unchecked copy for inspection.
Pass a changed copy to Check before use.
Legacy flow.Program values and Go continuations are not valid checked IR.
Do not put them in a production generation.
Documentation
¶
Overview ¶
Package ir defines Effectus's callback-free, checked execution representation.
Index ¶
- Constants
- Variables
- func CanonicalPlanOrder(plans []*effectusv1.Plan)
- func ContractHash(contract VerbContract) (string, error)
- func EnvironmentDigest(environment Environment) (string, error)
- type Checked
- type Environment
- type FunctionContract
- type IdempotencyPolicy
- type Limits
- type RetryPolicy
- type TypeDefinition
- type TypeKind
- type VerbContract
Constants ¶
const FormatVersion uint32 = 1
FormatVersion is the only artifact format accepted by this package.
Variables ¶
var ( // ErrInvalidArtifact identifies a structural or semantic IR failure. ErrInvalidArtifact = errors.New("invalid checked IR artifact") // ErrLimitExceeded identifies a configured structural or value limit. ErrLimitExceeded = errors.New("checked IR limit exceeded") )
var DefaultLimits = Limits{
MaxArtifactBytes: 4 << 20,
MaxPlans: 1_000,
MaxSteps: 10_000,
MaxStepsPerPlan: 1_000,
MaxArgumentsPerStep: 128,
MaxPredicateNodes: 1_024,
MaxLiteralNodes: 10_000,
MaxDepth: 64,
MaxStringBytes: 1 << 20,
MaxBytesValue: 1 << 20,
MaxCollectionItems: 10_000,
MaxObjectFields: 1_024,
MaxTotalStringBytes: 4 << 20,
}
DefaultLimits are conservative production defaults.
Functions ¶
func CanonicalPlanOrder ¶
func CanonicalPlanOrder(plans []*effectusv1.Plan)
CanonicalPlanOrder sorts a mutable artifact into the only accepted plan order. Callers must still pass the result to Check.
func ContractHash ¶
func ContractHash(contract VerbContract) (string, error)
ContractHash returns the canonical SHA-256 digest of a verb contract.
func EnvironmentDigest ¶
func EnvironmentDigest(environment Environment) (string, error)
EnvironmentDigest returns the canonical SHA-256 digest used by artifacts.
Types ¶
type Checked ¶
type Checked struct {
// contains filtered or unexported fields
}
Checked is an opaque, immutable execution plan. It contains no callbacks.
func Check ¶
func Check(artifact *effectusv1.RuleArtifact, environment Environment, limits Limits) (*Checked, error)
Check validates an artifact and stores only its deterministic protobuf form. The input and environment may be mutated after this call without changing the returned Checked value.
func Parse ¶
func Parse(data []byte, environment Environment, limits Limits) (*Checked, error)
Parse decodes untrusted protobuf bytes and rechecks every reference.
func (*Checked) CloneArtifact ¶
func (c *Checked) CloneArtifact() *effectusv1.RuleArtifact
CloneArtifact returns a mutable copy for compatibility and inspection. The returned value is not checked state and must be passed through Check again.
type Environment ¶
type Environment struct {
Facts map[string]string `json:"facts"`
Verbs map[string]VerbContract `json:"verbs"`
Functions map[string]FunctionContract `json:"functions"`
Types map[string]TypeDefinition `json:"types"`
}
Environment is immutable input to checking. Check copies it before use. It contains declarations only; checking never calls executors or user code.
type FunctionContract ¶
type FunctionContract struct {
ArgumentTypes []string `json:"argument_types"`
ReturnType string `json:"return_type"`
Pure bool `json:"pure"`
Total bool `json:"total"`
}
FunctionContract describes an expression function. Checked predicates may reference only functions explicitly declared pure and total.
type IdempotencyPolicy ¶
type IdempotencyPolicy string
IdempotencyPolicy states which retry guarantee an executor binding provides.
const ( IdempotencyNone IdempotencyPolicy = "none" IdempotencyKeyRequired IdempotencyPolicy = "key_required" IdempotencySinkGuaranteed IdempotencyPolicy = "sink_guaranteed" )
type Limits ¶
type Limits struct {
MaxArtifactBytes int
MaxPlans int
MaxSteps int
MaxStepsPerPlan int
MaxArgumentsPerStep int
MaxPredicateNodes int
MaxLiteralNodes int
MaxDepth int
MaxStringBytes int
MaxBytesValue int
MaxCollectionItems int
MaxObjectFields int
MaxTotalStringBytes int
}
Limits bounds untrusted artifacts. A zero field uses DefaultLimits.
type RetryPolicy ¶
type RetryPolicy struct {
MaxAttempts uint32 `json:"max_attempts"`
InitialBackoffMillis uint64 `json:"initial_backoff_millis"`
MaxBackoffMillis uint64 `json:"max_backoff_millis"`
}
RetryPolicy is frozen into every checked step that invokes the verb.
type TypeDefinition ¶
type TypeDefinition struct {
Kind TypeKind `json:"kind"`
ElementType string `json:"element_type,omitempty"`
Fields map[string]string `json:"fields,omitempty"`
RequiredFields []string `json:"required_fields,omitempty"`
}
TypeDefinition declares a named structural type. Object fields not present in Fields are rejected. Maps always have string keys.
type VerbContract ¶
type VerbContract struct {
Arguments map[string]string `json:"arguments"`
RequiredArgs []string `json:"required_args"`
ResultType string `json:"result_type"`
InverseVerb string `json:"inverse_verb,omitempty"`
RetryPolicy RetryPolicy `json:"retry_policy"`
IdempotencyPolicy IdempotencyPolicy `json:"idempotency_policy"`
FencingRequired bool `json:"fencing_required"`
}
VerbContract describes the serializable part of a verb contract.
Source Files