Define hibernatable actor WebSocket contracts
Draft
VA
1d ago+5385+5385+0123456789012345678901234567890123456789-736-736-012345678901234567890123456789
Actors currently have no typed socket lifecycle or effect contract. Add hibernatable incoming/outgoing socket declarations, checkpointed delivery offsets and effect identities, the unified URL/actor Connect target, bounded attachments/tags/frames/buffers, exact text auto-response settings and timestamps, runtime keepalive templates and metering. Generate protobuf, descriptor fixtures and TypeScript from the executable Rust declarations.
Validation
- Remote focused socket ingress tests: initial 8 passed; final 9 plus descriptor suite queued on shared build slots.
- Remote contract-derive socket shape regression: passed (repeated scalars, double, Error oneof case).
- Remote Actors TypeScript noEmit check: passed again at signed commit 130903562. Root cause fixed with #[ts(optional)] on new Option fields; canonical type assertions remain intact.
- Remote attachment helper test: passed, six assertions.
- Generation completed remotely; git diff --check, LF and touched-file size checks passed.
Decisions
- Follow decision-substrate points 7–9 and the coordinator decisions in Q:/lanes/session-protocol.md. ConnectTargetInternal is removed: one API chooses internal or external transport at runtime.
- Session kind 13 encodes SocketOpen; kind 14 encodes ActorCall. Keep the common Streams envelope rather than duplicating it. One-based actor offsets map to SessionCursor.next = applied actor offset + 1.
- Represent repeated oneof recipients and secret-header maps with typed messages and enforce uniqueness at admission. Compact raw generated protobuf TS comments to keep touched source files below 800 lines; semantic declarations retain their documentation.
- Teach the contract derive repeated scalars and double, and qualify generated conversion errors so the Error variant is legal.
- This PR delivers the contract prerequisite. Actors platform local runtime, pooled client/adapters and a small socket-hibernation test follow separately; none are claimed complete here. Decision point 10 removes all harness socket wiring and the 10k harness test from this lane. There are no harness edits in this PR.
Live steps
- c39/c40: consume these payloads in shared session slots 13/14. Authenticate placement, fence generations/owner epochs, retain replay from the last applied offset and persist per-connection delivery dedup with checkpoint and effect outbox. Deduplicate (actor_id, checkpoint_sequence, index_in_outbox), including fixed broadcast recipients.
- Runtime owns Ping/Pong, channel-0 keepalive, idle/dead-peer detection, fixed outbound keepalive and exact text auto-response (connection override before actor default). These never wake actors; expose last_auto_response_at on wake. Final timeout produces SocketClose with runtime initiator.
- Internal actor/platform targets including public actor WebSocket URLs resolve to virtual channels with no per-actor socket or external host-rule consumption. Authorize platform capabilities. External dials enforce host/port/CIDR and checked resolved IPs, resolve secret headers at the node, and follow the declared reconnect policy. Validate again on reconnect/redirect, and dial only checked addresses.
- Enforce frame/attachment/tag/connection limits and inbound byte/frame/actor aggregate caps. Stop reading on full buffers; close 1013 after handler timeout. Meter broadcast N deliveries; real_socket_seconds only for physical external/edge sockets. Rate-limit runtime auto-response and Ping/Pong without billing them.
- External-peer exactly-once effects require remote protocol acknowledgement/dedup; socket write completion alone does not establish it.
Paused at user request
- Latest signed commit: 563fcb50d, pushed to hf/actor-sockets-contract.
- Includes an unvalidated local Actors socket engine draft and focused lifecycle/control tests. No harness wiring was added. The driver for real outbound sockets, client/adapters and full runtime integration remain incomplete.
- Actors TypeScript noEmit check passed at 130903562 after fixing optional-field generation. Attachment helper test and contract-derive shape regression passed. Final socket/descriptor and local-runtime validation commands were queued on the shared builder when the user requested stopping; no passing result is claimed for them.
- Keep this PR draft. The lane is deprioritised in favour of following many streams over few connections. No further work until resumed.