Spin-Off Price Adjustment: Separate Parent Price from Distributed Value

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

/** Point-in-time spin-off price-adjustment reference implementation. */
const PRICE_TYPES = new Set(["when_issued", "regular_way"]);
const textValue = (value: unknown, name: string): string => {
  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
  return value;
};
const numberValue = (value: unknown, name: string, minimum?: number): number => {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
  if (minimum !== undefined && value < minimum) throw new RangeError(`${name} must be at least ${minimum}`);
  return value;
};
const positive = (value: unknown, name: string): number => {
  const result = numberValue(value, name); if (result <= 0) throw new RangeError(`${name} must be positive`); return result;
};
const positiveInteger = (value: unknown, name: string): number => {
  const result = positive(value, name); if (!Number.isInteger(result)) throw new RangeError(`${name} must be a positive integer`); return result;
};
const instant = (value: unknown, name: string): number => {
  const source = textValue(value, name);
  if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(source) || Number.isNaN(Date.parse(source))) throw new RangeError(`${name} must be an ISO 8601 instant with a UTC offset`);
  return Date.parse(source);
};
/** Round the shortest round-trippable decimal form half away from zero at 6dp. */
export const roundHalfUp6 = (value: number): number => {
  if (!Number.isFinite(value)) throw new TypeError("rounding input must be finite");
  const negative = value < 0;
  const [coefficient, exponentText = "0"] = Math.abs(value).toString().toLowerCase().split("e");
  const [whole, fraction = ""] = coefficient.split(".");
  const exponent = Number(exponentText);
  const digits = (whole + fraction).replace(/^0+(?=\d)/, "") || "0";
  const decimalPlaces = fraction.length - exponent;
  const shift = 6 - decimalPlaces;
  let scaled: bigint;
  if (shift >= 0) {
    scaled = BigInt(digits) * (10n ** BigInt(shift));
  } else {
    const divisor = 10n ** BigInt(-shift);
    const numerator = BigInt(digits);
    scaled = numerator / divisor;
    if ((numerator % divisor) * 2n >= divisor) scaled += 1n;
  }
  if (scaled === 0n) return 0;
  const padded = scaled.toString().padStart(7, "0");
  const decimal = `${negative ? "-" : ""}${padded.slice(0, -6)}.${padded.slice(-6)}`;
  return Number(decimal);
};
const round6 = roundHalfUp6;
type RecordValue = Record<string, any>;

function selectRevision(revisions: unknown, asOf: number): RecordValue {
  if (!Array.isArray(revisions) || !revisions.length) throw new TypeError("revisions must be a non-empty list");
  let eventId: string | null = null; const seen = new Set<string>(); const candidates: Array<[number, number, RecordValue]> = [];
  revisions.forEach((revision) => {
    if (!revision || typeof revision !== "object" || Array.isArray(revision)) throw new TypeError("each revision must be an object");
    const item = revision as RecordValue; const current = textValue(item.eventId, "eventId");
    if (eventId === null) eventId = current; else if (eventId !== current) throw new RangeError("all revisions must describe the same eventId");
    if (!Number.isInteger(item.revisionSequence) || item.revisionSequence < 1) throw new RangeError("revisionSequence must be a positive integer");
    const identity = `${textValue(item.revisionId, "revisionId")}\u0000${item.revisionSequence}`;
    if (seen.has(identity)) throw new RangeError("duplicate revision identity"); seen.add(identity);
    const available = instant(item.availableAt, "availableAt"); if (available <= asOf) candidates.push([available, item.revisionSequence, item]);
  });
  if (!candidates.length) throw new RangeError("no event revision was available at asOf");
  candidates.sort((a, b) => a[0] - b[0] || a[1] - b[1]); return candidates[candidates.length - 1][2];
}

function validateTimeline(event: RecordValue): [number, number, number] {
  const times = [instant(event.recordAt,"recordAt"), instant(event.whenIssuedStartAt,"whenIssuedStartAt"), instant(event.distributionAt,"distributionAt"), instant(event.parentExAt,"parentExAt"), instant(event.childRegularWayAt,"childRegularWayAt")];
  if (!(times[0] <= times[1] && times[1] <= times[2] && times[2] <= times[3] && times[3] <= times[4])) throw new RangeError("timeline must satisfy record <= when-issued <= distribution <= parent ex <= child regular-way");
  return [times[1], times[3], times[4]];
}

function observation(value: unknown, name: string, asOf: number, currency: string): [number, number] {
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
  const item = value as RecordValue; if (textValue(item.currency, `${name}.currency`) !== currency) throw new RangeError(`${name}.currency must equal quoteCurrency`);
  const price = positive(item.price, `${name}.price`), observed = instant(item.observedAt, `${name}.observedAt`), available = instant(item.availableAt, `${name}.availableAt`);
  if (observed > available) throw new RangeError(`${name}.observedAt must not be later than availableAt`);
  if (available > asOf) throw new RangeError(`${name} was not available at asOf`); textValue(item.sourceId, `${name}.sourceId`); return [price, observed];
}

export function calculate(input: RecordValue): RecordValue {
  if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError("data must be an object");
  const value = structuredClone(input), asOf = instant(value.asOf, "asOf"), event = selectRevision(value.revisions, asOf), status = textValue(event.status, "status");
  if (status === "cancelled") throw new RangeError("selected event revision is cancelled"); if (status !== "confirmed") throw new RangeError("status must be confirmed or cancelled");
  const [whenIssuedAt, exAt, childRegularWayAt] = validateTimeline(event), quoteCurrency = textValue(event.quoteCurrency, "quoteCurrency");
  const [parentCum, parentCumObserved] = observation(event.parentCumObservation, "parentCumObservation", asOf, quoteCurrency);
  if (textValue(event.parentCumObservation.priceType,"parentCumObservation.priceType") !== "regular_way_cum_distribution") throw new RangeError("parentCumObservation.priceType must be regular_way_cum_distribution");
  if (parentCumObserved >= exAt) throw new RangeError("parent cum observation must precede parentExAt");
  if (!Array.isArray(event.children) || !event.children.length) throw new TypeError("children must be a non-empty list");
  const holding = event.holdingParentShares; if (holding !== undefined && (!Number.isInteger(holding) || holding < 0)) throw new RangeError("holdingParentShares must be a non-negative integer");
  const ids = new Set<string>(), components: RecordValue[] = [], componentValues: Array<[string,number]> = [], missing: string[] = [];
  event.children.forEach((child: RecordValue) => {
    if (!child || typeof child !== "object" || Array.isArray(child)) throw new TypeError("each child must be an object");
    const securityId = textValue(child.securityId,"securityId"); if (ids.has(securityId)) throw new RangeError("child securityId values must be unique"); ids.add(securityId);
    const childShares = positiveInteger(child.childShares,"childShares"), parentShares = positiveInteger(child.parentShares,"parentShares"), ratio = childShares / parentShares;
    if (!child.reference || typeof child.reference !== "object" || Array.isArray(child.reference)) throw new TypeError("child reference must be an object");
    const reference = child.reference, referenceStatus = textValue(reference.status,"reference.status");
    if (referenceStatus === "unavailable") { missing.push(securityId); return; }
    if (referenceStatus !== "available") throw new RangeError("reference.status must be available or unavailable");
    const priceType = textValue(reference.priceType,"reference.priceType"); if (!PRICE_TYPES.has(priceType)) throw new RangeError("reference.priceType must be when_issued or regular_way");
    const childCurrency = textValue(reference.currency,"reference.currency"), childPrice = positive(reference.price,"reference.price"), observedAt = instant(reference.observedAt,"reference.observedAt"), availableAt = instant(reference.availableAt,"reference.availableAt");
    if (observedAt > availableAt) throw new RangeError("reference.observedAt must not be later than reference.availableAt"); if (availableAt > asOf) throw new RangeError("child price evidence was not available at asOf"); if (priceType === "when_issued" && !(whenIssuedAt <= observedAt && observedAt <= exAt)) throw new RangeError("when-issued reference must be observed between whenIssuedStartAt and parentExAt"); if (priceType === "regular_way" && observedAt < childRegularWayAt) throw new RangeError("regular-way reference cannot precede childRegularWayAt");
    textValue(reference.sourceId,"reference.sourceId"); const fx = positive(reference.fxQuotePerChildCurrency ?? 1,"fxQuotePerChildCurrency");
    if (childCurrency === quoteCurrency) { if (Math.abs(fx-1)>1e-12) throw new RangeError("same-currency child requires fxQuotePerChildCurrency = 1"); }
    else { const fxObserved=instant(reference.fxObservedAt,"fxObservedAt"),fxAvailable=instant(reference.fxAvailableAt,"fxAvailableAt"); if(fxObserved>fxAvailable)throw new RangeError("fxObservedAt must not be later than fxAvailableAt"); if (fxAvailable > asOf) throw new RangeError("FX evidence was not available at asOf"); textValue(reference.fxSourceId,"fxSourceId"); }
    const priceQuote = childPrice * fx, valuePerParent = ratio * priceQuote;
    const component: RecordValue = {securityId,entitlementRatio:round6(ratio),priceType,priceQuote:round6(priceQuote),valuePerParent:round6(valuePerParent)};
    if (holding !== undefined) { const exact=holding*ratio, whole=Math.floor(exact); component.holderEntitlement={exactChildShares:round6(exact),wholeChildShares:whole,fractionalChildShare:round6(exact-whole),fractionalReferenceValue:round6((exact-whole)*priceQuote),actualCashInLieuKnown:false}; }
    components.push(component); componentValues.push([securityId,valuePerParent]);
  });
  if (missing.length) { const policy=textValue(event.unavailableChildPricePolicy ?? "pending","unavailableChildPricePolicy"); if(policy==="reject")throw new RangeError("one or more child reference prices are unavailable"); if(policy!=="pending")throw new RangeError("unavailableChildPricePolicy must be pending or reject"); return {eventId:event.eventId,revisionId:event.revisionId,status:"pending_child_price",missingChildSecurityIds:missing,adjustmentFactor:null,theoreticalParentExReference:null,referenceIsTradedParentExFact:false}; }
  const distributed=componentValues.reduce((sum,item)=>sum+item[1],0), theoreticalEx=parentCum-distributed; if(theoreticalEx<=0)throw new RangeError("distributed child value must remain below parentCumPrice");
  const allocation={parentWeight:round6(theoreticalEx/parentCum),children:componentValues.map(item=>({securityId:item[0],weight:round6(item[1]/parentCum)}))};
  let totalReturn=null; if(event.parentExObservation!==undefined){ const [parentEx,parentExObserved]=observation(event.parentExObservation,"parentExObservation",asOf,quoteCurrency); if(textValue(event.parentExObservation.priceType,"parentExObservation.priceType")!=="regular_way_ex_distribution")throw new RangeError("parentExObservation.priceType must be regular_way_ex_distribution"); if(parentExObserved<exAt)throw new RangeError("parent ex observation cannot precede parentExAt"); const fees=numberValue(event.feesPerParentQuote??0,"feesPerParentQuote",0),taxes=numberValue(event.taxesPerParentQuote??0,"taxesPerParentQuote",0),gross=parentEx+distributed,net=gross-fees-taxes; if(net<0)throw new RangeError("fees and taxes cannot make net combined value negative"); totalReturn={parentExObserved:round6(parentEx),grossCombinedValue:round6(gross),grossReturn:round6(gross/parentCum-1),netCombinedValue:round6(net),netReturn:round6(net/parentCum-1),feesPerParentQuote:round6(fees),taxesPerParentQuote:round6(taxes)}; }
  return {eventId:event.eventId,revisionId:event.revisionId,availableAt:event.availableAt,status:"ready",quoteCurrency,parentCumPrice:round6(parentCum),distributedValuePerParent:round6(distributed),theoreticalParentExReference:round6(theoreticalEx),backwardAdjustmentFactor:round6(theoreticalEx/parentCum),factorDirection:"multiply_pre_event_parent_prices",factorAnchor:"post_event_parent_only_basis",rounding:"shortest_decimal_half_up_6_on_output_only",components,economicValueAllocation:allocation,totalReturnBridge:totalReturn,referenceIsTradedParentExFact:false};
}