Stock-Dividend Adjustment: Convert Price and Quantity Bases Without Inventing 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

/** Auditable same-class stock-dividend adjustment with as-of revision selection. */
const OUTPUT_SCALE = 1000000000000n;
const exactRatio = (value) => {
  const bytes = new ArrayBuffer(8), view = new DataView(bytes); view.setFloat64(0,value,false); const bits=view.getBigUint64(0,false);
  const negative=(bits>>63n)===1n, exponent=Number((bits>>52n)&0x7ffn), fraction=bits&((1n<<52n)-1n);
  if(exponent===0x7ff)throw new TypeError("output must be finite");
  if(exponent===0&&fraction===0n)return {negative,numerator:0n,denominator:1n};
  const mantissa=exponent===0?fraction:(1n<<52n)|fraction, power=(exponent===0?1-1023:exponent-1023)-52;
  return power>=0?{negative,numerator:mantissa<<BigInt(power),denominator:1n}:{negative,numerator:mantissa,denominator:1n<<BigInt(-power)};
};
export const roundOutput = (value) => { numberValue(value,"output"); const {negative,numerator,denominator}=exactRatio(value);let quotient=(numerator*OUTPUT_SCALE)/denominator;const remainder=(numerator*OUTPUT_SCALE)%denominator;if(remainder*2n>=denominator)quotient+=1n;const result=Number(quotient)/1e12;return negative?-result:result; };
const rounded = roundOutput;
const numberValue = (value, name, minimum = null, strict = false) => {
  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be a finite number`);
  if (minimum !== null && (strict ? value <= minimum : value < minimum)) throw new RangeError(`${name} is outside its allowed range`);
  return value;
};
const textValue = (value, name) => { if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`); return value; };
const instant = (value, name) => {
  const text = textValue(value, name);
  if (!/(Z|[+-]\d\d:\d\d)$/.test(text) || Number.isNaN(Date.parse(text))) throw new TypeError(`${name} must be an ISO 8601 instant with offset`);
  return new Date(text).getTime();
};
const dateValue = (value, name) => { const text = textValue(value, name), parsed=new Date(`${text}T00:00:00Z`); if (!/^\d{4}-\d{2}-\d{2}$/.test(text) || Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0,10)!==text) throw new TypeError(`${name} must be YYYY-MM-DD`); return text; };

function selectEvent(event, asOf, securityId) {
  const eventId = textValue(event.eventId, "eventId");
  const subject = textValue(event.subjectSecurityId, `${eventId}.subjectSecurityId`);
  const distributed = textValue(event.distributedSecurityId, `${eventId}.distributedSecurityId`);
  if (subject !== securityId) throw new RangeError(`${eventId} does not apply to securityId`);
  if (distributed !== subject) throw new RangeError(`${eventId} distributes another security; use a distribution method`);
  const exAtText = textValue(event.exAt, `${eventId}.exAt`), exAt = instant(exAtText, `${eventId}.exAt`);
  dateValue(event.recordDate, `${eventId}.recordDate`); dateValue(event.payableDate, `${eventId}.payableDate`);
  if (!Array.isArray(event.revisions) || !event.revisions.length) throw new TypeError(`${eventId}.revisions must be a non-empty list`);
  const seen = new Set(), available = [];
  for (const revision of event.revisions) {
    if (!revision || typeof revision !== "object" || Array.isArray(revision)) throw new TypeError(`${eventId} revision must be an object`);
    const published = instant(revision.publishedAt, `${eventId}.publishedAt`);
    if (seen.has(published)) throw new RangeError(`${eventId} has ambiguous revisions at one publishedAt`);
    seen.add(published); if (published <= asOf) available.push({published, revision});
  }
  if (!available.length) return null;
  available.sort((a,b) => a.published - b.published); const {published, revision} = available.at(-1);
  if (!["confirmed","cancelled"].includes(revision.status)) throw new RangeError(`${eventId}.status must be confirmed or cancelled`);
  const sourceId = textValue(revision.sourceId, `${eventId}.sourceId`);
  if (revision.status === "cancelled") return {cancelled:true,eventId,published};
  const rate = numberValue(revision.rateNewSharesPerOld, `${eventId}.rateNewSharesPerOld`, 0, true), factor = 1 + rate;
  if (!Number.isFinite(factor)) throw new RangeError(`${eventId} factor is not finite`);
  return {cancelled:false,eventId,exAt,exAtText,published,publishedText:revision.publishedAt,rate,factor,sourceId};
}

export function calculate(data) {
  if (!data || typeof data !== "object" || Array.isArray(data)) throw new TypeError("data must be an object");
  const payload = structuredClone(data);
  if (payload.method !== "backward_post_event_same_class") throw new RangeError("unsupported method");
  const securityId = textValue(payload.securityId,"securityId"), asOf = instant(payload.asOf,"asOf"), anchorAt = instant(payload.anchorAt,"anchorAt");
  if(anchorAt>asOf)throw new RangeError("anchorAt must not be later than asOf");
  if (!["adjust_to_anchor_basis","preserve_reported"].includes(payload.volumePolicy)) throw new RangeError("invalid volumePolicy");
  if (!Array.isArray(payload.events)) throw new TypeError("events must be a list");
  const selected = [], unavailable = [], cancelled = [], ids = new Set();
  for (const event of payload.events) {
    if (!event || typeof event !== "object" || Array.isArray(event)) throw new TypeError("each event must be an object");
    const eventId = textValue(event.eventId,"eventId"); if (ids.has(eventId)) throw new RangeError("eventId must be unique"); ids.add(eventId);
    const chosen = selectEvent(event,asOf,securityId);
    if (!chosen) unavailable.push(eventId); else if (chosen.cancelled) cancelled.push(eventId); else if (chosen.exAt <= anchorAt) selected.push(chosen);
  }
  selected.sort((a,b) => a.exAt-b.exAt || a.eventId.localeCompare(b.eventId));
  if (!Array.isArray(payload.observations) || !payload.observations.length) throw new TypeError("observations must be a non-empty list");
  let previousAt = null;
  const rows = payload.observations.map(observation => {
    if (!observation || typeof observation !== "object" || Array.isArray(observation)) throw new TypeError("each observation must be an object");
    const atText = textValue(observation.at,"observation.at"), at = instant(atText,"observation.at");
    const availableAtText=textValue(observation.availableAt,"observation.availableAt"),availableAt=instant(availableAtText,"observation.availableAt"),sourceId=textValue(observation.sourceId,"observation.sourceId");
    if(availableAt<at)throw new RangeError("observation.availableAt must not precede observation.at");if(availableAt>asOf)throw new RangeError("observation was not available by asOf");
    if (previousAt !== null && at <= previousAt) throw new RangeError("observations must be strictly increasing"); if (at > anchorAt) throw new RangeError("observation occurs after anchorAt"); previousAt = at;
    const rawPrice=numberValue(observation.price,"price",0,true),rawShares=numberValue(observation.shares,"shares",0),rawVolume=numberValue(observation.volume,"volume",0);
    const applicable=selected.filter(event=>at<event.exAt); let factor=1; for(const event of applicable){factor*=event.factor;if(!Number.isFinite(factor))throw new RangeError("cumulative factor is not finite");}
    return {at:atText,availableAt:availableAtText,sourceId,rawPrice:rounded(rawPrice),adjustedPrice:rounded(rawPrice/factor),rawShares:rounded(rawShares),adjustedShares:rounded(rawShares*factor),rawVolume:rounded(rawVolume),adjustedVolume:rounded(payload.volumePolicy==="adjust_to_anchor_basis"?rawVolume*factor:rawVolume),cumulativeShareFactor:rounded(factor),appliedEventIds:applicable.map(event=>event.eventId)};
  });
  const appliedEvents=selected.map(event=>({eventId:event.eventId,exAt:event.exAtText,revisionPublishedAt:event.publishedText,knownByExDate:event.published<=event.exAt,rateNewSharesPerOld:rounded(event.rate),shareFactor:rounded(event.factor),priceFactor:rounded(1/event.factor),sourceId:event.sourceId}));
  return {method:payload.method,securityId,asOf:payload.asOf,anchorAt:payload.anchorAt,volumePolicy:payload.volumePolicy,appliedEvents,unavailableEventIds:unavailable,cancelledEventIds:cancelled,rows};
}

export function settleEntitlement(data) {
  if (!data || typeof data !== "object" || Array.isArray(data)) throw new TypeError("data must be an object");
  const held=numberValue(data.heldShares,"heldShares",0),rate=numberValue(data.rateNewSharesPerOld,"rateNewSharesPerOld",0,true),increment=numberValue(data.shareIncrement??1,"shareIncrement",0,true),policy=data.fractionalPolicy;
  if (!["preserve_fractional","cash_in_lieu"].includes(policy)) throw new RangeError("invalid fractionalPolicy");
  const exact=held*rate;
  if(policy==="preserve_fractional")return {status:"settled",exactNewShares:rounded(exact),deliveredShares:rounded(exact),fractionalShares:0,grossCash:0,netCash:0,currency:null};
  const delivered=Math.floor(exact/increment)*increment;if(delivered>exact)throw new RangeError("fractional policy would over-deliver shares");const fractional=Math.max(0,exact-delivered);
  if(fractional<=1e-12)return {status:"settled",exactNewShares:rounded(exact),deliveredShares:rounded(delivered),fractionalShares:0,grossCash:0,netCash:0,currency:null};
  if(data.cashInLieuPrice==null)return {status:"pending_cash_price",exactNewShares:rounded(exact),deliveredShares:rounded(delivered),fractionalShares:rounded(fractional),grossCash:null,netCash:null,currency:null};
  const price=numberValue(data.cashInLieuPrice,"cashInLieuPrice",0,true),currency=textValue(data.currency,"currency"),withholding=numberValue(data.withholdingRate??0,"withholdingRate",0),fees=numberValue(data.fees??0,"fees",0);
  if(withholding>1)throw new RangeError("withholdingRate must not exceed 1"); const gross=fractional*price,net=gross*(1-withholding)-fees;if(net < -1e-12)throw new RangeError("fees and withholding exceed gross cash");
  return {status:"settled",exactNewShares:rounded(exact),deliveredShares:rounded(delivered),fractionalShares:rounded(fractional),grossCash:rounded(gross),netCash:rounded(Math.max(0,net)),currency};
}