Keep a signed lab notebook

# Decosa signed lab notebook: use the hosted API

You are wiring Decosa's signed lab notebook into our lab's tools (an instrument script, our ELN or a data pipeline).
It keeps numbered entries on an append-only hash chain, instrument files by SHA-256, amendments that point at the
original and give a reason, e-signatures with meaning, a log of AI analyses (exact prompt, data hashes, model, signed
receipt, output) and RFC 3161 timestamps, and exports a signed record an inspector can check in their browser. Use only
what is listed below. If you need something else, stop and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- Hosted is for synthetic, public or published data. Unpublished results belong on a self-hosted box.
- It supports 21 CFR Part 11 audit-trail requirements; it does not make us compliant (validation and SOPs are ours).

## Auth
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page, in the environment variable
   `DECOSA_API_KEY`, never in code. Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "signed-lab-notebook"}` returns `{"token", "expires_at", "budget"}`.
   A notebook is visible only to the key or token that made it; hosted notebooks expire after 14 days.

## The flow
1. `POST /notebook/books` `{"title", "lab"?, "project"?, "description"?, "owner": {"name", "role"?, "pubkey"?}}` → `{notebook_id, ...}`.
2. Members who write or sign: `POST /notebook/books/{id}/members` `{"name", "role"?, "pubkey"?}`. A `pubkey` (raw Ed25519,
   64 hex) means that person must sign with their own key; without one, signatures are recorded as "account".
3. Entries: `POST /notebook/books/{id}/entries` `{"title", "text", "author", "attachments": [{"name", "sha256", "bytes", "kind": "instrument", "instrument": {"name", "serial"?, "run_id"?}}]}`.
   Hash files locally; never send them. Entries are numbered 1, 2, 3.
4. Corrections: `POST /notebook/books/{id}/amend` `{"amends": <entry number>, "text", "reason", "author"}`. The original stays.
5. AI analysis: `POST /notebook/books/{id}/analysis` `{"question", "requested_by", "of": [entry numbers], "data": [{"name", "text"}]}`.
   Each data file's SHA-256 must equal an attachment already recorded (409 otherwise). One receipted model call:
   `{entry, text, receipt, usage}`; `"stream": true` gives SSE `ready`, `receipt`, `analysis`, `budget`, `done`.
6. Sign: `POST /notebook/books/{id}/sign` `{"n", "meaning": "authored" | "witnessed" | "reviewed" | "approved", "signer", "signature"?: {"sig", "signed_ms"}}`.
   With an enrolled key, sign `"decosa.notebook-signature.v1\n" + canonical JSON of {v, notebook, target_seq, target_hash, meaning, signer, statement_sha256, signed_ms}`
   (see `GET /notebook/info`; `target_seq` and `target_hash` come from the entry, `statement_sha256` is the SHA-256 of the meaning's statement).
7. Timestamp: `POST /notebook/books/{id}/timestamp` `{}` (RFC 3161, at most one a minute per notebook).
8. Export: `GET /notebook/books/{id}/export` (signed JSON) and `GET /notebook/books/{id}/audit.csv`.

## Example (Python, `pip install httpx`)
```python
import hashlib, httpx, os, pathlib
API = "https://api.decosa.ai"
c = httpx.Client(base_url=API, headers={"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}, timeout=180)
nb = c.post("/notebook/books", json={"title": "Kinetics notebook", "owner": {"name": "Dr. Ada Lin"}}).raise_for_status().json()
N = nb["notebook_id"]
data = pathlib.Path("rates.csv").read_bytes()
c.post(f"/notebook/books/{N}/entries", json={"title": "Plate run", "text": "Initial rates attached.", "author": "Dr. Ada Lin",
       "attachments": [{"name": "rates.csv", "sha256": hashlib.sha256(data).hexdigest(), "bytes": len(data), "kind": "instrument",
                        "instrument": {"name": "Plate reader"}}]}).raise_for_status()
a = c.post(f"/notebook/books/{N}/analysis", json={"question": "Summarise and flag outliers.", "requested_by": "Dr. Ada Lin",
           "of": [1], "data": [{"name": "rates.csv", "text": data.decode()}]}).raise_for_status().json()
print(a["receipt"]["status"], a["text"][:200])
rec = c.get(f"/notebook/books/{N}/export").raise_for_status().json()
print(httpx.post(f"{API}/notebook/verify", json={"record": rec}).json()["summary"])
```

## Verify
- `POST https://api.decosa.ai/notebook/verify` `{"record", "earlier"?}` (no token): hashes, signatures, AI receipts, TSA tokens and
  the notebook rules; with `earlier`, whether nothing before it was rewritten.
- The site's verify page (`/notebook/verify`) runs the same checks in the browser, with no upload.

## Honest limits
- AI analyses are recorded and receipted, not checked for correctness; a person must review them.
- Our server signs exports. Keep your own copy of each export and use personal keys for signers: those catch an
  operator who rebuilds a notebook.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa signed lab notebook: run it yourself (containers)

You are setting up Decosa's signed lab notebook on this machine, so unpublished results and invention records stay
here. The notebook (decosa-api) needs no GPU. Qwen3.8-27B is only needed for AI analyses. The only outbound call is the
RFC 3161 timestamp request (a 32-byte digest to the Time-Stamp Authority), and it can be turned off.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Hardware: any Linux x86_64 machine for the notebook; 1x RTX 5090 32 GB or larger for Qwen3.8-27B (NVFP4). Ask me before
any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
   nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
   "test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
   https://decosa.ai/samples/signed-lab-notebook.zip (6 KB, 7 checks, synthetic or openly licensed: see `licence` in expected.json),
   show me what is in it, and run the rehearsal against the local API:
   `docker compose exec api python scripts/rehearse.py signed-lab-notebook` (the api image carries the same bundle under /app/rehearsal/signed-lab-notebook/;
   with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
   `python scripts/rehearse.py signed-lab-notebook --bundle signed-lab-notebook.zip --base-url http://127.0.0.1:<PORT>`.
   It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "the AI analysis flags the planted outlier well F7", "the analysis records the SHA-256 of the rates file it read", "the amendment points at the original run entry, which stays in the record"). Show me
   the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
   to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
   machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Rules you must keep
- Bind every port to 127.0.0.1. Expose nothing without my approval.
- The box's signing key is created on first start in the data volume (`attest/ed25519.pem`, 0600). Back it up with the
  notebooks (`/data/notebook/*.jsonl`); never print it.
- Set `DECOSA_NOTEBOOK_TTL_S` to our retention (the default is 14 days, for demos).
- Part 11: this supports audit-trail and signature-manifestation requirements; validation, SOPs and access control are ours.

## Steps
1. Docker (and the NVIDIA Container Toolkit if you run the model): if `docker compose version` fails, install it from
   the official Docker instructions.
2. Fetch the compose file: `mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`. Read it.
   Keep the `api` service; keep `llm` only for AI analyses. The api's data goes in a named volume, not a host folder.
3. In `.env`: `DECOSA_LLM_ROUTE=direct`, `DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b` (with `llm`),
   `DECOSA_ADMIN_SECRET` (a long random string, file mode 0600), `DECOSA_NOTEBOOK_TTL_S`, and `DECOSA_NOTEBOOK_TSA_URL`
   (`https://freetsa.org/tsr` by default, our own TSA, or `off`).
4. Start: `docker compose pull && docker compose up -d`. Wait for `curl -fsS http://localhost:<PORT>/notebook/info`.
5. Mint a key: `POST /v1/keys` with the admin secret and `{"label": "lab", "verticals": ["signed-lab-notebook"]}`.
6. Smoke test with a token from `POST /demo/session {"vertical": "signed-lab-notebook"}`: take the `enzyme-kinetics`
   sample from `GET /notebook/samples`, create a notebook, add the members, an entry with `rates.csv` attached by its
   SHA-256, an analysis of it (with `llm`; expect receipt status `attested`), an amendment with a reason, a witness
   signature, and a timestamp. Then `GET .../export` and `POST /notebook/verify {"record": ...}`: expect `ok: true`.
7. Change one digit in the analysis entry's data and verify again: it must fail at that entry.
8. Report back: health, the signing key id, the verify summary and the time each step took.

Off by default. Leave it off unless I ask.

No NVIDIA GPU? This tool also runs entirely on an Apple Silicon Mac (MLX, 32 GB of unified memory or more): use https://decosa.ai/prompts/signed-lab-notebook-mac.md instead.