Observer Model¶

schoolbus.observe is the layer that turns decoded protocol traffic into a cautious estimate of machine state.

Parsers answer: what did this frame, word, sentence, or transaction say?

Observers answer: what can a passive listener infer from repeated observations over time?

Canonical Shape¶

The long-term observation model is:

Observation(
    signal_name,
    value,
    unit,
    source_protocol,
    source_identifier,
    observed_at,
    freshness,
    confidence,
)

The current package may use smaller objects while it grows toward this shape.

Visual Model¶

flowchart LR decoded["Decoded protocol object"] --> observation["Observation"] observation --> freshness["Freshness check"] observation --> confidence["Confidence estimate"] observation --> missingness["Missingness state"] freshness --> state["Machine state estimate"] confidence --> state missingness --> state

Freshness¶

Freshness is about time. A signal may be decoded correctly and still be stale.

Examples:

engine speed observed 20 ms ago may be fresh
engine speed observed 20 seconds ago may be stale
a missing periodic message may matter more than a present one

Freshness logic should be explicit about clock assumptions and expected update rates.

Confidence¶

Confidence describes how strongly an observer should trust an inferred state.

Confidence can be affected by source quality, missing samples, conflicting messages, decode uncertainty, or a known pedagogical simplification.

Missingness¶

Missing data is information. An observer should eventually distinguish:

never observed
previously observed but stale
explicitly unavailable
contradictory
decoded but low-confidence

Passive Reconstruction¶

The observer layer is passive by default. It should reconstruct state from what has been seen, not transmit to a bus or coerce a machine into revealing state.

This is one of the distinguishing features of schoolbus: it is more than a set of parsers, but it remains educational and inspection-oriented. It is not a control-safety claim.

The passive state reconstruction lab shows the current API shape with synthetic first-workbook observations.