openalgo-script 0.1.0-alpha.0 → 0.2.0

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

@@ -0,0 +1,277 @@
+/**
+ * One order call becomes one or more intents, `stdlib.md` 17.2 and 17.3.
+ *
+ * **This file says what a call means; `sizing.ts` says how much it sends and
+ * against which position.** The two were one file until the second question
+ * arrived: how many orders a call becomes, how large each of them is and which
+ * position reference each one carries is arithmetic over what the leg holds, and
+ * it is long enough written down to crowd out the vocabulary of the calls. The
+ * sentences below about the split are still this file's, because they are why
+ * the calls mean what they mean.
+ *
+ * **Every order states its own side and its own quantity outright.** Nothing
+ * here computes a delta against an account position, for the reason 17.1 gives:
+ * an account position is held per contract, so a second strategy, a manual
+ * trade or this same script started twice all land in that one row, and an
+ * order sized against it is sized against somebody else's trade.
+ *
+ * What a flattening order does compute against is the strategy's **own**
+ * position, folded from its own settled fills, which is a different number with
+ * a different owner.
+ *
+ * **No order crosses zero.** An instruction that would take a leg from long to
+ * short is two orders, one closing the outgoing position and one opening the
+ * replacement, each carrying its own position reference, so that a fill
+ * arriving late can still say which of the two it settled. That is the split
+ * `entering` makes, and `order.reverse` is the same pair written as one call.
+ *
+ * **A reducing order is sized against what is available to reduce**, which is
+ * the settled position less everything already working against it. A position
+ * is folded from settled fills and from nothing else (`stdlib.md` 17.8), so an
+ * order the destination has not answered has filled nothing and has moved no
+ * position figure: measured against the leg alone, a second close sends the
+ * whole of it again, on the same bar and on every bar after it, and the leg
+ * ends short with no quantity written anywhere. `closableUnits` answers it and
+ * the ledger's own rows are where it is read from.
+ *
+ * **A bracket is an instruction, not an order.** `exit` and `order.bracket` set
+ * the leg's own protective level, which is what `stdlib.md` 17.2 means when it
+ * says a leg carries at most one stop and at most one target at a time. The tag
+ * they take defaults to the empty string and rides along as a label, for the
+ * destination and the report. It is not a reference to an order that has to
+ * exist, so a bracket naming a tag nothing was ever placed with is an ordinary
+ * call and is not refused: the level it sets belongs to the leg either way, and
+ * `refuse.ts` measures it from the leg's own average entry price. They send an
+ * intent so that a host has something to act on, and they append no ledger row
+ * and move no position, because nothing has been ordered until the level is
+ * reached.
+ *
+ * **A tag on a call that flattens is the other kind.** `close`'s tag defaults to
+ * absence rather than to the empty string, and it names the part of the position
+ * that tag entered, which is a reference to rows this ledger holds. A tag no
+ * order in the file can place is OS7016, at the call, before any bar runs.
+ *
+ * **Nothing here refuses anything.** This file says what a call means; `refuse.ts`
+ * says what the language will not do, and the ledger asks it first. The two were
+ * one file once, and what that produced was a call whose quantity did not make
+ * sense returning an empty list: no order, no refusal, and a script that had
+ * been told nothing.
+ */
+import type { OrderCall } from './call.js';
+import { closableUnits, closingFor, closingSide } from './closable.js';
+import type { OrderIntent, OrderType } from './intent.js';
+import { protecting } from './holdings.js';
+import { isTerminal } from './row.js';
+import { NOTHING, adding, entering, flattening } from './sizing.js';
+import type { MappedOrder, Placement, PlacingContext } from './sizing.js';
+
+export type { MappedOrder, Placement, PlacingContext } from './sizing.js';
+
+/**
+ * The type the prices imply.
+ *
+ * Stated on the intent rather than left to the host, so a destination never has
+ * to infer it: with neither price a market order, with a limit alone a limit
+ * order, with a trigger alone a stop order, and with both a stop limit order
+ * (`stdlib.md` 17.2).
+ */
+function typeOf(limit: number | null, trigger: number | null): OrderType {
+  if (limit !== null && trigger !== null) return 'stopLimit';
+  if (limit !== null) return 'limit';
+  if (trigger !== null) return 'stop';
+  return 'market';
+}
+
+/**
+ * A cancellation names the tag it cancels and nothing else.
+ *
+ * No side, no quantity and no price: it is not an order, and what becomes of
+ * the order it names arrives as a frame about that order.
+ */
+function cancelling(tag: string): Placement {
+  return { ...NOTHING, kind: 'cancel', tag, positionRef: 0 };
+}
+
+/** A protective level attached to a tag, `stdlib.md` 17.2 and 17.3. */
+function bracketing(
+  ctx: PlacingContext,
+  tag: string,
+  qty: number | null,
+  target: number | null,
+  stop: number | null,
+  profit: number | null,
+  loss: number | null,
+): readonly MappedOrder[] {
+  // A call that names no level at all removes one, which is a standing level of
+  // `stdlib.md` 17.9 and is planned. There is nothing to send.
+  if (target === null && stop === null && profit === null && loss === null) return [];
+  // Nothing has been ordered by a bracket, so it takes nothing out of the
+  // position: the level it sets belongs to the leg until it is reached.
+  return [
+    adding({
+      ...NOTHING,
+      kind: 'bracket',
+      qty,
+      qtyType: qty === null ? 'units' : ctx.qtyType,
+      target,
+      stop,
+      profit,
+      loss,
+      tag,
+      // The position the level protects, and zero where the leg holds none,
+      // which is the value a cancellation already carries for the same reason:
+      // neither is an order and neither has a position of its own. Minting one
+      // here burned a reference on an instruction that moves nothing, so a
+      // script whose first call is `exit()` opened on reference 2 and the
+      // bracket named a reference no order ever carried
+      // (`host-interface.md` 7.1).
+      //
+      // **Asked of the book, because what the leg holds is not what was minted
+      // last.** The reference minted last is cleared when that one reference
+      // returns to zero, so a leg still holding an older position reported none
+      // and a bracket went out carrying `0`, which is the one value 7.1 tells a
+      // host means there is nothing to look up (`holdings.ts`, `protecting`).
+      positionRef: protecting(ctx) ?? 0,
+    }),
+  ];
+}
+
+/**
+ * The orders one call sends, in the order it sends them.
+ *
+ * A call that has nothing to send sends nothing: flattening a leg that holds
+ * nothing and reversing a position that does not exist are both instructions
+ * about a position the strategy does not hold, and inventing a side for either
+ * would be the engine deciding a direction the script never stated.
+ */
+export function ordersFor(call: OrderCall, ctx: PlacingContext): readonly MappedOrder[] {
+  const side = call.side;
+
+  switch (call.name) {
+    case 'buy':
+    case 'sell':
+      if (side === null) return [];
+      return entering(
+        ctx,
+        {
+          side,
+          limit: call.limit,
+          trigger: call.trigger,
+          type: typeOf(call.limit, call.trigger),
+          tag: call.tag ?? '',
+        },
+        call.qty,
+      );
+
+    case 'order.place': {
+      // A side that is not one of the two is not a direction, and a buy is not
+      // the safe guess: the checker refuses a written value outside the set
+      // with OS3008, and a computed one that reaches here sends nothing rather
+      // than sending the opposite of what the script meant. A side the script
+      // stated as absent never reaches here at all: that is OS7002.
+      if (side === null) return [];
+      return entering(
+        ctx,
+        {
+          side,
+          limit: call.limit,
+          trigger: call.trigger,
+          // A type outside the set falls back to the one the prices imply,
+          // which is the correspondence `stdlib.md` 17.2 fixes between the two.
+          type: call.type ?? typeOf(call.limit, call.trigger),
+          tag: call.tag ?? '',
+        },
+        call.qty,
+      );
+    }
+
+    case 'close': {
+      // **The side comes from the part the call names**, which is the leg only
+      // where it names no tag. Taken from the leg's net, a close of a part
+      // holding four short on a leg netting six long was a sell of four: the
+      // part went to eight short, the other tag's long was cut to six, and a
+      // call named close had opened position (`closable.ts`, `stdlib.md` 17.2).
+      const closing = closingFor(ctx, call.tag);
+      if (closing === undefined) return [];
+      // A tag names the part of the position that tag entered, which is the
+      // settled quantity of its own rows, less what is already working against
+      // it. A quantity the script stated has already been held against this
+      // same number by `refuse.ts`, so nothing reaching here crosses zero.
+      return flattening(
+        ctx,
+        closableUnits(ctx, call.tag),
+        closing,
+        call.qty,
+        call.tag ?? '',
+        call.tag,
+      );
+    }
+
+    case 'order.reverse': {
+      const size = ctx.size();
+      const closing = closingSide(size);
+      if (closing === undefined) return [];
+      const tag = call.tag ?? '';
+      // What is left to close rather than the whole leg, so that a reverse
+      // after a close on the same bar does not send the position twice.
+      const out = flattening(ctx, closableUnits(ctx, null), closing, null, tag, null);
+      // The replacement is a position of its own, minted here, so that a fill
+      // on the outgoing order settles the position it belonged to.
+      const ref = ctx.mint();
+      const opening: Placement = {
+        ...NOTHING,
+        kind: 'place',
+        side: closing,
+        qty: call.qty ?? Math.abs(size),
+        qtyType: call.qty === null ? 'units' : ctx.qtyType,
+        type: 'market',
+        tag,
+        positionRef: ref,
+      };
+      return [...out, adding(opening)];
+    }
+
+    case 'exit':
+      return bracketing(
+        ctx,
+        call.tag ?? '',
+        call.qty,
+        call.target,
+        call.stop,
+        call.profit,
+        call.loss,
+      );
+
+    case 'order.bracket':
+      return bracketing(ctx, call.tag ?? '', null, null, null, call.profit, call.loss);
+
+    case 'cancel':
+      return [adding(cancelling(call.tag ?? ''))];
+
+    case 'cancelAll': {
+      const tags: string[] = [];
+      for (const row of ctx.rows()) {
+        if (!isTerminal(row.status) && !tags.includes(row.tag)) tags.push(row.tag);
+      }
+      return tags.map((tag) => adding(cancelling(tag)));
+    }
+
+    default:
+      return [];
+  }
+}
+
+/** The intent one placement becomes, `host-interface.md` 7.1. */
+export function intentFor(
+  placement: Placement,
+  intentId: number,
+  ctx: PlacingContext,
+): OrderIntent {
+  return {
+    ...placement,
+    intentId,
+    instrument: ctx.instrument,
+    product: ctx.product,
+    bar: ctx.bar,
+  };
+}

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

@@ -0,0 +1,123 @@
+/**
+ * The positions a leg holds, folded from settled fills and from nothing else,
+ * `stdlib.md` 17.1 and 17.7.
+ *
+ * **A fill settles the position its own order names, never whichever position
+ * the leg holds now.** That is what the position reference is for: during a
+ * flip a leg holds two positions at once, the outgoing one and its replacement,
+ * and a fill that arrives late would otherwise be applied to the position that
+ * replaced the one it belonged to.
+ *
+ * **Reducing a position does not move its average price.** The units that leave
+ * leave at the price the position was opened at, so what remains is still the
+ * average of what was bought. An engine that took the closing fill's price into
+ * the average would report an entry at a price nothing was entered at, and
+ * every level measured from the entry would be measured from that.
+ *
+ * Nothing here is money. Realised profit, equity and the trade list are
+ * `stdlib.md` 17.4's planned entries, and this holds the two facts the five
+ * position calls of this release read: how much is held, and at what average.
+ */
+
+interface Held {
+  /** Signed: positive long, negative short. */
+  size: number;
+  /** Signed cost of the open position, so cost over size is its average. */
+  cost: number;
+}
+
+export class Positions {
+  private readonly held = new Map<number, Held>();
+  private next = 1;
+
+  /**
+   * The settled size of one position reference, signed the way a position is.
+   *
+   * **Per reference rather than per leg**, because which position an order is
+   * sent against is a question about one position and the leg's net cannot
+   * answer it: a leg holds more than one position whenever an order that
+   * opposes it is outstanding, and two that net to zero are not the same thing
+   * as no position at all. `holdings.ts` reads this beside the ledger's own
+   * rows, which is the division the rest of the engine already keeps: what
+   * settled is the position book's, what is working is the ledger's.
+   *
+   * Zero for a reference this book has never been given a fill for, which is
+   * both a reference minted for an order that has not settled and one that is
+   * not a reference at all.
+   */
+  sizeOf(ref: number): number {
+    return this.held.get(ref)?.size ?? 0;
+  }
+
+  /** A fresh position, for the replacement half of a flip. */
+  mint(): number {
+    const ref = this.next;
+    this.next += 1;
+    this.held.set(ref, { size: 0, cost: 0 });
+    return ref;
+  }
+
+  /** Step 6 of the fold: `units` at `price` settle against one position. */
+  settle(ref: number, units: number, price: number): void {
+    const position = this.held.get(ref) ?? { size: 0, cost: 0 };
+    this.held.set(ref, position);
+    const before = position.size;
+
+    if (before === 0 || Math.sign(units) === Math.sign(before)) {
+      position.size = before + units;
+      position.cost += units * price;
+    } else {
+      const average = position.cost / before;
+      const after = before + units;
+      position.size = after;
+      // A destination that filled more than the order asked takes the leg
+      // through zero. The remainder is a position in the other direction and it
+      // opened at this fill's price, which is the truthful reading of what the
+      // account now holds. Dropping it would leave the strategy blind to a
+      // position it is carrying.
+      const held = Math.sign(after) === Math.sign(before) ? average : price;
+      position.cost = after === 0 ? 0 : after * held;
+    }
+  }
+
+  /** The leg's net position in units, `0` while flat. */
+  size(): number {
+    let total = 0;
+    for (const position of this.held.values()) total += position.size;
+    return total;
+  }
+
+  /**
+   * The average price of what the leg holds, absent while flat.
+   *
+   * Absent rather than zero, because zero is a price and a script comparing
+   * against it would take a branch that looks correct (`stdlib.md` 17.4).
+   *
+   * **Averaged over the positions that make up what the leg holds**, which is
+   * the ones on the side of its net, and not over every position open at once.
+   * A leg holds more than one whenever an order that opposes it is outstanding:
+   * during a flip it holds the outgoing position and its replacement, and where
+   * the engine could not size the opposing order against the leg it holds the
+   * position that order opened beside the one it was meant to replace. Summed
+   * across both, the cost of a position on the way out is subtracted from the
+   * cost of the one on the way in, and the quotient is a price nothing was
+   * entered at: three hundred bought at one hundred with two hundred and
+   * twenty five sold at one hundred and ten reported an entry at seventy, and
+   * every level a script measures from the entry would have been measured from
+   * it. Reducing a position does not move its average, and that is the same
+   * sentence read across a leg rather than inside one position.
+   */
+  avgPrice(): number | null {
+    const net = this.size();
+    if (net === 0) return null;
+    const side = Math.sign(net);
+    let size = 0;
+    let cost = 0;
+    for (const position of this.held.values()) {
+      if (Math.sign(position.size) !== side) continue;
+      size += position.size;
+      cost += position.cost;
+    }
+    return size === 0 ? null : cost / size;
+  }
+}