Patterns & Builders

fabula::pattern -- compiled pattern types. fabula::builder -- ergonomic construction API.

Pattern types

`Var`

A named position in a pattern traversal. Variables appearing in multiple clauses create joins.

pub struct Var(pub String);

Field	Type	Description
`0`	`String`	The variable name.

Methods

`Var::new`

pub fn new(name: impl Into<String>) -> Self

Parameter	Type	Required	Default	Description
`name`	`impl Into<String>`	yes	--	Variable name.

Returns: Var

Trait implementations

Debug, Clone, PartialEq, Eq, Hash, Display (formats as ?name).

`Target<V>`

Specifies what an edge's target must match.

pub enum Target<V> {
    Bind(Var),
    Literal(V),
    Constraint(ValueConstraint<V>),
}

Variant	Description
`Bind(Var)`	Bind the target to a variable for traversal or join.
`Literal(V)`	The target must equal this exact value.
`Constraint(ValueConstraint<V>)`	The target must satisfy this constraint.

Trait implementations

Debug, Clone.

`Clause<L, V>`

A single edge traversal constraint within a stage.

pub struct Clause<L, V> {
    pub source: Var,
    pub label: L,
    pub target: Target<V>,
    pub negated: bool,
}

Field	Type	Description
`source`	`Var`	Source node variable. Must be bound by a prior clause or be a scan root.
`label`	`L`	Edge label to follow.
`target`	`Target<V>`	What the target must match.
`negated`	`bool`	If `true`, the edge must NOT exist.

Trait implementations

Debug, Clone.

`Stage<L, V>`

A group of clauses anchored to a single event/node variable. Stages are the units of incremental matching -- each new edge tests against the next unmatched stage.

pub struct Stage<L, V> {
    pub anchor: Var,
    pub clauses: Vec<Clause<L, V>>,
}

Field	Type	Description
`anchor`	`Var`	The event/node variable this stage is anchored to.
`clauses`	`Vec<Clause<L, V>>`	Clauses that constrain this event/node.

Trait implementations

Debug, Clone.

`TemporalConstraint`

An explicit temporal ordering constraint between two event variables (beyond implicit left-to-right stage ordering).

pub struct TemporalConstraint {
    pub left: Var,
    pub relation: AllenRelation,
    pub right: Var,
    pub gap: Option<MetricGap>,
}

Field	Type	Description
`left`	`Var`	Variable whose interval should come first.
`relation`	`AllenRelation`	Required Allen relation (typically `Before` or `Meets`).
`right`	`Var`	Variable whose interval should come second.
`gap`	`Option<MetricGap>`	Optional metric bound (STN-style bounded difference). Set via `temporal_with_gap` on the builder or `gap min..max` in the DSL.

Trait implementations

Debug, Clone.

`Negation<L, V>`

A negation window -- a set of clauses that must NOT all match between two events. All clauses must match for the negation to fire (conjunctive).

pub struct Negation<L, V> {
    pub between_start: Var,
    pub between_end: Option<Var>,
    pub clauses: Vec<Clause<L, V>>,
}

Field	Type	Description
`between_start`	`Var`	Start of the negation window (must be bound).
`between_end`	`Option<Var>`	End of the negation window. `None` means open-ended (up to "now").
`clauses`	`Vec<Clause<L, V>>`	Clauses that must NOT all match within the window.

Trait implementations

Debug, Clone.

`Pattern<L, V>`

A compiled sifting pattern -- a named subgraph template with temporal constraints and negation windows.

pub struct Pattern<L, V> {
    pub name: String,
    pub stages: Vec<Stage<L, V>>,
    pub temporal: Vec<TemporalConstraint>,
    pub negations: Vec<Negation<L, V>>,
    pub group: Option<String>,
    pub metadata: HashMap<String, String>,
    pub deadline_ticks: Option<u64>,
    pub repeat_range: Option<RepeatRange>,
    pub unordered_groups: Vec<Vec<usize>>,
    pub private: bool,
}

Field	Type	Description
`name`	`String`	Pattern name, used in match results and gap analysis.
`stages`	`Vec<Stage<L, V>>`	Ordered event stages. Temporally ordered left-to-right.
`temporal`	`Vec<TemporalConstraint>`	Explicit temporal constraints beyond implicit ordering.
`negations`	`Vec<Negation<L, V>>`	Negation windows.
`group`	`Option<String>`	Mutual-exclusion group. When one pattern in a group completes, the engine kills active PMs for all other patterns in the same group. Set by `choice` composition.
`metadata`	`HashMap<String, String>`	Arbitrary key-value pairs propagated to `Match`, `SiftEvent`, and scored match types. Use for tagging patterns with narrative roles, priorities, or domain-specific attributes.
`deadline_ticks`	`Option<u64>`	If set, active partial matches for this pattern are expired (killed with `SiftEvent::Expired`) when they have been alive for more than this many ticks without completing. Checked during `end_tick()`.
`repeat_range`	`Option<RepeatRange>`	Looping repeat configuration. Set by `compose::repeat_range()` or DSL `* N..M` / `* N..`. When present, the engine loops over a segment of stages instead of completing after the last stage. See DSL Reference — Repeat.
`unordered_groups`	`Vec<Vec<usize>>`	Stage groups that can match in any order. Each inner `Vec<usize>` lists stage indices that form a concurrent group. Set by `PatternBuilder::unordered_group()` or DSL `concurrent { }`. See DSL Reference — Concurrent Groups.
`private`	`bool`	If true, this pattern's matches and events are suppressed from engine output (`evaluate()`, `drain_completed()`, `on_edge_added()`). The engine still evaluates the pattern internally for composition and exclusive group handling. Default `false`. Set by `PatternBuilder::private()` or DSL `private pattern`.

Methods

`all_vars`

Returns all variables used in this pattern (across all stages and negations), sorted and deduplicated.

pub fn all_vars(&self) -> Vec<&Var>

`unordered_group_for`

Returns the unordered group containing the given stage index, if any.

pub fn unordered_group_for(&self, stage_idx: usize) -> Option<&Vec<usize>>

`same_unordered_group`

Returns true if two stage indices are in the same unordered group.

pub fn same_unordered_group(&self, a: usize, b: usize) -> bool

`condition_count`

Total number of clauses across all stages in the pattern.

pub fn condition_count(&self) -> usize

`map_types`

Convert a pattern from one type system to another. Applies label_fn to all labels and value_fn to all values, producing a new pattern with different L2/V2 types. All fields (stages, negations, temporal constraints, unordered groups, metadata, repeat range) are preserved.

pub fn map_types<L2, V2>(
    &self,
    label_fn: impl Fn(&L) -> L2,
    value_fn: impl Fn(&V) -> V2,
) -> Pattern<L2, V2>

Trait implementations

Debug, Clone.

`RepeatRange`

Configuration for looping repeat patterns (DSL * N..M or * N..). The pattern's stages are laid out as [first_... | last_...]. The last_ segment loops in the engine.

pub struct RepeatRange {
    pub stage_start: usize,
    pub stage_end: usize,
    pub min_reps: usize,
    pub max_reps: Option<usize>,
    pub shared_vars: HashSet<String>,
}

Field	Type	Description
`stage_start`	`usize`	First stage index of the looping segment (inclusive).
`stage_end`	`usize`	Last stage index of the looping segment (exclusive).
`min_reps`	`usize`	Minimum total occurrences before the first completion. `* 3..` means 3.
`max_reps`	`Option<usize>`	Maximum total occurrences. `None` = unlimited (`* N..`).
`shared_vars`	`HashSet<String>`	Variables shared across repetitions (not prefixed, persist across loops).

Bindings in repeat-range matches:

first_* — variables from the first sub-pattern occurrence (preserved across loops)
last_* — variables from the most recent occurrence (overwritten each loop iteration)
Shared variables — unprefixed, consistent across all iterations

Trait implementations: Debug, Clone, PartialEq.

Builders

`PatternBuilder<L, V>`

Ergonomic builder for constructing a Pattern. Requires L: Clone, V: Clone.

let pattern = PatternBuilder::<String, MemValue>::new("my_pattern")
    .stage("event1", |s| {
        s.edge("event1", "type".into(), MemValue::Str("failure".into()))
            .edge_bind("event1", "actor".into(), "character")
    })
    .stage("event2", |s| {
        s.edge("event2", "type".into(), MemValue::Str("betrayal".into()))
            .edge_bind("event2", "target".into(), "character")
    })
    .unless_between("event1", "event2", |neg| {
        neg.edge(
            "recovery",
            "type".into(),
            MemValue::Str("trust_restored".into()),
        )
    })
    .build();

`PatternBuilder::new`

Starts building a new pattern.

pub fn new(name: impl Into<String>) -> Self

Parameter	Type	Required	Default	Description
`name`	`impl Into<String>`	yes	--	Pattern name for identification.

Returns: PatternBuilder<L, V>

`stage`

Adds an event stage. The anchor names the event variable. Use the callback to add clauses via StageBuilder.

pub fn stage(
    self,
    anchor: impl Into<String>,
    build: impl FnOnce(StageBuilder<L, V>) -> StageBuilder<L, V>,
) -> Self

Parameter	Type	Required	Default	Description
`anchor`	`impl Into<String>`	yes	--	Event variable name for this stage.
`build`	`FnOnce(StageBuilder) -> StageBuilder`	yes	--	Callback that adds clauses to the stage.