# ADR 0003: Current Net API State

## Status

Accepted

## Date

2026-06-07

## Context

`/apis/net` is the current networking abstraction in this repository.

It wraps modem messages with packet metadata and uses `/apis/eventloop` for listeners and request/response flows. It is useful for today's basic routed messages and RPC-like requests, but it is not a final protocol design.

## Decision

Keep using `/apis/net` for simple program and server messaging.

Document the current behavior as the baseline, without over-designing the future protocol before real needs appear.

## Current State

- Default routing channel is `10`.
- Ping channel is `9`.
- Packets include `sourceId`, `sourceLabel`, `routerId`, `destId`, and `message`.
- Main convenience APIs include `send`, `listen`, `sendRequest`, `sendMultipleRequests`, `listenRequest`, `createEvent`, `createRequest`, and `openChannel` (alias `open`). Listening on a non-default channel requires `openChannel` first.
- `sendRequest` and `sendMultipleRequests` run a private event loop, default to a `0.5s` timeout, and return `ok, result, packet` (or `ok, results, packets` for the multi variant).
- Router behavior currently lives separately in `/programs/router.lua`. A router must be running on the network — otherwise non-router senders produce packets with `routerId = nil` and `isPacketOk` drops them on receive, so cross-machine messages silently fail.

## Consequences

- Use `/apis/net` for current basic messaging needs.
- Keep duplicated well-known channel constants in sync while they remain duplicated.
- Future ADRs can replace or refine this one if the network protocol gains discovery, retries, schemas, versioning, auth, or a different routing model.