openalgo-script 0.1.0-alpha.1 → 0.4.0

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

@@ -0,0 +1,318 @@
+/**
+ * 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';
+
+const STATUSES: readonly OrderStatus[] = [
+  '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: ReadonlySet<OrderStatus> = new Set<OrderStatus>([
+  '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: OrderStatus): number {
+  if (status === 'placed') return 0;
+  return TERMINAL.has(status) ? 2 : 1;
+}
+
+export function isTerminal(status: OrderStatus): boolean {
+  return TERMINAL.has(status);
+}
+
+/** The word a host sent, or nothing when it is not one of the seven. */
+export function statusFrom(word: string): OrderStatus | undefined {
+  return STATUSES.find((one) => one === word);
+}
+
+/** 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 function workingUnits(row: LedgerRow): number {
+  const reduces = row.reduces;
+  if (reduces === null || isTerminal(row.status)) return 0;
+  return reduces.counted ? Math.max(0, reduces.claimed - row.filledQty) : reduces.claimed;
+}
+
+/** 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;
+}
+
+function refuse(frame: OrderFrame, why: FrameRefusal): FrameOutcome {
+  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: LedgerRow, frame: OrderFrame): FrameOutcome {
+  // 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,
+  };
+}

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

@@ -0,0 +1,292 @@
+/**
+ * How much each order of a call sends, and which position it is sent against,
+ * `stdlib.md` 17.1.
+ *
+ * **This is the half of a call that is arithmetic.** `place.ts` says what each
+ * call means and dispatches to the two functions here; these two decide how many
+ * orders the call becomes, how large each is, and which position reference each
+ * one carries. They were one file with the dispatch until the second question
+ * arrived: issue 0018 is about attachment rather than about quantity, and the
+ * two answers are long enough written down that keeping them beside the
+ * vocabulary of the calls made one file out of two subjects.
+ *
+ * The two entry points are `entering`, for a call that states a side and a size,
+ * and `flattening`, for one that reduces what the leg holds. What they differ
+ * about is not the split but the budget, and the difference is the whole of
+ * `holdings.ts`: an entry sends the size the script wrote whatever the leg holds,
+ * so the only question is where its units land; a close chooses its own number,
+ * so it may only choose one that has settled.
+ */
+import { closableUnits } from './closable.js';
+import type { Closing } from './closable.js';
+import { divide, holdings, joining, opposing, outgoingFor } from './holdings.js';
+import type { Book, Holding } 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 function adding(placement: Placement): MappedOrder {
+  return { placement, reduces: null };
+}
+
+/** The fields every placement states, so each case below states only its own. */
+export const NOTHING = {
+  side: null,
+  qty: null,
+  qtyType: 'units',
+  type: null,
+  limit: null,
+  trigger: null,
+  target: null,
+  stop: null,
+  profit: null,
+  loss: null,
+} as const;
+
+/** 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;
+}
+
+/** One order of an entry, at the quantity and the position it is given. */
+function placing(entry: Entry, qty: number, qtyType: string, positionRef: number): Placement {
+  return {
+    ...NOTHING,
+    kind: 'place',
+    side: entry.side,
+    qty,
+    qtyType,
+    type: entry.type,
+    limit: entry.limit,
+    trigger: entry.trigger,
+    tag: entry.tag,
+    positionRef,
+  };
+}
+
+/**
+ * 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 function entering(
+  ctx: PlacingContext,
+  entry: Entry,
+  qty: number | null,
+): readonly MappedOrder[] {
+  // The declaration's own size where the call named none, `stdlib.md` 17.2.
+  const wanted = qty ?? ctx.declaredQty;
+  const book = holdings(ctx);
+  // Nothing to cross: the leg holds no position this order opposes, so it opens
+  // one or joins the one it is on the side of.
+  if (opposing(book, entry.side).length === 0) {
+    return [adding(placing(entry, wanted, ctx.qtyType, openingOn(ctx, book, entry.side)))];
+  }
+
+  if (ctx.qtyType !== 'units') {
+    return [
+      {
+        // A position of its own, in every unit, because minting one needs no
+        // lot size. On the outgoing reference this order was the crossing
+        // 17.1 refuses outright: one order taking one position from one sign
+        // to the other, with a late fill on the entry it replaced settling
+        // against a book that had already gone the other way.
+        placement: placing(entry, wanted, ctx.qtyType, ctx.mint()),
+        // Unreadable in units, so it is taken to have reduced the whole of what
+        // was left: see `closable.ts` on why that is the only safe reading.
+        reduces: { part: null, claimed: closableUnits(ctx, null), counted: false },
+      },
+    ];
+  }
+
+  // What each position it opposes can absorb, oldest first. A position holding
+  // six is sent six of the nine, whether those six have settled or are still
+  // going, because six of this order is what brings that position back to zero.
+  const split = divide(book, entry.side, wanted, (one) => one.units);
+  const out: MappedOrder[] = split.shares.map((share) => ({
+    placement: placing(entry, share.units, 'units', share.ref),
+    reduces: { part: null, claimed: share.units, counted: true },
+  }));
+  if (split.left === 0) return out;
+  // The replacement is a position of its own where the leg holds none on this
+  // side, so that a fill on an outgoing order settles the position it
+  // belonged to.
+  out.push(adding(placing(entry, split.left, 'units', openingOn(ctx, book, entry.side))));
+  return out;
+}
+
+/** The reference an order that opens or adds to a position carries. */
+function openingOn(ctx: PlacingContext, book: readonly Holding[], side: OrderSide): number {
+  return joining(book, side) ?? ctx.mint();
+}
+
+/** One order of a flattening call, at the quantity and position it is given. */
+function reducing(
+  side: OrderSide,
+  qty: number,
+  qtyType: string,
+  tag: string,
+  positionRef: number,
+): Placement {
+  return { ...NOTHING, kind: 'place', side, qty, qtyType, type: 'market', tag, positionRef };
+}
+
+/**
+ * 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 function flattening(
+  ctx: PlacingContext,
+  units: number,
+  side: OrderSide,
+  qty: number | null,
+  tag: string,
+  part: string | null,
+): readonly MappedOrder[] {
+  // Nothing to flatten and no size named: an instruction about a position the
+  // strategy does not hold, which is not an error and is not an order either.
+  if (units <= 0 && qty === null) return [];
+  const sending = qty ?? units;
+  // A quantity the engine worked out is counted as itself. One the script
+  // stated in a unit the engine cannot read is counted as the whole of what was
+  // left, which is what keeps a close after it from sending the position again.
+  const counted = qty === null || ctx.qtyType === 'units';
+  const book = holdings(ctx);
+  if (!counted) {
+    // The position it is closing, which is the oldest one holding the side this
+    // order reduces (`holdings.ts`). **Where the leg holds no such position the
+    // call sends nothing**, which is the same answer the division below gives
+    // for the same reason: a close is never minted a position of its own
+    // (`stdlib.md` 17.1), and an order sent against a position on its own side
+    // would be a close adding to one. A part can read as holding something
+    // while no reference does, because a part is netted over the rows carrying
+    // one tag and a reference is not.
+    const outgoing = outgoingFor(ctx, book, side);
+    if (outgoing === null) return [];
+    return [
+      {
+        placement: reducing(side, sending, ctx.qtyType, tag, outgoing),
+        reduces: { part, claimed: units, counted: false },
+      },
+    ];
+  }
+  // Anything left when every position it reduces is full is left unsent rather
+  // than pushed onto one of them past its own size. A close states no quantity
+  // of its own, so the next one measures what is left and sends it, which is
+  // 17.2's idempotence and not a silence. By construction there is nothing
+  // left: what a close may send is the leg's settled net less what is working
+  // against it, and that is never more than the positions on that side hold.
+  return divide(book, side, sending, (one) => one.settled).shares.map((share) => ({
+    placement: reducing(side, share.units, 'units', tag, share.ref),
+    reduces: { part, claimed: share.units, counted: true },
+  }));
+}