# Tuna agent instructions

The tree calculus is the API. Compile an s-expression to a program hash, POST a run, and read the journal; every firing is a step and every run is replayable from its journal.

## Origin

Base URL (this host): https://club.pricklypear.club
Machine contract: GET https://club.pricklypear.club/.well-known/agent.json

## Auth

Scheme: Authorization: Bearer <identity token> (the agent tier).
Browser clients may use cookie tuna_session (HttpOnly,
SameSite=Lax) after POST /login; agents use Bearer.

How to get credentials: ask the human once. Store them in a local
secrets file (mode 600). This document never contains tokens.
An admin mints a non-admin identity + token at https://club.pricklypear.club
/identities (or POST /api/identities).
Rotate your own bearer token (self-serve): POST https://club.pricklypear.club
/api/identities/<your-id>/rotate -> {"token":"…"} returned
once; the previous token stops verifying immediately. An admin
may also rotate another identity's token.

## Eval API

Programs are compiled then run in two steps:

  POST https://club.pricklypear.club/api/programs   {"source":"(\\f. \\x. f x)"}
    -> {"hash":"…","ternary":"…"}

  POST https://club.pricklypear.club/api/runs       {"program":"<hash>","inputs":[]}
    -> {"id":"…","status":"normal","step_count":N,…}

Authentication is required on /api/*; /health, /welcome, /code,
/src.tgz, /agent.txt and /.well-known/agent.json are public.

## Verification surfaces

- GET  https://club.pricklypear.club/api/runs/<id>/trace    the firing trace
- POST https://club.pricklypear.club/api/runs/<id>/verify   replay verdict
- GET  https://club.pricklypear.club/api/journals/<run_id>  the prim-call journal

Replay re-executes program+inputs with prim calls answered
sequentially from the journal; it never touches the live host.

## First calls

- `curl -sS -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{"source":"(\\f. \\x. f x)"}' $BASE/api/programs`
- `curl -sS -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{"program":"<hash>","inputs":[]}' $BASE/api/runs`
- `curl -sS -H 'Authorization: Bearer $TOKEN' $BASE/api/runs/<id>/trace`
- `curl -sS $BASE/code`

## Rules

1. Authenticate with Authorization: Bearer <identity token> — the agent tier.  Browser clients may instead carry the tuna_session cookie (minted at /login); agents never need it.
2. POST /api/programs compiles an s-expression to a content-addressed program hash.  POST /api/runs executes one with inputs and grants.
3. Grants are arguments, not ambient: a prim call must be covered by a live grant row, checked by the host at the boundary.  Denial is a journaled error result, never an exception.
4. A step is one triage-rule firing; the two wrapper applications are application, not steps.  Step counts are an invariant of the calculus, so they are stable across engines.
5. Replay determinism: GET /api/runs/:id/trace and POST /api/runs/:id/verify re-execute program+inputs with prim calls answered sequentially from the run's journal.  Replay never touches the live host.
6. Fuel and size caps are ordinary results (fuel_exhausted / size_exhausted), never timeouts; a wall-clock cap only finalizes a run as deadline_exceeded at the operator boundary.
7. Publishing endpoints is a store write: POST /api/route/put writes a route/<site-path> record (method, template/program hash, content_type, grant_prefix) served data-first.  Do not hardcode endpoints.
8. Discovery: /code is the read-only program+run browser; /.well-known/agent.json is this contract; /agent.txt is prose.

## curl example

    curl -sS -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \
  -d '{"source":"(\\f. \\x. f x)"}' https://club.pricklypear.club/api/programs

## Related public surfaces

- Welcome: https://club.pricklypear.club/welcome
- Source browser: https://club.pricklypear.club/code
- Source tarball: https://club.pricklypear.club/src.tgz
- Health: https://club.pricklypear.club/health
- Interactive REPL (session required): https://club.pricklypear.club/repl