design: define initial net.http client contract

[vycdev2]

Summary

Define the first stable outbound net.http client contract before implementation: its canonical request/response API, Network capability behavior, failure model, initial buffering and cancellation semantics, HTTPS guarantees, and source-stdlib/runtime boundary.

Source documentation

• docs/progress.md — Phase K: Full Standard Library
• docs/design.md — Macro-Primitives / HTTP
• docs/design.md — Rule Set 16: Capability-Based I/O
• docs/design.md — Standard Library
• docs/architecture.md — Runtime Library
• docs/architecture.md — Compiler Intrinsics vs Standard Library

Current state

net.http and net.socket are both marked not started. Jett already recognizes the built-in Network capability and dotted local imports such as use net.http, but the repository has no HTTP stdlib module, runtime implementation, or HTTP fixture.

The design currently sketches http.get, http.post, HttpResponse.status, a string response body, and HttpError.connection_failed, timeout, and status_error. Those examples leave important conflicts and gaps unresolved: whether non-2xx responses are values or errors, how headers and binary bodies are represented, how redirects interact with capability narrowing, whether calls block or participate in run / join / cancel, and what HTTPS verification the language guarantees.

Scope

This issue includes selecting and documenting one initial outbound HTTP client contract:

• the canonical net.http namespace and public operation signatures;
• request methods, URL, headers, request body, response status, headers, and body representations;
• transport, URL, timeout, TLS, redirect, body-limit/read, status, and cancellation failure behavior;
• explicit view net: Network use and enforcement of narrowed capabilities such as allowed hosts;
• buffered-versus-streaming policy and structured-concurrency behavior for the first release;
• secure HTTPS defaults and the minimum portable target guarantees;
• public compiler-shipped .jett declarations versus private trusted runtime transport hooks.

This issue does not implement the HTTP client, design an HTTP server or http.respond, define the separate low-level net.socket API, or commit to HTTP/2, HTTP/3, WebSockets, streaming bodies, cookies, proxies, pooling, retries, or middleware. Those features should remain deferred unless the initial contract requires a narrow prerequisite.

Acceptance criteria

• One canonical initial outbound client API is selected, including whether convenience methods or a generic request operation own the public surface.
• Request and response types define URL, method, headers, text/byte body representation, ownership, and buffering limits.
• HttpError and non-2xx status behavior are unambiguous and preserve useful response context where intended.
• Timeout, redirect, cancellation, malformed-request, DNS/transport, TLS, and body-read/limit behavior is specified.
• Network borrowing and narrowing are defined, including enforcement across redirects and resolved destinations.
• Initial synchronous/asynchronous behavior and interaction with run, join, and cancel are documented.
• HTTPS certificate verification and unsupported-target behavior have secure, deterministic defaults.
• Public source-owned declarations and private runtime hooks are separated without hardcoding public HTTP names or signatures in the compiler.
• Representative GET and request-with-body examples use only the selected canonical spellings.
• docs/design.md, docs/architecture.md, and docs/progress.md are updated to reflect the decision without claiming implementation.
• The originating planning docs remain in place and reflect the issue's final status.

Dependencies / open questions

• design: define module imports and trusted stdlib origins #3 owns the broader import/prelude and trusted stdlib-origin policy.
• design: define initial HIR and monomorphization boundary #20 and design: define initial MIR CFG and ownership boundary #22 own future HIR/MIR and native ownership/lowering boundaries; this design issue can finish before those implementations.
• design: define crypto hashing and security contract #69, design: define encoding representations and failure contract #71, and design: define time and Clock capability contract #75 are adjacent crypto, encoding, and clock contracts that may constrain TLS, body representation, and deadlines.
• Decide whether net.http may use a private runtime transport directly or must depend on a future public net.socket contract.

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