lookout

Overview ¶

Command lookout is the fixture API the `monitor-coverage` acceptance task points a Provider Manifest at (issue #227). It mints a certificate, listens on a free loopback port, and serves a small JSON API behind a bearer token until it is killed. Nothing in `hyper` knows it exists: it is reached the way any vendor's API is, over TLS, through a Manifest an agent authored.

**Why any of this is here** is [ADR-0105](../../../docs/adr/0105-the-acceptance-endpoint-is-a-local-tls-server-and-no-artefact-trusts-it.md). A task that asks for a Manifest needs something for that Manifest to talk to, and the choice was between a public endpoint, a local one, and neither. A real vendor's API would put a live credential in a headless session running under `--permission-mode bypassPermissions`; an echo service is safe because nothing it accepts means anything; and either one buys a second variable — a rate limit, a schema change, an outage — into an experiment run a handful of times a year. What is not negotiable is that the trust be unreachable from where the agent writes: no artefact carries a root, a pin or a verification mode, so the sealed session trusts this certificate through `SSL_CERT_FILE` in the `hyper` process's environment and a Manifest that works here is one that would work against a vendor.

**It is Go rather than a script**, and that is a rule rather than a taste. `scripts/acceptance/run.sh` declares the tools it needs — `bwrap git go python3` — and the fence asserts the same four, so a fifth would be an edit to the seam this task is required not to make. `python3` is declared and cannot mint a certificate; `go` is declared, already builds the binary under test, and buys one thing more: `go build ./...` compiles this file on every change, where a script in another language is text nothing reads until a sealed run.

**The port comes from the kernel** because a fixed one is a port another process on this machine may already hold, and a task that failed on it would have failed for a reason that is not the task's. It costs no comparability between transcripts: `host:` is `"{from-target}"`, so the port lives in the Target declaration the setup script writes and appears in nothing the agent authors.

The shape of the API, and why it is awkward ¶

The fixture's shape is ours, which is the cost ADR-0105 records paying: an agent authoring a Manifest against an API we designed is graded against our own idea of one, and an API that fit §3 too neatly would flatter the transcript. So it is awkward exactly where real APIs are awkward, and each of the four is here to be survived rather than admired:

• **An envelope key.** Everything lands under `data`, so no path a projection carries starts at the thing it is about.
• **A collection under a name.** The list is `data.monitors`, not `data`, so `over:` names a member of a member.
• **An identity that is not the name.** A monitor is handled by an opaque `ref` and describes a `service`, and which of the two a Record is named by is the author's choice rather than the API's.
• **A create whose answer differs from an element of the list.** `POST` answers a single object under `data.monitor` with a `state` of its own, so a projection written off the list does not resolve against the create.

Two further facts of it are load-bearing rather than decorative. The list pages at two, so an agent that does not reach for a pagination Pattern sees half the monitors and concludes the other half are missing — and creating one that exists is refused `409`, which halts an effectful Step (§6). And `window` is validated as a whole number of seconds, so a Manifest that sends the integer as a string — the composition rule ADR-0078 states, a stray character beside a hole — is refused `400` rather than quietly accepted. Neither is announced as a trap anywhere: they are properties of an API, and the documentation the setup script ships describes them the way a vendor's would.