Behavioural Contract

Behavioural Contract

This page is an explanatory map of the tested Python reference behavior. The canonical document in the main repository is normative:

Read BEHAVIORAL_CONTRACT.md

If this Wiki and the canonical contract differ, use the current production code and canonical contract, then correct the Wiki. Future implementation changes must update tests and the contract together.

Scope

The contract covers observable behavior for:

• ingress frame production and compatibility-event acceptance;
• supported AIS NMEA extraction;
• multipart assembly and lifecycle outcomes;
• forwarding-owned TAG metadata;
• single and multipart deduplication;
• secure replay, session, and nonce state;
• routing snapshot timing; and
• forwarding and cleanup boundaries.

It is not an AIS semantic decoder, storage or analytics specification, spoof-detection specification, native interface, or ABI.

Processing pipeline

UDP / UDPSEC producer
    |
immutable IngressFrame
    |
representation-agnostic queue
    |
direct frame / one legacy IngressEvent adapter
    |
one routing snapshot and optional frame.source_id match
    |
bytes-native scan spans and ParsedSentence metadata
    |
feed_parsed_outcome()
    |
forwarding metadata selection
    |
global or target-scoped deduplication
    |
outbound TAG construction and UDP forwarding

Shared lifecycle invariant

Unless an explicitly documented wall-clock protocol rule applies, process-local TTL state is:

Live while age < ttl and expired when age >= ttl.

Exact duplicates do not refresh dedup entries, multipart groups, handshake replay records, or data-nonce records. Unique multipart progress and valid secure-session activity are the relevant refresh cases.

See State, Lifecycle, and Limits for the comparative owner model.

Frame and scanning boundaries

Built-in UDP and UDPSEC producers enqueue immutable IngressFrame objects. mixer_loop() transports queue items unchanged. A direct frame crosses the compatibility boundary by object identity; a legacy IngressEvent is adapted once when raw_line satisfies isinstance(raw_line, str). Invalid compatibility events and unsupported queue items are ignored before routing and scanning, and later queued items continue normally.

The bytes-native scanner accepts supported VDM and VDO talker/family combinations in input order. It requires checksum-field syntax of * followed by two hexadecimal characters but does not verify checksum arithmetic. A TAG block is associated only when its closing backslash immediately precedes the sentence.

Scanner results contain immutable half-open spans into the original frame. The scanner does not decode or copy sentence or TAG text. ParsedSentence retains the frame and spans while fragment fields and relevant TAG metadata are parsed once. The Python assembler later materializes sentence strings, so this is not an end-to-end zero-copy or fully bytes-native data plane.

Multipart identity and outcomes

The public identity is:

AssemblyKey = tuple[str, str, str, int]
# (assembler identity, sequential ID, channel, declared total)

The runtime assembler identity is the ingress peer IP and port. It is distinct from routing source_id. TAG g and the current fragment ordinal are not AssemblyKey fields.

Production calls feed_parsed_outcome() with fragment metadata already retained by ParsedSentence. The legacy string APIs feed() and feed_outcome() remain valid compatibility surfaces. Parsed and string entry points converge on the same lifecycle implementation and distinguish:

Status	Meaning
INVALID	Input cannot enter a valid assembly lifecycle.
SINGLE	One valid sentence is immediately ready without multipart state or clock use.
LIMIT_EXCEEDED	A valid multipart declaration exceeds the configured fragment limit.
PENDING	Unique progress was accepted but the group remains incomplete.
DUPLICATE	The exact sentence already occupies that ordinal.
CONFLICT	Different content occupied the ordinal, invalidating the generation.
COMPLETE	Every ordinal is present and output is materialized in order.

Fragments may arrive fully out of order. Exact duplicates are idempotent and do not refresh group lifetime. Unique progress does refresh it. A conflict removes the live generation and does not seed a replacement from the conflicting arrival.

discarded_keys reports expiry, conflict, and capacity removals in deterministic order. Completion consumes its own context separately; cleanup_expired() and reset() also return keys for external owners to consume. Together, these surfaces let forwarding metadata follow assembler lifecycle boundaries without reading assembler internals.

Blank sequential IDs remain supported. Fragments from separate physical transmissions can therefore form a synthetic group when all other identity fields collide within one live window; completion is not proof of common physical origin.

The Python assembler supports optional max_fragments_per_group and max_pending_groups. Current service wiring leaves both as None; they are not YAML configuration keys.

Forwarding-owned TAG metadata

The assembler owns fragment state. The forwarding loop separately owns multipart TAG s, c, and g context under the same AssemblyKey.

Every assembler-reported discarded key clears all three contexts before metadata on the current arrival is considered. Completion consumes them even when no route matches or deduplication suppresses all output.

• TAG s: the non-empty completion-arrival value can override earlier cached ingress metadata; final output selection still follows configured station/input policy.
• TAG c: multipart selection uses the minimum valid decimal observation. A duplicate may lower but not raise it. Multipart c:0 is preserved; single-sentence c:0 retains the server-time compatibility fallback.
• TAG g: candidates are non-empty decimal strings compared exactly. One observed value can be preserved; none or disagreement produces one generated ID for the completed group. TAG g does not define assembler identity.

See Multipart NMEA Assembly and TAG Handling.

Group-atomic deduplication

A single message uses its exact extracted sentence as the logical key. A multipart message uses the ordinal-ordered tuple of exact extracted sentences. Ingress TAG metadata is not part of either key.

The multipart tuple is decided once before any fragment is emitted:

• legacy mode uses one global scope;
• routing mode uses one independent scope per target_id; and
• ingress source identity does not add another scope for a target.

The Python Deduplicator supports optional max_entries. Current service wiring uses None, so the running service does not impose that capacity through this object and YAML does not expose it.

See Deduplication.

Secure local state

SecureState is the process-local owner for:

• verified handshake replay records;
• active secure sessions; and
• accepted data nonces scoped to each session.

Network policy is checked before secure-state clocks, cryptography, cleanup, or mutation. Allowed packets use one monotonic observation for local lifecycle decisions. Wall time remains separate for handshake freshness, pong timestamps, and diagnostics.

Replay and nonce duplicates do not refresh retention. Sessions are touched only by valid matching keepalive activity or fully validated secure ping/NMEA traffic. Secure state is hard-bounded, traffic-cleaned, non-durable, and lost at restart.

See UDPSEC Security and State for verified limits, replacement rules, and trust boundaries.

Routing snapshot boundary

When routing state is present, the consumer captures one immutable snapshot for each accepted direct or successfully adapted frame. If it contains a table, frame.source_id is matched once. All supported sentences from that frame use the same result.

A concurrent replacement affects a later accepted frame. An invalid compatibility event or unsupported item acquires no snapshot. A missing table uses legacy broadcast and global deduplication.

Statistics and reset surfaces

Deduplication, assembly, and secure state expose frozen point-in-time statistics objects. Reading them:

• does not read a clock;
• does not perform cleanup;
• does not expose mutable state; and
• cannot change an earlier snapshot.

Counters keep lifecycle reasons separate. These objects support regression and future differential-conformance testing; they are not a complete runtime metrics-export system.

Deduplication and assembly provide explicit reset behavior. Secure state has no public reset operation.

Delivery boundary

Multipart fragments and target destinations are sent sequentially. Dedup admission and metadata cleanup are not rolled back after a send failure. The contract does not promise transactional delivery, replay, or recovery after partial output.

Native conformance

Python remains the implemented and normative reference. Campaign C made the ingress frame, byte-span scanner, parsed metadata, and assembler entry boundary explicit. A future implementation can be compared through ordered sentences, TAG metadata, routing targets, dedup decisions, lifecycle outcomes and discarded keys, explicit no-output cases, and contract-relevant statistics.

No native processor, C or C++ API, ABI, binding technology, or performance claim is defined. See Native-Ready Reference Foundation.

Architecture history

Campaign A consolidated observable Python behavior and differential-test seams. Campaign B made state ownership, clocks, TTLs, limits, lifecycle outcomes, and immutable statistics explicit. Campaign C introduced immutable ingress frames, bytes-native scanning, immutable spans, parse-once fragment and TAG metadata, and the parsed assembler production path while preserving the established lifecycle and output behavior.

No campaign changes the rule that current production code and the canonical contract are the source of truth.

See Architecture Evolution.