docs/DEMO-SCRIPT.md (the one doc a judge actually runs commands from) still said `make build` produces 4 Go binaries and `scripts/run-demo.sh` starts audit-log/ledger-core/gateway/agent only — stale since the section-1 split added auth/tenant-registry/card-issuance/webhook-ingestion, same staleness class README.md had before today's earlier pass fixed it there. Verified live: `make build` produces 10 Go binaries, `scripts/run-demo.sh` starts 8 services. Also added a step showing `ration tenant`/`card`/`apikey` — 3 operator command groups built across many rounds today that this doc never mentioned at all, verified live against the real running stack.
10 KiB
Demo script — for hackathon judges
This is the exact command sequence to see Ration's agentic rationing
decision happen live, end to end, with no Airwallex sandbox credentials
required (everything below runs in AIRWALLEX_MODE=mock).
Total time: under 2 minutes of waiting, most of it a single 10-second agent poll interval.
0. Build
make build
Builds the C WAL (services/wal/libwal.a), the Rust ledger-core release
binary, and 10 Go binaries into ./bin (gateway, auth,
tenant-registry, card-issuance, webhook-ingestion, agent, tui,
ration, audit-log, verify-chain) — the full post-split service set
(docs/SCALE-EXPANSION.md section 1), not just the original 4 from the
first scaffold build.
1. Start the stack and seed demo tenants
scripts/run-demo.sh
This starts, as background processes, all 8 services (confirmed
against the script's own startup banner and docker-compose.yml's
service list — this doc previously undercounted it at 4, the same
staleness class README.md had before a 2026-10-29 pass fixed it there):
- audit-log (Go) — the append-only, hash-chained audit trail service
(
AUDIT_LOG_GRPC_ADDR, defaultlocalhost:7003), started first so ledger-core has a live mirror target from the moment it starts. - ledger-core (Rust, release build) — the authoritative ledger, on
LEDGER_CORE_ADDR(defaultlocalhost:7001). WithAUDIT_LOG_ADDRset (whichscripts/run-demo.shalways does), everyApplyEntryandRecordAgentDecisioncall is mirrored into audit-log's hash chain. - auth (Go) — tenant API-key issuance/verification and operator JWT
minting, on
AUTH_GRPC_ADDR(defaultlocalhost:7010). Every other service below mints a short-lived operator credential from this one at startup. - tenant-registry (Go) — tenant onboarding (
CreateTenant/ListTenants), onTENANT_REGISTRY_GRPC_ADDR(defaultlocalhost:7011) — whatration tenant create/tenant list(step 8 below) actually talks to. - card-issuance (Go,
AIRWALLEX_MODE=mock) — card issuance, limit adjustment, and the bridge-funding rationing math itself, onCARD_ISSUANCE_GRPC_ADDR(defaultlocalhost:7012). - webhook-ingestion (Go) — the HMAC-verified
POST /webhooks/airwallexlistener, onWEBHOOK_INGESTION_GRPC_ADDR/HTTP:8081. - gateway (Go) — the external BFF: gRPC + REST/JSON
/v1/*+ the judge-facing HTML dashboard, dialingauth/ledger-core/card-issuance/webhook-ingestiondirectly (nottenant-registry— that one's only reached via its own dedicated port, step 8 below), onGATEWAY_GRPC_ADDR(defaultlocalhost:7002). - agent — the polling loop that watches for late deposits and runs the rationing decision pipeline (default poll interval: 10s).
If this box is under load from other concurrent processes, any one of the
services above can fail to start with a DeadlineExceeded minting its
startup operator JWT against auth. If that happens, use
scripts/start-individually.sh instead — identical result, longer delays
between each service's startup.
It waits for ledger-core and gateway to actually be accepting TCP
connections on their gRPC ports before moving on (not a fixed sleep), then
runs ./bin/ration seed, which:
- creates 3 demo tenants (small/medium/large platforms, 3 different settlement currencies), and
- funds each one with settled opening capital above its reserve floor (e.g. the small tenant: $2,500 reserve floor, $7,500 opening capital → $5,000 of real headroom) — so the very first late-deposit scenario below has real money to ration against, not just a guaranteed decline.
You'll see output like:
Lumen Creator Payouts id=<tenant-id> currency=USD reserve_floor=2,500.00 USD
funded with 7,500.00 USD of settled opening capital (headroom 5,000.00 USD above reserve floor)
Copy one of the printed tenant IDs — you'll need it for the next step.
2. Open the TUI (second terminal)
./bin/tui
Watch the activity feed tab — this is where the deposit and agent
decision events land live, pushed over gateway.proto's StreamActivity
gRPC stream. Also check the tenants tab to see the funded balance from
step 1.
3. Trigger a late deposit
Back in the first terminal:
./bin/ration simulate-deposit --tenant <tenant-id> --amount 400000 --late
(400000 minor units = $4,000 for a USD tenant — minor units are always
cents/pence/etc., see pkg/money.) --late backdates the deposit's
expected-arrival time by default so the agent's ListLateDeposits scan
picks it up on its very next poll, instead of waiting for a real SLA
window to pass.
4. Watch for the decision
Within one poll interval (10s by default — RATION_AGENT_POLL_INTERVAL_SECONDS
to change it), two things happen:
- In the TUI's activity feed: a
depositevent for the simulated deposit, and — once the agent's policy envelope computes — a corresponding activity entry. - Via the CLI:
Look at Recent agent decisions. You should see something like:./bin/ration status --tenant <tenant-id>
That rationale is not a template string — it's the literal output ofWHEN TRIGGER ACTION RATIONALE 2026-10-19T02:59:02+03:00 deposit_late AGENT_ACTION_RATION_BRIDGE partial grant: capped to 240000 minor units by reserve-floor headroom (500000) and the 60% bridge cap (240000) against a 400000 requestservices/agent/internal/policy/rules.go's envelope computation (policy.ComputeBridgeEnvelope), run against this tenant's actual headroom and this deposit's actual amount, and persisted viaRecordAgentDecisionbefore the LLM is even called (seedocs/AGENT-DESIGN.md's audit-trail section).
5. What to watch for if ANTHROPIC_API_KEY is unset
The agent logs a clear warning on startup (ANTHROPIC_API_KEY is not set; LLM calls will fail until it is configured) and keeps running. Every tick
still:
- computes the deterministic hard-rule envelope (reserve floor, 60% bridge
cap, 24h velocity cap — see
docs/AGENT-DESIGN.md), - records it as an auditable
AgentDecisionviaRecordAgentDecision, then - attempts the LLM call for tenant-facing phrasing / spend-control
tightening, which fails with a logged
ERROR(LLM conversation: llm: ANTHROPIC_API_KEY is not set) — never silently.
This is the fail-safe property the architecture is built around: the
hard-rule envelope is money-safety-critical and runs independently of the
LLM; the LLM only ever adds judgment on top of an already-safe,
already-logged decision. You can verify this live by running the sequence
above without setting the key — the ration status decision table still
populates.
6. Watch the velocity cap kick in (optional)
Run ration status again a few poll cycles later (the same late deposit is
still outstanding, so the agent keeps re-evaluating it on every tick). You
should see a second decision for the same tenant:
AGENT_ACTION_DECLINE velocity cap: a prior bridge grant within the last 24h has not yet been repaid
This is docs/AGENT-DESIGN.md rule 3 — "max 1 bridge grant per tenant per
rolling 24h unless the prior grant was fully repaid" — enforced exactly as
documented.
7. Verify the audit trail independently
Every ledger write and agent decision above was mirrored into audit-log's append-only, hash-chained log as it happened. Verify that chain is intact without trusting the live audit-log process at all — the standalone verifier re-derives the hash chain straight from the log file on disk:
./bin/verify-chain ./data/audit.log
Expected output:
verify-chain: intact (<N> records checked) — ./data/audit.log
<N> should be at least one record per ApplyEntry/RecordAgentDecision
call so far (the opening-capital funding from step 1, the simulated
deposit from step 3, and every agent decision from steps 4/6). A nonzero
exit code and a CHAIN BROKEN at sequence ... message would mean the log
was tampered with or corrupted after the fact — this is what makes "the
audit trail is the point" (README, docs/SUBMISSION.md) a checkable claim
instead of an assertion.
8. Operator surface: onboard a tenant, issue a card, mint a credential
The steps above exercise the agent's own decision loop. Separately, ration
has 3 operator-facing command groups added across later rounds of this
build (tenant, card, apikey) that a judge can drive directly — none
of these mutate anything the agent's own demo flow above depends on, so
they're safe to run before or after it:
./bin/ration tenant create --name "Acme Platform Payouts" --currency USD --reserve-floor-minor-units 500000
./bin/ration tenant list
./bin/ration card issue --tenant <tenant-id> --cardholder "Jane Operator" --limit 100000
./bin/ration status --tenant <tenant-id> # the new card shows up, Held balance reflects its limit
./bin/ration apikey issue --tenant <tenant-id> # mints a real credential for sdk/go/ration or sdk/rust/ration-client
ration tenant create/card issue both go through real gRPC round trips
(tenant-registry/card-issuance respectively, fronted by gateway for
the card path) — the new tenant and card are both independently visible
via ration status, not a local echo.
9. Shut everything down
scripts/stop-demo.sh
Kills every PID recorded in .ration-demo.pid from step 1 and removes the
file. Safe to run even if some processes already exited.
Troubleshooting
- "missing binary ... run 'make build' first": you skipped step 0.
- A port is already in use: an earlier demo run's processes weren't
stopped. Run
scripts/stop-demo.sh, orlsof -i :7001/:7002to find and kill stragglers manually, then retry. ration statusshows 0 decisions after waiting: confirm the agent process is actually running — checkdata/logs/agent.logfor atick: scanning late depositsline withcount> 0. Ifcountis 0, the deposit wasn't recorded as late; re-run step 3 with--late.