# Canonical Log Records

Logline consumes canonical records derived from source logs.

## Canonical record purpose

Source logs can come from text logs, CSV files, multi-channel logs, converted binary sources, or multiple independent inputs. Import/source adapters interpret source-specific data, but ordinary Engine execution receives canonical records.

## Canonical timestamp

Each executable canonical record has one top-level canonical timestamp. In a multi-source run, that timestamp is normalized exactly onto the run's Canonical Timeline Epoch (CTE) before the record reaches ordinary Engine execution.

The `t` and `timestamp` expression aliases refer to this canonical timestamp.

## Automatic versus explicit temporal handling

Automatic normalization applies only to the canonical top-level record timestamp.

Timestamp-like values in `fields.*`, `signals.*`, `record.raw`, or other payload data remain untouched source data. A program explicitly interprets those values with `time` operators when it needs CTE semantics.

## Record identity and provenance

`record.index` is the final canonical execution-stream index. For multi-source runs it is assigned after source timestamps have been normalized and the source cursors have been deterministically merged.

It must not be interpreted as “index within this input file.”

Source identity remains available through `source`/record provenance, and `record.sourceLine` remains the original source line/index when the source format exposes one.

## Transition-compatible records

A transition-compatible record normally includes:

- canonical timestamp (`t` / `timestamp`)
- `signal`
- `from`
- `to`
- `type`
- optional `source`
- optional `channel`
- optional structured fields

## Event-compatible records

An event-compatible record may include:

- canonical timestamp (`t` / `timestamp`)
- `message`
- optional `level`
- optional `source`
- optional `channel`
- optional structured fields

## Mixed records

A single canonical stream may contain transition-compatible, event-compatible, snapshot-style, and neutral records. Transitions, events, groups, and collectors evaluate the same stream according to their own semantics.

## Multi-signal snapshots

The optional `signals.*` namespace represents multi-signal snapshot values. It is separate from the direct `signal` field used by single signal-transition records.

## Type inference

Numeric-looking values may be normalized as `int`, `float`, or `hex` according to importer/schema semantics. A decimal-point value remains float even when its fractional part is zero.

## Literal string values and typed nulls

Built-in text import primitive parsing preserves textual state values such as `NONE`, `NIL`, and `NULL` as strings, including case variations. These can be legitimate signal states: a transition from `NONE` is not a transition from a missing value. Empty text is likewise not automatically a typed null. A true `null` is retained when supplied as a typed value by a source format or an explicitly defined adapter contract. Do not instruct an importer, AI authoring tool, or Workbench projection to infer missing data merely because a state name resembles an English null marker. Check the source-specific adapter contract before making assumptions about missing-field representation.

## Neutral records

Some valid canonical records may satisfy no transition or event condition. They remain part of the stream and may still contribute to Group observation, collectors, diagnostics, or provenance.