openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/engine/ledger/closable.ts

@@ -0,0 +1,269 @@
+/**
+ * What is left to reduce and which side reduces it, `stdlib.md` 17.1 and 17.2.
+ *
+ * **Both questions are about a part rather than about the leg**, and the leg is
+ * the case of a part that no tag names. A leg can be long under one tag and
+ * short under another, and then its net answers neither question for either of
+ * them: `close(tag)` taking its side from the net sent an order that added to
+ * the part it was told to flatten, and a count taken from the net did not see
+ * the close already on its way to that part.
+ *
+ * **What is available to reduce is the settled position less everything already
+ * working against it.** A position is folded from settled fills and from
+ * nothing else (17.8), which is right and is what makes this file necessary: an
+ * order the destination has not answered has filled nothing, so the leg still
+ * reads what it held before that order left. Measured against that alone, every
+ * reducing order sends the whole position again.
+ *
+ * **The scope is the run and the position, not the bar.** That correction is
+ * the whole of this file's history and it was arrived at twice. The first
+ * reading counted the orders of one call, and `close()` twice on one bar took a
+ * leg holding three long to three short. The second counted the orders of one
+ * bar, and the same two closes one bar apart did the same thing: the bar's own
+ * record was emptied when the bar index changed, so bar three asked what the leg
+ * held, was told three, and sent three. With a destination slower than the chart
+ * the plainest exit a strategy can write,
+ *
+ *     if bar.index > 0 and pos.size > 0
+ *         close()
+ *
+ * sent one close per bar for the length of the run, and a flat exit became a
+ * short position that grew without limit. The script was not wrong: `pos.size`
+ * is folded from settled fills and correctly still read three.
+ *
+ * So the record is not the call's and not the bar's. It is the ledger's, which
+ * is the run's, and the ledger already holds it: a row carries a status and a
+ * filled quantity, and an order the destination still has is exactly a row that
+ * is neither terminal nor fully filled (`row.ts`, `workingUnits`). A bar-scoped
+ * rule is the special case of this one where nothing has been answered yet, so
+ * this subsumes it rather than sitting beside it, and the bar keeps no record of
+ * its own.
+ *
+ * Four cases decide the shape, and each is a case a strategy meets:
+ *
+ * - **A partial fill.** Three sold with one filled leaves two working, not
+ *   three and not none, because the one that filled has already moved the leg.
+ * - **A rejection.** The row ends, the working quantity is released, and the
+ *   script may close again. That is correct, and it is why a frame matters.
+ * - **A destination that never answers.** The strategy cannot close again,
+ *   which is right: it already has a close working, and a second one would sell
+ *   a position it is already selling. `cancel` is the way out, and it works
+ *   because the cancellation comes back as a frame that ends the row.
+ * - **An entry working against the same leg.** An unsettled `buy` adds nothing
+ *   to what a close may reduce. Nothing has settled, so there is nothing extra
+ *   to close, and counting it would send a close for a position that may never
+ *   exist.
+ *
+ * **In units, because a position is.** A quantity the script stated is in the
+ * declaration's own unit (`host-interface.md` 7.1), so it is a number this file
+ * can read only where that unit is units. In lots, cash or an equity percent
+ * the two are different kinds of number and the lot size that would join them
+ * is the fact OS7005 is deferred on.
+ *
+ * **What is done with an order it cannot read is the only reading that cannot
+ * cross zero: that the order took the whole of the part.** Counted as nothing,
+ * `close(qty = 1)` in lots followed by a bare close on the same bar sent the
+ * position a second time and the leg ended short, which is the defect this file
+ * exists for wearing a different unit. Counted as everything, the second close
+ * sends nothing, which leaves the strategy holding a position it may believe it
+ * closed. That is the worse-of-two choice `stdlib.md` 17.1 already makes: an
+ * order that crosses zero is the failure the sentence is unconditional about,
+ * and a close that sends nothing is the idempotence the same section describes.
+ *
+ * So what is left carries whether it was counted or assumed. The mapping reads
+ * the number, because sending nothing is safe either way. The refusal reads
+ * both, because a refusal may only name a number it measured: an assumed zero
+ * is not a fact about the leg and OS7017 is not raised on one.
+ */
+import type { OrderSide } from './intent.js';
+import { isTerminal, workingUnits } from './row.js';
+import type { LedgerRow } from './row.js';
+
+/**
+ * The side that reduces a position, or nothing when there is none to reduce.
+ *
+ * One fact with two readers. The mapping uses it to give a close its direction,
+ * and the arithmetic below uses it to tell an order that is on its way out of
+ * the position from one that is on its way in, which is the difference between
+ * a reduction that is still working and an entry that holds nothing.
+ */
+export function closingSide(size: number): OrderSide | undefined {
+  if (size > 0) return 'sell';
+  if (size < 0) return 'buy';
+  return undefined;
+}
+
+/**
+ * What the arithmetic below needs: the leg and the rows of its own ledger.
+ *
+ * Narrower than the context the mapping is given, so that this file states what
+ * it reads rather than importing the whole of it.
+ */
+export interface Closing {
+  /** The leg's net position in units, folded from settled fills. */
+  size(): number;
+  /** The rows this strategy placed, newest last. */
+  rows(): readonly LedgerRow[];
+}
+
+/** The settled units held under one tag, signed the way a position is. */
+function heldUnder(ctx: Closing, tag: string): number {
+  let held = 0;
+  for (const row of ctx.rows()) {
+    if (row.tag !== tag) continue;
+    held += row.side === 'buy' ? row.filledQty : -row.filledQty;
+  }
+  return held;
+}
+
+/**
+ * What the part a call names holds, signed the way a position is.
+ *
+ * The leg where the call names no tag, and the settled quantity of that tag's
+ * own rows where it names one. **One function because it is one question**, and
+ * every number this file produces about a part is taken from it: how much is
+ * there to close, which side reduces it, and how much of it an order the engine
+ * cannot read is assumed to have taken.
+ */
+function holdingOf(ctx: Closing, tag: string | null): number {
+  return tag === null ? ctx.size() : heldUnder(ctx, tag);
+}
+
+/**
+ * The side that reduces the part a call names, or nothing where it holds none.
+ *
+ * **The direction of a close comes from the part it was told to flatten**, and
+ * taking it from the leg is how a call named `close` opened a position: a leg
+ * holding ten long under one tag and four short under another is a net six
+ * long, so `close(tag)` on the short part was answered with a sell, which took
+ * that part to eight short and cut the other one to six. `stdlib.md` 17.2 says
+ * the call flattens the part of the position carrying one tag, and says of the
+ * reading that takes the leg's net that it would let close open a position.
+ *
+ * A part whose own rows have netted to nothing has no side and the call sends
+ * nothing, which is 17.2's idempotence and the same answer a flat leg gives a
+ * bare close.
+ */
+export function closingFor(ctx: Closing, tag: string | null): OrderSide | undefined {
+  return closingSide(holdingOf(ctx, tag));
+}
+
+/** What one part of the leg can still close, and whether that was measured. */
+export interface Closable {
+  /** The units a close may still send against it. */
+  readonly units: number;
+  /** Whether every order counted against it stated a quantity in units. */
+  readonly counted: boolean;
+}
+
+/**
+ * The units already working against the position, across the whole run.
+ *
+ * Every reduction comes out of the leg, and a reduction naming a tag comes out
+ * of that tag as well, so the leg is asked with no tag and a part is asked with
+ * its own.
+ *
+ * **Only an order on the side that reduces what the leg holds now**, and
+ * **every** order on that side. A row records what it reduced at the moment it
+ * was sent, and a leg that has changed sign since is being reduced from the
+ * other side: an order still working on the old side is adding to the leg
+ * rather than taking from it, and subtracting it would leave a close sending
+ * less than there is to close. The same sentence read the other way is the
+ * half that was missing. An order recorded as adding to a position, on a leg
+ * that has since gone the other way, is a reduction now whatever it was then,
+ * and leaving it out let a close be sized against a position an entry was
+ * already coming to take off: `buy(qty = 5)` unanswered on a leg the sells
+ * after it took short offered a close the whole twelve, five of which were
+ * already on their way.
+ *
+ * **The side is the part's own**, which is the leg's where no tag names one. A
+ * part can sit on the side its leg is not on, and then the orders that reduce
+ * it are the ones the leg's net calls additions: measured from the leg, the
+ * count for a short part under a long leg counted the sells that were adding to
+ * it and missed the buys that were taking it off.
+ *
+ * `holdings.ts` makes the same reading per position reference, and the two
+ * agree by construction: what a close may send across the leg is never more
+ * than the positions on that side can give it.
+ */
+function committed(ctx: Closing, tag: string | null): Closable {
+  const held = holdingOf(ctx, tag);
+  const side = closingSide(held);
+  if (side === undefined) return { units: 0, counted: true };
+  let units = 0;
+  let counted = true;
+  for (const row of ctx.rows()) {
+    if (row.side !== side || isTerminal(row.status)) continue;
+    const reduces = row.reduces;
+    if (reduces !== null) {
+      if (tag !== null && reduces.part !== tag) continue;
+      const working = workingUnits(row);
+      if (working === 0) continue;
+      units += working;
+      counted = counted && reduces.counted;
+      continue;
+    }
+    // An order that was an entry when it left. Its own tag is what names it,
+    // because a reduction's `part` is the tag a close named and an entry named
+    // no part of anything.
+    if (tag !== null && row.tag !== tag) continue;
+    if (row.units === null) {
+      // A quantity in the declaration's own unit, working against this part and
+      // unreadable as a number of units. Taken to cover the whole of what is
+      // there, which is the reading `stdlib.md` 17.1 already makes for the
+      // other order it cannot read: a close that sends nothing over an order
+      // that crosses zero.
+      units += Math.abs(held);
+      counted = false;
+      continue;
+    }
+    units += Math.max(0, row.units - row.filledQty);
+  }
+  return { units, counted };
+}
+
+/**
+ * What a `close` can still close, in units, whether or not it names a quantity.
+ *
+ * The whole leg where the call names no tag, and the part that tag entered
+ * where it names one, less what is already working against it. Zero while the
+ * leg is flat, zero for a tag whose rows have netted to nothing, and zero once
+ * the orders already sent have the whole of it going.
+ *
+ * **A part on the leg's own side is bounded by the leg**, so that closing a
+ * part can never take the leg through zero: the part is what the call names,
+ * and the leg is what the order comes out of.
+ *
+ * **A part on the other side is not**, and bounding it there was the second
+ * half of taking a direction from the net. Closing a short part under a long
+ * leg is a buy, which moves the leg away from zero rather than towards it, so
+ * there is nothing for the leg's own number to bound: measured against it, a
+ * part holding ten short on a leg netting two long was offered two, and on a
+ * leg netting nothing at all it was offered nothing. What that order may
+ * actually send is still bounded per position by what has settled there
+ * (`holdings.ts`), so a part whose reference has already returned to zero sends
+ * nothing rather than opening it again.
+ *
+ * Both readers ask this one question. The quantity a script states is refused
+ * against this number (OS7017) and the quantity the engine works out for itself
+ * is this number. Two readings of what a part holds would be one fact in two
+ * files, and the refusal would be about a quantity the mapping was not going to
+ * send.
+ */
+export function closable(ctx: Closing, tag: string | null): Closable {
+  const spent = committed(ctx, null);
+  const leg = Math.max(0, Math.abs(ctx.size()) - spent.units);
+  if (tag === null) return { units: leg, counted: spent.counted };
+  const held = heldUnder(ctx, tag);
+  const own = committed(ctx, tag);
+  const part = Math.max(0, Math.abs(held) - own.units);
+  if (Math.sign(held) !== Math.sign(ctx.size())) return { units: part, counted: own.counted };
+  return part <= leg
+    ? { units: part, counted: own.counted }
+    : { units: leg, counted: spent.counted };
+}
+
+/** What a close can still close, for the mapping, which sends a number. */
+export function closableUnits(ctx: Closing, tag: string | null): number {
+  return closable(ctx, tag).units;
+}

package/src/core/engine/ledger/holdings.ts

@@ -0,0 +1,354 @@
+/**
+ * What a leg holds, one entry per position reference, including what is still
+ * working, `stdlib.md` 17.1 and 17.7.
+ *
+ * **This file answers which position an order is sent against.** Three rounds
+ * corrected how much a reducing order may send, against the call, against the
+ * bar and then against the run. None of them asked which position reference an
+ * order carries, and the mapping was still deciding it from `ctx.size()`, which
+ * is the leg's net folded from settled fills. That number cannot answer the
+ * question, and the plainest script there is shows why:
+ *
+ *     if bar.index == 0
+ *         buy(qty = 6)
+ *     if bar.index == 1
+ *         sell(qty = 9)
+ *
+ * With the destination silent the leg's settled net is zero on bar one, so the
+ * sell was not seen as opposing anything and went on the reference the buy was
+ * already on. Both filled, and reference 1 opened six long and settled three
+ * short: one reference holding both signs, which is the one failure 17.1 names,
+ * because a fill arriving late can no longer say which position it settled.
+ *
+ * **So a reference is measured by what is on it, settled and working
+ * together.** An order the destination has not answered has moved no position
+ * figure, and the ledger's rows are where it is visible (`row.ts`). A reference
+ * with six units of buy still to come is a long position whether or not any of
+ * it has settled, and an opposing order has to take those six off it before it
+ * opens anything new: otherwise nothing can ever bring that reference back to
+ * zero, which is 17.7's sentence about how a position ends.
+ *
+ * **Two numbers, because two questions are asked and they are not the same
+ * question.**
+ *
+ * - `units` is what an opposing order may take, and it counts what is working.
+ *   The order is being sent either way, at the size the script wrote; the only
+ *   thing being decided is which reference each unit lands on, and the answer
+ *   that lets every reference return to zero is the one that puts the units
+ *   where the quantity they cancel is.
+ * - `settled` is what a close may send, and it counts only what has settled,
+ *   less what is already working against it. A close chooses its own quantity,
+ *   so a close counting a working entry would sell units that may never exist.
+ *   That is `closable.ts`'s rule, and this is the same rule read per reference
+ *   instead of per leg.
+ *
+ * **What this costs, stated rather than discovered.** An entry that opposes an
+ * unanswered entry is sent against it, so if the first order is rejected and
+ * the second fills, that reference settles on the side it did not open on. No
+ * engine avoids that without holding an order back until the destination
+ * answers, which is an engine that stops trading when a destination is slow.
+ * What 17.1 asks for is kept either way: every order names exactly one
+ * position, so every fill, however late, says which position it settled.
+ */
+import type { OrderSide } from './intent.js';
+import { isTerminal } from './row.js';
+import type { LedgerRow } from './row.js';
+
+/** One position reference a leg holds, and what may still be done to it. */
+export interface Holding {
+  readonly ref: number;
+  /** The side it is on: `buy` for a long position, `sell` for a short one. */
+  readonly side: OrderSide;
+  /**
+   * The units an opposing order may take from it, settled and working
+   * together, or absent where the engine cannot read one of its quantities.
+   *
+   * Absent is not zero. It means the reference holds something on `side` whose
+   * size is stated in the declaration's own unit, which is the fact OS7005 is
+   * deferred on, so an opposing order cannot be divided against it.
+   */
+  readonly units: number | null;
+  /** The settled units nothing is working against, which is what a close sends. */
+  readonly settled: number;
+}
+
+/** What this file reads: the rows of the ledger and the position book. */
+export interface Book {
+  /** The rows this strategy placed, newest last. */
+  rows(): readonly LedgerRow[];
+  /** The settled size of one position reference, signed the way a position is. */
+  sizeOf(ref: number): number;
+}
+
+/** One reference under construction, before it is decided what it holds. */
+interface Tally {
+  /** Settled, signed, from the position book, which is the fold's owner. */
+  readonly settled: number;
+  /** Working units, signed, over the orders whose quantity is readable. */
+  working: number;
+  /**
+   * Working units on the side that reduces what has settled here, unsigned.
+   *
+   * **Which side that is depends on what settled, not on what an order was
+   * when it left.** A row records what it reduced at the moment it was sent,
+   * and a position that has moved since is being reduced from the other side:
+   * an order recorded as adding is a reduction now, and a reduction recorded
+   * then is adding now. Counting by the record instead of by the direction
+   * offered a close seven units against a reference holding two short, which
+   * took that reference's own book to five long. `closable.ts` makes the same
+   * correction one scope out, on the leg.
+   */
+  against: number;
+  /** The side of a working order whose quantity is not readable, or none. */
+  unreadable: OrderSide | null;
+  /** Whether a quantity it cannot read is working against what settled here. */
+  blocked: boolean;
+}
+
+function sideOf(signed: number): OrderSide {
+  return signed > 0 ? 'buy' : 'sell';
+}
+
+/**
+ * Every position reference this leg holds, oldest first.
+ *
+ * Oldest first is the order the references were minted in, which is the order
+ * the rows first name them in, and it is the order a reducing order takes them
+ * in: the position opened first is the position closed first.
+ *
+ * A reference with nothing left on it is not here. It has no room for an
+ * opposing order and nothing for a close to send, and it is either already back
+ * at zero or has its whole quantity spoken for by orders that are still going.
+ */
+export function holdings(ctx: Book): readonly Holding[] {
+  const tallies = new Map<number, Tally>();
+  const minted: number[] = [];
+
+  for (const row of ctx.rows()) {
+    let tally = tallies.get(row.positionRef);
+    if (tally === undefined) {
+      tally = {
+        settled: ctx.sizeOf(row.positionRef),
+        working: 0,
+        against: 0,
+        unreadable: null,
+        blocked: false,
+      };
+      tallies.set(row.positionRef, tally);
+      minted.push(row.positionRef);
+    }
+    // An order that has ended has nothing more coming from it, whatever it
+    // filled: the fill is already in the settled figure above, and the rest is
+    // released. That is how a strategy whose order was rejected gets its room
+    // back.
+    if (isTerminal(row.status)) continue;
+    const sign = row.side === 'buy' ? 1 : -1;
+    // **Every row is read the same way, by the order's own quantity in units**,
+    // because this sum is compared against what has settled on this reference
+    // and both halves have to fall together when a fill arrives.
+    //
+    // A reduction used to be read by what it claimed of the leg when it was
+    // sent (`row.ts`, `Reduction`), which is a number about the leg rather than
+    // about the order: a second stated close claims nothing, because the first
+    // already spoke for the whole leg, and it still fills and still takes what
+    // it filled off what has settled here. The settled half fell, the claimed
+    // half did not, the sum went negative, the reference read as the side it is
+    // not on, and an entry opposing it was handed it as an order that adds. It
+    // then opened long and settled short with every order answered in full.
+    const remaining = row.units === null ? null : Math.max(0, row.units - row.filledQty);
+    const reduces = Math.sign(tally.settled) === -sign;
+    if (remaining === null) {
+      tally.unreadable = row.side;
+      // Nothing is sent against a position an order the engine cannot read is
+      // working against. Between a close that sends nothing and an order that
+      // crosses zero, `stdlib.md` 17.1 has already chosen.
+      if (reduces) tally.blocked = true;
+      continue;
+    }
+    tally.working += sign * remaining;
+    if (reduces) tally.against += remaining;
+  }
+
+  const held: Holding[] = [];
+  for (const ref of minted) {
+    const tally = tallies.get(ref) as Tally;
+    const outstanding = tally.settled + tally.working;
+    if (outstanding === 0 && tally.unreadable === null) continue;
+    const side = outstanding === 0 ? (tally.unreadable as OrderSide) : sideOf(outstanding);
+    // A reference holding a quantity the engine cannot read holds an unknown
+    // number of units, and understating it is the safe half of that: an
+    // opposing order divided against too small a number opens the remainder on
+    // a reference of its own, which crosses nothing.
+    const units = outstanding === 0 ? null : Math.abs(outstanding);
+    // **What a close may send is what settled here and is not already coming
+    // off**, and only where what settled is on this side. A reference whose
+    // working orders run past its settled quantity reads as the other side,
+    // because that is what it will hold, and nothing of that side has settled
+    // yet: a reference two long with nine of sell working offered a close seven
+    // units to send against it, which took its own book to five long.
+    const facing = side === 'buy' ? 1 : -1;
+    const settled =
+      tally.blocked || Math.sign(tally.settled) !== facing
+        ? 0
+        : Math.max(0, Math.abs(tally.settled) - tally.against);
+    held.push({ ref, side, units, settled });
+  }
+  return held;
+}
+
+/**
+ * The references an order of this side reduces, oldest first.
+ *
+ * A reference is reduced by the side it is not on, which is the same test a
+ * close makes on the leg as a whole and is why `closingSide` and this agree.
+ */
+export function opposing(book: readonly Holding[], side: OrderSide): readonly Holding[] {
+  return book.filter((one) => one.side !== side);
+}
+
+/**
+ * The position an order the engine cannot size is sent against, `stdlib.md`
+ * 17.1, or none where the leg names no position at all.
+ *
+ * **A close is never minted a position of its own.** It is named for reducing,
+ * so it goes on the position it is closing, and where the engine cannot read
+ * the quantity it states, that position is the one the order may take past
+ * zero: the one shape of 17.1 an engine does not keep, waiting on the lot size
+ * OS7005 is deferred on.
+ *
+ * **What has settled comes first, and the book's own list second.** A reference
+ * whose settled quantity is entirely spoken for by orders that are still going
+ * is not in the book above, because it has nothing left for an engine-sized
+ * close to send. An order the engine cannot size is not choosing a quantity, so
+ * that exclusion does not apply to it: the position it is closing is still that
+ * one. Taking the book's answer alone sent a close on a reference an entry was
+ * opening on the other side, which is an order named close adding to a
+ * position: with the leg's whole long inside a close the destination still had,
+ * `close(qty = 1)` in cash was handed the reference a short entry had just
+ * opened, and was a sell on it.
+ *
+ * A reference with nothing settled either way is the second answer rather than
+ * the first, because a position being opened is a position under 17.1 and an
+ * order that reduces the leg has to name one of them.
+ */
+export function outgoingFor(
+  ctx: Book,
+  book: readonly Holding[],
+  side: OrderSide,
+): number | null {
+  const facing = side === 'buy' ? -1 : 1;
+  const seen = new Set<number>();
+  for (const row of ctx.rows()) {
+    if (seen.has(row.positionRef)) continue;
+    seen.add(row.positionRef);
+    if (Math.sign(ctx.sizeOf(row.positionRef)) === facing) return row.positionRef;
+  }
+  return opposing(book, side)[0]?.ref ?? null;
+}
+
+/**
+ * The position a bracket protects, or none where the leg holds none,
+ * `stdlib.md` 17.7 and `host-interface.md` 7.1.
+ *
+ * **Holding first, opening second, which is the order 17.7 states them in.** A
+ * bracket appends no row and moves no position, so it has nothing of its own to
+ * name: it names what the leg has, and what the leg has is what its own fills
+ * settled. Only where nothing has settled at all is the answer the position the
+ * leg is opening, which is the ordinary shape of an `exit()` written beside the
+ * entry it protects.
+ *
+ * **The newest of them where the leg holds more than one**, which it does
+ * whenever an order that opposes it is outstanding. The newest is the one an
+ * entry on that side would join (`joining`), so a bracket set after an entry
+ * names the position that entry is in.
+ *
+ * **Derived here rather than kept as the last reference minted.** A stored slot
+ * answered neither question: it was set by the mint and cleared when that one
+ * reference returned to zero, so a leg whose newer position closed while an
+ * older one was still held was reported as holding none, and `exit()` handed a
+ * host `0` with ten units on the books. The mirror of it is the same slot read
+ * the other way: a reference minted for an order the destination then refused
+ * stayed the answer, and the bracket named a position that never opened while
+ * the leg's own sat on another reference. Neither needs a slot to answer, and
+ * both are wrong in the direction a host cannot check: `0` says the leg holds
+ * nothing, and 7.1 tells a host to look a reference up only when it is not `0`.
+ */
+export function protecting(ctx: Book): number | null {
+  let held: number | null = null;
+  const seen = new Set<number>();
+  for (const row of ctx.rows()) {
+    if (seen.has(row.positionRef)) continue;
+    seen.add(row.positionRef);
+    // Rows are oldest first and references are minted in order, so the last one
+    // this loop keeps is the newest reference something has settled on.
+    if (ctx.sizeOf(row.positionRef) !== 0) held = row.positionRef;
+  }
+  if (held !== null) return held;
+  const book = holdings(ctx);
+  return book.length === 0 ? null : (book[book.length - 1] as Holding).ref;
+}
+
+/**
+ * The reference an order that adds to a position joins, or none to mint one.
+ *
+ * The newest open reference on that side, so that two entries sent on two bars
+ * before either fills belong to one position rather than to two, which is what
+ * `stdlib.md` 17.7 means by a reference being kept while a position is being
+ * opened.
+ *
+ * **A reference whose whole quantity is already going is not open to join.** A
+ * leg long ten with a close of ten working is on its way out: an entry joining
+ * it would settle into a position that reaches zero and ends, and 17.7's
+ * sentence would then have to happen twice for one reference. The entry takes a
+ * reference of its own, and if the close is rejected the leg simply holds two
+ * positions on one side, each of which a close can still send.
+ */
+export function joining(book: readonly Holding[], side: OrderSide): number | null {
+  for (let index = book.length - 1; index >= 0; index -= 1) {
+    const one = book[index] as Holding;
+    if (one.side === side) return one.ref;
+  }
+  return null;
+}
+
+/** One order of a call: the units it sends and the reference it sends them on. */
+export interface Share {
+  readonly ref: number;
+  readonly units: number;
+}
+
+/**
+ * How a quantity is divided across the references it reduces, oldest first.
+ *
+ * **A reducing order that spans two positions is two orders**, for the reason
+ * 17.1 already gives for a flip: one order against two positions would leave a
+ * late fill with no way to say which of them it settled. A leg holds more than
+ * one position whenever an order that opposes it is outstanding, and before
+ * this the whole of a leg's closable quantity was attached to a single
+ * reference with nothing asking whether that reference could absorb it.
+ *
+ * `room` is which of the two numbers a holding offers is the ceiling here: what
+ * an opposing order may take, or what has settled. The caller chooses, because
+ * the caller knows whether the quantity is the script's or the engine's.
+ *
+ * What is left over when every reference is full is the caller's to open or to
+ * drop. Nothing is ever sent past a reference's own ceiling.
+ */
+export function divide(
+  book: readonly Holding[],
+  side: OrderSide,
+  units: number,
+  room: (one: Holding) => number | null,
+): { readonly shares: readonly Share[]; readonly left: number } {
+  const shares: Share[] = [];
+  let left = units;
+  for (const one of opposing(book, side)) {
+    if (left <= 0) break;
+    const ceiling = room(one);
+    if (ceiling === null || ceiling <= 0) continue;
+    const take = Math.min(left, ceiling);
+    shares.push({ ref: one.ref, units: take });
+    left -= take;
+  }
+  return { shares, left };
+}

package/src/core/engine/ledger/index.ts

@@ -0,0 +1,28 @@
+/**
+ * The ledger: what this strategy sent, and what became of it.
+ *
+ * One module because it is one fact with three faces. An intent leaves, a row
+ * records it, a frame folds into that row, and the position every `pos` call
+ * reads is the sum of the fills those frames settled. Splitting them would put
+ * the fold in one place and the field names it folds into in another, which is
+ * how a cumulative quantity becomes a double counted one.
+ *
+ * The door carries the shapes that cross a boundary and the one class that
+ * holds state. The fold, the position book, the mapping from a call to an
+ * order and the refusals stay behind it: they are one algorithm with one
+ * caller.
+ */
+export type {
+  Identity,
+  IntentBar,
+  IntentKind,
+  OrderFrame,
+  OrderIntent,
+  OrderSide,
+  OrderType,
+} from './intent.js';
+
+export { Ledger } from './ledger.js';
+export type { LedgerOptions, PlacedCall } from './ledger.js';
+
+export type { FrameOutcome, FrameRefusal, LedgerRow, OrderStatus } from './row.js';