Implementation-Shortfall Execution

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
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238

/** Deterministic reference algorithms for D13-F02 Cost/Risk Optimization. */

export type JsonObject = Record<string, unknown>;

function integer(name: string, value: unknown, options: { positive?: boolean; nonnegative?: boolean } = {}): number {
  if (typeof value !== "number" || !Number.isInteger(value)) throw new Error(`${name} must be an integer`);
  if (options.positive && value <= 0) throw new Error(`${name} must be positive`);
  if (options.nonnegative && value < 0) throw new Error(`${name} must be nonnegative`);
  return value;
}

function finiteNumber(name: string, value: unknown, options: { positive?: boolean; nonnegative?: boolean } = {}): number {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${name} must be a finite number`);
  if (options.positive && value <= 0) throw new Error(`${name} must be positive`);
  if (options.nonnegative && value < 0) throw new Error(`${name} must be nonnegative`);
  return value;
}

function sideValue(value: unknown): "buy" | "sell" {
  if (value !== "buy" && value !== "sell") throw new Error("side must be 'buy' or 'sell'");
  return value;
}

function validateQuantity(totalQuantity: unknown, lotSize: unknown): [number, number] {
  const total = integer("total_quantity", totalQuantity, { positive: true });
  const lot = integer("lot_size", lotSize, { positive: true });
  if (total % lot !== 0) throw new Error("total_quantity must be divisible by lot_size");
  return [total, lot];
}

function lotFloor(quantity: number, lotSize: number): number {
  return Math.max(0, Math.floor(quantity / lotSize + 1e-12) * lotSize);
}

function round(value: number, digits: number): number {
  const scale = 10 ** digits;
  return Math.round((value + Number.EPSILON) * scale) / scale;
}

function allocateLots(totalQuantity: number, weights: number[], lotSize: number): number[] {
  if (!weights.length || weights.some((value) => !Number.isFinite(value) || value < 0) || weights.reduce((a, b) => a + b, 0) <= 0) {
    throw new Error("allocation weights must be finite, nonnegative, and have positive total");
  }
  const totalLots = totalQuantity / lotSize;
  const weightSum = weights.reduce((a, b) => a + b, 0);
  const exact = weights.map((weight) => totalLots * weight / weightSum);
  const bases = exact.map((value) => Math.floor(value + 1e-12));
  let residual = totalLots - bases.reduce((a, b) => a + b, 0);
  const order = weights.map((_, index) => index).sort((left, right) => {
    const difference = (exact[right] - bases[right]) - (exact[left] - bases[left]);
    return difference !== 0 ? difference : left - right;
  });
  for (const index of order) {
    if (residual <= 0) break;
    bases[index] += 1;
    residual -= 1;
  }
  return bases.map((lots) => lots * lotSize);
}

function signedMoveBps(side: "buy" | "sell", current: number, benchmark: number): number {
  const direction = side === "buy" ? 1 : -1;
  return direction * (current - benchmark) * 10000 / benchmark;
}

export function almgrenChrissOptimalExecution(input: JsonObject): JsonObject {
  const [total, lot] = validateQuantity(input.total_quantity, input.lot_size);
  const intervals = integer("interval_count", input.interval_count, { positive: true });
  const impactWeight = finiteNumber("temporary_impact_weight", input.temporary_impact_weight, { positive: true });
  const riskWeight = finiteNumber("inventory_risk_weight", input.inventory_risk_weight, { nonnegative: true });
  if (total / lot < intervals) throw new Error("interval_count cannot exceed available lots");

  let kappa = 0;
  let rawTrades: number[];
  if (riskWeight === 0) {
    rawTrades = Array(intervals).fill(1);
  } else {
    kappa = Math.acosh(1 + riskWeight / (2 * impactWeight));
    const denominator = Math.sinh(kappa * intervals);
    const holdings = Array.from({ length: intervals + 1 }, (_, step) => total * Math.sinh(kappa * (intervals - step)) / denominator);
    rawTrades = Array.from({ length: intervals }, (_, index) => holdings[index] - holdings[index + 1]);
  }
  const trades = allocateLots(total, rawTrades, lot);
  let remaining = total;
  let impactScore = 0;
  let riskScore = 0;
  const schedule = trades.map((quantity, index) => {
    remaining -= quantity;
    const impactComponent = impactWeight * quantity * quantity;
    const riskComponent = riskWeight * remaining * remaining;
    impactScore += impactComponent;
    riskScore += riskComponent;
    return { interval: index + 1, target_quantity: quantity, target_remaining_quantity: remaining, temporary_impact_score: round(impactComponent, 6), inventory_risk_score: round(riskComponent, 6) };
  });
  return { total_quantity: total, interval_count: intervals, lot_size: lot, temporary_impact_weight: impactWeight, inventory_risk_weight: riskWeight, kappa: round(kappa, 12), scheduled_quantity: trades.reduce((a, b) => a + b, 0), remaining_quantity: remaining, temporary_impact_score: round(impactScore, 6), inventory_risk_score: round(riskScore, 6), objective_score: round(impactScore + riskScore, 6), schedule, state: riskWeight === 0 ? "risk-neutral" : "risk-adjusted" };
}

export function implementationShortfallExecution(input: JsonObject): JsonObject {
  const [remaining, lot] = validateQuantity(input.remaining_quantity, input.lot_size);
  const side = sideValue(input.side);
  const decisionPrice = integer("decision_price_atoms", input.decision_price_atoms, { positive: true });
  const currentPrice = integer("current_price_atoms", input.current_price_atoms, { positive: true });
  const spread = finiteNumber("spread_bps", input.spread_bps, { nonnegative: true });
  const impact = finiteNumber("impact_coefficient_bps", input.impact_coefficient_bps, { nonnegative: true });
  const adv = integer("average_daily_volume", input.average_daily_volume, { positive: true });
  const volatility = finiteNumber("volatility_bps", input.volatility_bps, { nonnegative: true });
  const aversion = finiteNumber("risk_aversion", input.risk_aversion, { nonnegative: true });
  const urgency = finiteNumber("urgency_bps", input.urgency_bps, { nonnegative: true });
  const intervals = integer("intervals_remaining", input.intervals_remaining, { positive: true });
  const maxChild = Math.min(remaining, integer("max_child_quantity", input.max_child_quantity, { positive: true }));
  const candidateStep = integer("candidate_step_quantity", input.candidate_step_quantity, { positive: true });
  if (maxChild % lot !== 0 || candidateStep % lot !== 0) throw new Error("max_child_quantity and candidate_step_quantity must be lot-aligned");
  const signedMove = signedMoveBps(side, currentPrice, decisionPrice);
  const adverseMove = Math.max(0, signedMove);
  const quantities: number[] = [];
  for (let quantity = 0; quantity <= maxChild; quantity += candidateStep) quantities.push(quantity);
  if (quantities[quantities.length - 1] !== maxChild) quantities.push(maxChild);
  const candidates = quantities.map((quantity) => {
    const residual = remaining - quantity;
    const immediate = quantity * (spread / 2 + impact * quantity / adv);
    const opportunity = residual * (adverseMove + urgency / intervals);
    const risk = residual * (aversion * volatility / Math.sqrt(intervals));
    return { child_quantity: quantity, residual_quantity: residual, immediate_cost_score: round(immediate, 6), opportunity_cost_score: round(opportunity, 6), inventory_risk_score: round(risk, 6), total_score: round(immediate + opportunity + risk, 6) };
  });
  const selected = [...candidates].sort((left, right) => left.total_score - right.total_score || left.child_quantity - right.child_quantity)[0];
  return { side, decision_price_atoms: decisionPrice, current_price_atoms: currentPrice, signed_move_bps: round(signedMove, 6), adverse_move_bps: round(adverseMove, 6), remaining_quantity: remaining, selected_child_quantity: selected.child_quantity, post_child_quantity: selected.residual_quantity, selected_total_score: selected.total_score, selected_immediate_cost_score: selected.immediate_cost_score, selected_opportunity_cost_score: selected.opportunity_cost_score, selected_inventory_risk_score: selected.inventory_risk_score, candidates, state: selected.child_quantity > 0 ? "execute-now" : "wait" };
}

export function arrivalPriceExecution(input: JsonObject): JsonObject {
  const [remaining, lot] = validateQuantity(input.remaining_quantity, input.lot_size);
  const side = sideValue(input.side);
  const arrival = integer("arrival_price_atoms", input.arrival_price_atoms, { positive: true });
  const current = integer("current_price_atoms", input.current_price_atoms, { positive: true });
  const tolerance = finiteNumber("tolerance_bps", input.tolerance_bps, { nonnegative: true });
  const marketVolume = integer("observed_market_volume", input.observed_market_volume, { nonnegative: true });
  const baseRate = integer("base_participation_bps", input.base_participation_bps, { nonnegative: true });
  const defensiveRate = integer("defensive_participation_bps", input.defensive_participation_bps, { nonnegative: true });
  const maxRate = integer("max_participation_bps", input.max_participation_bps, { positive: true });
  const intervals = integer("intervals_remaining", input.intervals_remaining, { positive: true });
  const deadline = integer("deadline_threshold_intervals", input.deadline_threshold_intervals, { positive: true });
  const maxChild = integer("max_child_quantity", input.max_child_quantity, { positive: true });
  if (!(0 <= defensiveRate && defensiveRate <= baseRate && baseRate <= maxRate && maxRate <= 10000)) throw new Error("participation rates must satisfy 0 <= defensive <= base <= max <= 10000");
  if (maxChild % lot !== 0) throw new Error("max_child_quantity must be lot-aligned");
  const signedMove = signedMoveBps(side, current, arrival);
  let priceState: string;
  let chosenRate: number;
  if (intervals <= deadline) { priceState = "deadline-override"; chosenRate = maxRate; }
  else if (signedMove <= -tolerance) { priceState = "favorable"; chosenRate = maxRate; }
  else if (signedMove >= tolerance) { priceState = "adverse"; chosenRate = defensiveRate; }
  else { priceState = "inside-band"; chosenRate = baseRate; }
  const target = lotFloor(marketVolume * chosenRate / 10000, lot);
  const child = Math.min(remaining, maxChild, target);
  return { side, arrival_price_atoms: arrival, current_price_atoms: current, signed_move_bps: round(signedMove, 6), tolerance_bps: tolerance, price_state: priceState, chosen_participation_bps: chosenRate, observed_market_volume: marketVolume, target_from_volume_quantity: target, child_quantity: child, remaining_quantity: remaining - child, state: child === remaining ? "parent-complete" : priceState };
}

export function liquiditySeekingExecution(input: JsonObject): JsonObject {
  const [total, lot] = validateQuantity(input.total_quantity, input.lot_size);
  const side = sideValue(input.side);
  const limitPrice = integer("limit_price_atoms", input.limit_price_atoms, { positive: true });
  const minimumConfidence = integer("minimum_confidence_bps", input.minimum_confidence_bps, { nonnegative: true });
  const maxAge = integer("maximum_age_ms", input.maximum_age_ms, { nonnegative: true });
  const maxTake = integer("max_take_per_event", input.max_take_per_event, { positive: true });
  if (minimumConfidence > 10000) throw new Error("minimum_confidence_bps cannot exceed 10000");
  if (maxTake % lot !== 0) throw new Error("max_take_per_event must be lot-aligned");
  if (!Array.isArray(input.liquidity_events) || input.liquidity_events.length === 0) throw new Error("liquidity_events must be a nonempty array");
  let remaining = total;
  let accepted = 0;
  const events = (input.liquidity_events as unknown[]).map((raw, index) => {
    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`liquidity_events[${index}] must be an object`);
    const event = raw as JsonObject;
    if (typeof event.event_id !== "string" || !event.event_id.trim()) throw new Error(`liquidity_events[${index}].event_id must be a nonempty string`);
    const price = integer(`liquidity_events[${index}].price_atoms`, event.price_atoms, { positive: true });
    const available = integer(`liquidity_events[${index}].available_quantity`, event.available_quantity, { nonnegative: true });
    const age = integer(`liquidity_events[${index}].age_ms`, event.age_ms, { nonnegative: true });
    const confidence = integer(`liquidity_events[${index}].confidence_bps`, event.confidence_bps, { nonnegative: true });
    if (confidence > 10000) throw new Error(`liquidity_events[${index}].confidence_bps cannot exceed 10000`);
    let reason: string;
    let quantity = 0;
    if (remaining === 0) reason = "parent-complete";
    else if (age > maxAge) reason = "stale";
    else if (confidence < minimumConfidence) reason = "confidence-below-threshold";
    else if ((side === "buy" && price > limitPrice) || (side === "sell" && price < limitPrice)) reason = "outside-limit";
    else { quantity = Math.min(remaining, maxTake, lotFloor(available, lot)); reason = quantity > 0 ? "accepted" : "below-one-lot"; }
    remaining -= quantity;
    accepted += quantity;
    return { event_id: event.event_id.trim(), price_atoms: price, available_quantity: available, age_ms: age, confidence_bps: confidence, planned_take_quantity: quantity, reason, remaining_quantity: remaining };
  });
  return { side, limit_price_atoms: limitPrice, total_quantity: total, accepted_quantity: accepted, remaining_quantity: remaining, accepted_event_count: events.filter((row) => row.reason === "accepted").length, rejected_event_count: events.filter((row) => row.reason !== "accepted").length, events, state: remaining === 0 ? "parent-complete" : accepted > 0 ? "opportunity-found" : "no-eligible-liquidity" };
}

export function opportunisticDarkPoolExecution(input: JsonObject): JsonObject {
  const [total, lot] = validateQuantity(input.total_quantity, input.lot_size);
  const maxFraction = integer("maximum_dark_fraction_bps", input.maximum_dark_fraction_bps, { positive: true });
  const minProbability = integer("minimum_firm_probability_bps", input.minimum_firm_probability_bps, { nonnegative: true });
  const minImprovement = integer("minimum_price_improvement_atoms", input.minimum_price_improvement_atoms, { nonnegative: true });
  const minExecution = integer("minimum_execution_quantity", input.minimum_execution_quantity, { positive: true });
  const maxWindow = integer("max_exposure_per_window", input.max_exposure_per_window, { positive: true });
  const fallback = integer("fallback_window", input.fallback_window, { positive: true });
  if (maxFraction > 10000 || minProbability > 10000) throw new Error("basis-point parameters cannot exceed 10000");
  if (minExecution % lot !== 0 || maxWindow % lot !== 0) throw new Error("minimum_execution_quantity and max_exposure_per_window must be lot-aligned");
  if (!Array.isArray(input.dark_opportunities) || input.dark_opportunities.length === 0) throw new Error("dark_opportunities must be a nonempty array");
  const darkCap = lotFloor(total * maxFraction / 10000, lot);
  let exposed = 0;
  const opportunities = (input.dark_opportunities as unknown[]).map((raw, index) => {
    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`dark_opportunities[${index}] must be an object`);
    const opportunity = raw as JsonObject;
    if (typeof opportunity.opportunity_id !== "string" || !opportunity.opportunity_id.trim()) throw new Error(`dark_opportunities[${index}].opportunity_id must be a nonempty string`);
    const window = integer(`dark_opportunities[${index}].window`, opportunity.window, { positive: true });
    const indicated = integer(`dark_opportunities[${index}].indicated_quantity`, opportunity.indicated_quantity, { nonnegative: true });
    const probability = integer(`dark_opportunities[${index}].firm_probability_bps`, opportunity.firm_probability_bps, { nonnegative: true });
    const improvement = integer(`dark_opportunities[${index}].price_improvement_atoms`, opportunity.price_improvement_atoms, { nonnegative: true });
    if (probability > 10000) throw new Error(`dark_opportunities[${index}].firm_probability_bps cannot exceed 10000`);
    const capRemaining = Math.max(0, darkCap - exposed);
    let reason: string;
    let quantity = 0;
    if (window >= fallback) reason = "fallback-active";
    else if (probability < minProbability) reason = "firm-probability-below-threshold";
    else if (improvement < minImprovement) reason = "price-improvement-below-threshold";
    else if (indicated < minExecution) reason = "minimum-size-not-met";
    else if (capRemaining === 0) reason = "dark-cap-reached";
    else { quantity = Math.min(capRemaining, maxWindow, lotFloor(indicated, lot)); reason = quantity >= minExecution ? "expose-dark" : "minimum-size-not-met"; if (reason !== "expose-dark") quantity = 0; }
    exposed += quantity;
    return { opportunity_id: opportunity.opportunity_id.trim(), window, indicated_quantity: indicated, firm_probability_bps: probability, price_improvement_atoms: improvement, planned_dark_exposure_quantity: quantity, reason, dark_cap_remaining_quantity: Math.max(0, darkCap - exposed) };
  });
  const fallbackQuantity = total - exposed;
  return { total_quantity: total, maximum_dark_fraction_bps: maxFraction, dark_quantity_cap: darkCap, planned_dark_exposure_quantity: exposed, lit_fallback_quantity: fallbackQuantity, dark_opportunity_count: opportunities.length, accepted_dark_window_count: opportunities.filter((row) => row.reason === "expose-dark").length, opportunities, state: fallbackQuantity === 0 ? "dark-plan-complete" : "lit-fallback-required" };
}

export function calculate(topicId: string, input: JsonObject): JsonObject {
  if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("inputs must be an object");
  if (topicId === "D13-F02-A01") return almgrenChrissOptimalExecution(input);
  if (topicId === "D13-F02-A02") return implementationShortfallExecution(input);
  if (topicId === "D13-F02-A03") return arrivalPriceExecution(input);
  if (topicId === "D13-F02-A04") return liquiditySeekingExecution(input);
  if (topicId === "D13-F02-A05") return opportunisticDarkPoolExecution(input);
  throw new Error(`unsupported topic_id: ${topicId}`);
}