4.8 Ensemble Networks

Interaction Guide

New to the design? Start with the sequence diagrams:

• Opening a connection: transport, identity, mutual authorization, election and public readiness.
• Opening a stream: admission callbacks, OPEN/OPEN-ACCEPT and initial flow-control windows.
• Sending data: local buffering, transport ownership and read-driven credit replenishment.
• Gracefully closing a stream: independent Writer half-closes, FIN, EOF and eventual retirement.

Construction

Public Methods

See interface.md for argument contracts and full interface requirements, config.md for defaults and resource limits, and network.md for orchestration, callback ordering and ownership. There is no separate public renewal/request method: an uncovered finite requirement on connect! requests renewal of the shared connection.

listen! returns the actual bound address, including an assigned TCP port for a port-zero request. Unix listeners use the existing sidecar-lock ownership contract. TCP always uses mutual TLS; Unix uses signed identity proofs over plaintext under the trusted local OS/path threat model. Both paths require mutual UCAN authorization before publishing a connection.

connect! shares one live connection per canonical peer DID. A new attempt uses Unix addresses first, then the remaining supplied preferences. Concurrent callers join the same attempt without replacing addresses or restarting its budget. Empty addresses mean reuse-or-join only, with no implicit discovery or reconnect. Supplied auth is an optional positional DELEGATE parent, not transport identity. Omitted auth uses the context’s output policy.

Each finite lifetime override is resolved once at call start. expire: takes precedence over ttl:; explicit false means omitted. Both arguments retain their public type contracts even when one takes precedence. A stream’s authorized expiration is independent of the connection’s lease; opening a stream never renews its connection.

Lease Policies

Network.connect! accepts lease: 'renewable to maintain finite credential-backed leases without an application-requested final expiration. #f retains fixed/default behavior. Connection.open-stream! accepts lease: 'connection for a stream that follows successful connection extensions through protocol-specific reauthorization; #f retains fixed stream behavior. Reject any other policy, and reject a nonfalse policy with a nonfalse ttl: or expire: before reserving work or changing policy. Fixed calls may still supply both lifetime arguments with the existing precedence.

Renewable interest lasts until that shared connection closes. Acceptance is the serialized policy attachment, not caller return: it survives waiter timeout. Each accepted nonfalse auth accompanying renewable policy replaces one retained seed; omitted auth leaves the seed unchanged. Each automatic operation considers that seed and refreshed context authority rather than pinning policy to an expired parent. Explicit finite renewal parents belong only to their shared operation. Policy never silently transfers to a new physical connection after closure or failed establishment.

Accepting renewal policy or work requires protected capacity within the existing control budget: four frames and control-payload + 13 + 3 * 38 bytes. Inadequate configured or currently available capacity fails admission before policy changes; this is not extra capacity or a reason to revoke already borrowed buffers. Pending interest first validates configuration, then the winning parent admits the actual allowance before activation. Later joiners use that parent’s real capacity even before the connection becomes publicly ready.

Already-ready renewal requests use renewal-timeout measured from the original connect! call start. Establishment joiners retain the original handshake budget; any additional renewal phase is capped by its remainder and the renewal timeout. Covered/default callers are not held for unrelated work. The Network mutex is not held during a renewal wait.

Renewal preserves Connection/Stream identity, addresses, direction and IO handles, and does not repeat open/allow callbacks. Connection.expire is the last installed finite parent lease; Stream.expire is independently installed stream authority. Linked streams can follow explicit extensions on a fixed connection without enabling automatic connection renewal themselves. Opening a stream never initiates connection renewal. Fixed streams do not gain renewal behavior. No IO timeout is reset by renewal.

The revised transport uses HELLO version 1, with no version-0 fallback. Its connection capability protocol remains /network/connect/v0. See the renewal runtime for protocol, timing, bounded resource ownership and precommit/postcommit failure rules; the renewal handoff preserves the design baseline.

Integration Status

Public Unix/TLS networks, authorized multiplexed streams, explicit connection renewal, dual-endpoint automatic policy, linked-stream renewal and delegated credential refresh are implemented. They are not contract-only or codec-only placeholders.

The final-coverage baseline 15f010bf records a successful eight-core stdlib build, 44 focused renewal cases (23 protocol, 12 policy, 9 limits), and a passing 41-module regression. The main-owned current checkpoint is authoritative for commands, revision scope, failures and final-acceptance results, including the separate retained-resource and bounded mixed-load work. This documentation audit checks source contracts; it does not rerun that verification or claim final acceptance on its own.

The subsequent final acceptance workload and resource audit cover retained public views after joined shutdown, a verifier that outlives service, and bounded renewal/stream churn under backpressure on Unix and TLS. Consult the current checkpoint for its exact results and sign-off status.

Callbacks And Shutdown

Callbacks run promptly outside owner/connection locks. Connection-open completes before activation and framed admission; it is not a readiness notification. Its Connection supports metadata, close and timeout settings, but not stream opening yet. An application worker needing readiness must obtain the connection through Network.connect! (an empty address list joins pending establishment); do not block the callback on that call. Only normal open-callback return qualifies for a matching close notification. Local callback exceptions retain their identity after cleanup. Inbound stream rejection is stream-local. Eligible stream-close callbacks finish before connection-close notification; close-callback exceptions are logged without preventing further cleanup.

Connection.close and Stream.close are safe from monitor callbacks. Closing the whole stream or reader aborts; writer close drains accepted DATA and sends FIN, leaving the reverse direction available. IO timeouts do not extend authorization. Stream Reader/Writer handles are stable, including after close. They transfer u8vector bytes, not characters: each Writer.write consumes the whole requested slice or raises, under one captured deadline. See the byte IO contract for read minimums, buffer ownership and deadline behavior across renewal.

Network.close is idempotent and blocking. It stops admission, closes owned sockets before joins, finishes worker/resource cleanup and eligible notifications, then releases TLS. Calling it from any network-owned worker, including monitor callbacks and finalizers, raises contextual ContractViolation before acquiring the network mutex, changing shutdown state or joining workers. This applies to another network and to an already closing or closed network too. Dispatch global shutdown to an application worker instead: a thread spawned by a callback does not inherit the network-worker marker. Let the callback return; do not wait there for the closer. No early public waiter-cancel API is added; public callers use existing deadlines and global close. Internal waiter withdrawal affects only that caller, not shared network-owned work. After close, host and object metadata remain accessible, while network operations and registry queries raise Closed. Connection/Stream IO, opening and timeout operations preserve an earlier stored failure rather than replacing it with Closed.

Cancellation is cooperative: publish close/abort/pending state under the associated mutex and notify its CVs while holding that mutex. Socket close interrupts blocked IO structurally, not through exception-raising thread-interrupt!; production network cancellation does not invoke it. Credential/admission workers finish their current context, encoder or callback call without unsafe preemption, then observe cancellation. Quotas and ownership remain held until work, cleanup and eligible callbacks actually finish, even if a waiting caller has already returned.

Constructor and callback failures, including failures after normal callback return, still require cleanup and eligible callback pairing. Synchronous source-private fault injection is the test policy. vyzo explicitly withdrew the Interrupt API and asynchronous raising-recovery machinery, not deprecated it or retained a fallback. Arbitrary external thread interruption and forced termination remain unsupported. See the withdrawal.

All network test source is now free of thread-interrupt! and thread-terminate!. Production network code never calls thread-interrupt!; the new explicit retry wrappers in stage-handler/completion/join paths were removed first. The remaining Interrupt catches and abort/release/wake/native-close retries are now removed too. Normal ownership cleanup, SSL lifetime cleanup and the shared Reader minimum-read fix are preserved. Preexisting debugger/profiler/REPL interrupt primitives are outside this withdrawal’s scope.