Published document · Markdown source · part of the specifications index. Experimental drafts can change section numbers; archived revisions are linked from the specifications index.

JSQ Transport Service Specification #

Status: Engineering draft for consolidation and implementation
Document version: 1.0-draft
Date: 2026-08-19
Protocol suite: JSQ
Reference implementation: OpenJSQ
Scope: Modem-agnostic amateur-radio digital communication transport and service layer
Normative position: This document supersedes earlier JSQ monolithic waveform/application drafts where they conflict with the modem-agnostic architecture defined here.

0. Executive definition #

JSQ is a modem-agnostic transport service for amateur-radio digital communications.

JSQ sits above the modem or TNC and provides a common set of operator-facing services regardless of how bits, symbols, audio, frames, or packets are carried over the radio link.

The defining stack is:

OpenJSQ application / other JSQ client
                |
                v
+-----------------------------------------------+
| JSQ service layer                             |
|                                               |
| live chat      automatic station actions      |
| mail           file transfer                  |
| presence       groups                         |
| topology       relay and route recommendation |
| delivery state / custody / receipts           |
+-----------------------------------------------+
                |
                v
+-----------------------------------------------+
| JSQ bearer adapter                            |
| capabilities, addressing, timing, integrity,  |
| channel state, TX completion, signal evidence |
+-----------------------------------------------+
                |
                v
+----------------+----------------+-------------+
| Native modem   | Direct-control | Outsourced  |
| provider       | provider       | TNC/provider|
+----------------+----------------+-------------+
                |
                v
             Radio

JSQ does not require one waveform, one modem, one RF band, one link framing method, one TNC implementation, or one user interface.

The same JSQ conversation, mail object, file, relay request, presence observation, or route recommendation may be carried over different bearers as long as each bearer adapter preserves the JSQ semantic contract.

The core design goal is to combine the most useful operating concepts of FSQ/FSQCall and JS8-style digital messaging:

• immediate keyboard-to-keyboard conversation;
• optional verified delivery without sacrificing live copy;
• automatic station queries and replies;
• self-enrolled groups;
• unattended mail and store-and-forward operation;
• reliable file transfer;
• station presence and heard-list awareness;
• relay and route assistance;
• a modern conversation-oriented application model;
• operation without a required Internet service.

JSQ is therefore a service protocol above the modem, not a modem.

Part I — Normative model #

1. Normative language #

The terms MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are normative when written in uppercase.

A JSQ implementation conforms only to the services and provider capabilities it advertises.

A station MUST NOT advertise a JSQ capability that it cannot complete according to this specification.

Unknown optional service records or extensions SHOULD be ignored safely. Unsupported operations MUST NOT cause undefined automatic transmission behavior.

2. Design principles #

2.1 Service semantics are independent of the modem #

JSQ defines what an operation means, not how a particular modem encodes it.

For example, a JSQ SIGNAL_REPORT_REQUEST has one semantic meaning whether it is carried as:

• a translated legacy FSQ ? command;
• an FSQ++ structured envelope;
• an AX.25/OFQ2 record;
• a JG25 bearer envelope (JG25_SPECIFICATION.md);
• a managed modem API transaction;
• or another published JSQ bearer binding.

Bearer-specific punctuation, packet headers, CRC placement, FEC, audio timing, and TNC framing are not JSQ Core semantics.

2.2 One application service model #

Chat, files, mail, presence, groups, automatic station actions, relay, and route/delivery state MUST be implemented once above the bearer boundary.

Adding a new modem provider MUST NOT require a second implementation of those services.

2.3 Preserve immediacy and add certainty #

JSQ SHALL support both:

• 1.live unverified delivery, optimized for conversational speed; and
• 2.verified delivery, optimized for integrity and positive end-to-end confirmation.

The operator SHOULD be able to see useful provisional text immediately while the protocol separately works toward integrity verification or delivery confirmation when requested.

2.4 Decentralized by default #

Core JSQ operation SHALL NOT require:

• an Internet connection;
• a cloud account;
• a central message server;
• global time synchronization;
• a central station registry;
• a specific vendor modem.

2.5 Amateur-radio transparency #

JSQ provides integrity, duplicate suppression, routing metadata, and optional public authentication mechanisms, but Core JSQ does not require secrecy.

The protocol MUST NOT depend on encryption intended to obscure amateur-radio RF message content.

2.6 Bounded automatic behavior #

Automatic replies, presence reports, relay activity, route discovery, mail announcements, retries, and background services MUST be bounded and rate-limited.

No JSQ service may retry indefinitely.

No JSQ service may create an uncontrolled forwarding or reply loop.

2.7 Honest state #

The application MUST distinguish among:

• handed to a modem or TNC;
• transmitted over RF when known;
• integrity verified;
• acknowledged by the destination;
• stored by an intermediate custodian;
• delivered to the final endpoint;
• displayed/read by a human when optional read receipts are enabled.

These states MUST NOT be collapsed into a generic “delivered” indication.

Part II — Provider and bearer architecture #

3. Provider classes #

JSQ recognizes three implementation classes beneath the service layer.

3.1 Class A — Native modem provider #

A Native Modem Provider is implemented inside the JSQ host application or a directly linked first-party modem subsystem.

The host owns the modem DSP and normally owns the radio audio path.

Examples:

• FSQ++;
• native AX1200;
• JG25 native;
• future first-party HF or VHF modems.

A native provider normally gives JSQ the richest evidence:

• normalized or framed receive events;
• channel busy/clear state;
• signal strength and/or calibrated SNR;
• receive quality/confidence;
• precise transmit lifecycle;
• actual RF/audio completion;
• modem configuration;
• optional frequency/slot/profile information.

A native provider SHOULD report rf_complete when the host knows the generated RF audio has completed.

3.2 Class B — Direct-Control / Managed Modem Provider #

A Direct-Control Provider uses an external modem application or process, but the JSQ host manages it as part of the operating experience.

The host may:

• locate the executable;
• generate configuration;
• configure hardware-facing settings;
• start and stop the process;
• monitor process health;
• connect to its API, KISS endpoint, socket, or other documented local interface;
• fail closed if the process becomes unavailable.

Examples:

• OpenJSQ-managed Dire Wolf;
• a future VARA-style managed external modem integration;
• another locally controlled modem daemon with a documented interface.

A Direct-Control provider is distinct from an outsourced TNC because the JSQ application owns the lifecycle and configuration experience even though it does not own the DSP implementation.

A Direct-Control provider SHOULD run out of process unless a separately reviewed provider architecture explicitly permits otherwise.

Loss of the managed process MUST detach the provider safely. Automatic process restart MUST be explicit policy, not an implicit default.

3.3 Class C — Outsourced TNC / External Provider #

An Outsourced Provider is a separately managed modem or TNC to which JSQ sends and receives already framed packet data.

Initial supported boundary:

• BLE KISS;
• Serial KISS;
• TCP KISS.

This provider class is initially restricted to AX-style framed packet operation.

The outsourced device owns some or all of:

• modem DSP;
• carrier detection;
• framing/FCS;
• audio devices;
• PTT;
• radio-specific timing.

JSQ therefore MUST NOT pretend to possess evidence the provider did not report.

For a generic KISS provider:

• transmit completion normally means handed_to_device, not confirmed RF completion;
• channel state may be unknown;
• calibrated SNR may be unavailable;
• local audio/PTT controls are not applicable;
• host rig/CAT control MAY still remain available independently.

3.4 Provider identity #

Provider selection SHOULD use stable string identifiers rather than persisted enum ordinals.

Initial reference IDs:

native.fsq
native.ax1200
native.jg25
managed.direwolf
external.kiss.ble
external.kiss.serial
external.kiss.tcp

Provider existence, availability in the current build, configuration readiness, and runtime connection state are separate concepts.

4. Bearer boundary types #

A provider exposes one of these primary boundaries:

audio_samples
kiss_frames
connected_stream

Additional boundaries MAY be standardized later.

The boundary type does not determine JSQ service behavior. It determines how the bearer adapter obtains and transmits JSQ semantic units.

5. Bearer capability contract #

Every active JSQ bearer adapter SHALL expose a capability descriptor sufficient for the service layer to make honest decisions.

At minimum:

provider_id
provider_class
boundary_type
protocol_family
maximum_payload
addressing_modes
broadcast_supported
group_delivery_supported
channel_state_capability
signal_metrics_capability
tx_completion_semantics
link_integrity_semantics
link_reliability_semantics
supports_relay_observation
supports_host_rig_control

5.1 Channel state capability #

Values:

reliable
advisory
unknown

JSQ services that depend on channel-idle timers MUST adapt when channel state is unknown.

5.2 Signal evidence capability #

A provider MAY expose:

• SNR;
• decode margin;
• modem quality Q;
• frequency offset;
• error counts;
• RSSI or device-specific measurements;
• no metric.

JSQ MUST label device-specific metrics honestly and MUST NOT reinterpret an arbitrary vendor number as calibrated SNR.

5.3 Transmit completion semantics #

At minimum:

rf_complete
handed_to_device
unknown

rf_complete means the provider can establish that the RF/audio transmission completed.

handed_to_device means JSQ successfully transferred the frame or command to another modem/TNC but cannot establish that RF transmission occurred or completed.

An application MUST NOT display handed_to_device as confirmed RF transmission.

5.4 Link integrity semantics #

A provider reports what the bearer itself guarantees, such as:

• no integrity guarantee;
• frame CRC/FCS validated;
• bearer-level FEC;
• bearer-level ARQ;
• ordered connected stream;
• duplicate suppression.

These properties inform service policy but do not replace JSQ end-to-end integrity requirements unless a service specification explicitly permits that substitution.

Part III — Common JSQ data model #

6. Station identity #

The primary human-visible JSQ identity is the amateur-radio callsign.

A JSQ implementation MAY maintain a compact internal station identifier, but:

• callsign remains the authoritative operator-visible identity;
• a compact identifier MUST be resolvable to a callsign;
• a callsign CRC or packet source field is not cryptographic authentication;
• identity binding evidence MUST be retained separately from message integrity.

A station record SHOULD include:

callsign
first_heard
last_heard
provider/bearer
frequency or channel when known
last signal metrics
best signal metrics
capabilities
presence state
group information when publicly advertised
route observations
link quality
staleness

7. Message and object identity #

Every directed JSQ chat item SHOULD have a stable message ID.

Persistent objects such as formal mail and reliable files MUST have a stable Object ID.

A stable ID MUST remain unchanged across:

• retransmission;
• application relay;
• custody transfer;
• restart/resume;
• cross-provider forwarding.

A recommended persistent object identity is a random 128-bit identifier.

Persistent objects SHOULD also carry an end-to-end content hash.

The same Object ID with a different end-to-end hash MUST be treated as corruption or an identifier collision.

8. Common delivery states #

The normalized JSQ service layer SHALL use states with explicit meaning.

Recommended common states:

draft
queued
waiting_for_channel
transmitting
handed_to_device
rf_sent
awaiting_verification
verified
awaiting_delivery_receipt
hop_acknowledged
stored_by_relay
stored_by_mailbox
forwarding
delivered
displayed
read
paused
cancelled
expired
rejected
failed

Not every provider or service can produce every state.

8.1 Verified #

verified means the destination endpoint reconstructed the intended JSQ payload and validated the required integrity check.

It does not by itself mean the final recipient accepted custody or that a human read the message.

8.2 Delivered #

delivered means the final destination JSQ endpoint generated the required end-to-end delivery acknowledgment or receipt.

A relay or mailbox custody acknowledgment is not final delivery.

8.3 Read #

read is an optional user-interface receipt indicating that a human-facing client marked the item as displayed/read.

Read receipts MUST be optional and separate from transport delivery.

9. Capability discovery #

JSQ capabilities are advertised per station and per service.

Capabilities SHOULD be named semantically rather than by modem implementation.

Representative capabilities:

chat.live
chat.verified
groups
actions.fsq
mail.quick
mail.formal
mail.custody
file.quick
file.reliable
presence
heard.report
network.map
relay
route.recommendation
public.signatures
file.shared

file.shared means the station serves its shared folder right now: it answers a shared-files listing request and serves fetches by index and fingerprint. It is a promise to answer, not merely to understand the request. Each bearer carries it in its own form (AX1200 and JG25 in the capability exchange, FSQ++ as the capability token letter L; see the public protocol specification §78.1), and the service layer sees only the name. A station whose folder is empty or switched off does not advertise it.

Bearer capabilities and remote-station JSQ service capabilities are separate.

A local modem being capable of reliable file transport does not prove that a particular peer supports reliable files.

The service layer MUST select only capabilities established for both the active local bearer and the remote endpoint.

Part IV — Service 1: Live chat and groups #

10. Live chat #

JSQ SHALL provide keyboard-to-keyboard digital conversation as a first-class service.

Two delivery modes are defined.

10.1 Live Unverified Chat #

LIVE_CHAT is immediate best-effort conversation.

Characteristics:

• text MAY be surfaced incrementally while receiving;
• no end-to-end acknowledgment is required;
• no retransmission is required;
• partial text may be displayed;
• the UI MUST mark uncertain or incomplete copy honestly;
• directed, channel-wide, or group-addressed operation is permitted when the bearer supports it.

This is the closest JSQ equivalent to classic FSQ conversational operation.

10.2 Verified Chat #

VERIFIED_CHAT preserves the conversational UI but requests integrity-verified and positively acknowledged delivery.

Characteristics:

• the receiver MAY display provisional text during reception;
• the message MUST have a stable Message ID;
• full payload integrity MUST be checked before the message is marked verified;
• the final destination MUST acknowledge successful acceptance for the sender to show delivered;
• retransmission is bounded;
• duplicate Message IDs MUST NOT produce duplicate conversation items.

Verified chat is message-oriented, not a long-lived TCP byte stream.

10.3 User choice #

The application SHOULD allow the operator to choose the delivery expectation per message or per conversation:

Live
Verified

An implementation MAY remember a per-contact default.

The UI SHOULD make the difference obvious without requiring the operator to understand modem or ARQ details.

10.4 Replies #

Chat messages MAY carry a stable reply_to reference.

A missing referenced message MUST degrade gracefully in the UI.

11. Self-enrolled groups #

A JSQ group is a decentralized shared destination.

The reference human-visible form is:

@GROUPNAME

Joining a group means the local station subscribes itself to traffic addressed to that group.

There is no required central membership server.

A station MAY:

• subscribe;
• unsubscribe;
• transmit to the group;
• receive group traffic;
• advertise selected group subscriptions according to privacy policy.

11.1 Group acknowledgments #

Group chat MUST avoid acknowledgment storms.

Default group live chat is unacknowledged.

A verified group message MAY verify integrity independently at each receiver but MUST NOT require every group member to transmit an immediate ACK.

Future or optional group delivery confirmation MAY use:

• a designated net-control station;
• an explicitly selected response coordinator;
• randomized/suppressed receipts;
• a poll-based group repair protocol.

Part V — Service 2: Automatic station actions #

12. Structured automatic action service #

JSQ SHALL provide structured request/response actions corresponding to the useful automatic behaviors historically exposed by FSQCall.

JSQ itself uses semantic action identifiers. A legacy FSQ bearer adapter MAY translate them to or from punctuation triggers.

Automatic actions MUST be:

• capability-advertised where appropriate;
• policy-controlled;
• rate-limited;
• visible in the operator activity history;
• suppressed when unsafe or likely to cause reply storms.

12.1 Required FSQ-derived action set #

12.2 Automatic action safety #

Read-only information actions SHOULD be the default allowed automatic actions.

Any action that changes radio configuration, launches software, executes a command, writes outside the JSQ data store, or performs general remote code execution is outside Core JSQ.

LINK_FASTER and LINK_SLOWER are suggestions. The remote station retains control of actual modem/profile selection.

12.3 Broadcast and group requests #

Requests that generate responses MUST normally be directed.

Broadcast/group automatic queries MUST use a suppression or coordinator mechanism if they can generate more than one response.

A bearer compatibility profile MAY impose stricter limits.

Part VI — Service 3: Mail #

13. Mail service overview #

JSQ defines two operator-facing mail workflows:

• 1.Quick Mail — a lightweight message created from an ordinary chat context.
• 2.Formal Mail — a durable, verifiable message object with richer metadata, custody, and end-to-end delivery state.

Both appear in a unified modern inbox.

14. Quick Mail #

Quick Mail is designed for:

“They are not here right now; leave them this message.”

It SHOULD be creatable directly from a chat conversation without opening a full mail composer.

A Quick Mail item minimally contains:

message_id
origin
final_recipient
body
created_time
expiry

Optional fields:

subject
priority
reply_to

Default behavior:

• the sender's station stores the item locally;
• the item remains parked while the recipient is absent;
• a recent presence observation triggers a bounded announcement;
• the recipient can fetch the item;
• the recipient ACK prevents duplicate insertion;
• restart MUST NOT lose parked mail.

Quick Mail does not require the operator to select a third-party custodian.

A client MAY offer “Leave with mailbox…” to promote the message into formal custodial delivery.

15. Formal Mail #

Formal Mail is a persistent JSQ object suitable for unattended and multi-hop delivery.

Recommended fields:

object_id
origin
final_recipient
subject
body
created_time
expiry
priority
content_hash
attachment_object_ids
custody_policy
delivery_receipt_requested

Formal Mail MUST support:

• end-to-end integrity;
• positive final delivery receipt;
• duplicate suppression;
• restart-safe persistence;
• optional third-party custody;
• explicit expiry;
• clear intermediate states.

15.1 Custody #

A station accepting custody MUST NOT acknowledge custody until the message/object is durably recoverable according to local policy.

Custody means:

“I have accepted responsibility for retaining and attempting onward delivery of this object.”

Custody does not mean final delivery.

15.2 Third-party mailbox deposit #

A sender MAY leave formal mail with a station advertising mailbox/custodian capability.

The depositing station MUST retain its own copy until the mailbox has:

• 1.accepted the object;
• 2.verified required integrity;
• 3.made the object durable;
• 4.acknowledged custody.

A mailbox decline or timeout leaves the sender's local copy intact.

15.3 Presence-triggered discovery #

Mail discovery SHOULD use a hybrid model:

• presence-triggered announce as the fast path;
• explicit query as the recovery path.

Announcements MUST be jittered and rate-limited.

15.4 Recipient fetch #

The recipient MAY query a custodian for held mail and fetch selected messages.

Large mail bodies MAY reuse the reliable file-transfer service rather than creating a second bulk transport.

15.5 Redundant custodians #

JSQ permits redundant custody.

A recipient ACK or equivalent durable receipt MUST suppress duplicate delivery from other custodians.

Receipt tombstones SHOULD survive restart long enough to prevent late duplicate delivery.

15.6 Mail states #

Recommended mail states:

draft
queued
parked
announced
fetching
stored_local
stored_by_mailbox
forwarding
delivered
expired
rejected
failed

16. Modern inbox requirements #

A JSQ reference application SHOULD present mail as a compact message inbox rather than a raw file directory.

The inbox SHOULD show:

• sender;
• subject or body preview;
• received/created time;
• unread state;
• priority;
• direct vs custodial delivery;
• delivery status;
• attachment indicator;
• expiry where relevant.

A separate Holding or Custody view SHOULD show messages the local station currently stores for other stations.

Protocol metadata such as Object IDs and custody hops SHOULD be available in details/diagnostics without dominating the normal inbox UI.

Part VII — Service 4: File transfer #

17. File service overview #

JSQ defines two operator-facing file workflows:

• 1.Quick File — immediate best-effort small-file transfer from chat or command context.
• 2.Reliable File — verified, resumable, TCP-like delivery semantics over a radio-appropriate block protocol.

The term “TCP-like” describes the reliability expectation, not the wire algorithm. JSQ reliable files are message/block oriented and optimized for half-duplex radio.

18. Quick File #

Quick File is intended for small objects when speed and convenience matter more than repair.

Characteristics:

• initiated from chat or a command-style action;
• bounded maximum size defined by the active bearer profile;
• no restart/resume requirement;
• no selective retransmission requirement;
• whole-object integrity SHOULD be supplied when practical;
• failure SHOULD be visible, but no delivery guarantee is implied.

Quick File MAY be implemented as:

• one semantic datagram;
• a small bounded fragment set;
• an inline object in the active conversation.

A provider that cannot carry the file within its Quick File policy MUST offer Reliable File instead.

19. Reliable File #

Reliable File SHALL use the common JSQ reliable-file state machine.

The reference reliability algorithm is polled selective-repeat ARQ.

Semantic operations:

FILE_OFFER
FILE_ACCEPT
FILE_DATA
FILE_POLL
FILE_STATUS
FILE_FINISH
FILE_DONE
FILE_ABORT
FILE_ABORTED

19.1 Core invariant #

The sender initiates each file-protocol exchange.

The receiver sends file-protocol traffic only as a direct response to a sender request.

There is no timer-generated DATA ACK stream.

19.2 Burst/poll behavior #

Reference exchange:

sender                         receiver

FILE_DATA ----------------------->
FILE_DATA ----------------------->
FILE_DATA ----------------------->
FILE_POLL ----------------------->
             <----------- FILE_STATUS

missing FILE_DATA --------------->
FILE_POLL ----------------------->
             <----------- FILE_STATUS

FILE_FINISH --------------------->
             <------------- FILE_DONE

This design is intentionally suited to half-duplex radio and prevents independent sender/receiver ACK timers from competing for the channel.

19.3 Selective repeat #

FILE_STATUS identifies what is missing using a cumulative position plus a selective bitmap or an equivalent bearer encoding.

The sender retransmits missing blocks rather than an entire window.

19.4 Integrity #

Reliable File MUST provide:

• per-block corruption detection;
• whole-object end-to-end hash;
• final completion only after the whole object validates.

SHA-256 is RECOMMENDED for whole-object identity/integrity.

19.5 Resume #

Transfer identity and immutable block geometry MUST survive restart for exact block-map resume.

A resumed transfer MUST NOT silently reinterpret old acknowledgments under different block geometry.

19.6 Durability #

A receiver MUST NOT acknowledge a file block as durable if it cannot recover that block after the persistence point the service claims.

FILE_DONE means the receiver has successfully completed and published the verified object according to local policy.

19.7 Pause and cancel #

Reliable file transfer SHOULD support:

• pause;
• resume;
• cancel/abort;
• restart recovery.

Pause MUST stop future queued transfer traffic after the currently unavoidable in-flight transmission.

Cancel MUST be idempotent.

Part VIII — Service 5: Network awareness #

20. Presence #

Presence is the foundation of JSQ network awareness.

A presence observation says:

“This station appears to be reachable through this observed bearer/path at approximately this time.”

Presence MAY come from:

• an explicit presence/sounding transmission;
• a heartbeat;
• admitted ordinary traffic;
• a verified transaction;
• a remote heard-list report;
• relay evidence.

Presence records SHOULD include, when available:

callsign
timestamp
provider/bearer
frequency/channel
direct/relayed/reported classification
signal metrics
service capabilities
availability/status
group summary
mail-waiting indication

Presence SHALL expire or become stale unless refreshed.

Automatic presence transmissions MUST be:

• configurable;
• suppressible;
• jittered;
• rate-limited;
• deferred by higher-priority traffic.

21. Heard list #

Every accepted reception MAY update the local heard list.

A heard record SHOULD retain:

callsign
first_heard
last_heard
last and best signal metrics
provider/bearer
frequency/channel when known
direct/relayed status
capabilities
link quality
recent activity

A remote HEARD_LIST action returns a bounded set of observations according to operator policy and channel limits.

22. Network topology #

JSQ maintains a directional graph of network observations.

An edge means:

listener <- source

with metadata such as:

time
provider/bearer
frequency/channel
SNR
Q
Link Quality
direct or reported
observation source
freshness

Edges are directional and MUST NOT be silently merged into a symmetric link.

If A hears B strongly and B hears A weakly, both facts are preserved.

22.1 Passive mapping #

Ordinary receptions continuously add local topology evidence without additional airtime.

This is the preferred source of network knowledge.

22.2 Active mapping crawl #

A JSQ application MAY provide a user-initiated Map the network operation.

The crawl MAY query neighbors for their heard lists and follow bounded relay paths to discover remote edges.

Active mapping MUST be:

• explicit, not automatic by default;
• query-budgeted;
• depth-limited;
• cancellable;
• rate-limited;
• scheduled through normal channel-access rules.

The UI SHOULD estimate airtime cost before a significant crawl begins.

23. Link Quality #

JSQ distinguishes physical signal strength from successful communication.

Recommended concepts:

• SNR — physical signal-to-noise evidence where calibrated;
• Q — per-reception decoder quality/confidence;
• LQ — station-level evidence of whether recent traffic actually gets through.

A route algorithm SHOULD NOT use raw SNR alone.

Link Quality MAY incorporate:

• successful/failed reception outcomes;
• integrity success;
• continuity;
• Q;
• retry history;
• freshness.

Until calibrated for a provider, LQ SHOULD remain advisory and MUST NOT silently drive high-impact automation.

Part IX — Relay and route services #

24. JSQ application relay #

JSQ application relaying is distinct from link-layer digipeating.

A JSQ relay:

• 1.receives a JSQ semantic unit or object;
• 2.validates required integrity/evidence;
• 3.applies relay policy;
• 4.records provenance;
• 5.transmits a new bearer-specific representation toward the next destination.

A relay MAY receive on one provider and transmit on another.

Cross-provider forwarding MUST preserve immutable JSQ identity and object content.

Example:

FSQ++ -> JSQ relay -> AX1200
AX1200 -> JSQ relay -> FSQ++

24.1 Manual relay #

The operator MAY explicitly choose:

Send via <relay callsign>

Manual relay is a Core JSQ network function.

24.2 Relay provenance #

Relayed traffic MUST retain:

• original origin;
• final destination;
• current/previous relay information;
• stable Message/Object ID.

A relay MUST NOT rewrite the origin so that the relay appears to have authored the message.

25. Route recommendation #

JSQ SHALL permit applications to recommend the best known route to a destination.

A route recommendation is advisory, not a guarantee.

Candidate routes SHOULD be ranked using a cost model including:

hop count
estimated airtime
provider/bearer throughput
link quality
retry history
freshness
congestion
relay willingness
required service capability
custody availability when relevant

A strong but stale path SHOULD NOT automatically outrank a slightly weaker fresh path.

A route that lacks a required service capability MUST NOT be recommended for that service.

Examples:

• a path suitable for live chat may not support formal custodial mail;
• an external KISS path may not supply reliable channel metrics;
• a relay may support text but reject files;
• a mailbox may accept mail but not application relay.

25.1 Measured vs inferred #

Route displays MUST distinguish:

• directly measured edges;
• remotely reported edges;
• inferred paths;
• previously successful paths.

25.2 Loops and bounds #

Automatic forwarding MUST use:

• hop/TTL limits;
• duplicate suppression;
• loop detection;
• expiry;
• congestion policy.

A station MUST reject a source route that already contains its own identity in a way that would create a loop.

Part X — Service scheduling and half-duplex discipline #

26. Shared transmit resource #

All JSQ services sharing one physical radio/PTT domain MUST coordinate through one transmit scheduler.

Chat, mail, files, automatic actions, presence, mapping, and relay MUST NOT independently assume they own the radio.

26.1 Suggested priority classes #

From highest to lowest:

• 1.in-progress protocol response required to close a transaction safely;
• 2.operator-initiated live/verified chat;
• 3.delivery receipts and custody stabilization;
• 4.operator-initiated mail/file control;
• 5.continuing reliable file blocks;
• 6.mail announcements;
• 7.presence;
• 8.network mapping/background discovery.

An implementation MAY refine priorities but MUST prevent starvation and uncontrolled background airtime.

26.2 Channel access #

When the bearer provides reliable busy/clear state, JSQ automatic traffic SHOULD wait for channel-clear policy.

When channel state is unknown, the service MUST use the provider's documented conservative access policy and MUST NOT claim that the channel was verified clear.

26.3 Busy-paused timers #

Where a protocol response timer represents time in which the peer could reasonably answer, known third-party channel-busy time SHOULD be excluded.

A separate absolute watchdog MAY still terminate a transaction that makes no progress for an operator-defined maximum period.

Part XI — Persistence and restart semantics #

27. Durable services #

The following SHOULD survive application restart when active:

• formal mail;
• parked Quick Mail;
• mail custody;
• reliable file receive state;
• reliable file transmit/resume state;
• delivery receipts/tombstones;
• network observation history;
• conversation history.

Live unverified chat need not survive as an active protocol transaction after restart, although its history SHOULD.

27.1 Restart rule #

A restart MUST regress transient protocol states to a safe durable state rather than pretending an in-flight transmission succeeded.

Examples:

transmitting -> queued or failed/retryable
mail delivering -> parked
file awaiting status -> resynchronization/re-offer
managed provider running -> disconnected until lifecycle is re-established

The application MUST start with PTT unkeyed.

Part XII — Integrity, authorization, and safety #

28. Integrity #

Different services require different integrity levels.

28.1 Live unverified #

May be shown without end-to-end CRC verification, provided the UI indicates uncertainty and the bearer admission policy permits display.

28.2 Automatic actions #

An automatic action MUST NOT execute from a reception that fails the bearer/service admission policy.

A partially decoded request may be shown to the operator but MUST NOT trigger an automatic response unless the action's integrity/evidence requirement is satisfied.

28.3 Verified chat #

Requires end-to-end message integrity and final acknowledgment.

28.4 Formal mail #

Requires stable identity, end-to-end content integrity, duplicate suppression, and durable custody rules when custody is used.

28.5 Reliable file #

Requires block integrity plus whole-object integrity.

29. Authentication and privacy #

JSQ does not equate a callsign with authenticated legal identity.

A callsign CRC, AX.25 source address, KISS source, or self-announced public key does not prove license ownership.

Optional public digital signatures MAY be defined or used to establish consistency of a public message without encrypting it.

Applications SHOULD treat received text, files, filenames, forms, and metadata as untrusted input.

Received content MUST NOT be executed automatically.

File paths MUST be sanitized and path traversal rejected.

Part XIII — Application behavior #

30. Reference user experience #

JSQ is intended to feel like a modern messaging service over radio.

The operator should be able to:

• 1.start the radio/provider;
• 2.see stations currently/recently reachable;
• 3.open a station conversation;
• 4.type and send live or verified chat;
• 5.join an @GROUP;
• 6.run station actions from a menu rather than typing punctuation;
• 7.leave Quick Mail when someone is absent;
• 8.compose Formal Mail when custody or verified delivery matters;
• 9.send a Quick File or Reliable File;
• 10.see network topology and recommended relay paths.

Raw protocol syntax MAY remain available in diagnostics, but normal operation MUST NOT require it.

31. Recommended application surfaces #

A complete JSQ application SHOULD provide:

Chats
Inbox
Files
Network
Channel
Radio
Settings
Diagnostics

Chats #

• directed conversations;
• group conversations;
• Live/Verified send mode;
• Quick Mail action;
• Quick File action;
• station actions;
• Send via relay;
• visible automatic activity.

Inbox #

• Quick and Formal Mail;
• compact sender/subject/preview list;
• unread state;
• custody/delivery indicators;
• Holding/Custody view.

Files #

• quick file history where retained;
• reliable transfers;
• progress;
• pause/resume/cancel;
• integrity state.

Network #

• heard list;
• presence;
• topology graph;
• route recommendation;
• Map the network action;
• relay shortcuts.

Channel #

• raw/admitted/rejected traffic according to provider evidence;
• visibility into unaddressed traffic when lawful and supported.

Radio #

• provider selection;
• provider-specific configuration;
• audio/PTT only when applicable;
• rig/CAT independently where supported;
• provider health;
• signal/channel state.

Part XIV — Conformance profiles #

32. JSQ service conformance #

Rather than requiring every modem/provider to implement every service, JSQ defines service profiles.

32.1 JSQ Chat #

Required:

• station identity;
• Live Chat;
• presence/heard tracking;
• basic automatic station actions.

32.2 JSQ Verified #

Adds:

• Verified Chat;
• stable Message IDs;
• end-to-end ACK/receipt;
• duplicate suppression.

32.3 JSQ Groups #

Adds:

• self-enrolled named groups;
• group chat;
• ACK-storm prevention.

32.4 JSQ Mail #

Adds:

• Quick Mail;
• Formal Mail;
• persistence;
• announce/query/fetch;
• end-to-end delivery receipts.

32.5 JSQ Custody #

Adds:

• third-party mail custody;
• durable-before-acknowledge;
• expiry;
• redundant-custodian duplicate suppression.

32.6 JSQ Files #

Adds:

• Quick File;
• Reliable File;
• polled selective-repeat ARQ;
• whole-object integrity;
• resume.

32.7 JSQ Network #

Adds:

• presence;
• heard reports;
• topology;
• relay;
• route recommendations;
• route provenance.

A provider/peer advertises only the profiles it can actually complete.

Part XV — Bearer adaptation requirements #

33. Semantic preservation #

A bearer adapter SHALL preserve JSQ service meaning even when its wire representation differs.

For every semantic unit the adapter MUST define:

• how source and destination are represented;
• how service kind is identified;
• maximum payload/fragmentation;
• integrity evidence;
• duplicate identity;
• transmit-completion meaning;
• busy/channel evidence;
• response timing behavior;
• capability discovery;
• relay provenance;
• unsupported-service behavior.

33.1 Legacy FSQ compatibility adapter #

A legacy FSQ adapter MAY translate structured JSQ actions into legacy punctuation and translate decoded legacy actions back into semantic JSQ requests.

The adapter MUST preserve the distinction between:

• legacy best-effort behavior;
• JSQ reliable/verified semantics.

It MUST NOT claim verified JSQ delivery merely because a legacy FSQ transmission completed.

33.2 FSQ++ adapter #

FSQ++ SHOULD carry JSQ services using its structured envelopes and first-party modem evidence while retaining legacy interoperability where intended.

33.3 AX1200 native adapter #

Native AX1200 SHOULD carry JSQ semantics over AX.25/OFQ2 while exposing first-party modem channel state, signal metrics, and RF-completion evidence where available.

33.4 KISS adapters #

BLE, serial, and TCP KISS SHALL feed the same AX.25/OFQ2 JSQ application runtime.

KISS transport choice MUST NOT create different chat/mail/file service implementations.

Exactly one physical KISS client may own an attached runtime at a time.

33.5 Managed Dire Wolf adapter #

Managed Dire Wolf SHOULD:

• generate a private configuration;
• start and monitor Dire Wolf;
• connect through a local documented interface;
• reuse the normal AX.25/OFQ2 JSQ runtime;
• fail closed if the process disappears.

Generic TCP KISS remains a separate outsourced-provider option.

Part XVI — Versioning and extensions #

34. JSQ versioning #

JSQ Core semantic versioning is independent of individual modem/provider versions.

A provider may change its DSP without changing JSQ service semantics.

A JSQ Core version change is required when interoperable service meaning or required semantic fields change incompatibly.

Bearer profile versions control bearer-specific serialization.

34.1 Extension rule #

New services SHOULD be added as optional capabilities.

Unknown optional extensions MUST be safely ignorable.

A new provider MUST NOT require changes to existing JSQ service semantics merely to accommodate its modem design.

Part XVII — Conformance testing #

35. Cross-provider equivalence #

For each service implemented over more than one bearer, tests SHOULD prove semantic equivalence.

At minimum:

Chat #

• same Live Chat object reaches application layer;
• same Verified Chat delivery states;
• duplicate suppression identical.

Actions #

• FSQ punctuation adapter and structured packet adapter produce the same semantic action;
• unsafe/malformed requests never auto-execute.

Mail #

• same park/announce/query/fetch/ACK state machine;
• same durable-before-release rule;
• no duplicate inbox insertion;
• restart recovery.

Files #

• same offer/accept/data/poll/status/finish/done semantics;
• loss recovery;
• pause/resume;
• restart resume;
• hash failure cannot complete.

Network #

• same station and edge model;
• directional links preserved;
• provider/bearer metadata retained;
• relay paths preserve origin and destination.

36. Required field tests #

A JSQ release SHOULD include real-radio validation of:

• live unverified conversation;
• verified chat with lost frame/retry;
• group chat without ACK storm;
• each automatic FSQ-derived action where supported;
• Quick Mail to an absent/reappearing station;
• Formal Mail through a third-party custodian;
• redundant custody without duplicate delivery;
• Quick File;
• Reliable File with loss and resume;
• passive topology mapping;
• explicit network crawl;
• manual relay;
• route recommendation over asymmetric links;
• at least one cross-provider/cross-bearer relay when available.

Part XVIII — Reference implementation mapping #

37. OpenJSQ mapping #

OpenJSQ is the reference application implementing JSQ.

The intended architecture is:

OpenJSQ UI and persistence
           |
           v
JSQ common services
 chat / actions / groups
 mail / custody
 files / ARQ
 presence / topology / routing
           |
           v
normalized bearer/runtime interface
           |
   +-------+--------------------+--------------------+
   |       |                    |                    |
FSQ++   AX1200 native     AX.25/OFQ2 runtime     JG25 native
                            |
                    +-------+--------+
                    |       |        |
                  BLE     Serial    TCP
                  KISS    KISS      KISS
                                      |
                              managed Dire Wolf
                              or external server

Each bearer's on-air form is published separately: FSQ++ in FSQ_FAST_PUBLIC_SPEC.md (waveform, alphabet, framing, integrity) and JSQ_PUBLIC_PROTOCOL_SPEC.md (service bodies); AX1200 in JSQ_PUBLIC_PROTOCOL_SPEC.md Part I; JG25 in JG25_SPECIFICATION.md.

No service should be duplicated merely because the lower provider changes.

Appendix A — Legacy FSQ action mapping #

This appendix defines the compatibility intent, not a requirement that non-FSQ bearers use punctuation.

Appendix B — Service state examples #

B.1 Verified Chat #

queued
  -> waiting_for_channel
  -> transmitting
  -> rf_sent OR handed_to_device
  -> awaiting_verification
  -> awaiting_delivery_receipt
  -> delivered

failure branches:
  -> retrying
  -> failed
  -> cancelled
  -> expired

B.2 Quick Mail #

draft
  -> parked
  -> announced
  -> fetching
  -> delivered

Restart of announced or fetching safely returns to parked unless durable evidence establishes a later state.

B.3 Formal custodial mail #

draft
  -> queued
  -> stored_local
  -> custody_offer
  -> stored_by_mailbox
  -> forwarding
  -> delivered

stored_by_mailbox is never displayed as final delivery.

B.4 Reliable File #

offered
  -> accepted
  -> sending_burst
  -> awaiting_status
  -> sending_burst
  -> finishing
  -> complete

Any recoverable restart returns through offer/resynchronization using durable transfer identity and receive state.

Appendix C — Initial provider capability expectations #

These are reference expectations, not permanent limits. A provider may expose richer evidence through a documented extension.

Appendix D — Design lineage #

This specification consolidates and supersedes the applicable concepts from:

• JSQ_Full_System_Protocol_Specification_v0.3.md
• JSQ_Full_System_Protocol_Specification_v0.4.md
• JSQ_v0.4.1_Core1_Wire_Revision.md
• JSQ_Full_System_and_Protocol_Specification_v0.5.md
• JSQ_Core_Protocol_and_Service_Specification_v0.3.1.md
• JSQ-FM_Transport_Profile_v0.3.1.md
• JSQ-HF_Transport_Profile_v0.3.1.md
• OpenFSQ_Reference_Implementation_Specification_v0.3.1.md
• OpenJSQ_JSQ_Unification_and_Rename_Plan.md
• FSQ_PlusPlus_Protocol_and_Service_Specification_v0.1.md
• FSQ_PP_Protocol_Service_Specification_v0.2.md
• OpenJSQ transport/OPENFSQ_MODEM_AGNOSTIC_ARCHITECTURE.md
• OpenJSQ transport/JSQ_FILE_ARQ.md
• OpenJSQ transport/JSQ_MAIL_CUSTODY_STAGE5_IMPLEMENTATION_PLAN.md
• OpenJSQ docs/NETWORK_MAPPING.md
• OpenJSQ modem-provider architecture handoffs

The important consolidation decision is:

JSQ owns service meaning. Modems and bearer adapters own physical/link representation. OpenJSQ is one application implementing the JSQ service model.

Earlier JSQ drafts that defined JSQ9 or another physical waveform as part of JSQ Core are historical design material. Their physical-layer ideas may survive in separate modem specifications, but they are not requirements of JSQ Transport Service conformance.

Appendix E — Items intentionally left to bearer profiles #

The following are outside this core specification and MUST be specified by each bearer profile where applicable:

• physical modulation;
• tone spacing;
• baud/symbol rate;
• FEC coding;
• interleaving;
• packet framing;
• AX.25 details;
• KISS link details;
• RF occupied bandwidth;
• audio sample rate;
• PTT lead/tail;
• CSMA/p-persistence details;
• modem-level retransmission;
• modem-specific channel-busy algorithm;
• provider-specific SNR calibration;
• provider-specific maximum payload;
• provider-specific regulatory/channel profile.

This separation is deliberate and is the defining architectural boundary of JSQ.

End of JSQ Transport Service Specification v1.0-draft