@insiderfinance/totalfinance 0.1.0

package/modules/portfolio/dist/events.js

@@ -0,0 +1,1061 @@
+/**
+ * `@insiderfinance/totalfinance/portfolio/events` — the FC7 economic-event grammar (Stage 4.4).
+ *
+ * Portfolio truth is EVENT-DERIVED (agent-native platform doc, Permanent law 1; spec decision
+ * D16): positions, cash, cost basis, and realized P&L are a pure fold over immutable economic
+ * events — never mutable fields, never conversation memory. This module owns the closed
+ * discriminated union of first-slice event payloads, the decided `PortfolioEventEnvelope`, the
+ * Law-12 teaching validator, and the event content identity that defines the duplicate boundary.
+ *
+ * The families and their event lists are the agent-native doc's decided table ("Economic event
+ * model"): cash (deposit, withdrawal, transfer, FX conversion), trading (fill), costs
+ * (commission, exchange/regulatory fee, slippage adjustment), income (dividend, coupon, interest,
+ * staking/funding receipt), financing (margin interest, borrow charge, funding payment), and
+ * corporate actions (split, in this slice). Derivative lifecycle, further corporate actions, and
+ * correction/reversal folding are later FC7 slices — see `docs/specs/fc7-first-slice.md`.
+ *
+ * Order submission/acknowledgement/rejection belongs to the EXECUTION JOURNAL, not this ledger
+ * (Permanent law 3): an order does not change holdings; a fill does.
+ */
+import { ErrorCode, InputError, ensureKnownKeys } from '../../core/dist/index.js';
+import { canonicalJsonOf, contentHash } from '../../core/dist/artifacts/index.js';
+import { describeInputValue, hasOwnKey, ownValue, requireCurrencyCode, requireDenseDataArray, requireEpochMsField, requireFiniteNumberField, requireIdentityString, requireNoInheritedFields, requirePlainDataObject, requirePositiveNumberField, requireProvenanceShape, } from './internal.js';
+/**
+ * Version of the event grammar carried by EVERY envelope. Bump only with a payload shape change,
+ * landed together with a registered ledger migration.
+ */
+export const PORTFOLIO_EVENT_SCHEMA_VERSION = 1;
+/** A deep copy of plain JSON data (the only kind these boundaries accept); typed, lib-free. */
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+const ENVELOPE_KEYS = [
+    'eventId',
+    'schemaVersion',
+    'eventType',
+    'sourceId',
+    'accountId',
+    'effectiveTimestampMs',
+    'recordedTimestampMs',
+    'correlationId',
+    'causationId',
+    'reversesEventId',
+    'event',
+    'provenance',
+];
+const EVENT_KEYS = {
+    'admin.reversal': ['eventType', 'original', 'reason'],
+    'admin.correction': ['eventType', 'original', 'replacement', 'reason'],
+    'admin.account-migration': ['eventType', 'fromAccountId', 'toAccountId', 'reason'],
+    'cash.deposit': ['eventType', 'amount', 'currency', 'settleTimestampMs'],
+    'cash.withdrawal': ['eventType', 'amount', 'currency', 'settleTimestampMs'],
+    'cash.transfer': ['eventType', 'amount', 'currency', 'fromAccountId', 'toAccountId'],
+    'cash.conversion': ['eventType', 'fromCurrency', 'toCurrency', 'fromAmount', 'toAmount'],
+    'trade.fill': [
+        'eventType',
+        'instrumentId',
+        'side',
+        'quantity',
+        'pricePerUnit',
+        'currency',
+        'settleTimestampMs',
+        'lotSelections',
+        'contractMultiplier',
+        'settlementStyle',
+        'contract',
+        'accruedInterest',
+    ],
+    'cost.charge': [
+        'eventType',
+        'costType',
+        'amount',
+        'currency',
+        'instrumentId',
+        'relatesToEventId',
+    ],
+    'income.received': [
+        'eventType',
+        'incomeType',
+        'amount',
+        'currency',
+        'instrumentId',
+        'settleTimestampMs',
+    ],
+    'financing.charge': ['eventType', 'financingType', 'amount', 'currency', 'instrumentId'],
+    'corporate.split': ['eventType', 'instrumentId', 'sharesAfterSplit', 'sharesBeforeSplit'],
+    'derivative.exercise': [
+        'eventType',
+        'instrumentId',
+        'quantity',
+        'settlement',
+        'premiumTreatment',
+        'settleTimestampMs',
+        'lotSelections',
+    ],
+    'derivative.assignment': [
+        'eventType',
+        'instrumentId',
+        'quantity',
+        'settlement',
+        'premiumTreatment',
+        'settleTimestampMs',
+        'lotSelections',
+    ],
+    'derivative.expiration': ['eventType', 'instrumentId', 'quantity', 'lotSelections'],
+    'derivative.multiplier-change': [
+        'eventType',
+        'instrumentId',
+        'contractMultiplierAfter',
+        'strikePricePerUnitAfter',
+        'reason',
+    ],
+    'derivative.variation-margin': ['eventType', 'instrumentId', 'settlementPricePerUnit'],
+    'derivative.roll': [
+        'eventType',
+        'fromInstrumentId',
+        'toInstrumentId',
+        'quantity',
+        'closePricePerUnit',
+        'openPricePerUnit',
+        'contract',
+        'lotSelections',
+    ],
+    'fixed-income.redemption': [
+        'eventType',
+        'instrumentId',
+        'redemptionType',
+        'quantity',
+        'pricePerUnit',
+        'currency',
+        'settleTimestampMs',
+        'lotSelections',
+    ],
+    'corporate.symbol-change': ['eventType', 'fromInstrumentId', 'toInstrumentId'],
+    'corporate.merger': [
+        'eventType',
+        'fromInstrumentId',
+        'toInstrumentId',
+        'sharesPerShare',
+        'cashPerShare',
+        'currency',
+        'settleTimestampMs',
+    ],
+    'corporate.spin-off': [
+        'eventType',
+        'parentInstrumentId',
+        'childInstrumentId',
+        'sharesPerParentShare',
+        'basisAllocationFraction',
+    ],
+    'corporate.return-of-capital': [
+        'eventType',
+        'instrumentId',
+        'amountPerShare',
+        'currency',
+        'settleTimestampMs',
+    ],
+    'corporate.cash-in-lieu': [
+        'eventType',
+        'instrumentId',
+        'quantity',
+        'amount',
+        'currency',
+        'relatesToEventId',
+        'settleTimestampMs',
+    ],
+    'position.transfer': [
+        'eventType',
+        'instrumentId',
+        'quantity',
+        'fromAccountId',
+        'toAccountId',
+        'lotSelections',
+    ],
+};
+const SETTLEMENT_STYLES = ['cash-on-trade', 'variation-margin'];
+const CONTRACT_KINDS = ['option', 'future', 'perpetual'];
+const PREMIUM_TREATMENTS = ['fold-into-underlying-basis', 'realize'];
+const REDEMPTION_TYPES = [
+    'maturity',
+    'call',
+    'principal-paydown',
+    'sinking-fund',
+];
+const COST_TYPES = [
+    'commission',
+    'exchange-fee',
+    'regulatory-fee',
+    'slippage-adjustment',
+];
+const INCOME_TYPES = [
+    'dividend',
+    'coupon',
+    'interest',
+    'staking-reward',
+    'funding-receipt',
+];
+const FINANCING_TYPES = [
+    'margin-interest',
+    'borrow-charge',
+    'funding-payment',
+];
+const EXAMPLE_ENVELOPE = "{ eventId: 'evt-1', schemaVersion: 1, eventType: 'cash.deposit', sourceId: 'manual', accountId: 'main', " +
+    'effectiveTimestampMs: 1735689600000, recordedTimestampMs: 1735689600000, ' +
+    "event: { eventType: 'cash.deposit', amount: 100_000, currency: 'USD' }, provenance: {} }";
+function requireEnumField(functionName, field, value, allowed) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new InputError(`${functionName}: ${field} must be one of ${allowed.map((v) => `'${v}'`).join(' | ')}. Received ${describeInputValue(value)}.`, { code: ErrorCode.InputInvalidEnum, context: { function: functionName, field } });
+    }
+}
+function requireOptionalSettle(functionName, path, event, effectiveTimestampMs) {
+    if (event.settleTimestampMs === undefined)
+        return;
+    requireEpochMsField(functionName, `${path}.settleTimestampMs`, event.settleTimestampMs);
+    if (event.settleTimestampMs < effectiveTimestampMs) {
+        throw new InputError(`${functionName}: ${path}.settleTimestampMs (${event.settleTimestampMs}) is before the envelope's effectiveTimestampMs (${effectiveTimestampMs}) — a cash leg cannot settle before its economic effect occurs.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: `${path}.settleTimestampMs` },
+        });
+    }
+}
+/** Validate an optional `lotSelections` array (shared by every lot-relieving family). */
+function requireLotSelectionsShape(functionName, path, selections) {
+    if (selections === undefined)
+        return;
+    if (!Array.isArray(selections) || selections.length === 0) {
+        throw new InputError(`${functionName}: ${path}.lotSelections must be a non-empty array of { lotId, quantity } when present. Received ${selections === null ? 'null' : Array.isArray(selections) ? 'an empty array' : typeof selections}.`, {
+            code: ErrorCode.InputWrongType,
+            context: { function: functionName, field: `${path}.lotSelections` },
+        });
+    }
+    requireDenseDataArray(functionName, `${path}.lotSelections`, selections);
+    const seen = new Set();
+    selections.forEach((selection, index) => {
+        const selectionPath = `${path}.lotSelections[${index}]`;
+        requirePlainDataObject(functionName, selectionPath, selection);
+        requireNoInheritedFields(functionName, selectionPath, selection, ['lotId', 'quantity']);
+        ensureKnownKeys(functionName, selectionPath, selection, ['lotId', 'quantity']);
+        const row = selection;
+        requireIdentityString(functionName, `${selectionPath}.lotId`, row['lotId']);
+        requirePositiveNumberField(functionName, `${selectionPath}.quantity`, row['quantity'], 'the unsigned quantity relieved from the named lot');
+        if (seen.has(row['lotId'])) {
+            throw new InputError(`${functionName}: ${selectionPath}.lotId '${String(row['lotId'])}' appears twice — name each relieved lot once, with its total relieved quantity.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: `${selectionPath}.lotId` },
+            });
+        }
+        seen.add(row['lotId']);
+    });
+}
+/** Validate derivative contract terms (closed per kind). */
+function requireContractTerms(functionName, path, value) {
+    requirePlainDataObject(functionName, path, value);
+    const terms = value;
+    requireNoInheritedFields(functionName, path, terms, ['kind', 'underlyingInstrumentId']);
+    const kind = ownValue(terms, 'kind');
+    requireEnumField(functionName, `${path}.kind`, kind, CONTRACT_KINDS);
+    requireIdentityString(functionName, `${path}.underlyingInstrumentId`, terms['underlyingInstrumentId']);
+    if (kind === 'option') {
+        const keys = [
+            'kind',
+            'underlyingInstrumentId',
+            'type',
+            'strikePricePerUnit',
+            'expiryTimestampMs',
+        ];
+        requireNoInheritedFields(functionName, path, terms, keys);
+        ensureKnownKeys(functionName, path, terms, keys);
+        requireEnumField(functionName, `${path}.type`, terms['type'], ['call', 'put']);
+        requireFiniteNumberField(functionName, `${path}.strikePricePerUnit`, terms['strikePricePerUnit']);
+        requireEpochMsField(functionName, `${path}.expiryTimestampMs`, terms['expiryTimestampMs']);
+    }
+    else if (kind === 'future') {
+        const keys = ['kind', 'underlyingInstrumentId', 'expiryTimestampMs'];
+        requireNoInheritedFields(functionName, path, terms, keys);
+        ensureKnownKeys(functionName, path, terms, keys);
+        requireEpochMsField(functionName, `${path}.expiryTimestampMs`, terms['expiryTimestampMs']);
+    }
+    else {
+        const keys = ['kind', 'underlyingInstrumentId'];
+        requireNoInheritedFields(functionName, path, terms, keys);
+        ensureKnownKeys(functionName, path, terms, keys);
+    }
+}
+/**
+ * The fill's instrument profile: multiplier (> 0, required with contract terms), settlement style
+ * (variation margin exactly for futures/perpetuals), and contract terms.
+ */
+function requireContractProfile(functionName, path, event) {
+    if (event['contractMultiplier'] !== undefined) {
+        requirePositiveNumberField(functionName, `${path}.contractMultiplier`, event['contractMultiplier'], 'units of the underlying per unit of quantity');
+    }
+    if (event['settlementStyle'] !== undefined) {
+        requireEnumField(functionName, `${path}.settlementStyle`, event['settlementStyle'], SETTLEMENT_STYLES);
+    }
+    if (event['contract'] !== undefined) {
+        requireContractTerms(functionName, `${path}.contract`, event['contract']);
+        if (event['contractMultiplier'] === undefined) {
+            throw new InputError(`${functionName}: ${path}.contractMultiplier is required with ${path}.contract — a derivative fill states its multiplier (an equity option's 100, a futures contract size); the ledger never assumes one.`, {
+                code: ErrorCode.InputMissingField,
+                context: { function: functionName, field: `${path}.contractMultiplier` },
+            });
+        }
+        const kind = event['contract']['kind'];
+        const style = event['settlementStyle'] ?? 'cash-on-trade';
+        if ((kind === 'future' || kind === 'perpetual') && style !== 'variation-margin') {
+            throw new InputError(`${functionName}: ${path}.settlementStyle must be 'variation-margin' for a ${kind} — no cash changes hands at the fill; P&L settles through derivative.variation-margin. Received ${describeInputValue(event['settlementStyle'])}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: `${path}.settlementStyle` },
+            });
+        }
+        if (kind === 'option' && style !== 'cash-on-trade') {
+            throw new InputError(`${functionName}: ${path}.settlementStyle must be 'cash-on-trade' for an option (the premium is paid at the fill). Received ${describeInputValue(event['settlementStyle'])}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: `${path}.settlementStyle` },
+            });
+        }
+    }
+    else if (event['settlementStyle'] === 'variation-margin') {
+        throw new InputError(`${functionName}: ${path}.contract is required with settlementStyle 'variation-margin' — only an explicitly described future or perpetual receives daily variation-margin treatment; a multiplier alone does not turn a cash instrument into a derivative.`, {
+            code: ErrorCode.InputMissingField,
+            context: { function: functionName, field: `${path}.contract` },
+        });
+    }
+}
+/** A dated contract may be opened/rolled only while its expiry has not passed (inclusive). */
+function requireContractLiveAt(functionName, path, value, effectiveTimestampMs) {
+    if (value === undefined)
+        return;
+    const terms = value;
+    if ((terms['kind'] === 'option' || terms['kind'] === 'future') &&
+        terms['expiryTimestampMs'] < effectiveTimestampMs) {
+        throw new InputError(`${functionName}: ${path}.expiryTimestampMs (${String(terms['expiryTimestampMs'])}) is before the event's effectiveTimestampMs (${effectiveTimestampMs}) — a dated contract cannot be opened or rolled after it has expired.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: `${path}.expiryTimestampMs` },
+        });
+    }
+}
+function requireDerivativeSettlement(functionName, path, value) {
+    requirePlainDataObject(functionName, path, value);
+    const settlement = value;
+    const kind = ownValue(settlement, 'kind');
+    requireEnumField(functionName, `${path}.kind`, kind, ['physical', 'cash']);
+    if (kind === 'physical') {
+        requireNoInheritedFields(functionName, path, settlement, ['kind']);
+        ensureKnownKeys(functionName, path, settlement, ['kind']);
+    }
+    else {
+        const keys = ['kind', 'settlementPricePerUnit'];
+        requireNoInheritedFields(functionName, path, settlement, keys);
+        ensureKnownKeys(functionName, path, settlement, keys);
+        requireFiniteNumberField(functionName, `${path}.settlementPricePerUnit`, settlement['settlementPricePerUnit']);
+    }
+}
+function requireQuantityField(functionName, path, event, meaning) {
+    requirePositiveNumberField(functionName, `${path}.quantity`, event['quantity'], meaning);
+}
+function validateEventPayload(functionName, path, envelope) {
+    const event = envelope.event;
+    requirePlainDataObject(functionName, path, event);
+    const eventType = ownValue(event, 'eventType');
+    if (typeof eventType !== 'string' || !hasOwnKey(EVENT_KEYS, eventType)) {
+        throw new InputError(`${functionName}: ${path}.eventType must be one of ${Object.keys(EVENT_KEYS)
+            .map((t) => `'${t}'`)
+            .join(' | ')}. Received ${describeInputValue(eventType)}.`, {
+            code: ErrorCode.InputInvalidEnum,
+            context: { function: functionName, field: `${path}.eventType` },
+        });
+    }
+    const knownKeys = EVENT_KEYS[eventType];
+    requireNoInheritedFields(functionName, path, event, knownKeys);
+    ensureKnownKeys(functionName, path, event, knownKeys);
+    if (envelope.eventType !== eventType) {
+        throw new InputError(`${functionName}: the envelope's eventType (${describeInputValue(envelope.eventType)}) must equal ${path}.eventType ('${eventType}') — the redundant discriminator exists so a mismatched envelope is heard, not guessed around.`, { code: ErrorCode.InputOutOfRange, context: { function: functionName, field: 'eventType' } });
+    }
+    switch (eventType) {
+        case 'cash.deposit':
+        case 'cash.withdrawal': {
+            requirePositiveNumberField(functionName, `${path}.amount`, event['amount'], `the ${eventType === 'cash.deposit' ? 'deposited' : 'withdrawn'} magnitude (direction comes from the event type)`);
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            requireOptionalSettle(functionName, path, event, envelope.effectiveTimestampMs);
+            break;
+        }
+        case 'cash.transfer': {
+            requirePositiveNumberField(functionName, `${path}.amount`, event['amount'], 'the transferred magnitude');
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            requireIdentityString(functionName, `${path}.fromAccountId`, event['fromAccountId']);
+            requireIdentityString(functionName, `${path}.toAccountId`, event['toAccountId']);
+            if (event['fromAccountId'] === event['toAccountId']) {
+                throw new InputError(`${functionName}: ${path} transfers from account '${String(event['fromAccountId'])}' to itself — fromAccountId and toAccountId must differ.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.toAccountId` },
+                });
+            }
+            if (envelope.accountId !== event['fromAccountId']) {
+                throw new InputError(`${functionName}: the envelope's accountId ('${envelope.accountId}') must equal ${path}.fromAccountId ('${String(event['fromAccountId'])}') — a transfer is recorded against the account it leaves.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: 'accountId' },
+                });
+            }
+            break;
+        }
+        case 'cash.conversion': {
+            requireCurrencyCode(functionName, `${path}.fromCurrency`, event['fromCurrency']);
+            requireCurrencyCode(functionName, `${path}.toCurrency`, event['toCurrency']);
+            if (event['fromCurrency'] === event['toCurrency']) {
+                throw new InputError(`${functionName}: ${path} converts ${String(event['fromCurrency'])} into itself — fromCurrency and toCurrency must differ.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.toCurrency` },
+                });
+            }
+            requirePositiveNumberField(functionName, `${path}.fromAmount`, event['fromAmount'], 'the magnitude of the currency sold');
+            requirePositiveNumberField(functionName, `${path}.toAmount`, event['toAmount'], 'the magnitude of the currency received');
+            break;
+        }
+        case 'trade.fill': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requireEnumField(functionName, `${path}.side`, event['side'], ['buy', 'sell']);
+            requirePositiveNumberField(functionName, `${path}.quantity`, event['quantity'], 'the filled quantity (side carries the direction)');
+            requireFiniteNumberField(functionName, `${path}.pricePerUnit`, event['pricePerUnit']);
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            requireOptionalSettle(functionName, path, event, envelope.effectiveTimestampMs);
+            requireLotSelectionsShape(functionName, path, event['lotSelections']);
+            requireContractProfile(functionName, path, event);
+            requireContractLiveAt(functionName, `${path}.contract`, event['contract'], envelope.effectiveTimestampMs);
+            if (event['accruedInterest'] !== undefined) {
+                requireFiniteNumberField(functionName, `${path}.accruedInterest`, event['accruedInterest']);
+                if (event['accruedInterest'] < 0) {
+                    throw new InputError(`${functionName}: ${path}.accruedInterest is the unsigned accrued amount exchanged with the fill (side carries the direction: paid on a buy, received on a sell). Received ${event['accruedInterest']}.`, {
+                        code: ErrorCode.InputOutOfRange,
+                        context: { function: functionName, field: `${path}.accruedInterest` },
+                    });
+                }
+            }
+            break;
+        }
+        case 'cost.charge': {
+            requireEnumField(functionName, `${path}.costType`, event['costType'], COST_TYPES);
+            requireFiniteNumberField(functionName, `${path}.amount`, event['amount']);
+            if (event['amount'] === 0) {
+                throw new InputError(`${functionName}: ${path}.amount must be non-zero — positive charges cash, negative is a rebate/credit; a zero cost is not an economic event.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.amount` },
+                });
+            }
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            if (event['instrumentId'] !== undefined) {
+                requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            }
+            if (event['relatesToEventId'] !== undefined) {
+                requireIdentityString(functionName, `${path}.relatesToEventId`, event['relatesToEventId']);
+            }
+            break;
+        }
+        case 'income.received': {
+            requireEnumField(functionName, `${path}.incomeType`, event['incomeType'], INCOME_TYPES);
+            if (event['incomeType'] === 'dividend' || event['incomeType'] === 'coupon') {
+                requireFiniteNumberField(functionName, `${path}.amount`, event['amount']);
+                if (event['amount'] === 0) {
+                    throw new InputError(`${functionName}: ${path}.amount must be non-zero — positive receives income, negative pays a short-position dividend/coupon obligation; omit a zero income event.`, {
+                        code: ErrorCode.InputOutOfRange,
+                        context: { function: functionName, field: `${path}.amount` },
+                    });
+                }
+            }
+            else {
+                requirePositiveNumberField(functionName, `${path}.amount`, event['amount'], 'income received in cash (a financing PAYMENT is financing.charge)');
+            }
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            if (event['instrumentId'] !== undefined) {
+                requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            }
+            requireOptionalSettle(functionName, path, event, envelope.effectiveTimestampMs);
+            break;
+        }
+        case 'financing.charge': {
+            requireEnumField(functionName, `${path}.financingType`, event['financingType'], FINANCING_TYPES);
+            requirePositiveNumberField(functionName, `${path}.amount`, event['amount'], 'the financing magnitude paid (a funding RECEIPT is income.received)');
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            if (event['instrumentId'] !== undefined) {
+                requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            }
+            break;
+        }
+        case 'admin.reversal':
+        case 'admin.correction': {
+            requirePlainDataObject(functionName, `${path}.original`, event['original']);
+            // The applied envelope, verbatim — validated as the closed grammar it must already satisfy.
+            requirePortfolioEventEnvelope(functionName, `${path}.original`, event['original']);
+            const original = event['original'];
+            const originalType = original.event.eventType;
+            // A reversal may undo a repair (a reversal of a reversal re-applies the fact; a reversal of a
+            // correction undoes the replacement and re-applies the fact) — that is what makes a wrong
+            // repair recoverable. A correction, and a migration marker, are never the subject of a repair.
+            const repairable = eventType === 'admin.reversal'
+                ? originalType !== 'admin.account-migration'
+                : !originalType.startsWith('admin.');
+            if (!repairable) {
+                throw new InputError(`${functionName}: ${path}.original is an '${originalType}' event — ${eventType === 'admin.correction'
+                    ? 'a correction repairs an economic fact; to undo a repair, record an admin.reversal of it'
+                    : 'a migration marker has no effect to reverse'}.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.original` },
+                });
+            }
+            if (envelope.reversesEventId !== original.eventId) {
+                throw new InputError(`${functionName}: ${path.replace(/\.event$/, '')}.reversesEventId must equal ${path}.original.eventId (${describeInputValue(original.eventId)}) — the link and the carried original name the same applied fact. Received ${describeInputValue(envelope.reversesEventId)}.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.original.eventId` },
+                });
+            }
+            if (original.accountId !== envelope.accountId) {
+                throw new InputError(`${functionName}: ${path}.original was recorded on account '${original.accountId}', but this ${eventType} is on account '${envelope.accountId}' — a repair is recorded on the account it repairs.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.original.accountId` },
+                });
+            }
+            if (eventType === 'admin.correction') {
+                requirePlainDataObject(functionName, `${path}.replacement`, event['replacement']);
+                const replacementType = ownValue(event['replacement'], 'eventType');
+                if (typeof replacementType === 'string' && replacementType.startsWith('admin.')) {
+                    throw new InputError(`${functionName}: ${path}.replacement must be an economic event (cash/trade/cost/income/financing/corporate), not '${replacementType}'.`, {
+                        code: ErrorCode.InputInvalidEnum,
+                        context: { function: functionName, field: `${path}.replacement.eventType` },
+                    });
+                }
+                // Validated at the ORIGINAL's instant — that is when the replacement folds.
+                validateEventPayload(functionName, `${path}.replacement`, {
+                    ...original,
+                    event: event['replacement'],
+                });
+            }
+            if (event['reason'] !== undefined) {
+                requireIdentityString(functionName, `${path}.reason`, event['reason']);
+            }
+            break;
+        }
+        case 'admin.account-migration': {
+            requireIdentityString(functionName, `${path}.fromAccountId`, event['fromAccountId']);
+            requireIdentityString(functionName, `${path}.toAccountId`, event['toAccountId']);
+            if (event['fromAccountId'] === event['toAccountId']) {
+                throw new InputError(`${functionName}: ${path} migrates account '${String(event['fromAccountId'])}' to itself — a migration marker names two different account identities.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.toAccountId` },
+                });
+            }
+            if (event['reason'] !== undefined) {
+                requireIdentityString(functionName, `${path}.reason`, event['reason']);
+            }
+            break;
+        }
+        case 'corporate.split': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            for (const field of ['sharesAfterSplit', 'sharesBeforeSplit']) {
+                const value = event[field];
+                if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
+                    throw new InputError(`${functionName}: ${path}.${field} must be a positive safe-integer share count (a 2-for-1 split is { sharesAfterSplit: 2, sharesBeforeSplit: 1 }; ratios past 2^53 are not share counts). Received ${value === null ? 'null' : typeof value === 'number' ? value : typeof value}.`, {
+                        code: typeof value === 'number' ? ErrorCode.InputOutOfRange : ErrorCode.InputWrongType,
+                        context: { function: functionName, field: `${path}.${field}` },
+                    });
+                }
+            }
+            if (event['sharesAfterSplit'] === event['sharesBeforeSplit']) {
+                throw new InputError(`${functionName}: ${path} declares a ${String(event['sharesAfterSplit'])}-for-${String(event['sharesBeforeSplit'])} split — a 1:1 "split" changes nothing and is not an economic event.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.sharesAfterSplit` },
+                });
+            }
+            break;
+        }
+        case 'derivative.exercise':
+        case 'derivative.assignment': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requireQuantityField(functionName, path, event, 'the contracts settled');
+            requireDerivativeSettlement(functionName, `${path}.settlement`, event['settlement']);
+            requireEnumField(functionName, `${path}.premiumTreatment`, event['premiumTreatment'], PREMIUM_TREATMENTS);
+            requireOptionalSettle(functionName, path, event, envelope.effectiveTimestampMs);
+            requireLotSelectionsShape(functionName, path, event['lotSelections']);
+            break;
+        }
+        case 'derivative.expiration': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requireQuantityField(functionName, path, event, 'the contracts expiring');
+            requireLotSelectionsShape(functionName, path, event['lotSelections']);
+            break;
+        }
+        case 'derivative.multiplier-change': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requirePositiveNumberField(functionName, `${path}.contractMultiplierAfter`, event['contractMultiplierAfter'], 'the adjusted units of the underlying per contract');
+            if (event['strikePricePerUnitAfter'] !== undefined) {
+                requireFiniteNumberField(functionName, `${path}.strikePricePerUnitAfter`, event['strikePricePerUnitAfter']);
+            }
+            if (event['reason'] !== undefined && typeof event['reason'] !== 'string') {
+                throw new InputError(`${functionName}: ${path}.reason must be a string.`, {
+                    code: ErrorCode.InputWrongType,
+                    context: { function: functionName, field: `${path}.reason` },
+                });
+            }
+            break;
+        }
+        case 'derivative.variation-margin': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requireFiniteNumberField(functionName, `${path}.settlementPricePerUnit`, event['settlementPricePerUnit']);
+            break;
+        }
+        case 'derivative.roll': {
+            requireIdentityString(functionName, `${path}.fromInstrumentId`, event['fromInstrumentId']);
+            requireIdentityString(functionName, `${path}.toInstrumentId`, event['toInstrumentId']);
+            if (event['fromInstrumentId'] === event['toInstrumentId']) {
+                throw new InputError(`${functionName}: ${path} rolls ${String(event['fromInstrumentId'])} into itself — a roll closes one contract and opens its successor.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.toInstrumentId` },
+                });
+            }
+            requireQuantityField(functionName, path, event, 'the contracts rolled');
+            requireFiniteNumberField(functionName, `${path}.closePricePerUnit`, event['closePricePerUnit']);
+            requireFiniteNumberField(functionName, `${path}.openPricePerUnit`, event['openPricePerUnit']);
+            if (event['contract'] !== undefined) {
+                requireContractTerms(functionName, `${path}.contract`, event['contract']);
+                requireContractLiveAt(functionName, `${path}.contract`, event['contract'], envelope.effectiveTimestampMs);
+            }
+            requireLotSelectionsShape(functionName, path, event['lotSelections']);
+            break;
+        }
+        case 'fixed-income.redemption': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requireEnumField(functionName, `${path}.redemptionType`, event['redemptionType'], REDEMPTION_TYPES);
+            requireQuantityField(functionName, path, event, 'the face units redeemed');
+            requireFiniteNumberField(functionName, `${path}.pricePerUnit`, event['pricePerUnit']);
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            requireOptionalSettle(functionName, path, event, envelope.effectiveTimestampMs);
+            requireLotSelectionsShape(functionName, path, event['lotSelections']);
+            break;
+        }
+        case 'corporate.symbol-change': {
+            requireIdentityString(functionName, `${path}.fromInstrumentId`, event['fromInstrumentId']);
+            requireIdentityString(functionName, `${path}.toInstrumentId`, event['toInstrumentId']);
+            if (event['fromInstrumentId'] === event['toInstrumentId']) {
+                throw new InputError(`${functionName}: ${path} renames ${String(event['fromInstrumentId'])} to itself — not an economic event.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.toInstrumentId` },
+                });
+            }
+            break;
+        }
+        case 'corporate.merger': {
+            requireIdentityString(functionName, `${path}.fromInstrumentId`, event['fromInstrumentId']);
+            const hasShares = event['sharesPerShare'] !== undefined;
+            const hasCash = event['cashPerShare'] !== undefined;
+            if (!hasShares && !hasCash) {
+                throw new InputError(`${functionName}: ${path} must declare a consideration — sharesPerShare (with toInstrumentId), cashPerShare (with currency), or both.`, {
+                    code: ErrorCode.InputMissingField,
+                    context: { function: functionName, field: `${path}.sharesPerShare` },
+                });
+            }
+            if (hasShares) {
+                requirePositiveNumberField(functionName, `${path}.sharesPerShare`, event['sharesPerShare'], 'new shares per share held');
+                if (event['toInstrumentId'] === undefined) {
+                    throw new InputError(`${functionName}: ${path}.toInstrumentId is required with sharesPerShare — the shares must be of something.`, {
+                        code: ErrorCode.InputMissingField,
+                        context: { function: functionName, field: `${path}.toInstrumentId` },
+                    });
+                }
+                requireIdentityString(functionName, `${path}.toInstrumentId`, event['toInstrumentId']);
+                if (event['toInstrumentId'] === event['fromInstrumentId']) {
+                    throw new InputError(`${functionName}: ${path} merges ${String(event['fromInstrumentId'])} into itself — use corporate.split for a share-count change.`, {
+                        code: ErrorCode.InputOutOfRange,
+                        context: { function: functionName, field: `${path}.toInstrumentId` },
+                    });
+                }
+            }
+            else if (event['toInstrumentId'] !== undefined) {
+                throw new InputError(`${functionName}: ${path}.toInstrumentId is only meaningful with sharesPerShare (a cash merger delivers no shares).`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.toInstrumentId` },
+                });
+            }
+            if (hasCash) {
+                requirePositiveNumberField(functionName, `${path}.cashPerShare`, event['cashPerShare'], 'cash per share held');
+                requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            }
+            else if (event['currency'] !== undefined) {
+                throw new InputError(`${functionName}: ${path}.currency is only meaningful with cashPerShare.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.currency` },
+                });
+            }
+            requireOptionalSettle(functionName, path, event, envelope.effectiveTimestampMs);
+            break;
+        }
+        case 'corporate.spin-off': {
+            requireIdentityString(functionName, `${path}.parentInstrumentId`, event['parentInstrumentId']);
+            requireIdentityString(functionName, `${path}.childInstrumentId`, event['childInstrumentId']);
+            if (event['parentInstrumentId'] === event['childInstrumentId']) {
+                throw new InputError(`${functionName}: ${path} spins ${String(event['parentInstrumentId'])} off from itself.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.childInstrumentId` },
+                });
+            }
+            requirePositiveNumberField(functionName, `${path}.sharesPerParentShare`, event['sharesPerParentShare'], 'child shares per parent share');
+            requireFiniteNumberField(functionName, `${path}.basisAllocationFraction`, event['basisAllocationFraction']);
+            if (event['basisAllocationFraction'] < 0 || event['basisAllocationFraction'] > 1) {
+                throw new InputError(`${functionName}: ${path}.basisAllocationFraction is the fraction of the parent's basis that moves to the child, in [0, 1]. Received ${event['basisAllocationFraction']}.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.basisAllocationFraction` },
+                });
+            }
+            break;
+        }
+        case 'corporate.return-of-capital': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requirePositiveNumberField(functionName, `${path}.amountPerShare`, event['amountPerShare'], 'capital returned per share held');
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            requireOptionalSettle(functionName, path, event, envelope.effectiveTimestampMs);
+            break;
+        }
+        case 'corporate.cash-in-lieu': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requireQuantityField(functionName, path, event, 'the fractional quantity surrendered');
+            requireFiniteNumberField(functionName, `${path}.amount`, event['amount']);
+            if (event['amount'] < 0) {
+                throw new InputError(`${functionName}: ${path}.amount is the cash received in lieu, ≥ 0. Received ${event['amount']}.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.amount` },
+                });
+            }
+            requireCurrencyCode(functionName, `${path}.currency`, event['currency']);
+            if (event['relatesToEventId'] !== undefined) {
+                requireIdentityString(functionName, `${path}.relatesToEventId`, event['relatesToEventId']);
+            }
+            requireOptionalSettle(functionName, path, event, envelope.effectiveTimestampMs);
+            break;
+        }
+        case 'position.transfer': {
+            requireIdentityString(functionName, `${path}.instrumentId`, event['instrumentId']);
+            requireQuantityField(functionName, path, event, 'the unsigned quantity moved');
+            requireIdentityString(functionName, `${path}.fromAccountId`, event['fromAccountId']);
+            requireIdentityString(functionName, `${path}.toAccountId`, event['toAccountId']);
+            if (event['fromAccountId'] === event['toAccountId']) {
+                throw new InputError(`${functionName}: ${path} transfers ${String(event['instrumentId'])} from account '${String(event['fromAccountId'])}' to itself — fromAccountId and toAccountId must differ.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${path}.toAccountId` },
+                });
+            }
+            if (envelope.accountId !== event['fromAccountId']) {
+                throw new InputError(`${functionName}: the envelope's accountId ('${envelope.accountId}') must equal ${path}.fromAccountId ('${String(event['fromAccountId'])}') — a transfer is recorded against the account it leaves.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: 'accountId' },
+                });
+            }
+            requireLotSelectionsShape(functionName, path, event['lotSelections']);
+            break;
+        }
+    }
+}
+/**
+ * Validate one {@link PortfolioEventEnvelope} at a public boundary (Law 12 closed request): known
+ * keys at every level, identity strings, finite explicit timestamps, the schema version, the
+ * envelope/payload discriminator agreement, and the full per-variant payload contract. The guard
+ * validates its own `functionName` and `label` first (the `requireFundamentalPeriod` precedent) so
+ * its teaching errors always name the real boundary.
+ */
+export function requirePortfolioEventEnvelope(functionName, label, envelope) {
+    if (typeof functionName !== 'string' || functionName.length === 0) {
+        throw new InputError(`requirePortfolioEventEnvelope: functionName must be a non-empty string (the public boundary being validated). Received ${functionName === null ? 'null' : functionName === undefined ? 'undefined' : typeof functionName === 'string' ? "''" : typeof functionName}.`, { code: ErrorCode.InputWrongType, context: { field: 'functionName' } });
+    }
+    if (typeof label !== 'string' || label.length === 0) {
+        throw new InputError(`requirePortfolioEventEnvelope: label must be a non-empty string (the caller's name for the envelope field being validated). Received ${label === null ? 'null' : label === undefined ? 'undefined' : typeof label === 'string' ? "''" : typeof label}.`, { code: ErrorCode.InputWrongType, context: { field: 'label' } });
+    }
+    requirePlainDataObject(functionName, label, envelope);
+    requireNoInheritedFields(functionName, label, envelope, ENVELOPE_KEYS);
+    ensureKnownKeys(functionName, label, envelope, ENVELOPE_KEYS);
+    requireIdentityString(functionName, `${label}.eventId`, envelope.eventId);
+    if (envelope.schemaVersion !== PORTFOLIO_EVENT_SCHEMA_VERSION) {
+        const received = describeInputValue(envelope.schemaVersion);
+        throw new InputError(`${functionName}: ${label}.schemaVersion must be ${PORTFOLIO_EVENT_SCHEMA_VERSION} (this build's event grammar). Received ${received}. Older stored events restore through readPortfolioLedgerSnapshot with a registered migration; a newer version needs a newer @insiderfinance/totalfinance release.\n  e.g. ${EXAMPLE_ENVELOPE}`, {
+            code: typeof envelope.schemaVersion === 'number'
+                ? ErrorCode.SnapshotUnsupportedVersion
+                : ErrorCode.InputWrongType,
+            context: { function: functionName, field: `${label}.schemaVersion`, received },
+        });
+    }
+    requireIdentityString(functionName, `${label}.sourceId`, envelope.sourceId);
+    requireIdentityString(functionName, `${label}.accountId`, envelope.accountId);
+    requireEpochMsField(functionName, `${label}.effectiveTimestampMs`, envelope.effectiveTimestampMs);
+    requireEpochMsField(functionName, `${label}.recordedTimestampMs`, envelope.recordedTimestampMs);
+    for (const field of ['correlationId', 'causationId', 'reversesEventId']) {
+        if (envelope[field] !== undefined) {
+            requireIdentityString(functionName, `${label}.${field}`, envelope[field]);
+        }
+    }
+    {
+        // Inspect the discriminator only after proving the nested value is stored data. Optional
+        // chaining would otherwise execute an inherited/accessor `eventType` before the payload guard
+        // got a chance to refuse it.
+        requirePlainDataObject(functionName, `${label}.event`, envelope.event);
+        const type = ownValue(envelope.event, 'eventType');
+        const isRepair = type === 'admin.reversal' || type === 'admin.correction';
+        if (envelope.reversesEventId !== undefined && !isRepair) {
+            throw new InputError(`${functionName}: ${label}.reversesEventId is set, but only admin.reversal and admin.correction fold that link — a ${describeInputValue(type)} event cannot reverse anything (its own effect stands). Record an admin.reversal naming the fact, or drop the link.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: `${label}.reversesEventId` },
+            });
+        }
+        if (envelope.reversesEventId === undefined && isRepair) {
+            throw new InputError(`${functionName}: ${label}.reversesEventId is required on an ${describeInputValue(type)} — the envelope names the applied fact it repairs (equal to event.original.eventId).`, {
+                code: ErrorCode.InputMissingField,
+                context: { function: functionName, field: `${label}.reversesEventId` },
+            });
+        }
+    }
+    if (envelope.provenance === undefined) {
+        throw new InputError(`${functionName}: ${label}.provenance is required — every economic event states where it came from (an empty object {} is a valid "no further detail"). It is caller-supplied, never fetched, and excluded from the event identity.\n  e.g. ${EXAMPLE_ENVELOPE}`, {
+            code: ErrorCode.InputMissingField,
+            context: { function: functionName, field: `${label}.provenance` },
+        });
+    }
+    requireProvenanceShape(functionName, `${label}.provenance`, envelope.provenance);
+    validateEventPayload(functionName, `${label}.event`, envelope);
+}
+/**
+ * The event's content identity and the CONFLICT boundary for duplicate `(sourceId, eventId)`
+ * delivery: the `sha256:` content hash (Gate B canonical JSON) of the envelope EXCLUDING
+ * `provenance` — two deliveries of the same economic fact under different source labels are the
+ * SAME event (Gate B Decision 3: provenance is outside every identity). The envelope is fully
+ * validated first; a malformed envelope never acquires a confident-looking hash.
+ */
+export function portfolioEventContentHash(envelope) {
+    requirePortfolioEventEnvelope('portfolioEventContentHash', 'envelope', envelope);
+    const body = { ...envelope };
+    delete body['provenance'];
+    return contentHash(body);
+}
+/**
+ * The `(sourceId, eventId)` duplicate-boundary key — the exact registry key `PortfolioState`
+ * records under `appliedEvents`, exposed so stores and importers can pre-check delivery without
+ * re-deriving the encoding.
+ */
+export function duplicateBoundaryKey(envelope) {
+    // A boundary, not a shortcut: the key is only meaningful for a VALID envelope, so the full
+    // closed-key validator runs here exactly as it does for the content hash — a malformed or
+    // decorated envelope teaches instead of reading `sourceId` off `undefined` (2026-08-28).
+    requirePortfolioEventEnvelope('duplicateBoundaryKey', 'envelope', envelope);
+    return canonicalJsonOf([envelope.sourceId, envelope.eventId]);
+}
+export const NORMALIZED_FILL_KEYS = [
+    'fillId',
+    'accountId',
+    'instrumentId',
+    'side',
+    'quantity',
+    'pricePerUnit',
+    'currency',
+    'filledTimestampMs',
+    'settleTimestampMs',
+    'contractMultiplier',
+    'settlementStyle',
+    'contract',
+    'accruedInterest',
+    'costs',
+    'executionPriceAdjustment',
+    'orderId',
+    'venue',
+    'liquidity',
+];
+const NORMALIZED_FILL_COST_KEYS = [
+    'commission',
+    'exchangeFees',
+    'regulatoryFees',
+    'slippageAdjustment',
+];
+/** Cost component → the ledger's `costType` and the event-id suffix, in emission order. */
+const COST_COMPONENTS = [
+    ['commission', 'commission'],
+    ['exchangeFees', 'exchange-fee'],
+    ['regulatoryFees', 'regulatory-fee'],
+    ['slippageAdjustment', 'slippage-adjustment'],
+];
+const EXAMPLE_FILL = "portfolioEventsFromFill({ fill: { fillId: 'f-1', accountId: 'main', instrumentId: 'AAPL', side: 'buy', quantity: 100, pricePerUnit: 150, currency: 'USD', filledTimestampMs: 1767200400000, costs: { commission: 1 } }, sourceId: 'backtest:run-1', recordedTimestampMs: 1767200400000 })";
+/**
+ * Validate a {@link NormalizedFill} at a public boundary: a closed plain-data record whose numbers
+ * are finite, whose quantity is positive, whose settlement never precedes the fill, whose cost
+ * components are non-negative, and whose derivative terms come with their multiplier. The
+ * economic laws a fill must satisfy inside the ledger (a future settles by variation margin, a lot
+ * selection names real lots, …) are enforced by the event validator the mapped events pass through.
+ */
+export function requireNormalizedFill(functionName, label, fill) {
+    requirePlainDataObject(functionName, label, fill);
+    requireNoInheritedFields(functionName, label, fill, NORMALIZED_FILL_KEYS);
+    ensureKnownKeys(functionName, label, fill, NORMALIZED_FILL_KEYS);
+    const record = fill;
+    for (const field of ['fillId', 'accountId', 'instrumentId']) {
+        requireIdentityString(functionName, `${label}.${field}`, record[field]);
+    }
+    if (record['side'] !== 'buy' && record['side'] !== 'sell') {
+        throw new InputError(`${functionName}: ${label}.side must be 'buy' | 'sell'. Received ${describeInputValue(record['side'])}.\n  e.g. ${EXAMPLE_FILL}`, {
+            code: ErrorCode.InputInvalidEnum,
+            context: { function: functionName, field: `${label}.side` },
+        });
+    }
+    requirePositiveNumberField(functionName, `${label}.quantity`, record['quantity'], 'the filled quantity; side carries the direction');
+    requireFiniteNumberField(functionName, `${label}.pricePerUnit`, record['pricePerUnit']);
+    requireCurrencyCode(functionName, `${label}.currency`, record['currency']);
+    requireEpochMsField(functionName, `${label}.filledTimestampMs`, record['filledTimestampMs']);
+    if (hasOwnKey(record, 'settleTimestampMs')) {
+        requireEpochMsField(functionName, `${label}.settleTimestampMs`, record['settleTimestampMs']);
+        if (record['settleTimestampMs'] < record['filledTimestampMs']) {
+            throw new InputError(`${functionName}: ${label}.settleTimestampMs (${String(record['settleTimestampMs'])}) precedes filledTimestampMs (${String(record['filledTimestampMs'])}) — cash settles at or after the fill, never before.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: `${label}.settleTimestampMs` },
+            });
+        }
+    }
+    if (hasOwnKey(record, 'contractMultiplier')) {
+        requirePositiveNumberField(functionName, `${label}.contractMultiplier`, record['contractMultiplier'], 'units of the underlying per unit of quantity');
+    }
+    if (hasOwnKey(record, 'settlementStyle')) {
+        if (record['settlementStyle'] !== 'cash-on-trade' &&
+            record['settlementStyle'] !== 'variation-margin') {
+            throw new InputError(`${functionName}: ${label}.settlementStyle must be 'cash-on-trade' | 'variation-margin'. Received ${describeInputValue(record['settlementStyle'])}.`, {
+                code: ErrorCode.InputInvalidEnum,
+                context: { function: functionName, field: `${label}.settlementStyle` },
+            });
+        }
+    }
+    if (hasOwnKey(record, 'contract')) {
+        requirePlainDataObject(functionName, `${label}.contract`, record['contract']);
+        if (!hasOwnKey(record, 'contractMultiplier')) {
+            throw new InputError(`${functionName}: ${label}.contract is given but ${label}.contractMultiplier is not — a derivative fill states its multiplier (an equity option's 100, a futures contract size); the ledger never assumes one.`, {
+                code: ErrorCode.InputMissingField,
+                context: { function: functionName, field: `${label}.contractMultiplier` },
+            });
+        }
+    }
+    if (hasOwnKey(record, 'accruedInterest')) {
+        requireFiniteNumberField(functionName, `${label}.accruedInterest`, record['accruedInterest']);
+    }
+    if (hasOwnKey(record, 'costs')) {
+        requirePlainDataObject(functionName, `${label}.costs`, record['costs']);
+        const costs = record['costs'];
+        requireNoInheritedFields(functionName, `${label}.costs`, costs, NORMALIZED_FILL_COST_KEYS);
+        ensureKnownKeys(functionName, `${label}.costs`, costs, NORMALIZED_FILL_COST_KEYS);
+        for (const component of NORMALIZED_FILL_COST_KEYS) {
+            if (!hasOwnKey(costs, component))
+                continue;
+            requireFiniteNumberField(functionName, `${label}.costs.${component}`, costs[component]);
+            if (costs[component] < 0) {
+                throw new InputError(`${functionName}: ${label}.costs.${component} must be ≥ 0 (a cost the account paid, in ${String(record['currency'])}); a rebate is income, not a negative cost. Received ${String(costs[component])}.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { function: functionName, field: `${label}.costs.${component}` },
+                });
+            }
+        }
+    }
+    if (hasOwnKey(record, 'executionPriceAdjustment')) {
+        requireFiniteNumberField(functionName, `${label}.executionPriceAdjustment`, record['executionPriceAdjustment']);
+        if (record['executionPriceAdjustment'] < 0)
+            throw new InputError(`${functionName}: ${label}.executionPriceAdjustment must be non-negative; it reports the absolute price deviation already embedded in the fill.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { function: functionName, field: `${label}.executionPriceAdjustment` },
+            });
+    }
+    if (hasOwnKey(record, 'orderId')) {
+        requireIdentityString(functionName, `${label}.orderId`, record['orderId']);
+    }
+    if (hasOwnKey(record, 'venue')) {
+        requireIdentityString(functionName, `${label}.venue`, record['venue']);
+    }
+    if (hasOwnKey(record, 'liquidity')) {
+        const liquidity = record['liquidity'];
+        if (liquidity !== 'maker' && liquidity !== 'taker' && liquidity !== 'unknown') {
+            throw new InputError(`${functionName}: ${label}.liquidity must be 'maker' | 'taker' | 'unknown'. Received ${describeInputValue(liquidity)}.`, {
+                code: ErrorCode.InputInvalidEnum,
+                context: { function: functionName, field: `${label}.liquidity` },
+            });
+        }
+    }
+}
+const EVENTS_FROM_FILL_KEYS = ['fill', 'sourceId', 'recordedTimestampMs', 'provenance'];
+/**
+ * Map one {@link NormalizedFill} to the economic events the ledger folds: exactly one `trade.fill`
+ * (id = `fillId`) followed by one `cost.charge` per non-zero cost component (id =
+ * `<fillId>:cost:<component>`, `relatesToEventId` = the fill), in the fixed order commission →
+ * exchange fees → regulatory fees → slippage adjustment. The mapping is deterministic and the ids
+ * are derived from the fill, so an identical fill delivered twice folds once (the ledger's
+ * duplicate boundary) and a replay emits identical envelopes. Every envelope passes the same
+ * validator a hand-written one would.
+ */
+export function portfolioEventsFromFill(input) {
+    const functionName = 'portfolioEventsFromFill';
+    requirePlainDataObject(functionName, 'input', input);
+    requireNoInheritedFields(functionName, 'input', input, EVENTS_FROM_FILL_KEYS);
+    ensureKnownKeys(functionName, 'input', input, EVENTS_FROM_FILL_KEYS);
+    const { fill, sourceId, recordedTimestampMs } = input;
+    requireNormalizedFill(functionName, 'input.fill', fill);
+    requireIdentityString(functionName, 'input.sourceId', sourceId);
+    requireEpochMsField(functionName, 'input.recordedTimestampMs', recordedTimestampMs);
+    const provenance = hasOwnKey(input, 'provenance')
+        ? input.provenance
+        : {};
+    requireProvenanceShape(functionName, 'input.provenance', provenance);
+    const tradeFill = {
+        eventType: 'trade.fill',
+        instrumentId: fill.instrumentId,
+        side: fill.side,
+        quantity: fill.quantity,
+        pricePerUnit: fill.pricePerUnit,
+        currency: fill.currency,
+        ...(fill.settleTimestampMs !== undefined ? { settleTimestampMs: fill.settleTimestampMs } : {}),
+        ...(fill.contractMultiplier !== undefined
+            ? { contractMultiplier: fill.contractMultiplier }
+            : {}),
+        ...(fill.settlementStyle !== undefined ? { settlementStyle: fill.settlementStyle } : {}),
+        ...(fill.contract !== undefined ? { contract: cloneJson(fill.contract) } : {}),
+        ...(fill.accruedInterest !== undefined ? { accruedInterest: fill.accruedInterest } : {}),
+    };
+    const correlation = fill.orderId !== undefined ? { correlationId: fill.orderId } : {};
+    const envelopes = [
+        {
+            eventId: fill.fillId,
+            schemaVersion: PORTFOLIO_EVENT_SCHEMA_VERSION,
+            eventType: 'trade.fill',
+            sourceId,
+            accountId: fill.accountId,
+            effectiveTimestampMs: fill.filledTimestampMs,
+            recordedTimestampMs,
+            ...correlation,
+            event: tradeFill,
+            provenance: cloneJson(provenance),
+        },
+    ];
+    const costs = fill.costs ?? {};
+    for (const [component, costType] of COST_COMPONENTS) {
+        const amount = costs[component];
+        if (amount === undefined || amount === 0)
+            continue;
+        const charge = {
+            eventType: 'cost.charge',
+            costType,
+            amount,
+            currency: fill.currency,
+            instrumentId: fill.instrumentId,
+            relatesToEventId: fill.fillId,
+        };
+        envelopes.push({
+            eventId: `${fill.fillId}:cost:${component}`,
+            schemaVersion: PORTFOLIO_EVENT_SCHEMA_VERSION,
+            eventType: 'cost.charge',
+            sourceId,
+            accountId: fill.accountId,
+            effectiveTimestampMs: fill.filledTimestampMs,
+            recordedTimestampMs,
+            ...correlation,
+            causationId: fill.fillId,
+            event: charge,
+            provenance: cloneJson(provenance),
+        });
+    }
+    envelopes.forEach((envelope, index) => requirePortfolioEventEnvelope(functionName, `events[${index}]`, envelope));
+    return envelopes;
+}
+//# sourceMappingURL=events.js.map