Home /Modules/http-3.0/STATION-SIGNALING-SPEC.md

STATION-SIGNALING-SPEC.md

http-3.0/station/STATION-SIGNALING-SPEC.md · 204 line(s) · markdown

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:

Both use the same classifier so the Station's judgment is identical whether it runs in the kernel hook or in userland.

1. Roles

RoleWhoResponsibility
Party A / Party Bthe two negotiating clientsemit signaling segments stating intent
Stationa Router on the pathclassify 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):

FlagBitSignaling use
SYN0x02begin a negotiation turn
ACK0x10acknowledge / accept the peer's premise
URG0x20this segment carries a premise signal; magnitude in the URGENT count
PSH0x08request the Station to witness/record now
RST0x04abort → DISASTROUS
FIN0x01orderly 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:

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

EncodingVerbMeaning
HOP = DIST + 0HOLDwitness/record at this station; do not advance the premise
HOP = DIST + 1ADVANCEmove the premise forward one phase
HOP = DIST − 1CANCELwithdraw / 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):

  1. START — a party's opening premise ("here is what I propose to send").
  2. INTERMEDIARY — a mediated or counter premise (the middle of the manualog).
  3. CANCELLING — withdrawal of a premise.

The premise selected by a signal is a function of the 8-URG signal and the hop verb:

urg_unitshop verbpremise
1..8ADVANCE (DIST+1)START if none open, else INTERMEDIARY
1..8HOLD (DIST+0)re-assert the current premise (witnessed, not advanced)
anyCANCEL (DIST−1)CANCELLING
0anyno 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:

ConditionSignaled byMeaning
INTENTIONALURG set, urg_units≥1, ADVANCE/HOLDa deliberate premise step
LEGALURG+ACK with full-scale urg_units==8a legally-framed assertion (legal dressing attaches)
WARNINGURG+PSHa caution; the peer must ACK before further advance
EMERGENCYURG+PSH+ACK, urg_units==8time-critical; expedited witnessing
NONEno URGnot 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

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:

  1. Records are append-only within a session; sequence numbers are monotonic.
  2. A session is sealed on CLOSE; sealed records are not mutated.
  3. 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:

ioctlDirectionEffect
SL_IOC_OPENIOWR sl_session_view_topen a witnessed session; kernel assigns session_id
SL_IOC_SIGNALIOWR sl_signal_tfeed one signaling event; returns the classified sl_record_t
SL_IOC_QUERYIOWR sl_session_view_tread a session's current witnessed view
SL_IOC_CLOSEIOW uint64_tseal 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