SLeeLa HTTP 3.0 — Station Signaling Specification
Series: J-STA-0001 · Status: Normative specification, rev 1.0.0 Layer: below the HTTP 3.0 application protocol; rides on TCP/IP control semantics.
0. Purpose
Before two clients exchange any HTTP 3.0 payload, they must be able to negotiate what they will actually send, and a Router on the path must be able to witness and record that negotiation as an International Station.
This specification defines how that negotiation is signaled using TCP/IP control semantics (the URG/ACK/SYN/RST/FIN/PSH flag family) plus a hop-distance encoding, how a Router classifies each signal into a condition, how the negotiation advances through a three-phase premise, and how the Station witnesses and stores the outcome — including the terminal states UNCLEAR, HUNG-UP, and DISASTROUS.
Because setting raw TCP control flags requires privileged, kernel-level access, the normative behavior is split:
- A kernel driver (
http-3.0/kernel/) inspects/marks TCP control flags on signaling segments via a Netfilter hook and exposes a character-device ioctl API — the known API for direct calls. - Userland (
http-3.0/station/) drives the negotiation state machine through that API, or through an equivalent in-process simulation backend when raw-socket privileges are unavailable.
Both use the same classifier so the Station's judgment is identical whether it runs in the kernel hook or in userland.
1. Roles
| Role | Who | Responsibility |
|---|---|---|
| Party A / Party B | the two negotiating clients | emit signaling segments stating intent |
| Station | a Router on the path | classify signals, advance premises, witness + store, decide terminal state |
The Station is an intermediary and witness, not a party: it never invents a premise, it records what the parties signal.
2. The wire: TCP control flags as signals
Signaling segments carry no application payload; meaning is in the flags
(RFC 793 bit positions; see station_abi.h):
| Flag | Bit | Signaling use |
|---|---|---|
SYN | 0x02 | begin a negotiation turn |
ACK | 0x10 | acknowledge / accept the peer's premise |
URG | 0x20 | this segment carries a premise signal; magnitude in the URGENT count |
PSH | 0x08 | request the Station to witness/record now |
RST | 0x04 | abort → DISASTROUS |
FIN | 0x01 | orderly close of a party's participation |
2.1 The URGENT count (the "8 URG")
The URGENT pointer field carries a small integer urg_units in 0..8
(SL_STATION_URG_MAX = 8). It selects the premise bank and intensity:
urg_units == 0— no premise carried (pure ACK/keepalive).1..8— a premise signal; 8 URG is the full-scale signal that, combined with the hop verb, selects among the three premises (§4).
3. HOP distance encoding (DIST±N)
Every Station knows its own hop index on the path, DIST. A signaling
segment carries a hop field; the relation of that field to DIST is the verb
(see sl_hop_verb_t):
| Encoding | Verb | Meaning |
|---|---|---|
HOP = DIST + 0 | HOLD | witness/record at this station; do not advance the premise |
HOP = DIST + 1 | ADVANCE | move the premise forward one phase |
HOP = DIST − 1 | CANCEL | withdraw / roll back the current premise |
hop_delta = hop − DIST is what the driver reports; only −1, 0, +1 are
meaningful here.
4. The three-phase premise
A negotiation turn moves through three premises (sl_premise_t):
- START — a party's opening premise ("here is what I propose to send").
- INTERMEDIARY — a mediated or counter premise (the middle of the manualog).
- CANCELLING — withdrawal of a premise.
The premise selected by a signal is a function of the 8-URG signal and the hop verb:
| urg_units | hop verb | premise |
|---|---|---|
| 1..8 | ADVANCE (DIST+1) | START if none open, else INTERMEDIARY |
| 1..8 | HOLD (DIST+0) | re-assert the current premise (witnessed, not advanced) |
| any | CANCEL (DIST−1) | CANCELLING |
| 0 | any | no premise (bare ACK) |
So the triple start premise → intermediary premise → cancelling premise is exactly: an ADVANCE that opens START, a later ADVANCE that yields INTERMEDIARY, and a CANCEL that yields CANCELLING.
5. Conditions
The Station classifies each premise-bearing signal into a condition
(sl_condition_t), from the flag combination:
| Condition | Signaled by | Meaning |
|---|---|---|
| INTENTIONAL | URG set, urg_units≥1, ADVANCE/HOLD | a deliberate premise step |
| LEGAL | URG+ACK with full-scale urg_units==8 | a legally-framed assertion (legal dressing attaches) |
| WARNING | URG+PSH | a caution; the peer must ACK before further advance |
| EMERGENCY | URG+PSH+ACK, urg_units==8 | time-critical; expedited witnessing |
| NONE | no URG | not a premise signal (bare ACK/keepalive) |
A condition is descriptive evidence, not authority: a LEGAL condition records a legal framing, it does not adjudicate legality (consistent with the HTTP 3.0 guiding principle that context is never authority).
6. Manualog
The negotiation is a manualog: a two-way, subsystem-backed dialog in which both parties and their subsystems participate. Each party maintains its own premise state; the Station maintains the joint witnessed view. A turn is:
Party A --signal(cond,premise,verb)--> Station --witness--> record
Party B --signal(cond,premise,verb)--> Station --witness--> record
... alternating, until agreement or a terminal state ...
Agreement (CLEAR) requires both parties to have advanced to a matching
premise and each to have ACKed the other (§7).
7. Witnessed state machine
The Station tracks a session state (sl_state_t):
IDLE ──open──> OPEN ──both parties ACK a matching INTERMEDIARY──> CLEAR
│
├── a party sends CANCELLING then no re-open ──> UNCLEAR
├── a party FIN / goes silent past timeout ────> HUNG_UP
└── RST, or contradictory/illegal premises ────> DISASTROUS
- CLEAR — both parties agreed on what to send.
- UNCLEAR — ended without a definite agreement (e.g. dangling CANCELLING).
- HUNG-UP — a party stopped responding (FIN or silence past timeout).
- DISASTROUS —
RST/abort, or a party asserts a premise that contradicts a LEGAL condition already witnessed.
8. Witness and storage
For every accepted signal the Station stores a sl_record_t
(session, party, condition, premise, hop verb, timestamp, monotonic sequence).
The sealed record of a session is the Station's evidence of the negotiation.
Storage rules:
- Records are append-only within a session; sequence numbers are monotonic.
- A session is sealed on CLOSE; sealed records are not mutated.
- The stored terminal state is authoritative for "what the Station witnessed", distinct from any claim about what the parties intended (evidence, not truth).
9. Kernel / userland split (the "known API")
station_abi.h is the contract. The driver exposes /dev/sleela_station with:
| ioctl | Direction | Effect |
|---|---|---|
SL_IOC_OPEN | IOWR sl_session_view_t | open a witnessed session; kernel assigns session_id |
SL_IOC_SIGNAL | IOWR sl_signal_t | feed one signaling event; returns the classified sl_record_t |
SL_IOC_QUERY | IOWR sl_session_view_t | read a session's current witnessed view |
SL_IOC_CLOSE | IOW uint64_t | seal and close a session |
The kernel Netfilter hook parses TCP headers of signaling segments into
sl_signal_t and runs the shared classifier; userland may instead submit
sl_signal_t directly through SL_IOC_SIGNAL (or the simulation backend),
yielding identical classification.
10. Governing principle
The Station makes a negotiation legible and witnessed without becoming a party to it. It records conditions, premises, and outcomes as evidence — never as adjudication — so two clients can agree on what to send, and a Router can stand as an International Station that remembers how they got there.
Reference layout
http-3.0/
station/
station_abi.h the driver<->userland contract (this spec's numbers)
station_classifier.{h,c} shared Station judgment (kernel + userland)
station_session.{h,c} session/state machine + witnessed store
station_backend.{h,c} device (ioctl) OR simulation transport
station_demo.c two-party manualog trace
test_station.py Python parity/behavior tests
kernel/
sleela_station.c the Linux kernel module (char dev + Netfilter)
Kbuild, Makefile kernel build