docs(protocol): airlock server black-box findings
Transfer independently black-box-verified server behavior from a source-assisted research phase conducted outside this repository. Only a sanitizer-candidate report of black-box findings and the packet captures it referenced were admitted; no upstream source, tests, history, harnesses, build trees, result files or source-assisted analysis crossed the boundary. Provenance and the boundary discipline are recorded in docs/clean-room/CLEANROOM_NOTES.md. New upstream robustness defect (Section 22.5). An open selecting timestamps while omitting the Clock parameter is accepted with a valid token and no Clock echoed, and the first echo on that session is fatal to the server process, taking unrelated sessions on the same process with it. An explicit Clock=0 is instead rejected at open, so parameter presence is externally meaningful. Recorded as an observed defect with a must-not-crash recommendation; the clean server's resolution is deliberately left to the implementation work. Also established or strengthened: - the idle grace and maximum-duration grace are fixed additive margins across the settings swept, and the maximum-duration clock starts at the first echo that is actually served; - a rate-limited request is the only tested drop class that keeps a session alive, and in one documented configuration a conforming client can observe the difference; - a post-deadline packet of several tested classes consumes an expired session's one remaining reply, including packets that are themselves dropped; - the reply-length cap is the bind interface's MTU on the interfaces where it was reachable, and a length the host cannot transmit ends the process; - DSCP marking follows the session, with unmarked open replies and no cross-session leakage across interleaved sessions; - repeated tags are last-valid-wins, with invalid-duplicate handling scoped to the orders actually tested, and unknown tag values are consumed as varints. Three captures were admitted, each rewritten to the container convention already used here and verified byte-identical in packet data and timestamps: server-clock-absent (3 packets), server-expiry-consumption (14) and server-dscp-interleaved (32). Two further captures were reviewed and rejected as redundant or unsupporting; their textual results were kept instead. Host-specific figures are labelled as such throughout, upstream defects are not promoted to protocol requirements, observations are separated from inferences and from recommendations, and no implementation policy is chosen here. The client specification gains matching refinements where the two compatibility baselines would otherwise state a lifecycle or marking rule differently. Documentation and evidence only; no production code changed.
This commit is contained in:
8 files changed
+1715
-102
No files matched your search
@@ -297,8 +297,9 @@ Two upstream robustness defects are recorded in the server specification
|
||||
reachable from ordinary client traffic and a clean implementation has to decide
|
||||
what to do instead. They are stated as observed outcomes plus **robustness
|
||||
recommendations for the clean implementation** — explicitly not as
|
||||
interoperability requirements, since no conforming client can observe which
|
||||
choice a server made — with no description of the internal cause.
|
||||
interoperability requirements. A conforming client cannot trigger the
|
||||
absent-Clock defect through conforming negotiation, but can observe a
|
||||
process-wide outage if another peer triggers it; no internal cause is described.
|
||||
|
||||
### Server-Pass Sanitization Audit
|
||||
|
||||
@@ -463,15 +464,17 @@ and removed.
|
||||
|
||||
### Statement classification
|
||||
|
||||
The outgoing documents now separate five kinds of statement and never conflate
|
||||
The outgoing documents now separate six kinds of statement and never conflate
|
||||
them: interoperability requirement; black-box observed upstream behavior;
|
||||
upstream policy or default; robustness recommendation for the clean
|
||||
implementation; and source-assisted historical conclusion.
|
||||
black-box inference; upstream policy or default; robustness recommendation for
|
||||
the clean implementation; and source-assisted historical conclusion.
|
||||
|
||||
Specific reclassifications made in this pass:
|
||||
|
||||
- Surviving a failed reply send is a **robustness recommendation**, not a
|
||||
protocol MUST. No conforming client can observe which choice a server made.
|
||||
protocol MUST. A process-wide failure can be visible to unrelated conforming
|
||||
clients, but that does not make a particular clean resilience policy an
|
||||
interoperability requirement.
|
||||
- Upstream's absence of session and per-peer bounds is **observed policy**, and
|
||||
the documents now say explicitly that it is not something a compatible server
|
||||
should reproduce. The clean server is expected to be bounded; the shape of that
|
||||
@@ -610,3 +613,243 @@ macOS Finder metadata file previously listed here is no longer present; the
|
||||
exclusion still stands, since Finder can recreate one at any time. Re-verified
|
||||
2026-08-11: the dotted directory is the only ignored entry under `docs/`, and no
|
||||
Finder metadata file exists anywhere in the outgoing tree.
|
||||
|
||||
---
|
||||
|
||||
## Server Deep-Dive Airlock (2026-08-12)
|
||||
|
||||
This section records **provenance and boundary discipline** for the material added
|
||||
on 2026-08-12. It is not implementation archaeology, and it deliberately contains
|
||||
no detail about what the contaminated-side work looked at.
|
||||
|
||||
### What happened outside this repository
|
||||
|
||||
A further source-assisted research phase on the upstream server took place in a
|
||||
separate contaminated workspace, outside this repository and outside `docs/`. As
|
||||
in the earlier passes, that workspace held upstream source, upstream tests,
|
||||
upstream history, source-assisted analysis, purpose-built harnesses, build trees,
|
||||
binaries, raw result files, server logs, and black-box packet evidence. The
|
||||
overwhelming majority of it is not admissible here and did not cross.
|
||||
|
||||
### What was admitted, and what the airlock agent was allowed to see
|
||||
|
||||
The transfer was performed by an agent working in this clean repository under an
|
||||
explicit airlock restriction. Its **entire** permitted view of the contaminated
|
||||
workspace was:
|
||||
|
||||
1. a single sanitizer-candidate report of **independently black-box-verified**
|
||||
findings — written to be transferable without upstream source access, and
|
||||
containing no source snippets, filenames, function or type names, or internal
|
||||
structure; and
|
||||
2. the black-box packet captures that report referenced, for the purposes of
|
||||
confirming the packet-level evidence, checking container metadata, and copying
|
||||
suitable files into the clean evidence set.
|
||||
|
||||
The agent was explicitly **prohibited** from inspecting, and did not inspect:
|
||||
|
||||
- the source-assisted findings report;
|
||||
- the unresolved/source question matrix;
|
||||
- the contaminated workspace's own README;
|
||||
- upstream source, upstream tests, or upstream git history;
|
||||
- any upstream checkout;
|
||||
- the research build trees and harnesses;
|
||||
- raw result files;
|
||||
- server logs.
|
||||
|
||||
It was further prohibited from searching the contaminated workspace at large. No
|
||||
recursive search, and no history or blame inspection, was performed there; the
|
||||
only accesses were direct reads of the two authorized items above. No raw result
|
||||
file was opened at all — the authorized report's own text proved sufficient for
|
||||
every statement transferred, so the narrowest available boundary was kept.
|
||||
|
||||
### What the boundary cost, deliberately
|
||||
|
||||
Several items in the authorized report were **not** transferred, and the reasons
|
||||
are worth recording because they are the boundary doing its job:
|
||||
|
||||
- An account of the order in which the server reports rejection reasons, taken
|
||||
from the server's own diagnostic output. Even though that output is externally
|
||||
emitted, it describes internal check ordering, and the clean specification had
|
||||
already deliberately replaced its admission narrative with a table of discard
|
||||
conditions plus the two precedence relationships that were verified on the
|
||||
wire. Re-importing an ordering narrative would have undone that work.
|
||||
- A statement that a session is removed before its close-flagged reply is sent.
|
||||
That is internal ordering; only its externally visible consequence crossed, and
|
||||
that consequence was already recorded.
|
||||
- A generalisation about which flag combinations are dropped on a data packet
|
||||
carrying a live token. The clean documents already carry a **more precise**
|
||||
account of the same behavior, and the broader statement would have weakened it.
|
||||
- An inference that the wire format offers no general extension channel. It
|
||||
crossed only as an explicitly labelled inference, alongside the byte encodings
|
||||
actually tested, rather than as a property of the format.
|
||||
|
||||
Where the authorized report was insufficient to support a clean statement, the
|
||||
statement was not made and the ambiguity was left standing. Nothing was resolved
|
||||
by consulting anything else.
|
||||
|
||||
### Classification discipline
|
||||
|
||||
Every new statement was classified before it was written, and the classification
|
||||
appears in the text: observed upstream behavior, black-box inference, upstream
|
||||
policy, protocol requirement, robustness recommendation for the clean
|
||||
implementation, or remaining unknown. The server specification's statement-level
|
||||
table was extended with the inference level and with the host-specific marking
|
||||
that several of these results require.
|
||||
|
||||
Two boundaries were held particularly deliberately:
|
||||
|
||||
- **An upstream defect was not promoted to a protocol requirement.** The most
|
||||
significant finding of this pass is an open request that upstream accepts and
|
||||
then faults on. It is recorded as an observed robustness defect with a
|
||||
must-not-crash recommendation for the clean server, and the documents state
|
||||
explicitly that reproducing the fault is not an interoperability requirement.
|
||||
- **No implementation policy was chosen.** The documents record what upstream
|
||||
does about an open that selects timestamps without a clock, about a negative
|
||||
Length, about out-of-range DSCP values, and about payload fill — and in
|
||||
each case say that the clean project's choice is a decision for the
|
||||
implementation work, not one this evidence settles. Those decisions remain open.
|
||||
|
||||
Host-specific figures — interface MTUs, the tested host's maximum outbound
|
||||
datagram size, interface-MTU effective-length decision knees, and platform
|
||||
handling of out-of-range DSCP values — are labelled as host-specific wherever
|
||||
they appear, so that none is mistaken for a protocol constant or compiled into an
|
||||
implementation.
|
||||
|
||||
### Captures admitted
|
||||
|
||||
Three captures crossed, each because it materially supports a finding that is new
|
||||
to the clean documents:
|
||||
|
||||
| File | Packets | What it proves |
|
||||
|------|---------|----------------|
|
||||
| `../protocol/captures/server-clock-absent.pcapng` | 3 | An open selecting timestamps with no Clock tag is answered with a token and no Clock parameter, and the first echo is the last packet in the exchange |
|
||||
| `../protocol/captures/server-expiry-consumption.pcapng` | 14 | Control and foreign-endpoint-first test: whether the first tested packet to reach an expired session emits a reply |
|
||||
| `../protocol/captures/server-dscp-interleaved.pcapng` | 32 | Four interleaved sessions with distinct DSCP values over three rounds, no cross-session leakage, unmarked open replies |
|
||||
|
||||
Each was reviewed before copying and rewritten into the container convention
|
||||
already used here: packet records and the rewriting tool's own version string
|
||||
only, with no capture comment, no section or interface description, no host, user
|
||||
or machine identification, no capture filter, and no filesystem path. Packet
|
||||
bytes and per-frame timestamps were **not** altered — for each file the full
|
||||
frame hexdump and the per-frame epoch timestamps were verified identical before
|
||||
and after, and the packet counts above are unchanged from the originals. The
|
||||
copied files were re-inspected afterwards and contain no string other than the
|
||||
rewriting tool's version.
|
||||
|
||||
Two further captures were reviewed and **not** admitted: one materially redundant
|
||||
with a capture already present, and one that on inspection did not demonstrate
|
||||
the behavior it was associated with. In both cases the textual result was kept
|
||||
instead, which is the preferred trade — a textual black-box result is better than
|
||||
an unnecessary addition to the evidence set. The reasoning is recorded in the
|
||||
verification report rather than only here.
|
||||
|
||||
### Review corrections applied before merge
|
||||
|
||||
Review of the airlock commit found several places where the wording claimed more
|
||||
than the admitted evidence supports. Each was narrowed to the observation, using
|
||||
the clean evidence set only — no contaminated material was consulted to resolve
|
||||
any of them:
|
||||
|
||||
- The reply-length cap is stated as byte-exact only for the two interfaces where
|
||||
that was measurable. The loopback row shows lengths up to 8000 emitted
|
||||
unclamped and nothing about a 16384-byte boundary, which this host cannot reach
|
||||
because a reply beyond roughly 9300 bytes ends the server first.
|
||||
- The interleaved DSCP capture is described as the three rounds it contains, and
|
||||
the separate observation that an open reply is unmarked on a listener that has
|
||||
already sent marked replies is attributed to the capture that actually shows it
|
||||
— an existing capture from the first pass — rather than to the new one, whose
|
||||
open exchanges all precede its first marked reply.
|
||||
- The fill-phase result is scoped to continuity across the sessions tested and
|
||||
across the tested IPv4 and IPv6 listeners, rather than asserting one stream
|
||||
shared by every session of a process. The recommendation previously drawn from
|
||||
it was **removed**: the default fill is a fixed public pattern, so its phase
|
||||
carrying across sessions discloses nothing about another peer, and the
|
||||
observation does not justify prescribing per-session fill state. The genuine
|
||||
no-cross-peer-data invariant was already stated for the no-fill mode and is
|
||||
untouched.
|
||||
- The must-not-crash advice no longer uses RFC 2119 keywords, which this document
|
||||
reserves for interoperability requirements. It is a robustness recommendation,
|
||||
and how strictly the implementing project binds itself to it belongs in that
|
||||
project's own guidance.
|
||||
- The presence-versus-zero rule is scoped to the reply direction. Requests do
|
||||
carry present zeros — `Length = 0` and `DSCP = 0` are accepted, and `Clock = 0`
|
||||
is rejected precisely because it is present.
|
||||
- The admission-table row for an open with no Clock now says the **open** is
|
||||
answered normally, not the session, which is what the evidence shows.
|
||||
- The maximum-duration origin refinement was carried into the client
|
||||
specification as well, since both documents are compatibility baselines and
|
||||
would otherwise state the lifecycle rule differently.
|
||||
|
||||
A second review round found five further places where the first correction pass
|
||||
had left an inconsistency behind, and these were fixed the same way:
|
||||
|
||||
- The must-not-crash advice is called a **recommendation** everywhere, including
|
||||
in the paragraph that follows it and in the behavioral vector, so that dropping
|
||||
the RFC 2119 keywords was not undone two sentences later.
|
||||
- The remaining-unknown entry on reply-length capping was brought into line with
|
||||
the corrected §9.2: exact only for the Ethernet and tunnel interfaces, with the
|
||||
loopback trial recorded as a lower bound.
|
||||
- The maximum-duration origin is stated for the **two** drop classes actually
|
||||
tested in the first-request position — oversized and foreign-endpoint — instead
|
||||
of generalising to any dropped request. Corrected in the specification, the
|
||||
vector and the verification report together.
|
||||
- The "first post-deadline request is still answered" rule is qualified to a
|
||||
request that would otherwise be served, since the same subsection then shows a
|
||||
foreign-endpoint packet being dropped while still consuming the release.
|
||||
- "Close packets are unmarked" is scoped to standalone datagrams. A
|
||||
server-initiated close is an echo reply carrying the session's marking, and
|
||||
both specifications now say so rather than leaving the two statements to
|
||||
contradict each other.
|
||||
|
||||
A final documentation-only review correction restricted the maximum-duration
|
||||
dropped-trigger result to the directly tested rate-limit case and corrected
|
||||
fill alternatives as observable but interoperability-equivalent. It used no new
|
||||
evidence or contaminated material.
|
||||
|
||||
None of these corrections required new evidence, and none changed a
|
||||
classification from observation to requirement or the reverse.
|
||||
|
||||
No binaries, source, harnesses, build trees, server logs, result files or
|
||||
research directories crossed.
|
||||
|
||||
### Clean-Room Compliance Checklist (Deep-Dive Airlock)
|
||||
|
||||
- [x] Source-assisted findings report never opened.
|
||||
- [x] Unresolved/source question matrix never opened.
|
||||
- [x] Upstream source, tests and history never opened.
|
||||
- [x] Research build trees and harnesses never opened.
|
||||
- [x] Raw result files never opened.
|
||||
- [x] Server logs never opened.
|
||||
- [x] No recursive search, log or blame inspection performed in the contaminated
|
||||
workspace.
|
||||
- [x] Only independently black-box-verified evidence transferred.
|
||||
- [x] Every transferred statement classified, with observation separated from
|
||||
inference and from recommendation.
|
||||
- [x] Upstream defects recorded as defects, not as protocol requirements.
|
||||
- [x] Host-specific figures labelled as host-specific.
|
||||
- [x] Clean implementation policy decisions left open for the implementation work.
|
||||
- [x] Captures metadata-reviewed, container-rewritten, and verified
|
||||
byte-identical in packet data and timestamps.
|
||||
- [x] No production code changed by the airlock work.
|
||||
|
||||
### 2026-08-12 — PR #76 final review wording cleanup
|
||||
|
||||
An interrupted prior agent's local maximum-duration and rate-limit corrections
|
||||
were reviewed rather than discarded: the maximum-duration trigger clarification
|
||||
was retained, while the rate-limit interaction was kept as a black-box inference
|
||||
rather than promoted to unsupported RFC 2119 language. Using clean evidence only,
|
||||
this review also removed the false request-length invariant, scoped normal DSCP
|
||||
marking to `0..=255`, and clarified that a dropped first post-expiry packet can
|
||||
release the session before any final reply is emitted. No contaminated material
|
||||
was consulted.
|
||||
|
||||
### 2026-08-12 — PR #76 black-box claim review correction
|
||||
|
||||
The latest review found a blanket discard-state claim that conflicted with the
|
||||
observed rate-limit idle refresh, stale compact maximum-duration and idle-expiry
|
||||
summaries, and an over-prescriptive parameter-presence statement. It also found
|
||||
two black-box observations expressed as internal mechanism claims: pre-policy
|
||||
receive truncation and a rejected OPEN leaving no internal state; configured and
|
||||
negotiated limiter intervals had likewise been conflated. The wording now states
|
||||
observable results or explicit inference only. No contaminated material was
|
||||
consulted, no new evidence was added, and no implementation policy was chosen.
|
||||
Reference in new issue
Block a user