carriers: meet bitwire's adopted close codes and closed classification (carrier contract, edition 1)

[jm9e]

Outcome

bitwire adopted the first part of its carrier contract in decision 0013 (bitwire a80981e, Bitspark/bitwire#69, bitwire#54). The adopted text is close codes and the closed classification. This issue brings bitruntime's carriers to it in Go and TypeScript, so that bitruntime can claim "bitwire/1 and carrier contract, edition 1".

The contract changes no protocol revision. Where bitwire/1 binds a code (4011 for a protocol violation, 1009 for an over-limit frame), nothing changes. The format rules for bitwire-stream/1 belong to #10.

What the adopted text requires

• Valid close codes. The frozen set 1000–1003, 1007–1014 and 3000–4999. 1005, 1006 and 1015 are observe-only and never sent; 1004 and every other number are never sent either.

• Close requests are validated before any state changes.

  • An invalid code, or a reason that is not UTF-8 or is over 123 bytes, is an argument error. Nothing is sent, the connection is unchanged, and the reason is not truncated.
  • A valid code the adapter cannot send is an unsupported-capability error. The adapter does not substitute a code, omit it, or abort instead.
  • A repeated valid close joins the ending under way. Abort is idempotent.

• Capabilities are declared. An adapter states the valid codes it cannot send, and whether it has an abort. A claim that needs a missing capability is not made. This settles the question transports: the TypeScript pipe has no receive limit and FrameConnection no abort; a Go pipe's own over-limit end reads as an abort #26 left open: a TypeScript FrameConnection without abort() cannot claim the contract, and the write-failure rule below needs an abort.

• One closed classification. Every endpoint, operator and helper reports a closed carrier as one local error kind carrying a termination record:

  • resource and cause;
  • the local close (code, reason, write status);
  • the first valid peer close;
  • the observed code;
  • whether the drain and the handshake completed.

  The record is local and is never serialized into a ProfileError. The public projection stays disconnected, and a received disconnected is not evidence of a local close. The v0.4.2 CloseError.Local field is a start.

• Closed(code, reason) reports the first valid peer close, and otherwise 1006 on a network transport. The locally selected code stays available in the record.

• Operational failures under bitwire/1.

  • A failed write path aborts and sends nothing more.
  • Other operational failures (overload, a stalled consumer, a full root queue) prefer an abort over 4011; 4011 stays for protocol violations.

• The revision-1 tunnel keeps sending channel.close 1006 on abort, as bitwire/1 requires. A claim over the tunnel states this compatibility exception.

Evidence

The API-boundary scenarios for these rules are not written yet. bitwire tracks them on bitwire#54, and they will run against released bitruntime as the bitwire/1 runs do. Until then, record the behavior in bitruntime's own tests, and list any deviation you keep as a documented deviation. Decision 0013 fixes deviations before D1 to D3 are adopted.

Refs Bitspark/bitwire#54, #10, #26, #2.

[jm9e]

Context for this work, from closing #21 and #26 (bitruntime session):

• A concrete "valid code the adapter cannot send". transports/ts webSocketConnection over a WHATWG WebSocket (a browser, or Node's global WebSocket used by Peer.connect): the platform's close() accepts only 1000 and 3000–4999. Today the adapter catches the platform's refusal and falls back to close() without a code (added in runtime: implement the path hand-written adapters use, ported from nightseam v0.6.0 #9 so the socket still closes).
  • The adopted text forbids that fallback: "does not substitute a code, omit it, or abort instead". So the WHATWG adapter must instead declare 1001–1003 and 1007–1014 as codes it cannot send, and refuse them with the unsupported-capability error.
  • The engine then needs a policy for when it wants 1009 or 4011 over such a transport. 4011 is in 3000–4999, so a protocol violation is sendable. 1009 is not. That is exactly where this issue's "a claim that needs a missing capability is not made" bites.
  • Over ws (Node) every valid code is sendable.
• Already in line with the text:
  • observe-only codes are refused before any state changes, in both languages (R27: Sendable/sendable, ErrUnsendableCode/RangeError);
  • one closed classification (R26);
  • in Go, a receiver's own over-limit refusal is a local termination record: CloseError{Code: 1009, Local: true}, since v0.4.2.
• Not yet:
  • reason validation (UTF-8, ≤123 bytes, never truncated) as an argument error;
  • declared capabilities;
  • abort() on the TypeScript FrameConnection (transports: the TypeScript pipe has no receive limit and FrameConnection no abort; a Go pipe's own over-limit end reads as an abort #26 item 2, which this issue settles);
  • the write-failure rule, prefer abort over 4011.

[jm9e]

Consultation started (maintainer's go-ahead, 27 September 2026). Before implementing, bitruntime research 0001 asks an outside expert how to carry carrier contract edition 1 into bitruntime's Go and TypeScript APIs. The questions: how adapters should declare capabilities, and what the engine should do when it needs a code its adapter cannot send (the WHATWG WebSocket case above); how to add abort() to the TypeScript FrameConnection without breaking implementers; the local termination record; and the write-failure rule. It is informed by bitwire's research 0004, and asks only what that research left open. Owner: bitruntime-17. Document: research-docs/0001-carrier-contract-edition-1.md on branch research/0001-carrier-contract. The run ID will be posted here.

[jm9e]

Research 0001: the four reviews, and what each caught (all applied before submission).

• Vocabulary. 27 findings. It asked us to define the core terms: seam, adapter, claim, root endpoint and root queue, call and call helper, operator, and the error-code/close-code split. It also asked us to:
  • separate the two meanings of "record" (the termination record versus a byte-stream framing record);
  • add a close-code constant table (CodeProtocol 4011 versus CodeProtocolError 1002);
  • add a Go primer, where embedding matters: embedded interfaces forward new methods, but not optional ones;
  • restore the dropped R4 and R6.
• Code completeness and accuracy. It corrected several claims against the code:
  • TypeScript violates R15. A received disconnected response is the same PublicError('disconnected') as the local closed classification, and ended() passes a disconnected cause through, leaving no separate cause.
  • The handshake result is already available. coder/websocket's Close returns nil only when the remote echoed the same code, so "handshake complete" can be reported; bitruntime discards that result.
  • The underlying net.Conn is unreachable. coder/websocket keeps it private, so the "drop it directly" option would need New's signature changed.
  • There is one TypeScript WebSocket adapter, wrapping either ws or browser sockets, and ws.terminate() is unreachable through it.
  • The dispatcher's 1002 reaches the connection only when the dispatcher owns its endpoint.
  • Go's rootWire.Close aborts on any unsendable code, not only observe-only ones.
  • closeReason trims to nothing when an invalid byte comes early.
  • ws also repairs unpaired surrogates.
• Narrative. It moved the central conflict, the constraints and "how an ending travels" ahead of the code. It merged the repeated material into two tables: an adapter-capability table and a rule-by-rule gap table. It added the missing calibration: scale, what "done" looks like, that there is no date for bitwire's types, that bitwire's Endpoint is fixed for us, and that the nightseam byte test covers only protocol-violation endings.
• Questions.
  • Dropped the settled parts: Closed projection (R17/R18), where the record lives (R12), and the classification of send errors, which the code already settles.
  • Merged the record and adapter questions into one: an ending as a process.
  • Added the missing testing question.
  • Grounded Q1 in bitwire's transport-properties text ("a receive limit … ends with 1009"), and pointed its comparison at gRPC-Web.
  • Lined up the Question section's list with the five questions.

[jm9e]

Research 0001 submitted: run run_1e55330d-37fb-4413-b815-4526426dd224, document doc_9a7e16b9-e38f-4af4-97e2-f0f0af78041b (sha256 767d7eb8…, collection bitruntime-research). The frozen copy and recovery record are on branch research/0001-carrier-contract. If this session ends before advice lands, resume with nightfall --json consult attach run_1e55330d-37fb-4413-b815-4526426dd224 --timeout 2h --output research-docs/0001-carrier-contract-edition-1.advice.md, then run /bb-research apply 0001.

[jm9e]

Research 0001, attempt 1 (run_1e55330d) failed at the service before anything was sent: provider account-1 could not load its model list (105_SELECT_MODEL, invalid_transition). Attempt 2 was submitted with a fresh key on account-2 as run_68a80ec1-7907-4c5f-b28c-d1c351b77066. It uses the same stored document (doc_9a7e16b9…, sha256 767d7eb8…). To resume: nightfall --json consult attach run_68a80ec1-7907-4c5f-b28c-d1c351b77066 --timeout 2h --output research-docs/0001-carrier-contract-edition-1.advice.md.

[jm9e]

Research 0001 has landed on main (#34) at evaluated. The advice from run run_68a80ec1 was verified, and all 52 recommendations were checked against f0327a9: 47 HOLDS, 4 NEEDS ADAPTATION, 1 DEFERRED, none rejected. It awaits the maintainer's grade. Once graded, delivery is a breaking v0.5.0 in three phases, plus one bitwire issue carrying five questions only bitwire can settle. The table is in research-docs/0001-carrier-contract-edition-1.md, section ## Applied.