Section 28: Networking and Communication Semantics¶

TECHSPEC-28 — Section 28 · Version 0.1 · Status: Initial Draft

Status: draft. This section is an Initial Draft (Section 57 is a Working Register). It describes intended or proposed behavior, not a finalized, implemented language rule. Do not treat examples here as normative.

1. Networking Philosophy¶

Network communication must be explicit, permission-controlled, and failure-aware.

The language must not treat sending a request as proof that it was received, processing it as proof that it succeeded, or receiving a response as proof that the response is trustworthy.

Every network operation must define its expected behavior and possible failures.

2. Network Effects¶

Network operations must declare their effects.

Supported effects include:

• NETWORK.CONNECT: Establish a connection.
• NETWORK.SEND: Transmit data.
• NETWORK.RECEIVE: Receive data.
• NETWORK.LISTEN: Accept incoming connections.
• NETWORK.CLOSE: Close a connection.

Effects must propagate through the call graph. A function cannot hide network activity behind another function.

3. Explicit Network APIs¶

Network communication must use standard-library APIs with declared contracts.

Example:

FUNCTION fetchUser(
    id: Integer
) -> Result<UserResponse, NetworkError>

    REQUIRES: id > 0
    EFFECTS: NETWORK.CONNECT, NETWORK.SEND, NETWORK.RECEIVE
    FAILURES: ConnectionFailed, Timeout, InvalidResponse

    LET response = HTTP.get(
        "https://example.com/users/" + String(id)
    )

    RETURN response

END FUNCTION

This is illustrative syntax. The final HTTP API and string-construction rules remain to be defined.

Rules: - Network access must be explicit. - Destination addresses must be identifiable. - Requests and responses must have declared data types. - Network operations must return explicit success or failure results. - Credentials must not be embedded in source code. - Network operations must not occur without the required permissions.

4. Timeouts and Cancellation¶

Network operations must not wait indefinitely by default.

Rules: - Requests must have explicit or documented timeout policies. - Timeout behavior must be distinguishable from other failures. - Cancellation must be supported where practical. - Cancellation must release resources safely. - A cancelled request must not be reported as successful. - The language must document whether cancellation can interrupt an operation or only stop waiting for its result.

5. Request and Response Guarantees¶

The language must distinguish between different stages of communication.

For an outgoing request:

1. Request constructed.
2. Permission granted.
3. Request transmission attempted.
4. Data transmitted, if confirmed.
5. Remote response received, if any.
6. Response validated.
7. Application operation completed, if established.

Rules: - Successful transmission does not prove remote processing. - A timeout does not prove that the remote operation failed. - Retrying a request may duplicate its effects. - Operations requiring safe retries must define idempotency behavior. - Response validation must be separate from successful receipt.

6. Data Validation and Trust¶

All network data must be treated as untrusted until validated.

Rules: - Received data must be decoded using an explicit format. - Deserialized values must satisfy destination type constraints. - Validation must establish only its declared guarantees. - Authentication must not imply authorization. - TLS or other transport security must be configured explicitly through documented APIs. - Certificate and identity validation failures must not be silently ignored.

7. Connection and Resource Management¶

Network connections and streams are resources with defined lifetimes.

Rules: - Connections must have identifiable owners. - Resources must be released on normal completion and handled failure paths. - Closed connections cannot be reused. - Ownership transfers must follow the language's resource rules. - Connection pooling must be explicit or provided through a documented standard-library abstraction. - Resource limits must be documented.

8. Concurrent Network Operations¶

The language must support concurrent network activity without concealing shared-state risks.

Rules: - Concurrent operations must use explicit task or asynchronous constructs. - Shared mutable state must follow concurrency and ownership rules. - Task failures must remain observable. - Cancellation must propagate according to documented rules. - Completion order must not be assumed unless explicitly guaranteed. - The runtime must not silently discard failed network tasks.

9. Network Permissions and Security¶

Network permissions must follow least-privilege principles.

Rules: - Programs must declare required network capabilities. - Destination restrictions should be supported. - Listening for incoming connections requires explicit permission. - Access to local network resources must follow documented permission rules. - Sensitive request and response data must not appear in logs by default. - Redirect behavior must be documented and subject to destination restrictions. - Network permissions must not be inherited automatically by unrelated dependencies.

10. Error Handling¶

Network failures must use structured error types.

Possible failures include: - Connection failure. - DNS resolution failure. - Timeout. - Connection refused. - TLS or certificate validation failure. - Permission denied. - Invalid request. - Invalid response. - Connection interrupted. - Remote service error. - Resource exhaustion. - Cancellation.

Errors must preserve relevant underlying causes without exposing credentials or other sensitive information.

11. Compiler and Runtime Responsibilities¶

The compiler and runtime must: - Enforce declared network effects. - Enforce required permissions. - Require explicit handling of network failures. - Track asynchronous network tasks. - Enforce resource ownership and cleanup. - Preserve request and response type guarantees. - Distinguish transmission, receipt, validation, and application-level success. - Report incomplete or uncertain operations honestly.

12. Verification Limitations¶

The language cannot guarantee that an external server is available, honest, correct, or reachable.

Network behavior depends on external systems beyond the program's control.

Verification reports must distinguish: - Network permission declared. - Permission granted. - Request attempted. - Response received. - Response validated. - Remote operation confirmed, when the protocol provides sufficient evidence.

13. Design Goal¶

An AI agent must be able to determine what network activity a program performs, which destinations it can contact, what data it exchanges, and what is actually known about the outcome.

A request being sent must never be confused with the requested operation being completed.

Source and related sections¶

Source file: TECHSPEC-28.md (preserved in source-original/LANG/). See the specification index, the glossary, and the cross-reference index.