Core Interface Guide

Downstream packages consume bijux-gnss-core through one curated API. That surface publishes shared meaning, not implementation organization: identities, units, time, coordinates, observations, navigation outcomes, diagnostics, configuration records, support inventory, and versioned artifacts.

Choose A Contract Family

flowchart TD
    need{"What must packages exchange?"}
    physical["identity, units,<br/>time, coordinates"]
    receiver["acquisition, tracking,<br/>observations, quality"]
    navigation["navigation outcomes"]
    governance["configuration, diagnostics,<br/>errors, support"]
    artifact["versioned persisted meaning"]

    need --> physical
    need --> receiver
    need --> navigation
    need --> governance
    need --> artifact

exchanged meaning	contract route	required clarity
Satellite, signal, physical quantity, epoch, or coordinate	Engineering conventions	identity, unit, time scale, frame, sign, and valid range
Acquisition request or result, tracking state, observation, differencing, or quality evidence	Observation and tracking contracts	lifecycle, uncertainty, timing, refusal, and producer responsibility
Measurement, engine-neutral boundary, or shared support record	Measurement and engine contracts	stable data meaning without runtime scheduling
Position result, residual, validity, lifecycle, or inter-system bias	Navigation solution contracts	frame, clock units, quality, covariance, integrity, and refusal
Configuration schema, diagnostic code, error category, or support status	Configuration and diagnostics	version, severity, ownership, and invalid states
Header, payload kind, reader policy, or versioned record	Artifact contracts	payload version, semantic validation, and compatibility policy

Import Through The Curated Surface

flowchart LR
    family["private contract family"]
    facade["curated core API"]
    producer["producer package"]
    consumer["consumer package"]
    persisted["versioned artifact"]

    family --> facade
    facade --> producer
    facade --> consumer
    facade --> persisted

Private modules own implementation, but callers rely only on deliberate exports. Use public imports for supported patterns and API surface before proposing a new export.

If a caller cannot express its work through the curated API, first check ownership. A receiver loop workspace, navigation filter state, repository path, or command report type should not become core API merely to shorten an import.

Read A Shared Record

Before consuming a record, identify:

• who produced it and which package owns that behavior;
• units, time scale, coordinate frame, sign, and ordering;
• valid, degraded, refused, unknown, and missing states;
• uncertainty, provenance, and model-version fields that qualify the value;
• payload version and reader policy if it survives serialization.

Parsing proves that bytes fit a shape. Contract validation determines whether the fields are coherent. The producing package’s evidence determines whether the scientific or runtime claim is supported.

Compatibility Boundary

Public exports and serialized fields are compatibility commitments. Do not change old meaning in place. Add a version boundary or documented reader policy when old and new consumers cannot assign the same semantics to the same value. Use compatibility commitments before changing a contract and entrypoints and examples for consumer-shaped use.

Sources Of Truth

The curated API is the supported surface. The contract map locates semantic ownership, the contract guide defines families, and the serialization guide governs persisted meaning.