Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ dist/
build/
target/
coverage/
.coverage
.coverage.*
.env
.env.*
!.env.example
Expand Down
234 changes: 230 additions & 4 deletions docs/pdr/0002-three-verdicts-not-two.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
status: proposed
status: accepted
decider: "@napkinstack-admin"
---

# PDR-0002 — Three verdicts, not two

- **Status**: Proposed
- **Status**: Accepted
- **Date**: 2026-09-21
- **Decision makers**: @napkinstack-admin, who delegated product decisions of this kind to the
framer on 2026-09-21; recorded here rather than left in the conversation
Expand Down Expand Up @@ -119,8 +119,8 @@ applies, so the headline alone is actionable.
- **The floor fails and a reservation would also apply** — `NOT COPYABLE` wins. Impossible
beats expensive, and the reservations are still printed so the administrator learns why the
trader is unsuitable twice over.
- **The window was cut short** — unchanged: the figures are named as extrapolated, and the
reservation thresholds are applied to them as they stand.
- **The window was cut short** — see the amendment below. The figures are named as
extrapolated, and how far they were stretched is itself a reservation.

**Business rules:**

Expand Down Expand Up @@ -188,3 +188,229 @@ measurements rather than in the verdict.
- **Support and documentation**: the module's `README.md` states the four verdicts and their
exit codes. An exit code is an interface and is documented as one.
- **Data**: no change. The same four measurements, from the same public reads.


---

## Amendment, 2026-09-21 — a fourth reservation, and a ceiling

**Decided by the framer**, under the delegation recorded above, while implementing this PDR.

### What changed

This PDR originally said a cut-short window changes nothing: name the figures as extrapolated
and apply the thresholds as they stand. Running the command against the live venue showed that
is not enough.

A 30-day question answered from **2.4 hours** of fills is stretched to a month by a factor of
**319**. Every downstream figure — turnover, fee burden, flet's revenue share — carries that
factor. The answer said `extrapolated`, truthfully, and then printed
`125.34% of their ticket per month in fees` as though it were a measurement. An administrator
cannot act on that, and the middle verdict was not warning them about it.

So:

- **Extrapolation is the fourth reservation**, alongside fees, reproducibility and
concentration. It applies when the window asked for was stretched by more than **3×** — that
is, when less than ten days of a thirty-day question were actually read.
- **Past 30×**, there is no verdict at all. A single day of fills stretched to a month is not
a weak answer, it is a guess with the shape of a measurement, and the module's own rule is
that a verdict without a usable measurement is not an answer.

### Why these two numbers

3× is where a month's question starts resting on a week. 30× is a single day. Neither is
sacred, and both are one set of numbers for every administrator and every community, as the
business rules above require.

Sampled live on 2026-09-21: a trader whose thirty days fit is stretched by 1× and trips
nothing; the densest trader in the test set reads about 2 days and is stretched by ~15, which
is a reservation; the 2.4-hour case is refused.

### The ceiling outranks every verdict, the floor included

Written because the framer read *"the floor alone decides `NOT COPYABLE`"* as *"the floor
outranks `NO VERDICT`"*, built that, and a verifier measured what it produced: `NOT COPYABLE`
printed above `8352.24% of their ticket per month in fees`, `extrapolated ... by a factor of
823.3`. The success criterion three paragraphs above says no administrator is ever shown a
figure stretched past 30×, and that change violated it within the hour.

So, explicitly: **the ceiling is checked before any verdict is formed.** `NO VERDICT` is the
most severe outcome and the exit codes already say so.

*"The floor alone decides `NOT COPYABLE`"* means nothing **other than** the floor may produce
that verdict. It is not a statement of precedence over the absence of one.

And the reasoning that seemed to justify the reorder — *the floor is read straight off the
notionals and needs no extrapolation* — is false. The notionals read are the ones inside the
window that was actually returned, so `refused_share` and `minimum_ticket` computed from half
an hour are inferences presented as facts about a trader: the same move this amendment forbids
one section earlier.

### Which window's days concentration counts against

Raised in verification, and settled here because the wording above did not settle it.
`concentration` counts the days traded against **the days actually read**, not the days asked
for. On a cut-short window those differ: a trader read over 2 days who traded on both shows a
ratio of 1 and trips nothing, although the month's volume the command reports landed on 2 of
the 30 days it asked about.

That is deliberate. The reservation is a statement about what was observed, and counting
against a window that was never read would be the same mistake as the figures this module
spent a cycle removing — a number derived from what was *asked for*, printed as a fact about
what was *read*. The `extrapolation` reservation is what warns about the unread part, and on
every trader sampled so far it fires whenever this one is silenced by a short window.

### What it does not change

The floor still decides `NOT COPYABLE` alone. A reservation is still never a refusal. The
ceiling is not a reservation that got stricter — it is the `NO VERDICT` case this PDR already
defined as *"the data cannot support an answer"*, given a threshold so that it can be applied
rather than argued about.

### Success criterion

By **2026-12-31**, no administrator has been shown a monthly figure stretched by more than
30×, and the share of real traders refused by the ceiling is under 5% of the ones screened.
Above that, the ceiling is screening out traders rather than protecting anyone, and the read —
not the verdict — is what needs fixing (`modules/screening/docs/adr/0003`).

### Removal condition

If the read ever covers the window it asks for reliably, the extrapolation reservation and the
ceiling both become dead code and are removed rather than left as reassurance.


---

## Amendment, 2026-09-22 — `NO VERDICT` is an empty stdout, not a word

**Decided by @napkinstack-admin**, asked directly, after a confirmation run raised the gap.

### What this settles

This PDR and D3's sixth acceptance criterion both say *"the verdict is `NO VERDICT`"*. The
command prints those two words nowhere. It writes **nothing at all on stdout**, puts
`no verdict: <reason>` on stderr, and exits `3`:

```
$ screening 0xabc --ticket 500
no verdict: the trader's account value must be a positive number # stderr
$ echo $?
3
```

That is the intended behaviour and it stays. **stdout carries the answer a script consumes;
stderr carries the explanation a human reads.** When there is no answer, stdout is empty, so
nothing a script reads back can be mistaken for a verdict — which is the same concern that
renumbered the exit codes by severity one section above.

### Why it is written here

The module's `README.md` had already restated the criterion this way, as
`*(nothing on stdout)*` | **3**. The verifier's finding was not about the behaviour, which it
had confirmed on twelve separate shapes of unreadable input: it was that **an expected result
had been changed in a README, by the author, without the decider agreeing to it visibly**
(`playbooks/verification.md`). The reading was right and the route was wrong, so the decision
is recorded where decisions live, and the README now follows the PDR rather than amending it.

### What it does not change

No code, no test, no threshold. `NO VERDICT` remains the name of the outcome in this document,
in the cycle's acceptance criteria and in the module's own vocabulary — it is the name of an
absence, and the absence is what is printed.


---

## Amendment, 2026-09-22 (second) — what "nothing on stdout" promises, and what it cannot

**Decided by @napkinstack-admin**, asked directly, after a third confirmation run.

### Why this one exists

The amendment above says *"it writes nothing at all on stdout"*. Taken literally, that is a
promise about every way a process can be started, and three confirmation runs walked into it
one layer at a time: the reason printed by this module's own code (closed), the reason printed
by the backstop under it (closed), the usage line printed by `argparse` (closed), and then
CPython's own finaliser, which writes `Exception ignored on flushing sys.stdout` and exits
**120** when it cannot flush a stream the command already gave up on.

Each was a real finding. The fourth is not reachable from inside the module, and a promise the
code cannot keep will keep producing refusals until it is written as what it actually is.

### What the command guarantees

**All three speak about what the command *chooses* to write.** Bytes it already handed to the
operating system, before a reader went away or a stream refused the rest, are not a choice and
are not covered — the third confirmation run had to say this once about a word and once about a
partial line, and it is written here as one rule so it does not have to be said a third time.

- **When no verdict is formed, nothing the command writes goes to stdout.** Not the reason, not
a usage line, not a partial answer. The reason goes to stderr when there is a stderr able to
take it, and nowhere at all when there is not. *No verdict formed*, not *exit code 3*: the
paragraph below establishes that 3 is also what a formed verdict returns when it cannot be
delivered, and on that route stdout holds whatever the failed write had already put there.
- **The exit code is the interface.** `0`, `1`, `2`, `3`, by severity. A caller decides on the
code; stdout is for a caller that also wants the figures.
- **No word this command chooses ever names a verdict on stdout unless that verdict was
formed.** The qualifier is owed: the address is echoed into the headline as the caller typed
it, so a caller passing an address that contains a newline and the words `NOT COPYABLE` reads
them back. Measured, and left as a caller attacking itself rather than fixed inside a
deliverable already over budget — unless the address comes from a list the caller did not
write, which is the day input validation stops being a follow-up. What the **venue** says
never reaches stdout: 150 fuzzed answers with coin names literally `"COPYABLE"` leaked
nothing.

**`--help` is the exception to the first two, and the only one.** It forms no verdict, writes
its usage to stdout by design, and exits **0** — the one exit 0 that is not a verdict, as the
module's README already said and this document did not. Nine routes to it were measured, from
`-h` to `0xabc --ticket 500 --help`; every one prints the usage and exits 0. It is an exception
rather than a defect because it says nothing about a trader: a caller who asked how to run the
command is not a caller being told an answer.

Recorded because narrowing the first guarantee to *no verdict formed* — which was the right
narrowing, and load-bearing — pulled `--help` squarely inside a sentence that then denied what
it does. The command was never wrong here; three drafts of this paragraph were.

### What it does not guarantee, named so it is not rediscovered as a defect

**A verdict that cannot be delivered comes back two different ways**, and the first sentence
written here named only the rarer one.

- **The write fails** — `PYTHONIOENCODING=ascii` cannot encode the em dash in the headline —
and the command's own backstop returns **3**. That is one of the four codes, and it reads as
*the data cannot support an answer* about a trader whose data supported one perfectly. It
fails in the safe direction: never a verdict, never a wrong one. A caller cannot tell it from
an unreadable venue, and that is the cost of the backstop, stated rather than discovered.

**How much of stdout survives depends on where the write died**, and the first version of this
bullet claimed the tidier half as though it were the whole. An encoder that refuses the answer
leaves stdout **empty** — measured, including on a 133 KB answer, because it refuses the chunk
whole. A reader that closes a pipe partway through an answer larger than the buffer leaves
**what was already written**: exit 3 over 40 bytes reading `COPYABLE — …`, measured three times
out of three. It needs an answer past 64 KB, which needs a ticket no validation rejects yet —
one more reason `--ticket` validation is the follow-up it is.
- **The flush fails** — the interpreter cannot empty a stream the command already gave up on —
and CPython prints its own message and exits **120**. Outside the four codes on purpose: a
caller switching on `0`/`1`/`2`/`3` never reads it as an answer.

**And a caller that changes how the interpreter exits replaces the code.** `PYTHONINSPECT=1`
re-enters the REPL after the script and discards its status: the command returns 3 and the
process exits 1. It is not this command deciding — `PYTHONINSPECT=1 python -c "sys.exit(3)"`
does the same — and it cannot be undone from inside the process. Named here as the general case,
because the first draft named only the 120 and the next verifier filed the rest as new.

The same is true of whatever a shell or a supervisor writes to the same descriptors.

### What it does not change

No threshold, no verdict, no exit code, and no line of the module. The three guarantees above
are what the command already does at this head, with the `argparse` route closed; this amendment
states them where the next verifier will read them, instead of leaving a stronger sentence that
the next layer would falsify again.

Its own first draft was falsified within the day, by the confirmation run it was written for:
two of the three paragraphs above exist because a verifier showed the sentence under them was
wrong in the common case, or written more absolutely than the code supports. Recorded that way
round on purpose.
2 changes: 1 addition & 1 deletion docs/pdr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,4 @@ The PDR describes **what the product must do and why**, never its implementation
| No. | Title | Status | Criterion to check on |
|---|---|---|---|
| [0001](./0001-charge-on-routed-volume-never-on-the-member-s-gains.md) | Charge a flat commission on routed volume, never a share of the member's gains | Accepted | 2027-03-21 |
| [0002](./0002-three-verdicts-not-two.md) | Three verdicts, not two: copyable, copyable with reservations, not copyable | Proposed | 2026-12-31 |
| [0002](./0002-three-verdicts-not-two.md) | Three verdicts, not two: copyable, copyable with reservations, not copyable | Accepted | 2026-12-31 |
46 changes: 46 additions & 0 deletions modules/screening/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,52 @@ nstack run screening # locally, with doubles for the dependencies

Commands: the `commands` section of the MANIFEST, to declare for this module's stack.

## What the command answers

```
screening <address> --ticket <amount>
```

One of four verdicts on the first line, then every figure it rests on. A verdict without its
measurement is not an answer here.

| Verdict | Exit | Means |
|---|---|---|
| `COPYABLE` | **0** | At least **80%** of the trader's orders clear the venue's 10 USDC floor at this ticket, and nothing else is worth reserving about. The share that would still be refused is printed. |
| `COPYABLE WITH RESERVATIONS (…)` | **1** | Clears the floor, and at least one reservation applies. The reservations are **named in the headline**, so the first line alone is actionable. |
| `NOT COPYABLE (…)` | **2** | More than 20% of the orders fall under the floor. The member cannot place this trader's orders at this ticket, whatever else is true — impossible beats expensive. Any reservations are still printed below. |
| *(nothing on stdout)* | **3** | **No verdict.** The venue could not be read or answered with something that is not a number, the command line was malformed, or the data cannot support an answer. |

`--help` prints the usage and exits **0**, as a command should. It is the one exit 0 that is not a verdict.

**Only these four codes are answers.** A verdict that cannot be written comes back as **3** when the write
itself fails — an stdout that cannot encode the answer — and as **120** when the interpreter cannot flush it.
Neither is an opinion about the trader, and a caller that changes how the interpreter exits, such as
`PYTHONINSPECT`, replaces the code outright
([PDR-0002](../../docs/pdr/0002-three-verdicts-not-two.md), second amendment of 2026-09-22).

**The codes run by severity**, so a script keeping the idiom it already has — `if code == 0` —
stops getting a zero for a trader the command was warning it about.

**No verdict outranks every verdict, including `NOT COPYABLE`.** If the window the venue
returned is stretched to a month by more than **30×**, the command refuses before forming any
verdict at all — because at that point the floor share and the minimum ticket are inferences
from half an hour, and printing them as facts about a trader is the thing this module exists
to not do.

### The four reservations

| Named | Applies when |
|---|---|
| `fees` | The monthly fee burden is **above 5%** of the member's ticket. The fees, not the strategy, will decide their result. |
| `reproducibility` | **More than half** the trader's fills were posted rather than taken. A copier arriving afterwards cannot reproduce them. |
| `concentration` | The volume landed on **a third or fewer** of the days read. A month's volume in one burst is not a month of trading. |
| `extrapolation` | The venue could not return the whole window, and the monthly figures are stretched by **more than 3×**. |

Thresholds are one set of numbers for every administrator and every community. An
administrator cannot tune them and a trader cannot be exempted
([PDR-0002](../../docs/pdr/0002-three-verdicts-not-two.md)).

## Contracts

- Provided: see `provides` in the MANIFEST
Expand Down
Loading
Loading