# 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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
@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

| JSQ action | Legacy FSQ meaning | Expected JSQ behavior |
|---|---|---|
| `SIGNAL_REPORT` | `?` | Return current/recent signal report using the best honest metric available |
| `HEARD_LIST` | `$` | Return bounded recent heard-station observations |
| `LOCATION` | `@` | Return configured QTH/grid/location according to operator policy |
| `STATUS` | `&` | Return configured station status/QTC text |
| `VERSION` | `^` | Return software/protocol/provider summary |
| `WAKE` | `*` | Request operator attention or wake/attention state; no unsafe remote control |
| `ECHO` | `!` | Return supplied short text promptly |
| `DELAYED_ECHO` | `~` | Return supplied short text after a bounded delay |
| `STORE` | `#` | Compatibility action mapped to quick mail or stored object service |
| `RETRIEVE` | `+` | Compatibility action mapped to mail/file retrieval |
| `ALERT` | `|` | Raise a visible local alert with supplied public text |
| `LINK_FASTER` | `>` | Suggest a faster supported link profile; recipient decides |
| `LINK_SLOWER` | `<` | Suggest a more robust/slower supported link profile; recipient decides |
| `RELAY` | `;` | Request JSQ application relay |
| `RELAYED_FROM` | `[` | Preserve relay provenance; not a user action by itself |
| `IMAGE_SEND` | `%` | Compatibility action mapped to the generic file service with image content type |
| `UNSUPPORTED` | `-` | Reserved/unsupported; MUST NOT execute arbitrary behavior |

### 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:

```text
message_id
origin
final_recipient
body
created_time
expiry
```

Optional fields:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
listener <- source
```

with metadata such as:

```text
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:

```text
FSQ++ -> JSQ relay -> AX1200
AX1200 -> JSQ relay -> FSQ++
```

### 24.1 Manual relay

The operator MAY explicitly choose:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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.

| Legacy trigger | JSQ semantic action |
|---|---|
| space | Live Chat |
| `?` | Signal Report |
| `$` | Heard List |
| `@` | Location |
| `&` | Status/QTC |
| `^` | Version |
| `*` | Wake/Attention |
| `!` | Echo/Repeat |
| `~` | Delayed Echo |
| `#` | Store / Quick Mail compatibility |
| `+` | Retrieve Mail/File compatibility |
| `|` | Alert |
| `>` | Link Faster Suggestion |
| `<` | Link Slower Suggestion |
| `;` | Relay |
| `[` | Relayed-from provenance |
| `%` | Image through File service |
| `-` | Reserved/unsupported |

---

# Appendix B — Service state examples

## B.1 Verified Chat

```text
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

```text
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

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

`stored_by_mailbox` is never displayed as final delivery.

## B.4 Reliable File

```text
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

| Provider | Class | Host owns DSP/audio | Boundary | TX completion | Channel/SNR evidence |
|---|---|---:|---|---|---|
| FSQ++ native | Native | Yes | audio/internal events | `rf_complete` | Rich |
| AX1200 native | Native | Yes | audio/internal frames | `rf_complete` | Rich |
| JG25 native | Native | Yes | audio/internal frames | `rf_complete` | Rich |
| Managed Dire Wolf | Direct-Control | No DSP; host manages process | KISS/managed stream | normally `handed_to_device` | Limited unless extended |
| BLE KISS TNC | Outsourced | No | KISS frames | `handed_to_device` | Usually unknown |
| Serial KISS TNC | Outsourced | No | KISS frames | `handed_to_device` | Usually unknown |
| TCP KISS TNC | Outsourced | No | KISS frames | `handed_to_device` | Usually unknown |

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**