openalgo-script 0.1.0-alpha.1 → 0.4.0

package/dist/core/engine/ledger/closable.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 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 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 declare function closingSide(size: number): OrderSide | 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 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 declare function closingFor(ctx: Closing, tag: string | null): OrderSide | undefined;
+/** 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;
+}
+/**
+ * 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 declare function closable(ctx: Closing, tag: string | null): Closable;
+/** What a close can still close, for the mapping, which sends a number. */
+export declare function closableUnits(ctx: Closing, tag: string | null): number;
+//# sourceMappingURL=closable.d.ts.map

package/dist/core/engine/ledger/closable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closable.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/ledger/closable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAI/D;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,kEAAkE;IAClE,IAAI,IAAI,MAAM,CAAC;IACf,kDAAkD;IAClD,IAAI,IAAI,SAAS,SAAS,EAAE,CAAC;CAC9B;AAyBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAElF;AAED,+EAA+E;AAC/E,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAoED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,CAWnE;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEtE"}

package/dist/core/engine/ledger/closable.js

@@ -0,0 +1,173 @@
+import { isTerminal, workingUnits } 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) {
+    if (size > 0)
+        return 'sell';
+    if (size < 0)
+        return 'buy';
+    return undefined;
+}
+/** The settled units held under one tag, signed the way a position is. */
+function heldUnder(ctx, tag) {
+    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, tag) {
+    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, tag) {
+    return closingSide(holdingOf(ctx, tag));
+}
+/**
+ * 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, tag) {
+    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, tag) {
+    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, tag) {
+    return closable(ctx, tag).units;
+}
+//# sourceMappingURL=closable.js.map

package/dist/core/engine/ledger/closable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closable.js","sourceRoot":"","sources":["../../../../src/core/engine/ledger/closable.ts"],"names":[],"mappings":"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"}

package/dist/core/engine/ledger/holdings.d.ts

@@ -0,0 +1,194 @@
+/**
+ * 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 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;
+}
+/**
+ * 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 declare function holdings(ctx: Book): readonly Holding[];
+/**
+ * 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 declare function opposing(book: readonly Holding[], side: OrderSide): readonly Holding[];
+/**
+ * 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 declare function outgoingFor(ctx: Book, book: readonly Holding[], side: OrderSide): number | 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 declare function protecting(ctx: Book): number | null;
+/**
+ * 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 declare function joining(book: readonly Holding[], side: OrderSide): number | 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 declare function divide(book: readonly Holding[], side: OrderSide, units: number, room: (one: Holding) => number | null): {
+    readonly shares: readonly Share[];
+    readonly left: number;
+};
+//# sourceMappingURL=holdings.d.ts.map

package/dist/core/engine/ledger/holdings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"holdings.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/ledger/holdings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,4EAA4E;AAC5E,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,IAAI;IACnB,kDAAkD;IAClD,IAAI,IAAI,SAAS,SAAS,EAAE,CAAC;IAC7B,gFAAgF;IAChF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AA+BD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG,SAAS,OAAO,EAAE,CA0EtD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,OAAO,EAAE,CAEtF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,IAAI,EAAE,SAAS,GACd,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAanD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAMhF;AAED,kFAAkF;AAClF,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,GACpC;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAY9D"}