design: define opaque runtime resource type representation

[vycdev2]

Summary

Define the source-language and compiler/runtime representation required for opaque owned resources such as net.socket.TcpStream and TcpListener, so public compiler-shipped declarations can expose linear handles without constructible fields, public Rust builtins, or accidental cloning, reflection, serialization, or equality.

Source documentation

• docs/open_design/net_socket_transport_contract.md, Public Semantic Model
• docs/open_design/net_socket_transport_contract.md, Lifecycle And Ownership
• docs/open_design/net_socket_transport_contract.md, Runtime And Stdlib Boundary
• docs/architecture.md, Runtime Library
• Socket contract issue design: define initial net.socket transport contract #104 and merged design PR docs: define initial net.socket contract #107

Current state

The TCP contract selected by #104 specifies owned linear stream/listener handles, explicit consuming close operations, scope cleanup, capability provenance, and public declarations in compiler-shipped .jett source. It also states that implementation cannot start with the illustrative fieldless export struct TcpStream spelling: Jett has no source declaration for an opaque runtime-backed type, ordinary structs expose source-defined data, and the current interpreter value model has no socket/resource carrier.

The compiler enforces move/view ownership for non-copyable values, but allowing an owned value to leave scope currently needs no resource-specific cleanup. There is no selected rule for declaring a non-constructible nominal resource, restricting reflection/serialization/equality, binding its private runtime carrier and destructor, or preserving exactly-once cleanup and authority metadata across interpreter and future HIR/MIR paths. Searches for socket, opaque resource, runtime-backed type, and linear resource issues/PRs found #104/#107 and the distinct C FFI opaque-pointer work in #53/#173, but no tracker for this runtime-resource representation.

Scope

This issue selects and documents the minimum representation needed by the first socket implementation:

• one canonical compiler-shipped source declaration for a nominal opaque runtime-backed resource type;
• construction and operation access limited to private trusted kernels while public names and signatures remain source-owned;
• default non-constructible, non-inspectable, non-clonable, non-comparable, non-serializable, and non-reflectable behavior, including any deliberately safe type-level metadata;
• owned transfer, view borrowing, use-after-move behavior, explicit consuming close, implicit scope cleanup, and exactly-once destruction on normal, error, and cancellation paths;
• interpreter carrier/storage identity, stale-handle prevention, authority provenance, and deterministic fake-provider testing;
• a future-backend handoff for HIR/MIR drop elaboration and native runtime carriers without choosing an OS socket ABI in the public language;
• the relationship to capability values and C FFI opaque pointers, reusing a rule only where ownership, authority, cleanup, and ABI semantics actually match.

This issue does not implement net.socket, select new socket semantics, add a general user-defined destructor feature, expose raw pointers or descriptors, implement C FFI, or build HIR/MIR/native lowering. It should avoid a broad resource framework beyond the decisions required to make the selected TCP handle contract implementable.

Acceptance criteria

• One canonical source spelling and declaration-order/visibility rule for opaque runtime-backed resource types is selected.
• User code cannot construct, inspect, clone, compare, serialize, or forge a resource value unless a separately specified operation explicitly permits it.
• Move, view, explicit close, scope exit, error propagation, task cancellation, and actor/task transfer have unambiguous ownership and exactly-once cleanup behavior.
• Trusted-kernel construction and operation dispatch preserve resource identity and authority provenance without hardcoding public net.socket names or signatures.
• Interpreter storage, deterministic fake-provider coverage, stale/closed-handle behavior, and future HIR/MIR/native handoff are specified.
• The relationship to built-in capability values and C FFI opaque pointers is explicit, with incompatible semantics kept separate.
• docs/design.md, docs/architecture.md, and the socket contract are updated to reflect the selected policy while the originating documents remain in place.

Dependencies / open questions

The socket behavior contract is complete in #104, but its interpreter-backed implementation should wait for this representation decision. #173 covers parsing and checking foreign declarations, not runtime socket resources. Future exactly-once drop elaboration and native carriers remain downstream of #20 and #22; this design can still select the source/frontend/interpreter boundary before those phases exist.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.