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;
• processor-owned TAG metadata;
• single and multipart deduplication;
• secure replay, session, and nonce state;
• routing snapshot timing;
• the processor-to-egress boundary; and
• process-local runtime supervision.

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

Processing pipeline

UDP / UDPSEC producers
    |
immutable IngressFrame
    |
per-input queues
    |
ingress fan-in
    |
processor stage
    |
direct frame / one legacy IngressEvent adapter
    |
one immutable ProcessingSnapshot
    |
PythonDataPlaneProcessor.process(frame, snapshot)
    |
optional frame.source_id match
    |
bytes-native scan spans and ParsedSentence metadata
    |
feed_parsed_outcome()
    |
processor-owned TAG metadata selection
    |
global or target-scoped deduplication
    |
complete ordered tuple of ProcessorOutput values
    |
private completion barrier
    |
egress stage
    |
sequential broadcast or named-target UDP sends

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. Ingress fan-in transports queue items unchanged and performs no validation, routing, parsing, assembly, deduplication, or sending. In the processor stage, 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 snapshot acquisition or processor invocation, 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 processor-owned output 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.

Processor-owned TAG metadata

The assembler owns multipart fragment groups. The long-lived PythonDataPlaneProcessor separately owns multipart output TAG s, c, and g context under the same AssemblyKey. These roles are deliberately separate.

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 processor stage captures one immutable snapshot for each accepted direct or successfully adapted frame and converts it to the processor's immutable ProcessingSnapshot. If it contains a table, frame.source_id is matched once by the processor. 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.

Processor and egress boundary

For every accepted frame, the processor stage acquires one processing snapshot and calls DataPlaneProcessor.process(frame, snapshot) exactly once. PythonDataPlaneProcessor completes all synchronous parsing, assembly, multipart metadata, deduplication, TAG construction, and output construction before returning one complete ordered tuple[ProcessorOutput, ...].

An empty tuple completes locally. A non-empty tuple crosses a private process-local handoff to the egress stage. The processor stage waits on that batch's completion barrier and does not consume the next ingress item until egress has completed the batch. This private runtime acknowledgement is not part of the public processor contract and is not an ingress or delivery acknowledgement.

Egress sends ProcessorOutput values sequentially in tuple order. Legacy output uses the existing broadcast path; routed output uses named target sends. If the processor call fails, no batch crosses to egress and no later frame is processed. A send failure prevents later outputs in the batch from being sent and likewise prevents processing of a later frame, but it does not roll back already completed processor effects or reconstruct the output tuple. There is no transactional delivery, retry, rollback, replay, or recovery guarantee after partial output.

Process-local runtime supervision

One process-local supervisor owns every essential top-level task: plain UDP and UDPSEC producers, ingress fan-in, the processor stage, and the egress stage. Tasks are created lazily from role-named specifications; partial task-creation failure closes the rejected coroutine and cleans already-created tasks. Fan-in privately owns and supervises its per-input reader tasks, and an empty fan-in remains idle until cancellation. The first real task failure is propagated; an unexpected normal return or internal task cancellation becomes a role-named runtime failure. External cancellation cancels and awaits all owned tasks, resolves pending completion state, and is re-raised as CancelledError. Sibling tasks are cancelled and awaited, and their outcomes are retrieved before termination propagates. UDPSEC closes its owned socket after bind failure, runtime failure, or cancellation.

This is single-process asyncio task supervision. It does not define coordinator or worker processes, cross-process supervision, IPC, automatic service restart, delivery retry, or durable recovery. A systemd unit may independently restart the whole service according to its unit policy; that policy is outside both task supervision and the data-plane processor contract.

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. Campaign D added the synchronous DataPlaneProcessor contract, PythonDataPlaneProcessor as the sole production and reference processor, and the explicit fan-in, processor, completion-barrier, and egress runtime boundary. A future implementation can be compared through ordered processor outputs, 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.

Campaign D then established the synchronous processor contract, the sole Python reference processor, complete ordered output batches, the processor-to-egress completion barrier, explicit runtime stages, and process-local fail-fast supervision.

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

See Architecture Evolution.