lookout

Overview ¶

Command lookout is the fixture API the lookout acceptance tasks point a Provider Manifest at (issues #227, #255, #268 and #271). 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.

**One service, three worlds.** `-fixture` names the initial state it starts in, and each of those states is a task's fiction: which monitors are already there, and which services will not answer the first look a create takes at them. The states and the argument for each are in api.go; nothing else about the service varies between them, so a Manifest written against one is a Manifest that works against the others.

**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.

A fifth is not awkwardness and is here for a different reason. **One route answers a value the service will not answer again** — a monitor's push credential, minted by a `POST` of its own — which is the class ADR-0007 names as not re-readable and the only thing this fixture offers that a Manifest would mark `secret:` (issue #271). Everything else here comes back as often as it is asked for.

Three 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). `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. And a monitor is looked at as soon as it is added, so a service that does not answer that first look leaves a `201` in the caller's hands and nothing in the list — which is the only way a monitor `hyper` created is gone before `hyper` deleted it, and therefore the only way to a `404` on a `destroy` from inside the seal (issue #255). None of the three is announced as a trap anywhere: they are properties of an API, and the documentation the setup scripts ship describes them the way a vendor's would.