# Logline Concepts and Vocabulary This document is the preferred reference for answering vocabulary questions about Logline. ## What Logline is Logline is a declarative language for describing expected behavior in timestamped logs. A Logline program declares scenarios and checks whether observed canonical records support those scenarios. Logline does not drive the system under test. It does not call functions, run procedures, send messages, or perform operational side effects. It evaluates evidence that already exists in logs. ## Top-level program constructs A Logline program may contain: - `scenarioDefaults` — optional defaults for scenario attempt classification. - `const` — named literal constants and arrays. - `collector` — program-level aggregation over input records. - `scenario` — an executable behavior description. Top-level constructs may be interleaved, but a valid program must contain at least one scenario. ## Scenario constructs A `scenario` names an expected behavioral flow. A scenario may include: - `attemptedBy` — named executable segments used to classify whether the scenario was attempted. - `attemptedWhen` — explicit attempt-classification policy. - `candidateConcurrency` — candidate lifecycle policy. - `candidateOpening` — candidate opening policy. - scenario-level `collector` declarations. - executable segments. ## Segment types When users ask for “Logline segment types,” answer with the current authoring-level segment constructs: - `transition` - `event` - `group` - `repeat` - `parallel` - `crossroads` Runtime roles differ: - `transition` and `event` are direct record-matching leaves. - `group` is a bounded observation/derivation segment over the canonical stream. - `repeat`, `parallel`, and `crossroads` are structured segment containers. ## Transition A `transition` describes an expected change in a named signal. It has: - `signal` - `type` - `condition` - optional `importance` - optional `retry` A transition observes log records. It does not contain system commands or operational effects. ## Event An `event` describes an expected condition over a canonical record. It is useful for free-text log messages, structured event records, diagnostics, and other evidence that is not naturally represented as a signal from-to transition. An event has: - `condition` - optional `importance` ## Group A `group` is a bounded observation scope over the canonical record stream. It can collect matching records, stop on an explicit completion condition, derive immutable values from the frozen collection, evaluate assertions, and publish an immutable result for downstream expressions. A Group has mandatory: - `collectionCondition` - `completionCondition` - `result` It may also contain: - a `derive` block - named `assert` blocks - `importance` Group does not emit records, create a second cursor, reorder records, or replay its completing record into the next sequential segment. ## Repeat A `repeat` segment runs its child segments a configured number of times. ```logline repeat Name { count =: 3; // child segments } ``` ## Parallel A `parallel` segment contains named branches and a policy. ```logline parallel Name { policy =: all; branch First { // child segments } branch Second { // child segments } } ``` Policies are `all` and `greedy`. ## Crossroads A `crossroads` segment selects among branches using branch conditions. ```logline crossroads Name { branch Nominal when condition { // child segments } branch Fault when condition { // child segments } } ``` ## Collectors A `collector` computes values from input records. Collectors may appear at program scope or inside scenarios. Collector kinds are: - `counter` - `sum` - `min` - `max` - `average` - `first` - `last` - `firstN` - `lastN` Collectors are declarations/supporting constructs. They are not scenario segment types. ## Canonical record stream and CTE The Engine consumes one canonical sequential record stream. For multi-source execution, source timestamps are normalized onto the run's Canonical Timeline Epoch (CTE) before records reach ordinary scenario execution. Automatic synchronization applies only to each record's canonical top-level timestamp. Timestamp-like payload fields remain untouched until a Logline expression explicitly interprets them. ## Records and field references Logline expressions may refer to runtime-bound fields of the current input record: - `t` - `timestamp` - `message` - `level` - `source` - `channel` - `signal` - `from` - `to` - `type` They may also refer to external schema paths through: - `fields.` - `signals.` - `record.` `record.index` is the canonical execution-stream index. It is assigned after deterministic source composition and is not a source-local file index. `record.sourceLine`, when available, is provenance for the original source location. Transition field references can use `TransitionName.field` or `ScenarioName.TransitionName.field` for fields such as `signal`, `type`, `timestamp`, `time`, `from`, and `to`. Completed Group results can be referenced through Group field/result access according to the language expression rules. ## Temporal reference and temporal anchor A temporal reference and an anchor are not synonyms: - `time.reference(source = ..., id = ...)` returns a temporal-reference identity used by conversions such as `time.toCte`. - `time.anchor(source = ..., id = ...)` resolves the named anchor and returns its CTE timestamp. A missing named reference or anchor does not fall back to the source's canonical clock. ## Common question answers ### What are Logline segment types? The current scenario segment types are `transition`, `event`, `group`, `repeat`, `parallel`, and `crossroads`. ### What is the difference between a transition and an event? A transition is for expected signal changes, usually involving a signal name, type, and from-to evidence. An event is for record-level evidence such as a message, level, source, channel, or structured record condition. ### What is a Group? A Group observes a bounded range of canonical records, optionally collects a subset, freezes the collection at explicit completion, derives immutable values, evaluates assertions, and publishes a result. It does not create or reorder records. ### Does a transition have actions? No. Current Logline transitions do not have action blocks or action fields. A transition describes expected evidence in logs; it does not perform effects. ### Are collectors segment types? No. Collectors are declarations that compute aggregate values. They are not executable scenario segments. ### Does Logline automatically convert every timestamp-looking payload value? No. Only the canonical record timestamp is normalized automatically before Engine execution. Payload time values require explicit temporal interpretation, typically with `time.toCte`.