openalgo-script 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,1204 @@ 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
+number.** `backtest(program, bars, settings)` walks a compiled program over a
+range of bars against a destination that prices fills, and hands back a
+`RunRecord`: the compiled program and the hash of the source it came from, the
+bars or a hash naming them, the settings the host chose, every frame the
+destination answered in delivery order, every fill the engine folded in fold
+order, the ledger the run ended with, the diagnostics and the report. Nothing in
+it is an object reference, a function or a shape only this engine can read,
+because the same document is what a second engine will be handed as a
+conformance case.
+
+**A stored run can be reported again and run again, and both are checked rather
+than asserted.** `replay(record)` folds the money again from the record's own
+fills with no bar executed, and has to produce the report the record carries:
+that is what says the report is a function of the fills and not of anything the
+engine happened to be holding. `rerun(record)` executes the record again and the
+two runs are compared as bytes. Bars are revised, so a replay over bars that do
+not hash to the record's is refused, OS6022, rather than reporting the original
+figures over different data.
+
+**The comparison that tells an improvement from noise.** `compareRuns` puts two
+records beside each other. Two runs over different bars or different contracts
+are two studies, so the pair is reported incomparable and given no separation at
+all; a different program over the same bars is exactly what is comparable, and
+every other difference is named, because the reason a run improved is as often a
+setting somebody forgot they changed as it is the change they meant to test.
+Separation is the gap between the two expectancies over the combined standard
+error, analytic and with no resampling, so the same pair gives the same figure
+for ever. It is null rather than infinite where neither run has the two closed
+trades a spread needs.
+
+**The phase's gate is executed rather than promised.**
+`scripts/check-reproducible.mjs` runs on every `npm test`, over the shipped
+strategy examples rather than over a probe written the same afternoon. Each run
+is written to JSON, every other reference to it is dropped, and the record is
+parsed back from that text alone; then it is reported again from its own fills to
+the same report, executed again to the same bytes, refused a replay over revised
+bars, compared with itself to no movement, and refused a separation against a run
+over other bars. A strategy needing a capability the driver cannot supply is
+named and counted, never skipped.
+
+**The report: a trade list, an equity curve, a drawdown and a month by month
+table.** A trade is one position reference from the fill that takes it off zero
+to the fill that returns it, so a pyramided entry is more entry fills on one
+trade, a partial close is an exit fill that does not close it, and a reversal is
+two trades. Win rate is over closed trades on the net after charges, with an
+exactly zero net counted as a scratch in neither half; expectancy carries its own
+standard error. None of it is readable by a script: the money entries of the
+`pos` namespace stay planned and go on refusing at the call, because the moment a
+script can branch on its own equity every formula joins the conformance surface.
+
+**Every bar supplied executes and only the ones inside the window are reported.**
+A bar before the window is warmup: it runs, its orders are real, and a position
+opened on one is carried in with its charges paid. A window holding none of the
+bars supplied is refused, OS6020, rather than reported as a flat curve, which is
+what a strategy that did nothing also produces.
+
+**The costs are the destination's, where the specification puts them.** Slippage
+is measured in ticks and is adverse always, worse on a buy and worse on a sell,
+and it applies to a market fill and to a stop and never to a limit. A platform
+that has its own rates supplies a charge schedule; a script that states a
+commission gets a schedule of one line derived from it; both at once is refused,
+OS6023, because two cost models charge the same money twice or charge whichever
+an engine preferred.
+
+**A quantity is converted into units by the destination, or the run is refused.**
+A quantity travels in the declaration's own unit and the destination is the party
+that converts it. Lots are converted through the instrument's lot size, and a lot
+on an instrument stating none is refused. Cash and a percentage of equity are
+refused by name: a backtest fills in units and works out no running equity to
+size against, so it can convert neither, and filling the number as written is
+what it used to do.
+
+**What it does not model, said here rather than left to be discovered.** A
+bracket reaches the destination as a protective instruction attached to a tag and
+the engine appends no order row for one, so a stop cannot fill in a backtest yet
+and a page that says otherwise is ahead of the engine. A limit fills only where
+the bar traded through it and a stop that gapped fills at the open, both of which
+a host can change in the fill policy; a bar is four prices and no path, and
+nothing here pretends to know which extreme came first.
+
+The equity curve marks a trade at the size it ended up entering from the bar it
+first opened, so a scale-in is marked, before its second entry, on units it did
+not hold at an average it had not reached: the curve reports a drawdown the
+account never had, and the maximum drawdown figures are folded from it, so a
+pyramiding strategy is reported as having risked more than it did. The realised
+total is unaffected. Folding the curve from the fills rather than from the trades
+is what fixes it, and that is a different fold rather than a correction to this
+one.
+
+The conformance case files a second engine would be handed are not written, and
+cannot be from a record alone: a case has to carry the source text and a record
+carries the source hash, its line count and its file name. Nothing can recompile
+a stored revision for the same reason. Both belong to the next phase, and both
+are now written down instead of implied.
+
+**Four defects found by review before any of this shipped**, each a wrong number
+rather than a crash:
+
+- A quantity stated in lots, cash or a percentage of equity was filled at the
+  number the script wrote, so a strategy sizing in lots of sixty five traded one
+  sixty fifth of what it asked for and every money figure went with it.
+- `checkSettings` asked about the cost model only when the host supplied one, so
+  on the path almost every run takes it asked nothing: a declared commission of
+  minus five was charged as a credit and turned a loss into a gain. A declared
+  slippage below zero improved both sides of every fill through the same hole.
+- A month's return was divided by the equity it had already earned, so a month
+  that doubled an account reported fifty percent, with the money column beside it
+  right.
+- A gross loss driven under zero by charges gave a negative profit factor, which
+  is a ratio nobody can act on. It is null there now, and the field says it can
+  go under zero instead of calling itself a positive magnitude.
+
+A bar time outside the range a calendar can hold, which is what nanoseconds
+instead of milliseconds produce, made the monthly table NaN and then threw a bare
+error with no catalogue code out of core. Such a time names no month.
+
+**`load` hands back the inputs it resolved**, beside the engine, so that a caller
+outside the engine can read the declaration's capital, commission and fill rule
+without resolving an input a second time under its own rules.
+
+**`settingsFor`'s second argument no longer names a contract it ignored.** It
+took a partial settings object whose contract field it discarded in favour of the
+positional one, so a caller passing a contract there silently got the other. It
+is now a compiler error at the call.
+
+## 0.3.0
+
+**The editor half is here: six functions, text in and data out, and a drop-in
+adapter for a text component.** `src/editor` is a new tier whose index is its
+only door. It imports the compiler and nothing else: no package, no browser
+global, no DOM type, which the layering check has enforced for it since before
+the directory existed. Nothing in it is on screen, and nothing in it is hand
+written: a hand written highlighter, completion list or tooltip drifts from the
+language and nobody notices for a release.
+
+**Two new entry points resolve: `openalgo-script/editor` and
+`openalgo-script/adapters/codemirror`.** They are declared now that the tier they
+name exists, because an entry point that resolves to half a tier fails at your
+run time rather than honestly at install. A fifteenth check,
+`scripts/check-entry-points.mjs`, builds a temporary install holding exactly what
+the `files` list ships, with no package of any kind beside it, and imports every
+door the export map declares. That is also what says both adapters' peer
+dependencies are optional in fact: neither could have loaded if it imported one.
+
+**`highlight(source)` gives every piece of a file, in order, covering every
+character exactly once.** The kind of each piece comes from the language's own
+tables, so a word added to the reserved list, a mark added to an operator table
+and a function added to the standard library manifest are each painted the day
+they are added. The covering property is the one a host cannot do without: a
+highlighter that drops one character leaves everything after it on that line
+drawn one column to the left, and that arrives as a bug report about the caret.
+`highlightLines(source)` is the same pieces per line, which is where a host
+otherwise makes the off-by-one itself.
+
+Comments come out of `highlight` and are recovered in one place rather than by
+each host. The lexer emits none, because the parser has no use for one; the two
+ways a consumer ends up doing it, reading the gaps between token spans and
+scanning the text for `//`, are folklore and a second lexer respectively, and the
+second is wrong inside a string literal.
+
+**`diagnose(source)` is the whole front end**, lexer through emitter, and returns
+the compiler's own diagnostics with the message and the fix the error catalogue
+gives them. Not a subset: there are codes the emitter raises and nothing before
+it does, so an editor that stopped after the checker would show a clean file and
+then have the apply refused. A source that does not parse answers usefully rather
+than throwing, which is the state a file being typed into is in most of the time.
+
+**What that costs is now a number rather than an impression.** Two measurements
+join the benchmark suite, `diagnose-heavy` and `diagnose-typing`, the second on a
+file with a call bracket left open half way down it, which is what a file looks
+like the moment somebody types one. A third of a millisecond and about a
+millisecond, against budgets of 1.5 and 4. That is the answer to whether an
+editor needs a compiler of its own: at this price it does not, and the number to
+beat is in the table rather than in somebody's judgement.
+
+**`format(source)` lays a file out in the canonical layout, now stated in
+`language.md` 3.13**, and formatting never changes what a script means. That is
+proved twice rather than asserted: every example and every gate script in the
+repository, a hundred and nineteen of them today, is laid out again, both texts are
+compiled, and the compiled programs are compared field for field; and every call
+lexes its own output and compares it with the tokens that went in, so a rule that
+is wrong returns your source untouched rather than a changed program. A source
+that does not parse comes back byte for byte, because a character the lexer
+refused produces no token and a reprint from the tokens would delete it.
+
+The three questions a reprinter usually guesses at are put to the parser instead:
+which `-` is a sign, which bracket groups an expression rather than opening an
+argument list, and which `:` belongs to a ternary rather than to a type. All
+three are in the tree already, and the guess is where every formatter that has
+turned `a - -b` into something else began.
+
+**`complete(source, offset)` offers what may be written there**: the library's
+names, the names the file has declared and still has in scope, the named
+arguments of the call being written, and the members of a namespace after a dot.
+The names are the standard library manifest, the same index the checker resolves
+against and the same one the example check reads its globals from, so a function
+added to the library is offered the day it is added. A name is offered from the
+end of the statement that declares it and inside the block that declared it,
+which are the compiler's own two rules rather than a second reading of them.
+
+A call the library names and has not implemented is offered, sorted after
+everything a script may write today, and carries the error catalogue's own OS2020
+sentence with its name filled in. Leaving those out would send a writer to the
+documentation to find out why a name is missing; offering them unmarked walks
+them into a script that will not compile.
+
+**`hover(source, offset)` says what the word under the pointer is**, and the
+sentence it shows is the cell `spec/stdlib.md` prints for that call. It is read
+out of the specification at build time by a new generator rather than retyped
+into the source, so a description improved in the specification is improved in
+the tooltip, and a test fails if the manifest and the specification ever describe
+different sets of names. A name the file declared carries the type the checker
+worked out and the span it was declared at; a named colour carries its channels.
+
+Three things a hover wants and has no machine readable source for are stated
+rather than invented: a reserved word has no per-word explanation anywhere, a
+name with several signatures is described by the first row the specification
+states for it, and a parameter has no description of its own. Those, and what the
+adapter narrows, are recorded in `spec/editor-narrowings.json`.
+
+**`signature(source, offset)` gives the call being written, which parameter the
+cursor is in, and each parameter's name, type, default and whether it is
+required.** The default is the one the compiler applies, which is the trap in
+this function: most defaults live in the library manifest, and the eight
+declaration calls keep theirs in the emitter, so a tooltip reading the manifest
+alone shows nothing beside `width?` while every plot is drawn 1.5 wide. Both are
+read through one answer that `scripts/check-defaults.mjs` holds to the
+specification, so a number in a tooltip and a number in a compiled program cannot
+differ without the build failing.
+
+**The adapter, `src/adapters/codemirror`, is a drop-in that draws nothing.** The
+text component is a peer dependency and nothing in the adapter imports it, the
+same way the chart adapter treats a chart. Both tooltips take their markup as a
+required parameter with no default, so no tier of this package names a browser
+global at all and every file in it loads in a worker and on a server. Offsets are
+translated between the document a component holds and the normalised text every
+span in this package indexes, so a file with two character line endings is
+underlined in the right place. Highlighting is computed a line at a time, which
+is how the component asks for it, and a test compares that against the whole-file
+`highlight` over every script in the repository: 4279 lines, not one piece
+different.
+
+**Two facts the core now exposes**, because a tier above it needs them and
+reading them out of a module's internals would be a second copy: what a
+declaration call's omitted argument resolves to, and the channels a colour name
+denotes.
+
+Eighty-eight further tests, each naming in a comment the wrong implementation it
+catches, on top of the fifty-eight the first three functions came with.
+Forty-five of those implementations were then written into the source one at a
+time, with every file copied first and restored from the copy by hash afterwards:
+forty-three were caught by a test and two by the compiler. One more was tried and
+changed nothing a caller can observe, a guard in a private function, and is left
+in place and untested for rather than counted as a catch.
+
+**The first run of that harness proved nothing and said it had.** It named the
+test directory, and `node --test <directory>` fails on this runtime whatever the
+directory holds, so every mutation came back caught. The harness now names the
+test files and runs each of its verify commands on the clean tree before it
+starts, and refuses to run at all if one of them does not pass. Five mutations
+then survived, every one of them a test that could not fail: a completion list
+filtered by a word the assertion was about, a signature rendering compared with
+the mapping it came from, a stale cache handed an empty cache to be stale with.
+All five are caught now, and a control change that nothing should catch is
+checked to be caught by nothing.
+
 ## 0.2.0
 
 **This release is the studies surface, finished.** A script compiles in a browser