# Playbook — Teach retrieval which paths pay, and check it cannot buy its way past a budget

Run a learning loop over real recalls, verify the reward shape penalises a numerous dead-end path, and confirm the learned field never overrides a bound.

## What you need

- Docker 24 or later
- Python 3.9 or later
- About 3 minutes

## 1. Start a disposable Corrobore

```bash
mkdir -p .corrobore-tls .corrobore-secrets
printf '%s\n' 'change-me' > .corrobore-secrets/http-token
openssl req -x509 -newkey rsa:2048 -sha256 -nodes \
  -keyout .corrobore-tls/server.key -out .corrobore-tls/server.crt \
  -days 30 -subj '/CN=localhost' \
  -addext 'basicConstraints=critical,CA:FALSE' \
  -addext 'keyUsage=critical,digitalSignature,keyEncipherment' \
  -addext 'extendedKeyUsage=serverAuth' \
  -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1'

docker run --rm -d --name corrobore-playbook \
  -p 127.0.0.1:8080:8080 \
  -e CORROBORE_STORAGE_MODE=ephemeral \
  -v "$PWD/.corrobore-secrets/http-token:/run/secrets/corrobore-http-token:ro" \
  -v "$PWD/.corrobore-tls/server.crt:/run/secrets/tls.crt:ro" \
  -v "$PWD/.corrobore-tls/server.key:/run/secrets/tls.key:ro" \
  ghcr.io/estance-labs/corrobore:latest

curl --insecure -H 'Authorization: Bearer change-me' https://127.0.0.1:8080/health/ready
```

## 2. Install the notebook dependencies

```bash
pip install requests
```

## 3. Run the notebook

```bash
jupyter lab notebook.ipynb
```

The notebook loads `dataset.json` from the same directory. Keep the three files together.

## 4. What to observe

1. The reward uses evidence reached per unit of cost, so the 54 restatements are penalised despite outnumbering the productive paths.
2. The path to registry filings gains utility while the path to restatements accumulates a negative trace.
3. The intrusion task learns a different field over the same graph; neither knows about the other's edge kinds.
4. A reinforced path under a small budget still returns a bounded outcome: utility changes ordering, not limits.
5. After six traversals every record is still at version 1, with confidence and provenance untouched.

## 5. Change one thing and re-run

- Change the reward to count records reached instead of evidence reached, and watch the restatement path win.
- Set `DECAY` to 1.0 and check whether a path that stops paying ever loses its lead.
- Merge the two fields into one and observe the financing experience steering the intrusion traversal.
- Raise `max_cost` in the starved recall until `complete` becomes true again.

## Boundaries

- The financing chain, the aggregators and the hosts are synthetic.
- Pheromone fields, navigation score and the contextual controller are `graph-core` primitives with no HTTP route in this release; the accumulation here is a deliberately simple client-side stand-in.
- The reward signal is real engine telemetry, and the budget behaviour is the contract's.
- Retrieval-efficiency figures for the real implementation are benchmark targets, not product promises.

## Tear down

```bash
docker rm -f corrobore-playbook
```

---

Documentation: https://docs.corrobore.org — Source: https://github.com/Estance-Labs/corrobore