Limit-Order Lifecycle State Machine

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203

export type JsonObject = Record<string, any>;

function numberValue(name: string, value: unknown, options: {positive?: boolean; nonnegative?: boolean} = {}): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
  if (options.positive && value <= 0) throw new RangeError(`${name} must be positive`);
  if (options.nonnegative && value < 0) throw new RangeError(`${name} must be nonnegative`);
  return value;
}
function integerValue(name: string, value: unknown, nonnegative = false): number {
  const result = numberValue(name, value);
  if (!Number.isInteger(result)) throw new RangeError(`${name} must be an integer`);
  if (nonnegative && result < 0) throw new RangeError(`${name} must be nonnegative`);
  return result;
}
function textValue(name: string, value: unknown): string {
  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
  return value;
}

export function limitOrderLifecycle(orderIdRaw: unknown, orderQuantityRaw: unknown, eventsRaw: unknown): JsonObject {
  const orderId = textValue("order_id", orderIdRaw), orderQuantity = numberValue("order_quantity", orderQuantityRaw, {positive: true});
  if (!Array.isArray(eventsRaw) || eventsRaw.length === 0) throw new RangeError("events must be a non-empty chronological list");
  let status = "pending-new", cumulative = 0, leaves = orderQuantity, notional = 0, executionCount = 0;
  const terminal = new Set(["filled", "canceled", "rejected", "expired", "replaced"]);
  const transitions: JsonObject[] = [];
  eventsRaw.forEach((raw, index) => {
    if (!raw || typeof raw !== "object") throw new TypeError(`events[${index}] must be an object`);
    const event = raw as JsonObject, eventType = textValue(`events[${index}].type`, event.type), before = status;
    if (terminal.has(status)) throw new RangeError("terminal order state cannot accept another event");
    if (eventType === "accept") {
      if (status !== "pending-new") throw new RangeError("accept is valid only from pending-new");
      status = "new";
    } else if (eventType === "reject") {
      if (status !== "pending-new") throw new RangeError("reject is valid only from pending-new");
      status = "rejected"; leaves = 0;
    } else if (eventType === "fill") {
      if (!["new", "partially-filled"].includes(status)) throw new RangeError("fill requires a live accepted order");
      const fillQuantity = numberValue(`events[${index}].quantity`, event.quantity, {positive: true});
      const fillPrice = numberValue(`events[${index}].price`, event.price, {positive: true});
      if (fillQuantity > leaves + 1e-12) throw new RangeError("fill quantity exceeds order leaves quantity");
      cumulative += fillQuantity; leaves = Math.max(0, orderQuantity - cumulative); notional += fillQuantity * fillPrice; executionCount += 1;
      status = leaves === 0 ? "filled" : "partially-filled";
    } else if (eventType === "cancel" || eventType === "expire") {
      if (!["new", "partially-filled"].includes(status)) throw new RangeError(`${eventType} requires a live accepted order`);
      status = eventType === "cancel" ? "canceled" : "expired"; leaves = 0;
    } else if (eventType === "replace") {
      if (!["new", "partially-filled"].includes(status)) throw new RangeError("replace requires a live accepted order");
      textValue(`events[${index}].new_order_id`, event.new_order_id); status = "replaced"; leaves = 0;
    } else throw new RangeError(`unsupported lifecycle event: ${eventType}`);
    transitions.push({event_index: index, event_type: eventType, before_status: before, after_status: status, cumulative_quantity: cumulative, leaves_quantity: leaves});
  });
  return {model: "accepted-order-lifecycle-state-machine", order_id: orderId, order_quantity: orderQuantity, cumulative_quantity: cumulative, leaves_quantity: leaves, average_fill_price: cumulative ? notional / cumulative : null, execution_count: executionCount, status, terminal: terminal.has(status), transitions, state: status};
}

export function cancelReplacePriority(originalRaw: unknown, replacementRaw: unknown): JsonObject {
  if (!originalRaw || typeof originalRaw !== "object" || !replacementRaw || typeof replacementRaw !== "object") throw new TypeError("original and replacement must be objects");
  const original = originalRaw as JsonObject, replacement = replacementRaw as JsonObject;
  const orderType = textValue("original.order_type", original.order_type);
  if (orderType !== "displayed-limit") throw new RangeError("canonical priority rule supports displayed-limit orders only");
  const originalId = textValue("original.order_id", original.order_id), replacementId = textValue("replacement.order_id", replacement.order_id);
  const originalPrice = numberValue("original.price", original.price, {positive: true}), replacementPrice = numberValue("replacement.price", replacement.price, {positive: true});
  const originalQuantity = numberValue("original.remaining_quantity", original.remaining_quantity, {positive: true}), replacementQuantity = numberValue("replacement.remaining_quantity", replacement.remaining_quantity, {positive: true});
  const originalSequence = integerValue("original.priority_sequence", original.priority_sequence, true), replaceSequence = integerValue("replacement.replace_sequence", replacement.replace_sequence, true);
  if (replaceSequence <= originalSequence) throw new RangeError("replace_sequence must be after original priority_sequence");
  const samePrice = Math.abs(originalPrice - replacementPrice) <= 1e-12, decreaseOnly = replacementQuantity <= originalQuantity, preserved = samePrice && decreaseOnly;
  const reason = preserved ? "same-price quantity decrease preserves canonical displayed-order priority" : !samePrice ? "price modification creates a new priority timestamp" : "quantity increase creates a new priority timestamp";
  return {model: "nasdaq-style-displayed-limit-priority-rule", original_order_id: originalId, replacement_order_id: replacementId, original_price: originalPrice, replacement_price: replacementPrice, original_remaining_quantity: originalQuantity, replacement_remaining_quantity: replacementQuantity, same_price: samePrice, decrease_only: decreaseOnly, priority_preserved: preserved, original_priority_sequence: originalSequence, effective_priority_sequence: preserved ? originalSequence : replaceSequence, reason, state: preserved ? "priority-preserved" : "new-priority"};
}

export function partialFillResidual(orderQuantityRaw: unknown, fillsRaw: unknown): JsonObject {
  const orderQuantity = numberValue("order_quantity", orderQuantityRaw, {positive: true});
  if (!Array.isArray(fillsRaw)) throw new TypeError("fills must be a list");
  let cumulative = 0, notional = 0;
  const seen = new Set<string>(), states: JsonObject[] = [];
  fillsRaw.forEach((raw, index) => {
    if (!raw || typeof raw !== "object") throw new TypeError(`fills[${index}] must be an object`);
    const fill = raw as JsonObject, executionId = textValue(`fills[${index}].execution_id`, fill.execution_id);
    if (seen.has(executionId)) throw new RangeError("execution_id values must be unique"); seen.add(executionId);
    const fillQuantity = numberValue(`fills[${index}].quantity`, fill.quantity, {positive: true}), fillPrice = numberValue(`fills[${index}].price`, fill.price, {positive: true});
    if (cumulative + fillQuantity > orderQuantity + 1e-12) throw new RangeError("fills exceed original order quantity");
    cumulative += fillQuantity; notional += fillQuantity * fillPrice;
    const leaves = Math.max(0, orderQuantity - cumulative);
    states.push({execution_id: executionId, last_quantity: fillQuantity, last_price: fillPrice, cumulative_quantity: cumulative, leaves_quantity: leaves, status: leaves === 0 ? "filled" : "partially-filled"});
  });
  const leaves = orderQuantity - cumulative, status = fillsRaw.length === 0 ? "new" : leaves === 0 ? "filled" : "partially-filled";
  return {model: "partial-fill-residual-accounting", order_quantity: orderQuantity, cumulative_quantity: cumulative, leaves_quantity: leaves, fill_notional: notional, average_fill_price: cumulative ? notional / cumulative : null, execution_count: fillsRaw.length, fill_states: states, status, state: status};
}

export function queuePositionAheadVolume(ordersRaw: unknown, targetIdRaw: unknown): JsonObject {
  if (!Array.isArray(ordersRaw) || ordersRaw.length === 0) throw new RangeError("orders must be a non-empty list");
  const targetId = textValue("target_order_id", targetIdRaw), ids = new Set<string>(), sequences = new Set<number>();
  const parsed = ordersRaw.map((raw, index) => {
    if (!raw || typeof raw !== "object") throw new TypeError(`orders[${index}] must be an object`);
    const order = raw as JsonObject, orderId = textValue(`orders[${index}].order_id`, order.order_id);
    if (ids.has(orderId)) throw new RangeError("order_id values must be unique"); ids.add(orderId);
    const sequence = integerValue(`orders[${index}].arrival_sequence`, order.arrival_sequence, true);
    if (sequences.has(sequence)) throw new RangeError("arrival_sequence values must be unique"); sequences.add(sequence);
    const side = textValue(`orders[${index}].side`, order.side);
    if (!["buy", "sell"].includes(side)) throw new RangeError("order side must be buy or sell");
    if (typeof order.displayed !== "boolean") throw new TypeError("displayed must be boolean");
    return {order_id: orderId, side, price: numberValue(`orders[${index}].price`, order.price, {positive: true}), remaining_quantity: numberValue(`orders[${index}].remaining_quantity`, order.remaining_quantity, {positive: true}), arrival_sequence: sequence, displayed: order.displayed};
  });
  const target = parsed.find(order => order.order_id === targetId);
  if (!target) throw new RangeError("target order is not present");
  if (!target.displayed) throw new RangeError("canonical queue position requires a displayed target");
  const samePrice = parsed.filter(order => order.side === target.side && Math.abs(order.price - target.price) <= 1e-12);
  const displayed = samePrice.filter(order => order.displayed).sort((a, b) => a.arrival_sequence - b.arrival_sequence);
  const ahead = displayed.filter(order => order.arrival_sequence < target.arrival_sequence), behind = displayed.filter(order => order.arrival_sequence > target.arrival_sequence);
  const aheadVolume = ahead.reduce((sum, order) => sum + order.remaining_quantity, 0);
  return {model: "displayed-price-time-fifo-ahead-volume", target_order_id: targetId, side: target.side, price: target.price, ahead_order_count: ahead.length, ahead_volume: aheadVolume, displayed_queue_rank: ahead.length + 1, behind_order_count: behind.length, behind_volume: behind.reduce((sum, order) => sum + order.remaining_quantity, 0), hidden_same_price_quantity_excluded: samePrice.filter(order => !order.displayed).reduce((sum, order) => sum + order.remaining_quantity, 0), ahead_order_ids: ahead.map(order => order.order_id), state: ahead.length ? "queued-behind-displayed-volume" : "front-of-displayed-queue"};
}

export function icebergReplenishment(totalRaw: unknown, initialRaw: unknown, displaySizeRaw: unknown, fillsRaw: unknown, priorityRaw: unknown): JsonObject {
  const total = numberValue("total_quantity", totalRaw, {positive: true});
  let displayed = numberValue("initial_display_quantity", initialRaw, {positive: true});
  const tranche = numberValue("display_size", displaySizeRaw, {positive: true});
  let priority = integerValue("starting_priority_sequence", priorityRaw, true);
  if (displayed > total) throw new RangeError("initial displayed quantity cannot exceed total quantity");
  if (!Array.isArray(fillsRaw)) throw new TypeError("fills must be a list");
  let reserve = total - displayed, executed = 0, unfilledRequested = 0, replenishments = 0;
  const events: JsonObject[] = [];
  const replenish = () => {
    if (displayed !== 0 || reserve <= 0) return;
    const amount = Math.min(tranche, reserve); reserve -= amount; displayed = amount; priority += 1; replenishments += 1;
    events.push({type: "replenish", quantity: amount, new_priority_sequence: priority, displayed_remaining: displayed, reserve_remaining: reserve});
  };
  fillsRaw.forEach((rawFill, index) => {
    let remainingRequest = numberValue(`fills[${index}]`, rawFill, {positive: true});
    while (remainingRequest > 1e-12) {
      replenish();
      if (displayed <= 0) { unfilledRequested += remainingRequest; break; }
      const amount = Math.min(displayed, remainingRequest);
      displayed -= amount; remainingRequest -= amount; executed += amount;
      events.push({type: "fill", fill_request_index: index, quantity: amount, displayed_remaining: displayed, reserve_remaining: reserve, priority_sequence: priority});
    }
    replenish();
  });
  const remainingTotal = displayed + reserve;
  return {model: "zero-displayed-tranche-replenishment", total_quantity: total, display_size: tranche, executed_quantity: executed, displayed_remaining: displayed, reserve_remaining: reserve, total_remaining: remainingTotal, replenishment_count: replenishments, current_priority_sequence: priority, unfilled_requested_quantity: unfilledRequested, events, state: remainingTotal === 0 ? "filled" : reserve > 0 ? "active-reserve" : "displayed-only"};
}

export function marketableOrderSweep(incomingRaw: unknown, restingRaw: unknown): JsonObject {
  if (!incomingRaw || typeof incomingRaw !== "object" || !Array.isArray(restingRaw)) throw new TypeError("incoming_order must be an object and resting_orders a list");
  const incoming = incomingRaw as JsonObject, incomingId = textValue("incoming_order.order_id", incoming.order_id), side = textValue("incoming_order.side", incoming.side);
  if (!["buy", "sell"].includes(side)) throw new RangeError("incoming side must be buy or sell");
  const orderType = textValue("incoming_order.order_type", incoming.order_type);
  if (!["market", "limit"].includes(orderType)) throw new RangeError("order_type must be market or limit");
  const tif = textValue("incoming_order.time_in_force", incoming.time_in_force);
  if (!["GTC", "IOC"].includes(tif)) throw new RangeError("time_in_force must be GTC or IOC");
  const quantity = numberValue("incoming_order.quantity", incoming.quantity, {positive: true});
  let limit: number | null = null;
  if (orderType === "limit") limit = numberValue("incoming_order.limit_price", incoming.limit_price, {positive: true});
  else if (incoming.limit_price != null) throw new RangeError("market order must not specify limit_price");
  const arrivalSequence = integerValue("incoming_order.arrival_sequence", incoming.arrival_sequence, true), ids = new Set([incomingId]), sequences = new Set<number>();
  const parsed = restingRaw.map((raw, index) => {
    if (!raw || typeof raw !== "object") throw new TypeError(`resting_orders[${index}] must be an object`);
    const order = raw as JsonObject, orderId = textValue(`resting_orders[${index}].order_id`, order.order_id);
    if (ids.has(orderId)) throw new RangeError("order_id values must be unique"); ids.add(orderId);
    const restingSide = textValue(`resting_orders[${index}].side`, order.side);
    if (!["buy", "sell"].includes(restingSide)) throw new RangeError("resting side must be buy or sell");
    const sequence = integerValue(`resting_orders[${index}].priority_sequence`, order.priority_sequence, true);
    if (sequences.has(sequence)) throw new RangeError("priority_sequence values must be unique"); sequences.add(sequence);
    return {order_id: orderId, side: restingSide, price: numberValue(`resting_orders[${index}].price`, order.price, {positive: true}), remaining_quantity: numberValue(`resting_orders[${index}].remaining_quantity`, order.remaining_quantity, {positive: true}), priority_sequence: sequence};
  });
  const opposite = side === "buy" ? "sell" : "buy";
  const candidates = parsed.filter(order => order.side === opposite).sort((a, b) => side === "buy" ? a.price - b.price || a.priority_sequence - b.priority_sequence : b.price - a.price || a.priority_sequence - b.priority_sequence);
  let remaining = quantity, notional = 0;
  const fills: JsonObject[] = [];
  for (const resting of candidates) {
    const marketable = limit == null || (side === "buy" ? resting.price <= limit : resting.price >= limit);
    if (!marketable) break;
    const amount = Math.min(remaining, resting.remaining_quantity);
    if (amount <= 0) continue;
    resting.remaining_quantity -= amount; remaining -= amount; notional += amount * resting.price;
    fills.push({resting_order_id: resting.order_id, price: resting.price, quantity: amount, resting_remaining_quantity: resting.remaining_quantity});
    if (remaining <= 1e-12) { remaining = 0; break; }
  }
  const filled = quantity - remaining;
  let residualAction = "none";
  if (remaining > 0) {
    if (orderType === "limit" && tif === "GTC") {
      parsed.push({order_id: incomingId, side, price: limit as number, remaining_quantity: remaining, priority_sequence: arrivalSequence}); residualAction = "posted";
    } else residualAction = "canceled";
  }
  const finalBook = parsed.filter(order => order.remaining_quantity > 0).sort((a, b) => {
    if (a.side !== b.side) return a.side === "buy" ? -1 : 1;
    return a.side === "buy" ? b.price - a.price || a.priority_sequence - b.priority_sequence : a.price - b.price || a.priority_sequence - b.priority_sequence;
  });
  const status = remaining === 0 ? "filled" : filled > 0 && residualAction === "posted" ? "partially-filled-and-posted" : filled > 0 ? "partially-filled-and-canceled" : residualAction === "posted" ? "posted" : "unfilled-and-canceled";
  return {model: "single-venue-price-time-marketable-sweep", incoming_order_id: incomingId, incoming_side: side, requested_quantity: quantity, filled_quantity: filled, residual_quantity: remaining, fill_notional: notional, average_fill_price: filled ? notional / filled : null, fills, residual_action: residualAction, final_book: finalBook, status, state: status};
}

export function calculate(topicId: string, inputs: JsonObject): JsonObject {
  if (!inputs || typeof inputs !== "object" || Array.isArray(inputs)) throw new TypeError("inputs must be an object");
  if (topicId === "D12-F04-A01") return limitOrderLifecycle(inputs.order_id, inputs.order_quantity, inputs.events);
  if (topicId === "D12-F04-A02") return cancelReplacePriority(inputs.original, inputs.replacement);
  if (topicId === "D12-F04-A03") return partialFillResidual(inputs.order_quantity, inputs.fills);
  if (topicId === "D12-F04-A04") return queuePositionAheadVolume(inputs.orders, inputs.target_order_id);
  if (topicId === "D12-F04-A05") return icebergReplenishment(inputs.total_quantity, inputs.initial_display_quantity, inputs.display_size, inputs.fills, inputs.starting_priority_sequence);
  if (topicId === "D12-F04-A06") return marketableOrderSweep(inputs.incoming_order, inputs.resting_orders);
  throw new RangeError(`unsupported topic_id: ${topicId}`);
}