docs

Notes that have to stay true. Everything here was measured against the live ledger or the live tape, not reasoned about.

What this is for — the standing list of what this service is meant to do, and what is blocking what. Read that first.

Layout


`findings/`	things the scorer discovered by running. One file per finding, dated.
`data/`	the tape: what it costs, where it lives, how it is shaped.
`ledger/`	what the desk's own schema actually contains, as opposed to what it looks like it contains.
`walkthrough.md`	start here: one pass through everything the service does, with the real commands and what they print.
`using-the-api.md`	for users: get a key, read scores, pull a day of tape, play it back.
`api.md`	the reference: auth, REST, and the two WebSockets — events, and the replay of a symbol-day at tape pace.
`deploy.md`	`/opt/postmortem` on the box, beside tradingdesk; the `api.slowdesk.io` ingress; minting keys.
`../seed/`	every source, sampled from the real ones: 31 rides, their scores, and 35 minutes of AAPL tape. `docker compose -f compose.yml -f compose.dev.yml up` runs on it alone. `bin/seed.ts` made it.
`feeding-selection.md`	how post-mortem learnings reach candidate selection — and the ratchet to avoid.

date	finding	status
2026-09-03	A booked entry price that never happened	gate shipped
2026-09-03	Mechanical R must respect the plan's horizon	fixed
2026-09-03	The Runner's 15:55 eject did not fire on 2 of 54 rides	open — desk-side
2026-09-03	The desk's sampled marks understate both excursions	open
2026-09-03	Half the lake's symbols cross a split	factors landed
2026-09-03	Cut plans are rewritten — the sample is ~51, not 228	open — desk-side

What Databento gave us for free — historical; the plan was cancelled 2026-09-24 (#14) and the tape is Massive
The lake layout — s3://slowdesk-io/market-history/, and why raw exists for ticks only
The no-spend guarantee — how it is enforced, and how it is tested
The replay tape — what slowsocket would have recorded, a year back, in the shape its loader already reads (tradingdesk#777)

The trainer repo asks for several things this service either already produces or directly blocks:

issue	overlap
#47 SC-5 — say whether the trader helped or hurt	this service, essentially in full: same three lines, same warning about preserving the issued stop and target
#4 DT-1 — the decision instant and the label	its label is our mechanical outcome; the entry gate is what makes the decision instant trustworthy
#32 DT-8 — the intra-trade action stream	the actions we reconstruct to explain a delta. Its hard rule — outcome-side only, never a feature — applies to everything we emit
#7 DT-4 — what execution cost is captured	measured: `positions` has no cost column at all, while `order.sent` carries the quote on 1,869 of 1,869 rows
#5 DT-2 — near-miss observability	the `skip` moment — but only ~51 plans are scoreable, not the 228 the table suggests
#50 — unadjusted daily bars	confirmed far worse on our universe: 60 of 125 symbols, not 2 of 8
#21 TN-11 — S3 is the source of truth	same premise as the lake layout

Recovering the issued levels — four sources, one of which is safe only by accident
Attribution — why delta has no owner yet

One finding per file, named YYYY-MM-DD-short-slug.md, with four headings: What we saw, Why it matters, What we did, Still open.

Two rules, both learned the hard way in this repo:

Put the evidence in. Real symbols, real numbers, real timestamps. A note that says "prices can be wrong" ages into noise; one that says "LHAI booked $1.02 at 13:30:11Z while the tape opened at $1.22" can be re-checked years later.
Say which half you checked. "The structured field is null on 88% of rides" and "the issued target is unrecoverable on 88% of rides" are different claims, and the first was true while the second was not. State the one you actually tested.