openalgo-script 0.1.0-alpha.0 → 0.2.0

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

@@ -0,0 +1,176 @@
+/**
+ * One row of the strategy's order and fill ledger, and the fold of one frame
+ * into it, `stdlib.md` 17.7 and 17.8.
+ *
+ * **A row is appended when the order is sent and is never rewritten by
+ * guesswork.** Every change to it comes from a frame the destination sent, so
+ * the sequence that produced a position can be replayed rather than inferred.
+ *
+ * **The fold is where double counting happens**, which is why it is written
+ * once, here, and why every step of it is the numbered step `stdlib.md` 17.8
+ * gives. Frames repeat, cross in flight and arrive after the order they are
+ * about has ended, and an engine that added each frame's quantity to a running
+ * total would report a position the strategy never held. Taking the greatest
+ * cumulative quantity instead makes a repeat cost nothing and makes a terminal
+ * frame that overtook a partial one carry the whole remainder in one piece.
+ *
+ * **A row also carries what its order takes out of the position**, because that
+ * is the only record of it that outlives the bar the order was sent on. A
+ * position moves when a fill settles, so an order that has been sent and not
+ * answered has moved nothing and is invisible to every position figure; the row
+ * is where it is visible. `closable.ts` reads the reduction back, and what makes
+ * the reading work is that a row already says whether the order is still going:
+ * an order neither terminal nor fully filled is one the destination still has.
+ */
+import type { Identity, OrderFrame, OrderSide, OrderType } from './intent.js';
+/**
+ * What one order claimed of the part it reduces, in units, when it was sent.
+ *
+ * Absent on an order that adds to a position, and absent on one whose quantity
+ * the engine cannot count in units, which are two different facts with the same
+ * consequence: neither subtracts anything from what is left to close.
+ *
+ * **`claimed` is a claim and not a size**, and the name says so because reading
+ * it as a size was a defect twice over. On an order the engine sized itself the
+ * two are the same number; on one it could not read they are not, and there it
+ * is the whole of what was left to close at the moment the order left, which is
+ * the reading `stdlib.md` 17.1 makes for an order it cannot count. That number
+ * belongs to one question, how much of a part is already spoken for, and it
+ * answers it whatever unit the order itself was written in. The order's own
+ * size, where the engine can read it, is `units` on the row beside this.
+ */
+export interface Reduction {
+    /** The tag the close named, or absent where it reduces the leg as a whole. */
+    readonly part: string | null;
+    /** The units of that part this order claimed when it was sent. */
+    readonly claimed: number;
+    /**
+     * Whether `claimed` is the order's own quantity or the most it could have
+     * been. False on an order whose quantity the engine cannot read in units,
+     * where `claimed` is the whole of what was left to close when it was sent.
+     */
+    readonly counted: boolean;
+}
+/**
+ * The words a row's status may take, `stdlib.md` 17.7.
+ *
+ * `placed` is the engine's own and no host may send it: it means an intent has
+ * left and nothing has come back, and a destination cannot report a state it
+ * has never described.
+ */
+export type OrderStatus = 'placed' | 'working' | 'triggerPending' | 'filled' | 'cancelled' | 'rejected' | 'expired';
+export declare function isTerminal(status: OrderStatus): boolean;
+/** The word a host sent, or nothing when it is not one of the seven. */
+export declare function statusFrom(word: string): OrderStatus | undefined;
+/** A row of the ledger, `stdlib.md` 17.7. */
+export interface LedgerRow {
+    readonly intentId: number;
+    /** The destination's own reference, recorded, shown, and never parsed. */
+    orderRef: string;
+    readonly tag: string;
+    readonly leg: string;
+    readonly positionRef: number;
+    /** The contract actually sent, which the host may restate in a frame. */
+    instrument: Identity;
+    /** The product actually sent, after the host's own translation. */
+    product: string;
+    readonly side: OrderSide;
+    readonly qty: number;
+    readonly type: OrderType;
+    readonly price: number | null;
+    readonly trigger: number | null;
+    status: OrderStatus;
+    filledQty: number;
+    avgFillPrice: number | null;
+    rejection: string;
+    readonly placedAt: number | null;
+    updatedAt: number | null;
+    /**
+     * What this order claimed of the position, absent where it claimed nothing.
+     *
+     * Fixed when the order was sent and never rewritten, because it is a record
+     * of what the engine measured at that moment and not a running total. What
+     * moves is `filledQty` beside it, and the two together say how much of the
+     * claim the destination still has.
+     */
+    readonly reduces: Reduction | null;
+    /**
+     * This order's own quantity in units, absent where the engine cannot read it.
+     *
+     * A quantity the script stated is in the declaration's own unit
+     * (`host-interface.md` 7.1) and a quantity the engine worked out is in units,
+     * and the two are told apart per order rather than per run: a reverse under a
+     * declaration counting in lots opens its replacement at a size the engine
+     * worked out, in units, on the same bar as orders that are not.
+     *
+     * `reduces` says what an order takes out of a position and this says what it
+     * puts into one, which is the half `holdings.ts` needs to see a position
+     * being opened before any of it has settled.
+     */
+    readonly units: number | null;
+}
+/**
+ * How much of this row's claim on the part it reduces is still outstanding.
+ *
+ * **An order that has been sent and not answered is the whole of what this
+ * file exists to make visible.** A position is folded from settled fills and
+ * from nothing else (17.8), so such an order has moved no position figure: the
+ * leg still reads what it held before it was sent, and a second reducing order
+ * measured against the leg alone sends the position a second time.
+ *
+ * Four facts decide the number, and each of them is a case a strategy meets:
+ *
+ * - **A partial fill of an order the engine counted.** Three sold with one
+ *   filled leaves two working, because the one that filled has already moved
+ *   the leg and only the other two are still to come.
+ * - **A partial fill of one it could not count**, where the claim stands whole
+ *   until the order ends. The claim is in units and the fill is in whatever
+ *   the destination answered a quantity in lots, cash or an equity percent
+ *   with, and subtracting one from the other is the drift this file is written
+ *   to make impossible: a destination answering more than the claim released
+ *   room that was never there and the next close sent the position again.
+ * - **An order that has ended.** A rejection, a cancellation and an expiry all
+ *   put the row at a terminal status, and nothing more is coming from any of
+ *   them, so the claim is released and the strategy may close again. That is
+ *   the script's way out of a destination that refused its close.
+ * - **An order that adds**, which claims nothing and holds nothing: an entry
+ *   that has not settled is not a position, and counting it would let a close
+ *   be sent for units that may never exist.
+ *
+ * **This answers one question and one reader.** What is left to close is a
+ * question about a part of the leg, and `closable.ts` is where it is asked.
+ * Which side a position reference is on is a different question, asked of one
+ * reference against what has settled on it, and `holdings.ts` reads the order's
+ * own size for it rather than this.
+ */
+export declare function workingUnits(row: LedgerRow): number;
+/** Why a frame was refused, `stdlib.md` 17.14. */
+export type FrameRefusal = 'unknownIntent' | 'fillWithNoPrice';
+/**
+ * What one frame did.
+ *
+ * A refused frame changes nothing and is recorded, because a frame naming an
+ * order this strategy never placed is a fact about the host rather than about
+ * the strategy, and one reporting a fill with no price cannot be marked against
+ * anything.
+ */
+export interface FrameOutcome {
+    readonly intentId: number;
+    readonly refused: FrameRefusal | undefined;
+    readonly changed: boolean;
+    /** Units this frame added, which is what settles against a position. */
+    readonly delta: number;
+    readonly price: number | null;
+    /** Whether the delta arrived after the row had already ended, 17.11. */
+    readonly afterTerminal: boolean;
+}
+/**
+ * Folds one frame into one row, `stdlib.md` 17.8 steps 2 to 5 and 7.
+ *
+ * Step 1 is the ledger's, because locating a row is a question about the whole
+ * ledger rather than about any one row, and step 6 is the position book's: this
+ * function says how many units settled and at what price, and where they settle
+ * is `positions.ts`.
+ */
+export declare function foldFrame(row: LedgerRow, frame: OrderFrame): FrameOutcome;
+//# sourceMappingURL=row.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"row.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/ledger/row.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,SAAS,GACT,gBAAgB,GAChB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,SAAS,CAAC;AAqCd,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEvD;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEhE;AAED,6CAA6C;AAC7C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,UAAU,EAAE,QAAQ,CAAC;IACrB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAInD;AAED,kDAAkD;AAClD,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,iBAAiB,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAaD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,YAAY,CAyEzE"}

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

@@ -0,0 +1,169 @@
+const STATUSES = [
+    'placed',
+    'working',
+    'triggerPending',
+    'filled',
+    'cancelled',
+    'rejected',
+    'expired',
+];
+/**
+ * Which words end an order.
+ *
+ * A terminal row still takes a fill, under 17.8, so this decides what the
+ * status may become and nothing about what the quantity may do.
+ */
+const TERMINAL = new Set([
+    'filled',
+    'cancelled',
+    'rejected',
+    'expired',
+]);
+/**
+ * How far along its life a status sits.
+ *
+ * Two words share the middle rank because an order that is live and one that is
+ * waiting for its trigger are the same distance from the end, and either may
+ * follow the other without going backwards.
+ */
+function rankOf(status) {
+    if (status === 'placed')
+        return 0;
+    return TERMINAL.has(status) ? 2 : 1;
+}
+export function isTerminal(status) {
+    return TERMINAL.has(status);
+}
+/** The word a host sent, or nothing when it is not one of the seven. */
+export function statusFrom(word) {
+    return STATUSES.find((one) => one === word);
+}
+/**
+ * How much of this row's claim on the part it reduces is still outstanding.
+ *
+ * **An order that has been sent and not answered is the whole of what this
+ * file exists to make visible.** A position is folded from settled fills and
+ * from nothing else (17.8), so such an order has moved no position figure: the
+ * leg still reads what it held before it was sent, and a second reducing order
+ * measured against the leg alone sends the position a second time.
+ *
+ * Four facts decide the number, and each of them is a case a strategy meets:
+ *
+ * - **A partial fill of an order the engine counted.** Three sold with one
+ *   filled leaves two working, because the one that filled has already moved
+ *   the leg and only the other two are still to come.
+ * - **A partial fill of one it could not count**, where the claim stands whole
+ *   until the order ends. The claim is in units and the fill is in whatever
+ *   the destination answered a quantity in lots, cash or an equity percent
+ *   with, and subtracting one from the other is the drift this file is written
+ *   to make impossible: a destination answering more than the claim released
+ *   room that was never there and the next close sent the position again.
+ * - **An order that has ended.** A rejection, a cancellation and an expiry all
+ *   put the row at a terminal status, and nothing more is coming from any of
+ *   them, so the claim is released and the strategy may close again. That is
+ *   the script's way out of a destination that refused its close.
+ * - **An order that adds**, which claims nothing and holds nothing: an entry
+ *   that has not settled is not a position, and counting it would let a close
+ *   be sent for units that may never exist.
+ *
+ * **This answers one question and one reader.** What is left to close is a
+ * question about a part of the leg, and `closable.ts` is where it is asked.
+ * Which side a position reference is on is a different question, asked of one
+ * reference against what has settled on it, and `holdings.ts` reads the order's
+ * own size for it rather than this.
+ */
+export function workingUnits(row) {
+    const reduces = row.reduces;
+    if (reduces === null || isTerminal(row.status))
+        return 0;
+    return reduces.counted ? Math.max(0, reduces.claimed - row.filledQty) : reduces.claimed;
+}
+function refuse(frame, why) {
+    return {
+        intentId: frame.intentId,
+        refused: why,
+        changed: false,
+        delta: 0,
+        price: null,
+        afterTerminal: false,
+    };
+}
+/**
+ * Folds one frame into one row, `stdlib.md` 17.8 steps 2 to 5 and 7.
+ *
+ * Step 1 is the ledger's, because locating a row is a question about the whole
+ * ledger rather than about any one row, and step 6 is the position book's: this
+ * function says how many units settled and at what price, and where they settle
+ * is `positions.ts`.
+ */
+export function foldFrame(row, frame) {
+    // A word outside the vocabulary leaves the status alone and the rest of the
+    // frame folds anyway. Mapping a destination's own words onto the vocabulary
+    // is the host's job under 17.7, and an engine that guessed at one would
+    // decide an order was dead on a word it had never seen. Refusing the whole
+    // frame instead would throw away the cumulative quantity it carries, which is
+    // real whatever the word beside it says, and losing a real fill is silent in
+    // exactly the way decision 24 describes.
+    const status = statusFrom(frame.status);
+    const wasTerminal = isTerminal(row.status);
+    // Step 2. The cumulative quantity never decreases, so a frame reporting less
+    // than the row already holds contributes nothing.
+    const filled = Math.max(row.filledQty, frame.filledQty);
+    const delta = filled - row.filledQty;
+    // Step 3. The destination computed its average over the cumulative quantity,
+    // so the row takes that average whole. The engine never averages two averages
+    // of its own.
+    const price = frame.avgFillPrice ?? null;
+    if (delta > 0 && price === null)
+        return refuse(frame, 'fillWithNoPrice');
+    // Step 4, which a frame arriving at a terminal row does not run: the status
+    // records how the order ended and the quantity records what traded, and the
+    // two are both true.
+    const moved = status !== undefined &&
+        status !== 'placed' &&
+        !wasTerminal &&
+        rankOf(status) >= rankOf(row.status) &&
+        status !== row.status;
+    const text = frame.text ?? '';
+    const newText = text !== '' && text !== row.rejection;
+    // Step 5.
+    const changed = moved || delta > 0 || newText;
+    // Step 7. A repeated frame and one overtaken by a later frame both end here,
+    // having changed nothing: no fill, no event, no report row.
+    if (!changed) {
+        return {
+            intentId: frame.intentId,
+            refused: undefined,
+            changed: false,
+            delta: 0,
+            price: null,
+            afterTerminal: false,
+        };
+    }
+    if (moved && status !== undefined)
+        row.status = status;
+    if (delta > 0) {
+        row.filledQty = filled;
+        row.avgFillPrice = price;
+    }
+    if (newText)
+        row.rejection = text;
+    if (typeof frame.orderRef === 'string')
+        row.orderRef = frame.orderRef;
+    if (frame.sentInstrument !== undefined && frame.sentInstrument !== null) {
+        row.instrument = frame.sentInstrument;
+    }
+    if (typeof frame.sentProduct === 'string')
+        row.product = frame.sentProduct;
+    if (typeof frame.time === 'number')
+        row.updatedAt = frame.time;
+    return {
+        intentId: frame.intentId,
+        refused: undefined,
+        changed: true,
+        delta,
+        price: delta > 0 ? price : null,
+        afterTerminal: wasTerminal && delta > 0,
+    };
+}
+//# sourceMappingURL=row.js.map

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

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

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

@@ -0,0 +1,142 @@
+import type { Closing } from './closable.js';
+import type { Book } from './holdings.js';
+import type { Identity, IntentBar, OrderIntent, OrderSide, OrderType } from './intent.js';
+import type { Reduction } from './row.js';
+/**
+ * An order this run is about to send, before it is given an id.
+ *
+ * The intent's own shape less the four fields that are the same for every
+ * order this run sends, so that the mapping below cannot state one of them
+ * differently from one call to the next.
+ */
+export type Placement = Omit<OrderIntent, 'intentId' | 'instrument' | 'product' | 'bar'>;
+/** One order a call sends, and what that order takes out of the leg. */
+export interface MappedOrder {
+    readonly placement: Placement;
+    readonly reduces: Reduction | null;
+}
+/** An order that adds to a position, or whose size the engine cannot count. */
+export declare function adding(placement: Placement): MappedOrder;
+/** The fields every placement states, so each case below states only its own. */
+export declare const NOTHING: {
+    readonly side: null;
+    readonly qty: null;
+    readonly qtyType: "units";
+    readonly type: null;
+    readonly limit: null;
+    readonly trigger: null;
+    readonly target: null;
+    readonly stop: null;
+    readonly profit: null;
+    readonly loss: null;
+};
+/** What the mapping and the refusals read: the declaration, the leg and the ledger. */
+export interface PlacingContext extends Closing, Book {
+    readonly instrument: Identity;
+    readonly product: string;
+    /** The unit a quantity the script stated is counted in, `language.md` 13.3. */
+    readonly qtyType: string;
+    /** The size an order that names none takes, from the declaration. */
+    readonly declaredQty: number;
+    /** The instrument's tick size, absent where the host states none. */
+    readonly tickSize: number | null;
+    /** Entries allowed in one direction before one is refused, `language.md` 13.3. */
+    readonly pyramiding: number;
+    readonly bar: IntentBar;
+    /** The average price of the open position, absent while flat. */
+    avgPrice(): number | null;
+    /** A fresh position, for the replacement half of a flip. */
+    mint(): number;
+}
+/** What an entering order states, at one quantity and one position. */
+interface Entry {
+    readonly side: OrderSide;
+    readonly limit: number | null;
+    readonly trigger: number | null;
+    readonly type: OrderType;
+    readonly tag: string;
+}
+/**
+ * The orders an entry sends, which is two where it crosses zero.
+ *
+ * **An instruction that would take a leg from long to short is sent as two
+ * orders** (`stdlib.md` 17.1), one that closes the outgoing position and one
+ * that opens the replacement, each carrying its own position reference. The
+ * reason is not tidiness: a single order that crossed zero would leave a late
+ * fill with no way to say which of the two positions it settled, and during a
+ * flip a leg holds both at once. `sell(qty = abs(pos.size) + more)` is the
+ * spelling the documentation teaches, and it is `order.reverse` with the
+ * arithmetic written out.
+ *
+ * **The closing half is what is left to close, not what the leg holds.** An
+ * order the destination has not answered has filled nothing, so a leg with a
+ * close already going has nothing left for the outgoing half to take, whether
+ * that close was sent on this bar or on one before it.
+ *
+ * **What it crosses is decided per position, not from the leg's net.** The net
+ * is folded from settled fills, so on a silent destination it reads zero while
+ * an entry is still going and an opposing entry is not seen as opposing
+ * anything at all: `buy(qty = 6)` and then `sell(qty = 9)` a bar later put both
+ * orders on reference 1, which opened six long and settled three short. The
+ * question is about one position rather than about the leg, so it is asked of
+ * one position (`holdings.ts`), and the answer is the same whether or not the
+ * destination has answered yet.
+ *
+ * **An order that spans two positions is that many orders.** A leg holds more
+ * than one position whenever an order that opposes it is outstanding, and each
+ * of them is reduced by an order of its own, oldest first, for the same reason
+ * the flip is two orders: a late fill has to be able to say which position it
+ * settled.
+ *
+ * **The reference is minted in every unit; only the arithmetic waits.** The
+ * split subtracts a position folded from filled quantities from a quantity the
+ * script stated, and those are the same kind of number only in a declaration
+ * counting in units: in lots, cash or an equity percent the engine cannot say
+ * how much of the instruction closes and how much opens, and the lot size that
+ * would tell it is the fact OS7005 is deferred on. Minting a reference needs
+ * none of that arithmetic. So an order the engine cannot size against the leg
+ * is still sent on a position of its own rather than on the outgoing one:
+ * `buy(qty = 3)` then `sell(qty = 9)` under a declaration counting in lots took
+ * reference 1 from seventy five units to minus one hundred and fifty, which is
+ * the crossing 17.1 is unconditional about and the late fill with no owner the
+ * split exists to prevent. What does not hold, and what has to exist before it
+ * can, is written where a reader meets it: `stdlib.md` 17.1 and OS7005.
+ */
+export declare function entering(ctx: PlacingContext, entry: Entry, qty: number | null): readonly MappedOrder[];
+/**
+ * The orders a flattening call sends, which is one per position it reduces.
+ *
+ * A quantity the script stated is in the declaration's own unit and is passed
+ * through as written. A quantity the engine worked out is in units, because a
+ * filled quantity is what it was folded from.
+ *
+ * **It is divided across the positions holding it, oldest first.** A leg holds
+ * more than one position whenever an order that opposes it is outstanding, and
+ * this sized against the whole leg and attached the result to a single
+ * reference with nothing asking whether that reference could absorb it: a leg
+ * holding two positions was flattened by one order large enough to take the
+ * first of them through zero and out the other side. Each position gets an
+ * order of its own, bounded by what has settled on it and is not already
+ * working against it, which is `closable.ts`'s rule read per position.
+ *
+ * **Only what has settled on a position**, never what is working into it. A
+ * close chooses its own quantity, so a close counting an entry that has not
+ * settled would send units that may never exist. That is the one place this
+ * differs from an opposing entry, which is sent at the size the script wrote
+ * whatever the leg holds, and whose only open question is where its units land.
+ *
+ * **A quantity the engine cannot read is one order.** It cannot be divided at
+ * all, so it goes on the position it is closing, oldest first, and that
+ * position is what it may take past zero: the one shape of 17.1 an engine does
+ * not keep, named there and in OS7005 and waiting on the same lot size. Which
+ * position that is, is not the question the two numbers above answer, and
+ * `outgoingFor` is where it is asked: an order that is not choosing a quantity
+ * is not held back by a position having no quantity left to give.
+ *
+ * `part` is what the order is counted against afterwards: the tag a close
+ * named, or the leg as a whole. A stated quantity is counted only where the
+ * declaration counts in units, for the reason `Reduction` gives.
+ */
+export declare function flattening(ctx: PlacingContext, units: number, side: OrderSide, qty: number | null, tag: string, part: string | null): readonly MappedOrder[];
+export {};
+//# sourceMappingURL=sizing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sizing.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/ledger/sizing.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,KAAK,CAAC,CAAC;AAEzF,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CACpC;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW,CAExD;AAED,iFAAiF;AACjF,eAAO,MAAM,OAAO;;;;;;;;;;;CAWV,CAAC;AAEX,uFAAuF;AACvF,MAAM,WAAW,cAAe,SAAQ,OAAO,EAAE,IAAI;IACnD,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,iEAAiE;IACjE,QAAQ,IAAI,MAAM,GAAG,IAAI,CAAC;IAC1B,4DAA4D;IAC5D,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,UAAU,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,SAAS,WAAW,EAAE,CAwCxB;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GAAG,IAAI,GAClB,SAAS,WAAW,EAAE,CAsCxB"}