openalgo-script 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,935 @@ nothing, fails the build before it can become permanent.
 
 ---
 
+## 0.5.0
+
+**`pow` has no library vector, and the reason is the same one.** A vector is a
+bit pattern a second engine is written to match, and `pow` returns different
+bits on two runtimes of the same virtual machine: publishing one hands that
+second engine a test it cannot pass and this engine cannot keep. The vectors
+were added after the last release, so this is the first build to check them
+anywhere but where they were made.
+
+`compiled-program.md` 8.3 already requires that the transcendental functions not
+use the platform's maths library, and the source records that they do until the
+portable algorithm it names exists. Everything in that group is provisional in
+the last bit; only `pow` has been measured to differ, so only `pow` is held out,
+and the index says why. The rest keep their vectors and the exposure is written
+down where the next one goes when it is measured.
+
+
+**A figure in the specification was one machine's reading.** Section 20.7 said
+how many powers of ten a host's `pow` gets wrong and which one, and a test
+measured it again on every build, which is the rule this project has for a
+printed figure. Both numbers turned out to belong to the host rather than to the
+language: the same engine misses a single count on one runtime of its virtual
+machine and thirty six on another, and the two sets do not overlap. The claim
+that matters, that a floating point power is not the nearest binary64 and that
+the difference reaches `round`, is true on both and is what is now printed and
+measured. The witnesses the two rounding tests use are found on the host running
+them rather than written down, because a literal witness demonstrates the claim
+on the machine it was written on and nothing on the next one.
+
+
+**A chart can draw a strategy, not just a study.** `descriptorFor` takes
+`simulateOrders`, and with it a program that places orders runs in the chart
+tier against the venue a backtest uses: its plots draw, its legend row and its
+settings dialog follow, and its position is right because the venue's frames
+reach the engine between bars. Until now a host had two choices, refuse the
+strategy or hand it a destination that answered nothing, and the second draws a
+strategy that never learns it holds anything: every close closes nothing, every
+entry is allowed again on the next signal, and a stop and reverse script
+measured five buys and no sells while looking entirely normal.
+
+It is the backtest's own `Simulator` rather than a second one written for
+charts, so the marks a trader sees on the price and the trades in the report of
+the same script are one answer. A test holds the two together: the position the
+chart ends on and the open size the report states are compared directly.
+
+**Off unless asked for.** Without `simulateOrders` a strategy with nowhere to
+send an order is still refused at load with OS6006, which is what a host that
+meant to wire a destination and forgot needs to be told. Supplying `orders`
+still wins over it: somewhere real to send an order is a better destination than
+a simulated one. Nothing is placed anywhere by this.
+
+
+**The Python engine is on the index.** `pip install openscript` gets the engine
+that runs a compiled program, Apache-2.0, zero dependencies, Python 3.12 or
+newer. Until now the only way to have it was to clone this repository and point
+an environment variable at a directory, which meant a platform built from a
+container image could not run a strategy at all, and anyone attempting the
+second half of Phase 6 had nothing to install. `RELEASING.md` carries the
+release, beside the npm one, and the two versions ship together because
+`check-python.mjs` holds them equal.
+
+`engine/README.md` is the page the index shows: what the package is, that it
+holds no compiler and is handed a compiled program, that nothing in it builds
+code out of text, and how a host drives it bar by bar. It was written because
+the first build had no long description at all and the page would have been
+blank, which is permanent for a version once it is up.
+
+**The Python distribution shipped one package out of six.** `[tool.setuptools]
+packages` named `openscript` alone, so an install carried the machine and none
+of the halves it calls: `import openscript` worked and
+`from openscript.adapter.serving import Serving` did not. A host that followed
+`docs/integrating/the-python-engine.md` and installed the directory got an
+engine that could not run anything, and the failure appeared at their first
+import rather than anywhere in this build.
+
+It was found by doing it: installing the engine into a platform and watching the
+adapter go missing. Nothing here could have caught it, because every test in this
+repository runs the package from the tree where all six directories are present
+whether or not the distribution would have carried them.
+
+`scripts/check-python.mjs` now compares the package list against the packages
+that exist, in both directions: a directory holding an `__init__.py` that the
+list omits is refused, and a name in the list that is not a package in the tree
+is refused too. A new subpackage is shipped because it exists, not because
+somebody remembered a line.
+
+**The phase the language was designed for is now scoped.** A strategy trades one
+instrument today, chosen by the host before the run starts. The surface for more
+than one has been designed and marked planned since `stdlib.md` was written:
+`leg.fixed` and `leg.relative` declare what each leg trades, the `leg.*` rules
+manage one, and the `book.*` rules reason across all of them. None of it
+executes, and a script calling any of it is refused at the call with OS2020.
+`ROADMAP.md` now carries Phase 8, which says what building it involves, in the
+order it has to be built, and the four questions that have to be answered before
+any of it is written. It is placed after Phase 7 deliberately, and the reason is
+in the phase: every rule in it is behaviour a third engine has to reproduce
+exactly, so designing it before the format is fixed means discovering the
+disagreements one at a time in somebody else's engine.
+
+The risk rules that a combination of contracts needs are the point of it. A
+position made of two or more derivative contracts has a risk profile belonging to
+the combination and not to any leg, so a stop placed per leg both fires on moves
+the combination absorbed and misses the ones it did not. Two independent
+single-instrument strategies are not a substitute for one multi-leg strategy;
+they are two strategies running at the same time.
+
+**Six capabilities that were missing rather than planned now have rows.** The
+feature matrix said nothing at all about an account-level drawdown halt, a
+position size cap, a cap on orders per session, a halt after consecutive losing
+sessions, indexed access to past trades, or a script stating whether it is
+evaluated on every update or only on a closed bar. Every one of them is ordinary
+in the prior art this language is measured against, and a gap nothing records is
+a gap nobody plans. They are `planned` with no section, which is what that status
+is for.
+
+**The second engine's host surface is documented, and proved.** `engine/openscript/run.py`
+has held everything a live runner needs since the engine was written, and no
+document mentioned it once: a host reading `docs/integrating/the-python-engine.md`
+concluded that the only way to use this engine was to hand it a case directory,
+because the one entry point that page named was the conformance adapter. Phase 6
+of the roadmap is a server-side engine running the same compiled program, and the
+surface that makes it possible was invisible to the people it exists for.
+
+`docs/integrating/running-a-strategy.md` is the page a platform engineer reads
+instead. It states plainly that the engine is handed a compiled program and never
+a script, and what that means for a server that cannot run the compiler: the
+program is compiled where the compiler runs and stored as data. Then `load` and
+`load_text` and what a refusal carries, `execute_bar` argument by argument, what a
+`BarResult` holds, the rollback a still-moving bar rests on and the single
+condition it needs, the order boundary with `adapter/ordering.py` as the worked
+reference, a worked example that runs, and a list of what the surface does not
+give a host: no scheduling, no process isolation, no persistence, no data feed, no
+destination, no compiler and no chart.
+
+`engine/tests/test_host_surface.py` is the other half. It drives the engine the way
+a live host does, with no conformance adapter in the loop: a program loaded from
+canonical text, bars pushed one at a time, the order calls read back and placed on
+a ledger, a frame folded in at a bar boundary, and a moving bar executed three
+times that accumulates once. Every existing test drove this engine in batch, so
+nothing held the surface a live host actually uses.
+
+**And the record says what is true.** The registry page claimed there was no second
+engine and no case files; both have existed for some time, and it now says the one
+thing that is still true, which is that no engine anybody else wrote has run the
+suite. The trading-mode sense of "paper" is gone from the documentation, the
+specification and the error catalogue, and `docs/running/paper-and-live.md` is now
+`docs/running/sandbox-and-live.md`: this platform maintains sandbox mode and
+analyzer mode and now says so everywhere. The trading sense of "arm" is gone from the language itself, not
+only from the prose: `leg.trail`'s and `book.lockProfit`'s `arm` parameter is
+now `activateAt`, and the events `trailArmed` and `lockProfitArmed` are now
+`trailActivated` and `lockProfitActivated`, which is the word the event table
+already used in `trailToEntryActivated`. Both names are marked planned, so no
+script running today is affected. A `switch` arm and a ternary arm are language
+vocabulary and are untouched.
+
+**Three cases where the destination behaves badly.** Every one of the 204 frames
+the suite held was an order working and then filling whole: no partial fill, no
+refusal, no cancellation, no expiry, and no frame arriving later than the bar
+that placed its order. Two engines agreeing over that agreed about the half of a
+day that costs nobody anything. Three cases are harvested from the crossing
+example against a destination told to behave badly on a schedule stated before
+the run, and each one reaches a shape `stdlib.md` 17.7 and 17.8 provide for and
+no case carried.
+
+- `order/partial-fill`. The first entry is acknowledged with nothing filled,
+  reports 400 of its 1084 units two boundaries later and the rest five
+  boundaries after it was taken, and the close that ends the trade arrives in
+  two pieces as well. The first trade has two entries and two exits where every
+  other trade in the suite has one of each, its entry price is the average over
+  two pieces filled at two prices, and the run is charged for fourteen fills
+  where the same run against a destination that fills whole is charged for
+  twelve. An engine that reads a cumulative quantity as a delta folds 1484 units
+  onto a 1084 unit order.
+- `order/ended-unfilled`. The first three entries are refused carrying the
+  destination's own text, expire, and are cancelled, each after being
+  acknowledged and each with nothing filled. Because nothing fills, no position
+  opens on any of the three, the crossing back finds the strategy flat and sends
+  nothing, and the run reaches three trades where the plain run reaches six. It
+  is the only case in the suite carrying a `rejection`.
+- `order/fold-after-terminal`. The first entry is cancelled a boundary after it
+  is taken and reported filled whole the boundary after that. The row ends
+  `cancelled` carrying 1084 filled and an average price, which is what 17.8
+  describes and why: a cancellation can race a fill at any destination, and an
+  engine that refuses the late frame leaves the account holding a position the
+  strategy cannot see.
+
+The suite is eight cases now, 273 frames, 140 ledger rows and 66 trades. Across
+it a frame says `working` 137 times, `filled` 132, `cancelled` twice, `rejected`
+once and `expired` once, and a ledger row ends `filled` 131 times, `placed` five
+times, `cancelled` twice, `rejected` once and `expired` once. Two of those
+`working` frames carry part of an order rather than none of it, and five of the
+`placed` rows are the order each run was holding when its bars ran out.
+
+**A schedule that stops producing its status is refused rather than harvested.**
+An act names an order by its ordinal and the run decides how many orders there
+are, so a schedule can stop reaching its order without anything failing: the
+case is still harvested, still passes, and tests whatever the plain run tests.
+`scripts/lib/venue-schedule.mjs` holds each act to the frames the run recorded,
+by the facts the act itself fixes and by the row it reached, with the status
+vocabulary read out of `stdlib.md` 17.7 rather than copied into it. Twenty four
+wrong schedules and wrong pages were put to it and all twenty four were refused:
+every ordinal moved past the orders the run places, one act moved past the end
+of the run, the plain run asked about a schedule it never ran under, the acts
+written in reverse, a verb no word on the page is the stem of, a page with no
+status table, a rejection text no frame carries, and a piece of 401 where the
+run reported 400. The first version passed one of them, a fill of a whole order
+answered by whichever later order happened to fill, which is why an act is now
+held to the row its own order was answered about.
+
+**The second engine now carries a frame's instant, and the suite is eight of
+eight between the engines.** It did not when the three cases landed: three places
+built a frame and left the column off, so every frame carried the instant of the
+bar that placed the order and the three new cases failed on the second engine at
+`orders[].updatedAt` and at nothing else, with the partial quantities, the
+cumulative averages, the refusal text, the trades with two entries and two exits
+and the whole summary agreeing exactly. The three were
+`openscript/adapter/ordering.py`, where the driver builds the frame it delivers;
+`tests/recorded.py`, whose `DeliveredFrame` had no field for the column and read
+seven of the file's eight; and `tests/replaying.py`, where the replay that holds
+the ledger to a case builds its own. Each now sets it, and an absent column still
+leaves the ledger whatever instant the placement carried.
+
+And the language's own `cancel(...)` is still exercised by nothing, because no
+shipped example calls it: the cancellation in `order/fold-after-terminal` is the
+destination's own and not the strategy's.
+
+**A report says how far the run climbed, and which side made the money.** The
+summary answered twenty six figures and could not answer three questions a
+reader decides on. A run that made ten and gave back nine reports the same net
+profit as one that made one and kept it, and no figure separated them. A run
+whose long trades paid for its short ones reported a healthy net, because every
+figure in the summary is folded over both sides at once. And how many times in a
+row a strategy was wrong, which is the number that actually stops somebody, was
+not derivable from the win rate, the drawdown or the trade count.
+
+`maxRunUp`, `maxRunUpPercent` and `maxRunUpAt` join the summary, and `runUp` and
+`runUpPercent` join every point of the equity curve. Run-up is measured from a
+running trough anchored at the run's capital, which is the running peak's rule
+rather than its mirror image: a trough anchored at the first reported point
+would report the gain a run arrived with as having come from nowhere. The
+fraction is **zero wherever that trough is not above zero**, and that asymmetry
+with `maxDrawdownPercent` is deliberate. A peak only rises and stays above zero
+throughout any funded run; a trough only falls, and an open position can lose
+more than the account holds, so it reaches zero and passes it. Against a
+negative basis a positive climb divides to a negative fraction, which is the
+shape that once reported a profit factor of minus a half. `maxRunUp` itself is
+unaffected and is the figure to read on such a run. The height and the depth
+name different bars, and the earliest bar reaching either wins the tie.
+
+`analysisOf` and the report's new `analysis` are the trades taken apart: the
+closed trades split long against short with each side's own net and win rate,
+the largest win and the largest loss as nets after charges, and the longest run
+of wins and of losses. The sides partition the closed trades, so their counts
+sum to `tradeCount` and their nets to `netProfit`. A streak is counted **in the
+order the trades closed**, which differs from the order they opened whenever a
+trade is held across another one's whole life, which is every strategy that
+scales in; two trades closing on one bar are ordered by the order they opened,
+so the answer does not depend on the order the list arrived in. A trade whose
+net is exactly zero breaks a streak and extends neither half.
+
+**What is proved, and what is not.** Run-up is in the `performance` channel, so
+all five conformance cases compare it between the two engines exactly; that was
+checked by removing it from one engine and watching every case fail. The trade
+analysis is **not** in that channel, because the channel holds one flat object
+and the side split is nested, so it is proved by unit tests on each engine and
+by nothing that compares them. Whether it is flattened into `performance` or
+becomes a channel of its own is left open rather than answered in passing.
+
+**And the gap that was invisible is now closed.** Until this release the
+summary's figures had no formula stated in any specification document: the two
+engines agreed on them because one was translated from the other, not because a
+sentence said what they are, so a third engine had nothing to be written
+against. `conformance.md` section 4 now defines every field of the summary: the
+words the formulas are written in, which trades each figure is counted over, the
+equity basis the curve figures are folded from, which figures are absent rather
+than zero and why, and the tie rules. The equity curve, drawdown and win rate
+rows of `feature-matrix.md` section 30 move from `planned` to `specified` on the
+strength of it.
+
+The trade list does **not** move, and the section says why in its own text: how a
+run folds the `trades` channel out of its fills is still unspecified, so that
+channel is the boundary of what these formulas promise. An engine checking itself
+against a case is handed every value they need; an engine folding a report out of
+fills alone still has that earlier fold to agree on. `spec/decisions.md` 64 is the
+minute.
+
+**A case supplies the frames, and this engine folds them.** `conformance.md`
+section 3 has said since it was written that `frames.csv` supplies order frames
+the way `bars.csv` supplies bars, so that a case asserts the fold against input
+the engine did not choose. This engine's adapter did something else: it re-ran
+the case on its own simulated destination and held the frames that run answered
+to the case's file byte for byte, reporting the case `unsupported` when the two
+differed. So the suite could hold only cases whose frames this engine would have
+produced anyway, which is why all 204 frames in it are an order working and then
+filling whole, and why a partial fill, a rejection, a cancellation, an expiry
+and a fill after a terminal status were all shapes the page provides for and no
+case could carry. Two engines agreeing on that suite agreed about the half of a
+destination's day that costs nobody anything.
+
+`backtest` now has a second driver beside it, `backtestSupplied`, which delivers
+the rows a case supplies and answers none of its own: no fill priced off a bar,
+no order resting and no schedule read, so an order the frames say nothing about
+stays where its placement left it. A case with no `frames.csv` still runs
+against the simulated destination, because section 3 ends that such a case is
+handed no frames at all. The two are one function underneath, so the window, the
+refusals before the first bar, the boundary a frame is folded at and the record
+are the same for both. A row naming an order the run never placed is delivered
+and refused by the fold rather than dropped on the way in, which is what section
+3 hands an engine such a row for, and a row no boundary of the run delivers, one
+after the last bar or one naming no bar, makes the case `unsupported` naming the
+row rather than run with part of its own input passed over. `spec/decisions.md`
+63 is the minute, and section 3 now says where a frame naming no row is
+answered.
+
+The backtest module's door also exports `VenueAct`, `VenueDoes` and
+`VenuePolicy` beside `Simulator` and `SimulatorOptions`. A host writing a
+schedule for the simulated destination had to reach them structurally, through
+`SimulatorOptions['fill']`, and a module's index is its only door.
+
+**What this does not close.** The second engine reads a frame's instant out of
+the file and does not put it on the frame it hands its ledger, so a case whose
+destination answered later than the bar that placed the order is answered
+differently by the two engines, by `updatedAt` and by nothing else: every other
+field of the ledger, the trades and the whole performance summary agree exactly
+on a case harvested and measured here. That line belongs to the file that owns
+that delivery. `BacktestSettings` still states no schedule of its own, because
+the field needs a row in a projection this stage does not own, and
+`docs/integrating/running-the-suite.md` still describes the reading this change
+replaces. None of this is a change to what an engine computes for a case that
+supplies the frames its own destination would have answered: the five cases in
+the suite pass in both modes, exactly, as they did.
+
+**A frame carries the instant it arrived at.** `frames.csv` gains a `time`
+column: the destination's own instant for that frame, UTC milliseconds, absent
+as `none`, last in the row and optional in the way `orderRef` and `text` are.
+`host-interface.md` 7.2 gives a frame that instant and `stdlib.md` 17.7 folds a
+ledger row's `updatedAt` from it, so while no column carried one an engine
+driven from a case file had nothing to move that field to and left it at
+`placedAt`, while an engine answering its own frames carried the instant it
+spoke. The two readings differ by one field, on exactly the rows whose
+destination answered later than the bar that placed the order, and every frame
+in the suite today arrives at the boundary that placed its own order, which is
+why a suite made of them passed both. The column makes the instant input, like
+every other byte of a case.
+
+A record carries it too, because a projection can only write what the run kept:
+`RECORD_VERSION` is 4, a record written before it reads with no instant on any
+frame, and a later revision is still refused rather than read under this one's
+rules. Both readers read the column, this engine's and the second engine's, and
+`conformance.md` section 3 now says what a `time` means, that a case is not
+required to state one, and why. `spec/decisions.md` 62 is the minute.
+
+**What this does not close.** The five cases in the suite were harvested before
+the column existed and carry the seven columns of the day, so they are stale
+rather than wrong, and until they are harvested again `npm test` stops on them
+at `scripts/harvest-cases.mjs --check`, which projects each run again and finds
+eight columns where the file on disk has seven. `frames.csv` is the only file it
+names. Measured with the five harvested again and nothing else changed: 1843 of
+1843 unit tests, the harvest check passes, and the two engines agree on 5 of 5,
+exactly. The second engine reads the instant and does not yet carry it onto the
+frame it hands its ledger, which is one line in the file that owns that
+boundary. None of this is a change to what an engine computes: the ledgers, the
+trades and the money of every case are what they were.
+
+**The destination can be told to behave badly, on a schedule stated before the
+run.** `SimulatorOptions.fill` now carries one: a list of acts, each naming the
+nth order this destination took, how many boundaries after the one that took it
+the act falls, and what it does. Four verbs, and between them they reach every
+status of `stdlib.md` 17.7 a host may send. A fill carries a cumulative
+quantity, so one verb covers the acknowledgement before anything has traded, a
+fill of part of the order and a fill of the whole of it, and the other three are
+the three ways an order ends carrying less than it asked for: refused, cancelled
+and expired. An order the schedule names is answered by the schedule and by
+nothing else, and a run that states no schedule is answered exactly as before,
+which is what keeps every case already harvested the bytes it was harvested as.
+
+There is no random number in it and there will not be one. `stdlib.md` 8.2 keeps
+a script that answers differently on a second run out of a conformance suite,
+and a venue that rolled a die would make every case harvested from it
+unreproducible in the same breath. The venue works out the average over the
+cumulative quantity itself, because that is the figure `stdlib.md` 17.8 step 3
+says the row takes whole, and a destination reporting the last piece's price as
+an average hands the engine a number that is not one, which the engine may not
+correct because it is forbidden to average two averages of its own.
+
+**What the suite had never been handed, measured rather than guessed.** Across
+the five cases in this suite there are 204 frames: 102 that say `working` with
+nothing filled and 102 that say `filled` with the whole order, and nothing else.
+No frame reports part of an order, none arrives at a boundary later than the one
+that took the order, and the words a host may send for a refusal, a cancellation
+and an expiry appear no times at all. So the two engines are held to each other
+over a destination that behaves perfectly, which is not the half of a day that
+costs a trader money. The venue above is the half of the fix that could ship
+here; the cases it can now produce cannot be added to the suite yet, for two
+reasons that this release records rather than hides.
+
+The first is this engine's own adapter. `conformance.md` section 3 says
+`frames.csv` supplies frames the way `bars.csv` supplies bars, so a case can
+assert the fold against input the engine did not choose, and a backtest here
+answers its own frames from its own destination and can be handed none. The
+adapter says so honestly, comparing the frames its run answered with the file
+and reporting `unsupported` when they differ, so every case in the suite today
+is one whose frames this engine's destination would have produced anyway. A case
+about a destination that behaves badly is by definition not one of those.
+
+The second is in the file. A frame carries a `time` under `host-interface.md`
+7.2 and `stdlib.md` 17.7 folds `updatedAt` from it, and `frames.csv` has no
+column for one, so an engine folding a case's frames leaves that field at
+`placedAt` where an engine answering its own frames carries the instant it
+spoke. Every ledger row in the suite today has the two equal, because every
+frame in it arrives after the bar that placed its own order, so no case can tell
+the two readings apart. Section 3 now says this, and says what would close it.
+The two engines were driven over three harvested cases carrying a partial fill,
+an order filled over more than one bar, a refusal with the destination's own
+text, an expiry, a cancellation and a fill arriving after a terminal status, and
+they agreed on every figure of all three except that one field.
+
+**The second engine has a home, and the gate covers both engines.** `engine/`
+holds a Python distribution: the package `openscript`, importable as one name,
+its tests beside it, and the tools that run them. It requires an interpreter and
+nothing else, so a clone runs the tests as it stands, with no install and
+nothing fetched from an index. The entry point the suite's adapter starts is
+`python -m openscript`, which works from an installed distribution and from the
+directory unchanged. `__init__.py` is the door, and it says what is where: the
+machine, the two halves of the library, the orders, the money and the adapter,
+each of which is an entry of its own below.
+
+`npm test` now runs `scripts/check-python.mjs`, which finds an interpreter,
+refuses one older than the distribution requires, reads every import in the tree
+against the module names that interpreter says are its own, and then runs the
+engine's tests under it. A missing interpreter fails the gate rather than
+skipping half of it, because a suite that quietly checks one engine is how two
+engines drift apart. The empty dependency list is therefore a measured fact
+rather than a claim about a file, and inside the package the network, threads,
+randomness and the locale are refused as well, each with the sentence from the
+specification that refuses it.
+
+**The no-eval check reads Python.** A `.py` file used to land in the check's
+`unknown` pile and stop the build, deliberately, because code that nothing scans
+is the one thing that check will not allow. It now has an arm of its own: a
+masker that removes comments, marks string literals, reads a formatted string's
+substitutions as code and normalises every identifier the way an interpreter
+does, and rules that refuse the string evaluator, the statement executor, the
+compiler underneath them, the import machinery driven by hand, objects loaded
+out of bytes, function and code objects built at run time, the namespace of the
+built-in names, a namespace taken as a dictionary, a process, and the modules
+whose purpose is running text handed to them. `ast.literal_eval` is safe and is
+allowed, and the rules are written so that it and an ordinary pattern builder
+both pass untouched.
+
+The identifier normalisation is the one with no counterpart on the JavaScript
+side. An interpreter normalises a name before resolving it, so a call written in
+mathematical or fullwidth letters is the same call to it and invisible to any
+pattern written against plain letters. Three such spellings are in the attack
+corpus, each one run under an interpreter before it was written down, and every
+form in that corpus goes through the rules before the check opens a file.
+
+**A Python test run leaves nothing behind and refuses to prove nothing.**
+Bytecode caching is off before the first test module is imported, so no cache
+directory appears in the tree, and the test count is a result rather than a line
+of output: a discovery that found no tests, which the standard runner reports as
+a pass, fails instead.
+
+**A run record becomes a conformance case.** `caseFilesFrom(record, identity)`
+returns the files of one case, keyed by the names `conformance.md` section 2
+gives them: `case.json`, `script.os`, `bars.csv`, `expected.json` and
+`instrument.json`, with `frames.csv` and `settings.json` where the run had
+frames or inputs. It returns text and writes nothing, because core does no I/O,
+so the caller decides where a case lives and the same call works in a browser.
+
+This is what the suite the second engine will be measured against is built from.
+A case written by hand asserts what somebody believed a run does; a harvested one
+asserts what an engine actually produced, over bars that existed, under settings
+somebody chose.
+
+**Record version 2 carries the script's text**, in a new `sourceText` channel.
+A record identified its script by hash, and a hash settles whether two files are
+the same without yielding either of them, so a case could never be given the
+`script.os` it is required to hold. The text is checked against that hash when
+the record is written: text from a different revision than the one compiled is
+refused, rather than written into a case that could not reproduce its own
+expected output.
+
+The text is on the record and not on the compiled program. A program is
+executable data that no engine needs the source to run, and it is the versioned
+artefact other implementations depend on; putting the text there would send a
+script everywhere a program travels and widen the format every engine reads. The
+compiled format is unchanged.
+
+**Record version 3 carries the instrument record**, in a new `instrument`
+channel: the twelve facts of `host-interface.md` 4.1 as the engine read them at
+load. A record carried the money layer's contract, which holds six of them, and
+the interval, the timezone, the session and the volume flag were handed to the
+engine and written down nowhere, so `instrument.json`, which section 2 says is
+that record, was the contract instead: a shape with a rounding digit count no
+instrument record has and without the one fact that page requires of every
+host. `backtest` takes `instrument` in its options, the six facts beside the
+contract; the six the contract holds cannot be stated there, so the two cannot
+disagree. A run whose host states no `hasVolume` still runs and still records,
+and is refused a case rather than handed a value, because no derivation
+recovers that flag and a case stating it would give the engine under test a
+study the expected output did not come from.
+
+**A record written before this still reads**, with the channels it never
+carried absent: `sourceText` before version 2, `instrument` before version 3. An
+earlier revision only ever has fewer channels, and every one it carries means
+here what it meant when it was written. A later revision is still refused, which
+is the asymmetry that matters: a later one may mean something new by a field this
+version thinks it knows. Such a record replays and reruns as before; the one
+thing it cannot do is become a case.
+
+**A harvested case's `expected.json` is the shape section 4 fixes.**
+`performance` is a list of one flat object, the summary statistics. The equity
+curve, the monthly table and the trade markers are no longer written inside it:
+the first two are not conformance channels, and a marker belongs to the
+`markers` channel, which a case about money does not assert. A case now writes
+exactly the channels it declares in `case.json` and no others.
+
+**Specification decisions for the second engine.** Three, all in
+`conformance.md` and `stdlib.md`, and each one was a place two implementations
+could not have been written against the same page.
+
+*The adapter is invoked once per case*, and the runner assembles the result
+document. The page allowed both readings. Per-case is forced by the `error`
+outcome, which covers a crash, a hang and a timeout: none of the three can be
+reported by the program that suffered it, so only a caller holding a clock and a
+child process can turn them into an outcome.
+
+*An adapter also answers `--actual`*, writing what it computed with no
+comparison. Section 10 requires comparing two engines channel by channel, and a
+case result carries an outcome and a first difference rather than the values, so
+two adapters both reporting `pass` proved only that each matched an expected
+file, which is the thing that section says is not enough.
+
+*The equity curve is not a conformance channel.* It is one value per bar derived
+from fills and closes that the case already asserts, so it can only fail with the
+channels it comes from or alone, and alone means the engines disagree about
+arithmetic section 6 compares directly. It was also most of the bytes in a case.
+Trade markers move to the `markers` channel, which already existed, and
+`performance` is a list of one flat object.
+
+**The transcendental gap is scoped out of conformance rather than solved.**
+`exp`, `log`, `pow`, the trigonometric family and the three indicators built on
+them have no portable reference algorithm, and `compiled-program.md` 8.3 forbids
+answering them from the platform's maths library. No conformance case may assert
+a value reaching them until one is written. They still compute what they always
+did; what they do not carry is a cross-engine guarantee. The deciding fact was
+deployment rather than theory: the first host installs across two processor
+architectures and most common operating systems, so that one library is several
+in practice, and the disagreement is two traders reading two numbers.
+
+**A harvested case carries the frames the run was handed.** Without them the
+case was unpassable on every engine, including the one that wrote it:
+`conformance.md` section 3 ends "a case with no `frames.csv` is handed no frames
+at all", and what `expected.json` asserts through its orders channel is what came
+of those frames. An engine handed none folds nothing, disagrees with every row,
+and takes the blame for a hole in the case. A frame names its intent by ordinal
+rather than by an engine's own id, because a case cannot know the id another
+engine minted.
+
+`caseFilesFrom` and its types are exported from the package root, so an install
+can reach the one function that turns a run into a case. `DriveOptions` and
+`InstrumentFacts` are exported beside them, so a host can name what `backtest`
+takes.
+
+`backtest` takes `sourceText` and `instrument` in its options. A caller that
+has only a compiled program leaves the first out, one that states nothing about
+the instrument beside the contract leaves the second out, and either loses
+nothing but the ability to harvest.
+
+**The first conformance cases are in the tree, harvested rather than written.**
+`scripts/harvest-cases.mjs` runs the shipped strategy examples over the Phase 5
+gate's fixture, the placeholder contract and four hundred formula bars, under
+the instrument facts `conformance.md` section 3 assumes of a case that states
+none, read from that page, and writes each run into `cases/<id>/` through
+`caseFilesFrom`, with a `notes.md` saying why the case exists and what it
+defends against. The first two: `order/buy`, from the crossing strategy, and
+`order/sell`, from the opening range strategy. The rows of
+`feature-matrix.md` that name them are the first marked `implemented`, and the
+gate's contract and bars now live in one module the reproducibility check and
+the harvest share, so what the gate reproduces is what the suite holds.
+
+**The harvest is a check as well as a writer.** Run with `--check`, which
+`npm test` does, it writes nothing and fails the build when a case on disk is
+not what this engine produces, byte for byte; when a case it wrote names a row
+that does not say `implemented`; when an `implemented` row names a case
+directory that is not there; or when a case directory exists that no row names.
+Every script is harvested twice and the two compared before anything is
+written. A script that reaches a gap of `stdlib.md` section 20.11 is refused by
+name with the call that reached it, by the gate's own reading of that table,
+which now lives in one module the gate's test and the harvest share; and a
+strategy this driver cannot run is named and counted rather than passed over.
+The short premium example reads a second instrument, which a backtest over one
+series of bars cannot supply, so nobody has chosen a case identity for it, and
+that is what the report names it for.
+
+**The feature matrix is checked against the tests and the pages it cites.**
+`scripts/check-matrix.mjs` enforces the preamble of `spec/feature-matrix.md`,
+which described a checker nobody had written, and `npm test` runs it. Every
+feature row has five cells and a status the page lists; every citation resolves
+to a Markdown document under `spec/` and, where it carries a locator, to a
+heading matching the shape the preamble gives; every test identifier is well
+formed under a listed area and no two rows share one; an `implemented` row
+names a test that exists, a `unit:` identifier written by a file under `tests/`
+or a case directory holding its `case.json`; and a case directory no row names
+fails the build. Existence is what it proves, and the unit runner and the suite
+prove passing. A `specified` or `planned` row naming a case that is not written
+is not a failure, which is the direction the preamble's paragraph on
+`conformance.md` settles: such rows reserve an identifier, and they are counted
+and printed rather than failed. The status words, the column names, the heading
+shapes and the areas are read out of the page rather than retyped, every rule
+is attacked with a row it must refuse and one it must accept over a fabricated
+document and tree before a row is read, and a run that reads no row refuses.
+It prints the row count, the count per status and the implemented ratio, which
+is the number the page says nobody types. The preamble now names the checker,
+says `none` is written in backticks, says what makes a unit test or a case
+exist, and no longer says every row is unimplemented.
+
+**This engine has a conformance adapter, and the suite has a runner.**
+`scripts/adapter.mjs` is the program `conformance.md` section 9 says an
+implementation ships, answering the three invocations that page gives:
+`--describe` for the engine's identity, a case directory for one case result,
+and `--actual` for what the engine computed with no comparison made. It loads
+the built package by its door and nothing behind it, reads a case directory by
+the file names section 2's table gives and refuses a file the table does not
+name, compiles `script.os`, runs it over `bars.csv` under `instrument.json` and
+`settings.json`, and answers the channels the case asserts in the encoding
+section 4 gives them. The channels are read out of the same projection the
+harvest writes a case with, so what this engine can be held to is stated once.
+
+`scripts/run-suite.mjs` walks `cases/`, invokes an adapter once per case in a
+child process with a timeout, turns a crash, a hang, a timeout or an answer
+that is not one JSON object into the `error` outcome with the reason in the
+row, and writes the result document of section 9. Both modes of section 10 are
+there: against the expected files, and `--against` a second adapter, where each
+is asked for `--actual` and the runner compares the two channel by channel with
+tolerance zero, whatever the case declares. A case outside the claimed profile
+is skipped and never counted as a pass; any failing, erroring or unsupported
+case exits non-zero. Every harvested case passes on this adapter, alone and
+against itself. `docs/integrating/running-the-suite.md` is the page.
+
+**The comparison of section 6 is written once**, in `scripts/lib/compare.mjs`,
+and the adapter and the runner both call it: absence first and never inside a
+tolerance, a non-finite value as its own `nonFinite` outcome, signed zero
+normalised, equality over the binary64 bits rather than a decimal rendering,
+exact by default, and the `max` form of the two bounds with the bound that was
+broken named. A declared tolerance is refused, not clamped, past the cap the
+page prints or without a reason. Every step has a test written against the
+implementation that would get it wrong, and each was run against that mutant.
+
+**What the adapter says it does not reach**, reported on the case rather than
+passed over. This engine's backtest answers its own frames from a simulated
+destination and takes none from a file, so the frames it answered are held to
+the case's `frames.csv` byte for byte and a case whose frames the destination
+did not answer is `unsupported`; every harvested case runs. A per-bar or chart
+channel, a warning case, `ticks.csv` and a secondary series are `unsupported`
+by name. A per-column tolerance is not read, because section 6 fixes no shape
+for one. Two facts the page owed a place when the adapter was written: the
+money rounding digit count, which `backtest.json` below now carries and which
+the adapter still takes from the fixture every harvested case ran under until
+it reads that file, and a currency for section 3's default instrument, without
+which the money layer refuses a strategy case that states no `instrument.json`.
+The suite revision has no fixed place either, and the document carries the
+package version until it does.
+
+**A case carries what its report was folded under.** `backtest.json` is a new
+file of a strategy case, `conformance.md` sections 2 and 3: the money rounding
+digit count, the charge schedule the host supplied or `null` for the
+declaration's own, and the report window with `null` for an unstated bound. A
+run under a supplied schedule or a narrowed window harvested to a case that said
+nothing about either, so a second engine ran under other values and took the
+blame, and no case file carried the digit count at all. The count is not in
+`instrument.json` because `host-interface.md` 4.1 has no such fact, and the
+three are not in `settings.json` because that file is the script's inputs keyed
+by name. Every field of `BacktestSettings` now has a place in a case,
+`caseFilesFrom` carries the table saying which, and a record whose settings hold
+a field the table does not know is refused by name rather than written into a
+case that ran under something it does not state. The two cases in the tree at
+the time were re-harvested and gain the file; nothing else in them changed. Decision 61 has
+the reasoning.
+
+**A record past the tolerance cap makes no case.** Section 6 caps a declared
+tolerance at `rel = 1e-9` and `abs = 1e-12`, and the runner refused a case past
+it while nothing refused a record past it, so a harvest could write a directory
+every runner errors on. `caseFilesFrom` now refuses such a record with OS6021,
+the code the run refuses a setting with, and writes no file. The cap's two
+figures are read out of the page by a test and held to the constants in core,
+which cannot read the page itself. `CaseRefusal` gains `code`: the catalogue
+code a refusal is filed under, or `null` for a refusal about what the record
+holds, which no catalogue entry is about. `reason` is unchanged.
+
+**How a number becomes text is one written rule, and one function.**
+`language.md` 5.5 states it completely: the shortest round trip digits, written
+positionally from ten to the minus seventh exclusive up to ten to the twenty
+first exclusive and with an exponent outside that range, spelled `1e21` and
+`1.5e-7` with never a plus, `0` for both zeros, and no spelling for a value that
+is not finite. `canonicalNumber` from the emit module is the writer every number
+goes through: `text(x)`, `text(x, decimals)`, the canonical encoding, and a
+harvested case's csv files. `spec/vectors/number-text.json` carries fifty one
+boundary cases as binary64 bit patterns, decimals and text, so an engine in
+another language can hold its own writer to the rule without parsing this
+repository's source. A new check, `scripts/check-number-writer.mjs`, asks the
+type checker for the type of every operand under `src` and refuses a number
+turned into text by the host anywhere else; the files that still format a
+number for a human are recorded in `spec/number-text-exceptions.json` with an
+exact count each.
+
+**`text(x, decimals)` writes the shortest digits at every magnitude.** It used
+to write the exact binary expansion of the rounded whole number inside the
+scaling range and the shortest form past it, so `text(1152921504606846976, 0)`
+gave `1152921504606846976` and now gives `1152921504606847000`, the same digits
+`text(x)` gives the value. Only a scaled whole at or above 2 ** 53 is affected;
+no price shaped value moves by a digit. The scale it multiplies by is now the
+binary64 nearest to the power of ten rather than the host's `pow`, which on this
+host is one ulp off at 23 decimals, so `text(3.0627e-8, 23)` no longer ends in a
+stray 1, and 20.7 prints the measured figures beside the claim.
+
+**`str.trim` and `toNumber` use a written whitespace set.** `stdlib.md` section
+10 now lists the twenty five code points with the Unicode White_Space property,
+and both calls are implemented from the list rather than from the host's trim.
+The one visible change: the byte order mark U+FEFF is no longer removed, and the
+next line character U+0085 now is. A test walks every code point of the basic
+plane against the table read out of the page.
+
+**Strings sort by code point, as the specification always said.** `sort` on an
+array of strings orders a symbol outside the basic plane after every code point
+of the plane, where the host's own order put it before U+E000 to U+FFFF.
+
+**Two corrections a script can observe, for anybody deciding whether to
+upgrade.** The `<` family of operators on two strings orders by code point, as
+`sort` does and `language.md` 9.3 always said, where it used the host's sixteen
+bit units: a comparison between a symbol outside the basic plane and a code
+point from U+E000 upward changes its answer, and no other pair of strings does.
+`round(x, decimals)` scales by the binary64 nearest to the power of ten, the
+scale `text(x, decimals)` uses, rather than the host's `pow`, so a value rounded
+at 23 decimals can move by one unit in the last place and a value rounded at any
+other count cannot. A stored run that did either reproduces to a different
+number after the upgrade; nothing else changes. Decision 60 has the reasoning
+for both.
+
+**A program at a lower minor of the same format major loads.** The engine
+required every table of its own minor, so a program compiled at format 1.0 was
+refused by the 1.1 engine at load, at `requests`, with a message about a
+malformed program. `compiled-program.md` 9.4 step 3 now says what 9.5 always
+promised: a table a later minor added and an earlier program lacks reads as
+empty, never as a refusal. A program at the engine's own minor or a later one
+that omits a table is still refused, because section 2 says an empty table is
+written and never omitted, and the version is what tells an older program from
+a malformed one. Decision 56 has the reasoning.
+
+**`loadText(text, options)` is the engine's text boundary.** A program that
+arrives from outside the process as text is parsed, written out again through
+the one canonical writer, and refused with OS6018 naming the character where
+the two part if the text is not the canonical encoding of 2.14; the object then
+goes through `load` so every later refusal applies in the same order.
+`load(object)` is unchanged and is not held to canonicity, because an object
+built beside the engine was never text. Section 13's first checklist line and
+9.4 step 1 now say the same thing (decision 57). The function lives in
+`src/core/engine/load.ts` and is exported through both doors, the engine's and
+the package's.
+
+**The compiled format is held to its page by four checks.**
+`check-format-tables.mjs` reads the instruction table of 4.13 and the tag table
+of 2.2 out of the page and compares them with the compiler's opcode table and
+tag list, probing a formula depth with several counts rather than reading it as
+arithmetic. `spec/format-history.json` records, per released format version,
+the field paths, opcodes and capability tags it defined and the sentence of
+section 9 that justified the bump, and `check-format-additive.mjs` fails on a
+field, opcode or tag the compiler gained that no version records and on one a
+version records that the compiler lost, naming the path. `spec/corpus/` holds
+the canonical encoding and `programHash` of every shipped example, and
+`check-format-corpus.mjs` recompiles each one and compares the bytes, reporting
+the first differing byte offset and the field path at it; the recompiled
+program is given the corpus's own `compiler` stamp first, so a package bump
+alone never fails it. A format change is now a deliberate act: record it in the
+history, rewrite the corpus with `--write`, and review the diff.
+
+**The named colours' channel values are published.** `stdlib.md` 11.1 said they
+are fixed in the library manifest and are part of the conformance suite, and
+they lived only in two source files. `spec/colours.json` now holds them, 11.1
+names that file as the authority, and `check-colour-channels.mjs` holds the
+compiler's table and the engine's table to it while stating no value of its
+own. No value changed; what changed is that a second engine can now read them
+from the specification.
+
+**The library's arithmetic ships as vectors a second engine can load.**
+`spec/vectors/library/` holds one JSON file per arithmetic function of the
+manifest, keyed by name and argument count, with inputs and results as binary64
+bit patterns (sixteen hex digits, sign bit first) rather than decimals, so
+nothing about this repository's number formatting sits between another
+implementation's arithmetic and this one's. Each function gets several cases:
+the full 80-bar fixture the gate tests already use, the same with holes in every
+series, a history shorter than any length, every constant argument absent, an
+edge table for the stateless calls, and a bar with no volume, no session or no
+tick where the function reads one; every case records the bar facts the
+function read and the warmup index of every output. `index.json` names every
+file and the 135 manifest entries in six groups that hold no arithmetic, each
+with the reason. `docs/integrating/library-vectors.md` says how to decode, drive
+and compare a file from another language, in under a page.
+
+**A case that reaches a gap of `stdlib.md` 20.11 is written and marked, not
+left out.** Twenty functions have such a case (the transcendental calls and what
+is built on them, `hma`, `eom`, and the `ma` and `keltner` cases that select
+`hma` by name), and each case carries the gaps its call reaches, read by the
+gate's own reading of the table, so an implementer knows which numbers they are
+not held to. `spec/decisions.md` 59 records why a vector is written where a
+conformance case would be refused. `npm test` regenerates the directory and
+fails on a byte that differs (`scripts/check-library-vectors.mjs`), so a vector
+is never older than the engine, and a regeneration is a deliberate act committed
+with the change that caused it.
+
+**The second engine runs a strategy, and the build fails when the two engines
+disagree.** `engine/` now holds an engine rather than a home for one: the
+machine of `compiled-program.md` section 5, both halves of the library in the
+accumulation order `stdlib.md` section 20 fixes, the order ledger and the fold
+of section 17, and the money that turns fills into trades and a summary. The
+conformance adapter joins them over a case directory: it reads `frames.csv` and
+`backtest.json`, delivers each frame after the bar it names and folds it before
+the next execution, applies the order calls a decided bar left behind, and
+answers the `orders`, `trades` and `performance` channels beside `diagnostics`
+and `values`.
+
+Every harvested case passes on it, against the expected files and against the
+first engine. That is four hundred bars a case, 104 ledger rows and 51 trades
+folded into five summaries, reproduced to the last bit, with every figure here
+read out of `cases/*/expected.json` rather than remembered.
+
+**What was read from the pages, and what was not.** The behaviour is the
+pages': the machine of `compiled-program.md` section 5, the fold and the ledger
+of `stdlib.md` section 17, and the accumulation order section 20 fixes for every
+library function, with the arithmetic held to `spec/vectors/library/` bit for
+bit. The decomposition is not: the modules of `strategy/` and `accounting/`
+fall one to one against the first engine's order ledger and money layer, name
+for name, and much of the prose explaining them is that engine's prose. A reader
+deciding what the gate is worth should have both halves of that. Two engines
+agreeing to the last bit says this one computes what the other computes, which
+is what a host needs and what the release is gated on. It does not say the pages
+alone were enough to build an engine from: a page with a hole in it can be read
+the same wrong way twice by somebody with the other engine open beside them, and
+no suite can tell that apart from two readings that agree because the page is
+complete. Only an implementation from the pages with nothing else to hand can,
+and there has not been one. `docs/integrating/the-python-engine.md` says the
+same on the page somebody reading the engine reaches.
+
+**`npm test` runs the two engines against each other.** `npm run suite:agree`
+hands every case to both adapters with `--actual` and compares what each
+computed, channel by channel, at tolerance zero whatever the case declares. A
+difference of one bit fails the build naming the case, the channel, the column
+and both values. `conformance.md` section 10 calls a disagreement between two
+engines a release blocker; this is the sentence made mechanical, and it is the
+gate the phase is measured by. `npm run suite` and `npm run suite:engine` run
+each engine against the expected files on its own.
+
+One rule belongs to that comparison alone: a run where every case was skipped
+now exits non-zero saying it compared nothing. A skipped case is one engine
+honestly reporting the profile it claims, which is what the first mode is for,
+but in the second mode it means neither engine was asked about a single case,
+and a green line there is the evidence a suite with no cases in it would
+produce.
+
+**The second engine claims the `strategy` profile**, so a strategy case is run
+rather than skipped, and every shortfall is named on the case with the
+`unsupported` outcome: a chart channel it does not draw, a capability it does not
+serve, a library function its manifest does not hold, a `ticks.csv`, a secondary
+series, a calendar in a timezone it cannot read, or a frame delivered after the
+last bar, which no fold boundary reaches. `docs/integrating/running-the-suite.md`
+holds the whole list and says why a cumulative profile table has no word for an
+engine that runs the money and draws nothing.
+
+**Three more cases, and a straight answer about how much the two engines
+agreeing proves.** The suite held two cases, and the script was the only thing
+that differed between them: no charge schedule, two rounding digits, the whole
+of the bars reported, no value stored for an input, one instrument and one entry
+at a time, in both. Between them, 47 ledger rows and 23 trades, and every frame
+in both was an order working and then filling whole. Three cases join them,
+harvested the same way from the same shipped strategies:
+
+- `perf/report-window` reports 151 of the 400 bars, with a position open at each
+  end of the window. The ledger, the trades and the realised profit are
+  `order/buy`'s to the bit and the summary is not: the bars reported, the bars
+  spent holding a position and the deepest drawdown all change, because every
+  bar still executes and only the ones inside the window are reported.
+- `perf/money-digits` folds the opening range run under a rounding count of zero
+  instead of two. Every figure is `order/sell`'s, which is the assertion: the
+  count reaches the total of one fill's charges, half to even, and no other
+  figure of the report. An engine reading `conformance.md` section 3 as every
+  money figure being rounded to that count writes a net profit of -654 where
+  this case says -653.55.
+- `input/host-values` runs the crossing strategy under three values a host
+  stored for its inputs, and is the only case that carries a `settings.json`.
+  Ten ledger rows and five trades, where the declared defaults give thirteen and
+  six.
+
+That harvest made the suite five cases, 104 ledger rows and 51 trades, each passing against
+the expected files on both engines and against the other engine exactly. Each
+one was mutation tested before it was committed: an engine that reports every
+bar supplied fails the window case at the bar count, one that never opens
+`settings.json` fails the input case on the length of the ledger, four rows
+where the case says ten, and one that rounds every money figure fails the digits
+case at the first trade. The one
+mutant that survives is an engine that ignores the digit count and rounds at
+two, and the case says so in its own notes rather than leaving it to be found.
+
+**A case is a run, so one example can be more than one case.**
+`scripts/harvest-cases.mjs` now harvests every identity that names an example
+rather than the first one, and an identity carries what the host chose for its
+run: a money rounding digit count, a report window as two bar indices, or values
+for the script's inputs. An identity that chooses none is the run the gate
+drives everywhere else, which is why the two cases already in the tree are byte
+for byte what they were. The harvest's report no longer files a strategy nobody
+has chosen a case identity for under the sentence about gaps, which is what it
+was doing to the short premium example on every run.
+
+**What the suite does not reach, written down rather than left to be
+discovered.** No case supplies a charge schedule: a supplied schedule beside a
+declared commission is refused before the first bar (OS6023) and every shipped
+strategy declares one, so a case for it needs a strategy example that declares
+none. No case hands an engine a partial fill, a repeated frame, two frames in
+the wrong order, a fill reported after the order had gone terminal, a rejection,
+a cancellation, or a frame naming no row of the ledger. The frames in a
+harvested case are the ones its own run was answered, the destination a backtest
+runs against fills an order once and in full, and no shipped strategy cancels an
+order or leaves one resting, so none of those shapes can be harvested from what
+is in the tree today. `docs/integrating/running-the-suite.md` carries the list
+beside the commands, because that is where somebody reading a green run is
+standing.
+
+---
+
 ## 0.4.0
 
 **A backtest is driven, and what it produces is a document rather than a